Execute Task API

API URL

/task/{taskId}/forced/{forced}/startTask

HTTP Method

POST

API Category

TDM_Tasks

API Description

Starts a task execution and returns the execution's task_execution_id on success. The API can get an optional input of overridden parameters for the task execution.

Validate the Task Execution Parameters

  • Verify that the TDM task execution processes are up and running. If the TDM task execution processes are down, stop the task execution and return an error message.
  • Test the connection details of the source and target environments of the task execution if the forced parameter is false.
  • Do not enable an execution if another execution with the same execution parameters is already running on the task.
  • Validate the task's BE and LUs with the TDM Systems of the task execution's source and target environment.
  • Verify that the user is permitted to execute the task on the task execution's source and target environment. For example, the user cannot run a Load task with a sequence replacement on environment X if the user does not have permissions to run such a task on this environment.
Data Versioning Validations
  • Data versioning extract tasks: validate the retention period to verify that it does not exceed the maximum days allowed for the tester.
Entity Reservation Validations
  • Validate the number of reserved entities: if the task reserves the entities whether the reserve_ind is set to true in the task itself or in the overridden parameters, accumulate the number of entities in the task to the total number of reserved entities for the user on the target environment. If the total number of reserved entities exceeds the user's permissions on the environment, return an error. For example, if the user is allowed to reserved up to 70 entities in ST1 and there are 50 entities that are already reserved for the user in ST1, the user can reserve up to 20 additional entities in ST1.
  • Validate the retention period to verify that the number of days does not exceed the maximum number of days allowed for the tester.

If at least one of the validations fail, the API does not start the task and returns the validation errors.

Below is the list of the validation codes, returned by the API:

  • BEandLUs

  • Reference

  • selectionMethod

  • Versioning

  • ReplaceSequence

  • DeleteBeforeLoad

  • syncMode

  • totalNumberOfReservedEntities

  • versioningRetentionPeriod

  • reverseRetentionPeriod

Start the Task Execution

If the validations pass successfully, start the task execution by populating the following TDM DB tables:

  • TASK_EXECUTION_LIST - populate the source and target environments by the task execution's environments:
    • If the overriden parameters include the task execution envionments, get the execution environments from the overriden parameters. Else, get the execution environments from the task record.
  • TASK_EXECUTION_OVERRIDE_ATTRS - populate the JSON of the overridden parameter by param name and param value pairs. For example- "SOURCE_ENVIRONMENT": "ST1"

