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
  }