This article describes how to trigger an xMart pipeline from an external application by calling the start origin web service. The web service supports both GET and POST.

Note that because a single pipeline may have several origins, technically we are triggering a specific origin. For more info, see what is the difference between a pipeline and an origin?

Setup

This external API uses a different clientID than the OData API.

Please request to be allowed to the new app or use your web session token to access temporarly.

To retrieve your current web session token:

  1. open xmart web in your browser, make sure your session is active
  2. Press F12 to open the DevTools console
  3. In DevTools console, run localStorage.getItem('xmart_access_token') to get YOUR_TOKEN
  4. In swagger UI (see link below), fill the Authorization input with “Bearer YOUR_TOKEN”

Swagger UI

New in v4.15.

The new endpoints are discoverable through swagger ui here

Trigger a new batch for origin

If an origin expects a file, see Upload a file first.

Endpoint

~/external/origin/start

Return Value

After the calling the web service (either GET or POST) it will return this json:

{
  "BatchID": {BatchID},
  "Success": true|false, 
  "ErrorMessage": ""
}

The value of the Success property only indicates whether the batch has successfully triggered or not. It is not related to whether the batch itself has failed or succeeded. The BatchID is the ID of the batch (same as in the UI) which can be used for tracking purposes.

GET Method

URL Parameters:

  • martCode: (required) code of the data mart containing the pipeline
  • originCode: (required) code of the origin
  • comment: (optional) batch comment (as in UI)
  • inputValuesJson: (optional way 1 (for swagger)) any required input variable for the origin passed in object as JSON
  • DYNAMIC: (optional way 2 (for simpler url)) any required input variable for the origin directly as query parameters

Example :

  • way 2 -> https://portal-uat.who.int/xmart4/external/origin/start?martCode=MART_CODE&originCode=ORIGIN_CODE&StartYear=2020
  • way 1 -> https://portal-uat.who.int/xmart4/external/origin/start?martCode=MART_CODE&originCode=ORIGIN_CODE&inputValuesJson={“StartYear”:”2020”}

Note: swagger UI does not support adding input variables as their name is not known ahead of time.

POST Method

Same than GET: pass all required parameters as URL parameters. This endpoint also supports providing a multipart/form-data body to upload a file to an origin.

Example:

To upload a CSV or Excel file using the standard export format to a target table MY_TABLE in MY_MART mart:

POST ~/external/origin/start?martCode=MY_MART&originCode=SYS_DATA_LOAD&tableCode=MY_TABLE&sourceTableName=MY_TABLE
Body (multipart/form-data): uploaded CSV or XLSX file.

Note: swagger UI does not support adding input variables as their name is not known ahead of time. Only the variables for the default origin SYS_DATA_LOAD are proposed. For custom inputs variables, use inputValuesJson={"key1":"value1", "key2":"value2"}.

Polling for batch status

Endpoint

~/external/batch/{batchId}/status

Return Value

After the calling the web service it will return this json:

{
  "BatchID": 0,
  "ProcessStepCode": "NONE" | "INITIATING" | "STAGING" | "PREVIEWING" | "APPROVING" | "COMMIT_QUEUING" | "COMMITTING" | "FINALIZING" | "COMPLETED" | "STAGE_QUEUING",
  "ProcessResultCode": "SYSTEM_ERROR" | "REJECTED" | "INVALID" | "SUCCESS" | "CANCELED" | "TIMEOUT_CANCELED" , // (only populated if ProcessStepCode == "COMPLETED", else null)
  "MartCode": "string",
  "OriginCode": "string",
  "PipelineCode": "string",
  "OriginTitle": "string",
  "ProcessStepTitle": "string",
  "ProcessResultTitle": "string"
}

GET Method

URL Parameters:

  • batchId: (required) id of ther batch

Example :

  • https://portal-uat.who.int/xmart4/external/batch/10223/status

TESTING

The endpoints can not be tested directly via browser but instead should use swagger page or postman using the Bearer Token Authorization scheme.