API Input

  • taskId

  • forced - this parameter indicates if the execution should ignore a failure of the task's environment connections validation. If the forced parameter is set to true, then the execution ignores the validation failure and executes the task. If the forced parameter is set to false and the environment validation fails, the execution is not initiated.

  • An optional request body with overriden parameters for task execution. It is possible to populate all, part , or none of the overriden parameters. The following parameters can be set:

    Parameter Name

    Parameter Description

    Task Types

    Data Versioning

    entitieslist

    Populated by a list of entities separated by a comma. Note that the entity list can only contain one entity ID when executing a task that clones an entity

    Load task

    True/False

    sourceEnvironmentName

    Source environment name

    Load or Extract tasks

    True/False

    targetEnvironmentName

    Target environment name

    Load, Delete, or Reserve tasks

    True/False

    taskGlobals

    A list of Global variables (task variables) and their values

    All tasks

    True/False

    numberOfEntities

    Populated with a number to change the number of entities processed by the task. This parameter is only irrelevant for the entity list if it is not set in the overridden parameters.

    All tasks

    False

    dataVersionExecId

    Populated with the task execution id of the selected data version. The parameter can be set on Data Versioning load tasks.

    Load task

    True

    dataVersionRetentionPeriod

    Populated with the retention period of the extracted data version. This parameter contains the unit (Hours, Days, Weeks…) and the value.

    Extract task True

    reserveInd

    Populated with true or false. Set to true if the task execution needs to reserve the entities on the target environment.

    Load or Reserve tasks

    Load task: True/False

     

    Reserve task: N/A

    reserveRetention

    Populated with the reservation period of the task's entities. This parameter contains the unit (Hours, Days, Weeks.) and the value.

    Load or Reserve tasks

    Load task: True/False

     

    Reserve task: N/A

    executionNote

    Free text. Add a note to the execution.

    All tasks

    True/False

    Request Body Structure

      {
        "entitieslist": "string",
        "sourceEnvironmentName": "string",
        "targetEnvironmentName": "string",
        "taskGlobals": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "numberOfEntities": 0,
        "dataVersionExecId": 0,
        "dataVersionRetentionPeriod": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "reserveInd": true,
        "reserveRetention": {
          "additionalProp1": {}
        },
        "executionNote": "string"
      }
    

    API Input Examples

    API URL

    http://localhost:3213/api/task/55/forced/true/startTask
    

    Request Body Examples

    Example 1
    {
        "entitieslist": "1,2,4,9,8,11",
        "sourceEnvironmentName": "SRC1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "Customer.Global2": "value2",
            "Customer.CUST_DETAILS": "'{\"name\":\"John\", \"age\":30, \"car\":null}'" 
        },
        "reserveInd": true,
          "reserveRetention": {
            "unit": "Days",
            "value": "10"
      }
    
    }
    
    Example 2
    {
        "sourceEnvironmentName": "SRC1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "Customer.Global2": "value2"
        },
     "numberOfEntities": 10
    }
    
    Example 3 - Data Versioning Load Task

    Override the selected version

    {
        "sourceEnvironmentName": "TAR1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "EMAIL": "john123@gmail.com"
        },
     "dataVersionExecId": 10
    }
    
    Example 4 - Data Versioning Extract Task
    {
        "entitieslist": "1,2,4,9,8,11,33",
        "sourceEnvironmentName": "TAR1",
        "taskGlobals": {
            EMAIL": "john123@gmail.com"
        },
         "dataVersionRetentionPeriod": {
            "unit": "Days",
            "value": "10"
        },
        "executionNote": "Snapshot 1"
    }
    

    API Output Examples

    Validation Failure Examples

    {
        "result":[{"Number of entity":"The number of entities exceeds the number of entities in the write permission","selectionMethod":"The User has no permissions to run the task's selection method on the task's target environment"}],
        "errorCode":"FAIL",
        "message":"validation failure"
    }
    
    { 
        "result": 
        [{"reference": "The user has no permissions to run tasks on Reference tables on source environment", 
          "syncMode": "the user has no permissions to ask to always sync the data from the source."    } ], 
        "errorCode": "FAIL",
        "message": "validation failure"
    } 
    

    The Test Connection of the Task's Environment Fails

    The test connection runs when the forced input parameter is set to false.

    {"errorCode":"FAIL","message":"The test connection of [CRM_DB] failed. Please check the connection details of target environment TAR"}
    

    Successful Execution Example

    {
      "result": {
        "taskExecutionId": 43
      },
      "errorCode": "SUCCESS",
      "message": null
    }
    

    Previous

Execute Task API

API URL

/task/{taskId}/forced/{forced}/startTask

HTTP Method

POST

API Category

TDM_Tasks

API Description

Starts a task execution and returns the execution's task_execution_id on success. The API can get an optional input of overridden parameters for the task execution.

Validate the Task Execution Parameters

  • Verify that the TDM task execution processes are up and running. If the TDM task execution processes are down, stop the task execution and return an error message.
  • Test the connection details of the source and target environments of the task execution if the forced parameter is false.
  • Do not enable an execution if another execution with the same execution parameters is already running on the task.
  • Validate the task's BE and LUs with the TDM Systems of the task execution's source and target environment.
  • Verify that the user is permitted to execute the task on the task execution's source and target environment. For example, the user cannot run a Load task with a sequence replacement on environment X if the user does not have permissions to run such a task on this environment.
Data Versioning Validations
  • Data versioning extract tasks: validate the retention period to verify that it does not exceed the maximum days allowed for the tester.
Entity Reservation Validations
  • Validate the number of reserved entities: if the task reserves the entities whether the reserve_ind is set to true in the task itself or in the overridden parameters, accumulate the number of entities in the task to the total number of reserved entities for the user on the target environment. If the total number of reserved entities exceeds the user's permissions on the environment, return an error. For example, if the user is allowed to reserved up to 70 entities in ST1 and there are 50 entities that are already reserved for the user in ST1, the user can reserve up to 20 additional entities in ST1.
  • Validate the retention period to verify that the number of days does not exceed the maximum number of days allowed for the tester.

If at least one of the validations fail, the API does not start the task and returns the validation errors.

Below is the list of the validation codes, returned by the API:

  • BEandLUs

  • Reference

  • selectionMethod

  • Versioning

  • ReplaceSequence

  • DeleteBeforeLoad

  • syncMode

  • totalNumberOfReservedEntities

  • versioningRetentionPeriod

  • reverseRetentionPeriod

Start the Task Execution

If the validations pass successfully, start the task execution by populating the following TDM DB tables:

  • TASK_EXECUTION_LIST - populate the source and target environments by the task execution's environments:
    • If the overriden parameters include the task execution envionments, get the execution environments from the overriden parameters. Else, get the execution environments from the task record.
  • TASK_EXECUTION_OVERRIDE_ATTRS - populate the JSON of the overridden parameter by param name and param value pairs. For example- "SOURCE_ENVIRONMENT": "ST1"

