:doc:`SFN <../../stepfunctions>` / Client / create_state_machine

********************
create_state_machine
********************



.. py:method:: SFN.Client.create_state_machine(**kwargs)

  

  Creates a state machine. A state machine consists of a collection of states that can do work ( ``Task`` states), determine to which states to transition next ( ``Choice`` states), stop an execution with an error ( ``Fail`` states), and so on. State machines are specified using a JSON-based, structured language. For more information, see `Amazon States Language <https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html>`__ in the Step Functions User Guide.

   

  If you set the ``publish`` parameter of this API action to ``true``, it publishes version ``1`` as the first revision of the state machine.

   

  For additional control over security, you can encrypt your data using a **customer-managed key** for Step Functions state machines. You can configure a symmetric KMS key and data key reuse period when creating or updating a **State Machine**. The execution history and state machine definition will be encrypted with the key applied to the State Machine.

   

  .. note::

    

    This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.

    

   

  .. note::

    

    ``CreateStateMachine`` is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. ``CreateStateMachine``'s idempotency check is based on the state machine ``name``, ``definition``, ``type``, ``LoggingConfiguration``, ``TracingConfiguration``, and ``EncryptionConfiguration`` The check is also based on the ``publish`` and ``versionDescription`` parameters. If a following request has a different ``roleArn`` or ``tags``, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, ``roleArn`` and ``tags`` will not be updated, even if they are different.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/states-2016-11-23/CreateStateMachine>`_  


  **Request Syntax**
  ::

    response = client.create_state_machine(
        name='string',
        definition='string',
        roleArn='string',
        type='STANDARD'|'EXPRESS',
        loggingConfiguration={
            'level': 'ALL'|'ERROR'|'FATAL'|'OFF',
            'includeExecutionData': True|False,
            'destinations': [
                {
                    'cloudWatchLogsLogGroup': {
                        'logGroupArn': 'string'
                    }
                },
            ]
        },
        tags=[
            {
                'key': 'string',
                'value': 'string'
            },
        ],
        tracingConfiguration={
            'enabled': True|False
        },
        publish=True|False,
        versionDescription='string',
        encryptionConfiguration={
            'kmsKeyId': 'string',
            'kmsDataKeyReusePeriodSeconds': 123,
            'type': 'AWS_OWNED_KEY'|'CUSTOMER_MANAGED_KMS_KEY'
        }
    )
    
  :type name: string
  :param name: **[REQUIRED]** 

    The name of the state machine.

     

    A name must *not* contain:

     

    
    * white space
     
    * brackets ``< > { } [ ]``
     
    * wildcard characters ``? *``
     
    * special characters ``" # % \ ^ | ~ ` $ & , ; : /``
     
    * control characters ( ``U+0000-001F``, ``U+007F-009F``, ``U+FFFE-FFFF``)
     
    * surrogates ( ``U+D800-DFFF``)
     
    * invalid characters ( `` U+10FFFF``)
    

     

    To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.

    

  
  :type definition: string
  :param definition: **[REQUIRED]** 

    The Amazon States Language definition of the state machine. See `Amazon States Language <https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html>`__.

    

  
  :type roleArn: string
  :param roleArn: **[REQUIRED]** 

    The Amazon Resource Name (ARN) of the IAM role to use for this state machine.

    

  
  :type type: string
  :param type: 

    Determines whether a Standard or Express state machine is created. The default is ``STANDARD``. You cannot update the ``type`` of a state machine once it has been created.

    

  
  :type loggingConfiguration: dict
  :param loggingConfiguration: 

    Defines what execution history events are logged and where they are logged.

     

    .. note::

      

      By default, the ``level`` is set to ``OFF``. For more information see `Log Levels <https://docs.aws.amazon.com/step-functions/latest/dg/cloudwatch-log-level.html>`__ in the Step Functions User Guide.

      

    

  
    - **level** *(string) --* 

      Defines which category of execution history events are logged.

      

    
    - **includeExecutionData** *(boolean) --* 

      Determines whether execution data is included in your log. When set to ``false``, data is excluded.

      

    
    - **destinations** *(list) --* 

      An array of objects that describes where your execution history events will be logged. Limited to size 1. Required, if your log level is not set to ``OFF``.

      

    
      - *(dict) --* 

      
        - **cloudWatchLogsLogGroup** *(dict) --* 

          An object describing a CloudWatch log group. For more information, see `AWS\:\:Logs\:\:LogGroup <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html>`__ in the CloudFormation User Guide.

          

        
          - **logGroupArn** *(string) --* 

            The ARN of the the CloudWatch log group to which you want your logs emitted to. The ARN must end with ``:*``

            

          
        
      
  
  
  :type tags: list
  :param tags: 

    Tags to be added when creating a state machine.

     

    An array of key-value pairs. For more information, see `Using Cost Allocation Tags <https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html>`__ in the *Amazon Web Services Billing and Cost Management User Guide*, and `Controlling Access Using IAM Tags <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_iam-tags.html>`__.

     

    Tags may only contain Unicode letters, digits, white space, or these symbols: ``_ . : / = + - @``.

    

  
    - *(dict) --* 

      Tags are key-value pairs that can be associated with Step Functions state machines and activities.

       

      An array of key-value pairs. For more information, see `Using Cost Allocation Tags <https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html>`__ in the *Amazon Web Services Billing and Cost Management User Guide*, and `Controlling Access Using IAM Tags <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_iam-tags.html>`__.

       

      Tags may only contain Unicode letters, digits, white space, or these symbols: ``_ . : / = + - @``.

      

    
      - **key** *(string) --* 

        The key of a tag.

        

      
      - **value** *(string) --* 

        The value of a tag.

        

      
    

  :type tracingConfiguration: dict
  :param tracingConfiguration: 

    Selects whether X-Ray tracing is enabled.

    

  
    - **enabled** *(boolean) --* 

      When set to ``true``, X-Ray tracing is enabled.

      

    
  
  :type publish: boolean
  :param publish: 

    Set to ``true`` to publish the first version of the state machine during creation. The default is ``false``.

    

  
  :type versionDescription: string
  :param versionDescription: 

    Sets description about the state machine version. You can only set the description if the ``publish`` parameter is set to ``true``. Otherwise, if you set ``versionDescription``, but ``publish`` to ``false``, this API action throws ``ValidationException``.

    

  
  :type encryptionConfiguration: dict
  :param encryptionConfiguration: 

    Settings to configure server-side encryption.

    

  
    - **kmsKeyId** *(string) --* 

      An alias, alias ARN, key ID, or key ARN of a symmetric encryption KMS key to encrypt data. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.

      

    
    - **kmsDataKeyReusePeriodSeconds** *(integer) --* 

      Maximum duration that Step Functions will reuse data keys. When the period expires, Step Functions will call ``GenerateDataKey``. Only applies to customer managed keys.

      

    
    - **type** *(string) --* **[REQUIRED]** 

      Encryption type

      

    
  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'stateMachineArn': 'string',
          'creationDate': datetime(2015, 1, 1),
          'stateMachineVersionArn': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **stateMachineArn** *(string) --* 

        The Amazon Resource Name (ARN) that identifies the created state machine.

        
      

      - **creationDate** *(datetime) --* 

        The date the state machine is created.

        
      

      - **stateMachineVersionArn** *(string) --* 

        The Amazon Resource Name (ARN) that identifies the created state machine version. If you do not set the ``publish`` parameter to ``true``, this field returns null value.

        
  
  **Exceptions**
  
  *   :py:class:`SFN.Client.exceptions.InvalidArn`

  
  *   :py:class:`SFN.Client.exceptions.InvalidDefinition`

  
  *   :py:class:`SFN.Client.exceptions.InvalidName`

  
  *   :py:class:`SFN.Client.exceptions.InvalidLoggingConfiguration`

  
  *   :py:class:`SFN.Client.exceptions.InvalidTracingConfiguration`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineAlreadyExists`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineDeleting`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineLimitExceeded`

  
  *   :py:class:`SFN.Client.exceptions.StateMachineTypeNotSupported`

  
  *   :py:class:`SFN.Client.exceptions.TooManyTags`

  
  *   :py:class:`SFN.Client.exceptions.ValidationException`

  
  *   :py:class:`SFN.Client.exceptions.ConflictException`

  
  *   :py:class:`SFN.Client.exceptions.InvalidEncryptionConfiguration`

  
  *   :py:class:`SFN.Client.exceptions.KmsAccessDeniedException`

  
  *   :py:class:`SFN.Client.exceptions.KmsThrottlingException`

  