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.

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 that specifies runtime overrides for task execution. All override values are nested under the overrideParameters object. You can provide all, some, or none of the supported override parameters. The following parameters are available.

  Note: Only parameters that are open for editing in the task can be overridden.

Request Body Structure

  {
    "overrideParameters": {
      "BE_ID": "string",
      "ENTITY_LIST": "string",
      "SOURCE_ENVIRONMENT_NAME": "string",
      "TARGET_ENVIRONMENT_NAME": "string",
      "TASK_GLOBALS": {
        "GlobalName": "value"
      },
      "NO_OF_ENTITIES": 0,
      "SELECTED_VERSION_TASK_EXE_ID": 0,
      "DATAFLUX_RETENTION_PARAMS": {
        "units": "string",
        "value": "string"
      },
      "RESERVE_IND": true,
      "RESERVE_RETENTION_PARAMS": {
        "units": "string",
        "value": "string"
      },
      "EXECUTION_NOTE": "string",
      "SELECTION_METHOD": "string",
      "PARAMETERS": "string",
      "BP_QUERY": "string",
      "LOGICAL_UNITS": [
        {
          "lu_id": 0,
          "lu_name": "string",
          "max_no_of_workers": 0,
          "source_affinity": "string",
          "target_affinity": "string"
        }
      ],
      "TABLE_FILTERS": [
        {
          "ref_table_name": "string",
          "interface_name": "string",
          "schema_name": "string",
          "fields": [
            {
              "field": "string",
              "condition": "string",
              "value": "string"
            }
          ]
        }
      ],
      "PRE_EXECUTION_PROCESSES_PARAMS": [
        {
          "process_id": 0,
          "parameter_overrides": [
            {
              "name": "string",
              "value": "string"
            }
          ]
        }
      ],
      "POST_EXECUTION_PROCESSES_PARAMS": [
        {
          "process_id": 0,
          "parameter_overrides": [
            {
              "name": "string",
              "value": "string"
            }
          ]
        }
      ]
    },
    "draftExecutionId": 0
  }

API Input Examples

API URL

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

Request Body Examples

Example 1

{
  "overrideParameters": {
    "ENTITY_LIST": "1,2,4,9,8,11",
    "SOURCE_ENVIRONMENT_NAME": "SRC1",
    "TARGET_ENVIRONMENT_NAME": "TAR1",
    "TASK_GLOBALS": {
      "Customer.Global2": "value2",
      "Customer.CUST_DETAILS": "'{\"name\":\"John\", \"age\":30, \"car\":null}'"
    },
    "RESERVE_IND": true,
    "RESERVE_RETENTION_PARAMS": {
      "units": "Days",
      "value": "10"
    }
  }
}

Example 2

{
  "overrideParameters": {
    "SOURCE_ENVIRONMENT_NAME": "SRC1",
    "TARGET_ENVIRONMENT_NAME": "TAR1",
    "TASK_GLOBALS": {
      "Customer.Global2": "value2"
    },
    "NO_OF_ENTITIES": 10
  }
}

Example 3 - Data Versioning Load Task

Override the selected version:

{
  "overrideParameters": {
    "SOURCE_ENVIRONMENT_NAME": "TAR1",
    "TARGET_ENVIRONMENT_NAME": "TAR1",
    "TASK_GLOBALS": {
      "EMAIL": "john123@gmail.com"
    },
    "SELECTED_VERSION_TASK_EXE_ID": 10
  }
}

Example 4 - Data Versioning Extract Task

{
  "overrideParameters": {
    "ENTITY_LIST": "1,2,4,9,8,11,33",
    "SOURCE_ENVIRONMENT_NAME": "TAR1",
    "TASK_GLOBALS": {
      "EMAIL": "john123@gmail.com"
    },
    "DATAFLUX_RETENTION_PARAMS": {
      "units": "Days",
      "value": "10"
    },
    "EXECUTION_NOTE": "Snapshot 1"
  }
}

Example 5 - Override Per-LU Settings

{
  "overrideParameters": {
    "SOURCE_ENVIRONMENT_NAME": "SRC1",
    "TARGET_ENVIRONMENT_NAME": "TAR1",
    "NO_OF_ENTITIES": 5,
    "LOGICAL_UNITS": [
      {
        "lu_id": 1,
        "lu_name": "Customer",
        "max_no_of_workers": 5,
        "source_affinity": "DC1",
        "target_affinity": "DC2"
      }
    ]
  }
}

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": "FAILED",
    "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": "FAILED",
    "message": "validation failure"
} 

Override Parameter Validation Error

{
  "result": null,
  "errorCode": "FAILED",
  "message": "LOGICAL_UNITS[0] is missing required field 'lu_name'."
}

The Test Connection of the Task's Environment Fails

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

{"errorCode": "FAILED", "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
}

Backward Compatibility - TDM 9.5 Override Parameter Structure

TDM 10 changed the startTask request body: all override parameters are now wrapped in an overrideParameters object, and parameter names use uppercase keys (e.g., ENTITY_LIST instead of entitieslist).

If your integration code was built on TDM 9.5 and populates override parameters using the previous flat structure, you can invoke V1 of the startTask API. This version accepts the TDM 9.5 flat parameter structure and internally builds the new overrideParameters JSON required by TDM 10.

The TDM 9.5 flat parameter names and their TDM 10 equivalents are:

| TDM 9.5 Parameter | TDM 10 overrideParameters Key | |---|---| | entitieslist | ENTITY_LIST | | sourceEnvironmentName | SOURCE_ENVIRONMENT_NAME | | targetEnvironmentName | TARGET_ENVIRONMENT_NAME | | taskGlobals | TASK_GLOBALS | | numberOfEntities | NO_OF_ENTITIES | | dataVersionExecId | SELECTED_VERSION_TASK_EXE_ID | | dataVersionRetentionPeriod | DATAFLUX_RETENTION_PARAMS (note: key renamed from unit to units) | | reserveInd | RESERVE_IND | | reserveRetention | RESERVE_RETENTION_PARAMS (note: key renamed from unit to units) | | executionNote | EXECUTION_NOTE |