API Input

  • taskId

  • forced - this parameter indicates if the execution should ignore a failure of the task's environment connections validation. If the forced parameter is set to true, then the execution ignores the validation failure and executes the task. If the forced parameter is set to false and the environment validation fails, the execution is not initiated.

  • An optional request body with overriden parameters for task execution. It is possible to populate all, part , or none of the overriden parameters. The following parameters can be set:

    Parameter Name

    Parameter Description

    Task Types

    Data Versioning

    entitieslist

    Populated by a list of entities separated by a comma. Note that the entity list can only contain one entity ID when executing a task that clones an entity

    Load task

    True/False

    sourceEnvironmentName

    Source environment name

    Load or Extract tasks

    True/False

    targetEnvironmentName

    Target environment name

    Load, Delete, or Reserve tasks

    True/False

    taskGlobals

    A list of Global variables (task variables) and their values

    All tasks

    True/False

    numberOfEntities

    Populated with a number to change the number of entities processed by the task. This parameter is only irrelevant for the entity list if it is not set in the overridden parameters.

    All tasks

    False

    dataVersionExecId

    Populated with the task execution id of the selected data version. The parameter can be set on Data Versioning load tasks.

    Load task

    True

    dataVersionRetentionPeriod

    Populated with the retention period of the extracted data version. This parameter contains the unit (Hours, Days, Weeks…) and the value.

    Extract task True

    reserveInd

    Populated with true or false. Set to true if the task execution needs to reserve the entities on the target environment.

    Load or Reserve tasks

    Load task: True/False

     

    Reserve task: N/A

    reserveRetention

    Populated with the reservation period of the task's entities. This parameter contains the unit (Hours, Days, Weeks.) and the value.

    Load or Reserve tasks

    Load task: True/False

     

    Reserve task: N/A

    executionNote

    Free text. Add a note to the execution.

    All tasks

    True/False

    Request Body Structure

      {
        "entitieslist": "string",
        "sourceEnvironmentName": "string",
        "targetEnvironmentName": "string",
        "taskGlobals": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "numberOfEntities": 0,
        "dataVersionExecId": 0,
        "dataVersionRetentionPeriod": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "reserveInd": true,
        "reserveRetention": {
          "additionalProp1": {}
        },
        "executionNote": "string"
      }
    

    API Input Examples

    API URL

    http://localhost:3213/api/task/55/forced/true/startTask
    

    Request Body Examples

    Example 1
    {
        "entitieslist": "1,2,4,9,8,11",
        "sourceEnvironmentName": "SRC1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "Customer.Global2": "value2",
            "Customer.CUST_DETAILS": "'{\"name\":\"John\", \"age\":30, \"car\":null}'" 
        },
        "reserveInd": true,
          "reserveRetention": {
            "unit": "Days",
            "value": "10"
      }
    
    }
    
    Example 2
    {
        "sourceEnvironmentName": "SRC1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "Customer.Global2": "value2"
        },
     "numberOfEntities": 10
    }
    
    Example 3 - Data Versioning Load Task

    Override the selected version

    {
        "sourceEnvironmentName": "TAR1",
        "targetEnvironmentName": "TAR1",
        "taskGlobals": {
            "EMAIL": "john123@gmail.com"
        },
     "dataVersionExecId": 10
    }
    
    Example 4 - Data Versioning Extract Task
    {
        "entitieslist": "1,2,4,9,8,11,33",
        "sourceEnvironmentName": "TAR1",
        "taskGlobals": {
            EMAIL": "john123@gmail.com"
        },
         "dataVersionRetentionPeriod": {
            "unit": "Days",
            "value": "10"
        },
        "executionNote": "Snapshot 1"
    }
    

    API Output Examples

    Validation Failure Examples

    {
        "result":[{"Number of entity":"The number of entities exceeds the number of entities in the write permission","selectionMethod":"The User has no permissions to run the task's selection method on the task's target environment"}],
        "errorCode":"FAIL",
        "message":"validation failure"
    }
    
    { 
        "result": 
        [{"reference": "The user has no permissions to run tasks on Reference tables on source environment", 
          "syncMode": "the user has no permissions to ask to always sync the data from the source."    } ], 
        "errorCode": "FAIL",
        "message": "validation failure"
    } 
    

    The Test Connection of the Task's Environment Fails

    The test connection runs when the forced input parameter is set to false.

    {"errorCode":"FAIL","message":"The test connection of [CRM_DB] failed. Please check the connection details of target environment TAR"}
    

    Successful Execution Example

    {
      "result": {
        "taskExecutionId": 43
      },
      "errorCode": "SUCCESS",
      "message": null
    }
    

    Previous