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. Starting from TDM 10.1, the API can also get an optional ID of a previous execution of the task, in order to rerun the task with the override parameters of that 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. Instead, it returns a FAILED status and the validation errors.

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

• BEandLUs

• Reference

• selectionMethod

• Versioning

• ReplaceSequence

• DeleteBeforeLoad

• syncMode

• totalNumberOfReservedEntities

• versioningRetentionPeriod

• reserveRetentionPeriod

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 overridden parameters include the task execution environments, get the execution environments from the overridden parameters. Else, get the execution environments from the task record.
• TASK_EXECUTION_OVERRIDE_ATTRS - populate the JSON of the overridden parameters by param name and param value pairs. For example- "SOURCE_ENVIRONMENT_NAME": "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 the following attributes:

  • overrideParameters - an optional object with the overridden parameters of the task execution. It is possible to populate all, part, or none of the overridden parameters. The parameter names are set in uppercase, for example: ENTITY_LIST, SOURCE_ENVIRONMENT_NAME.

  • taskExecutionId - new in TDM 10.1. An optional ID of an existing execution of the task. The override parameters of this execution (stored in the TASK_EXECUTION_OVERRIDE_ATTRS TDM DB table) are used as a baseline for the new execution:

  • Override parameters that are also populated in overrideParameters take precedence over the baseline.

  • Parameters that are populated neither in the baseline nor in overrideParameters are taken from the task itself.

  • A new task execution is always created. The input task execution ID is checked as a baseline.

The following override parameters can be set in the overrideParameters object:

Request Body Structure

{
  "overrideParameters": {
    "BE_ID": "string",
    "ENTITY_LIST": "string",
    "SOURCE_ENVIRONMENT_NAME": "string",
    "TARGET_ENVIRONMENT_NAME": "string",
    "TASK_GLOBALS": {
      "additionalProp1": "string"
    },
    "NO_OF_ENTITIES": 0,
    "SELECTED_VERSION_TASK_EXE_ID": 0,
    "SELECTED_SUBSET_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",
    "GENERATE_DATA_PARAMS": {
      "additionalProp1": {"value": "string"}
    },
    "CUSTOM_LOGIC_FLOW": "string",
    "CUSTOM_LOGIC_LU_NAME": "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"}]}
    ],
    "TABLE_SAMPLING": [
      {"ref_table_name": "string", "interface_name": "string", "schema_name": "string", "records_limit": 0, "partitions_limit": 0}
    ],
    "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"}]}
    ]
  },
  "taskExecutionId": 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 the LU Settings, Table Filters and Sampling, and Pre/Post Execution Process Parameters

{
  "overrideParameters": {
    "LOGICAL_UNITS": [
      {
        "lu_id": 1,
        "lu_name": "Customer",
        "max_no_of_workers": 5,
        "source_affinity": "DC1",
        "target_affinity": "DC2"
      }
    ],
    "TABLE_FILTERS": [
      {
        "ref_table_name": "RefT",
        "interface_name": "RefInterface",
        "schema_name": "RefSchema",
        "fields": [
          {"field": "col1", "condition": "=", "value": "val1"}
        ]
      }
    ],
    "TABLE_SAMPLING": [
      {
        "ref_table_name": "RefT",
        "interface_name": "RefInterface",
        "schema_name": "RefSchema",
        "records_limit": 100,
        "partitions_limit": 2
      }
    ],
    "PRE_EXECUTION_PROCESSES_PARAMS": [
      {
        "process_id": 1,
        "parameter_overrides": [
          {"name": "param1", "value": "v1"}
        ]
      }
    ],
    "POST_EXECUTION_PROCESSES_PARAMS": [
      {
        "process_id": 2,
        "parameter_overrides": [
          {"name": "param1", "value": "v1"}
        ]
      }
    ]
  }
}

Example 6 - Rerun a Previous Execution

Rerun the task with the override parameters of execution 120, and override its number of entities:

{
  "taskExecutionId": 120,
  "overrideParameters": {
    "NO_OF_ENTITIES": 20
  }
}

API Output Examples

Validation Failure Examples

Entity or environment permission errors - the validation errors are returned in the result:

{
  "result": {
    "Number of entity": "Exceeds write permission"
  },
  "errorCode": "FAILED",
  "message": "validation failure"
}

Invalid override parameters or permission errors - the error is returned in the message:

{
  "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
}

ease check the connection details of target environment TAR"}

#### Successful Execution Example

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