API Machine Learning Execute

Introduction¶


API title:		REST API for ML Execute
Description:		Machine Learning Execute data processing run API
Version:		1.000
Authentication:		OAuth2, API Key, JWT, Basic Auth
Base URL:		https://tenantxyz.api.saastagetik.com/basic https://tenantxyz.api.saastagetik.com/jwt https://tenantxyz.api.saastagetik.com/apikey https://tenantxyz.api.saastagetik.com/oauth2

Prerequisites¶

You must have user function 0004117 enabled in order to use the following APIs.

Request format: JSON

Response format: JSON

Shared headers

Content-Type: application/json
Authorisation: Bearer .

Endpoint¶

Method¶

POST

URL¶

/aih/ml/execute/v1/{database_id}/{workspace_code}/{aa_code}

Description¶

Runs the Execute data processing linked to Advanced analytics with code aa_code, belonging to the DB identified by database_id and defined in the Analytical Workspace indicated by workspace_code.Returns the data processing identifier (dataprocessingId).

The following launch context properties must be included in the body of the request:

Property	Description	Options
Process	Mandatory. Process selected for data processing launch.
Scenarios	Optional, to be used only for scenario-period processes, and not to be present in the case of single-submission processes. Scenario selected for data processing.
Period	Optional, to be used only for scenario-period processes, and not to be present in the case of single-submission processes. Period selected for data processing.
Dimension code	Optional, for use with multidimensional processes only. When not present, filter by Entity dimension.	- It is the code of the analytical dimension (e.g. CHANNEL)
Dimension Filter	Mandatory. Lowest level element or node of the Entity or of the analytical dimension from the data processing will be launched.	- Lowest level elements are specified by code (e.g. A01). - Nodes are specified by the string formed by 'GER
Train Label	Optional, to be used only if the model to which the Execute data processing is linked includes the train phase.
Flag delete data before to run Execute	Optional, the default value is false.

IMPORTANT: It is currently only possible to launch Execute data processes that do not involve the use of parameters required at run time.

Examples

Request¶

Launch of execute data processing from multidimensional process with period scenario, on the analytical dimension CHANNEL, from node, on a model with train phase.

Response¶

The response returns the ID:

{
    "process": "API_BU_MULTI",
    "scenario": "2019ACT",
    "period": "01",
    "trainLabelCode": "TL1",
    "dimensionCode": "CHANNEL",
    "dimensionFilter": "H01|01",
    "deleteBeforeRun": false
}

Data Processing status

Method¶

GET

URL¶

/aih/ml/execute/v1/{database_id}/{dataprocessingId}

Description¶

Returns the Execute data processing status.

Status	Description
RUNNING	Running
FAILED	Failed
COMPLETED	Completed successfully

Example answer

The response returns the ID:

{ "status": "COMPLETED", "parameters": {} }

Data processing interruption

Method¶

DELETE

URL¶

/aih/ml/execute/v1/{database_id}/{dataprocessingId}

Description¶

Allows you to interrupt the Execute data processing.

The response returns:

Message	Description
Processing interrupted	Data Processing was stopped
Processing still in progress	Data processing still running

Example answer

{ "message": "Processing interrupted" }

IMPORTANT:

The Delete operation indicates that data processing is still in progress in the following cases:

data processing is in the COMPLETED status
data processing is in the FAILED status

The delete operation returns error '401 Unauthorised' when the user requesting the interruption is not the same user who launched the data processing. The message 'The current user is not the one who started the processing' is displayed.

API Common Errors¶

The error cases handled are:¶

Error	Description
401 Unauthorized	- the user does not exist - the user authenticated with an incorrect password - the user requesting the interruption of the data processing is not the same user who launched it.
400 Bad Request	- Process does not exist - Standard process and the analytical dimension (dimensionCode) is indicated - Analytical workspace (workspace_code) does not exist - Advanced analytics (aa_code) does not exist in the analytical workspace (workspace_code) - Period or scenario indicated in a single submission process - Period or scenario not indicated in a scenario period process - Period or scenario do not belong to the indicated period scenario process. - The analytical dimension (dimensionCode) does not exist - Lowest level element or node (dimensionFilter) not existing - Lowest level element or node do not belong to the analytical dimension - In the rest of GET and DELETE the indicated dataprocessingId does not exist.
403 Forbidden	- Database (database_id) not associated with the user - the user does not have function 0004117 enabled
404 Not Found	- URL non valid.

Examples

Launch of the POST API, the process is standard but an analytical dimension is indicated

{
    "process": "API_BU",
    "scenario": "2020_ACTUAL",
    "period": "01",
    "trainLabelCode": "TL1",
    "dimensionCode": "CHANNEL",
    "dimensionFilter": "010|020",
    "deleteBeforeRun": false
}

Response

{
    "code": 400,
    "message": "Process is not multidimensional"
}

The correct POST body is:

{
    "process": "API_BU",
    "scenario": "2020_ACTUAL",
    "period": "01",
    "trainLabelCode": "TL1",
    "dimensionCode": "",
    "dimensionFilter": "010|020",
    "deleteBeforeRun": false
}