Orchestration Execution
Deploying an Orchestration Workflow File
Add the orchestration workflow file to the database by deploying it to the runtime engine. Do this once before running the first orchestration execution that uses the workflow file. Or whenever you update the BPMN workflow file.
orchestrationConfigurationId
(see Uploading an Orchestration Configuration Entry).POST <execution_uri>/api/v2/execution/orchestrations/{orchestrationConfigurationId}/deployment
Passing Custom Attributes During an Orchestration
When running an orchestration request, you can pass custom attributes as follows.
Custom attributes are used for the following situations.
- Customizing query criteria attributes in port-to-field map.
- Configuring dynamic tags in port-to-field map.
- These custom attributes are also passed to custom data connectors.
The following is a sample of the structure required to add custom attributes (customAttributes
) in an orchestration run request for a single asset.
{
"orchestrationConfigurationId": "a7d1c09d-000c-4017-a073-8a3df9058ffc",
"assetId": null,
"assetDataFieldsMap": null,
"assetGroup": {
"dataSourceId": "PredixAsset",
"assetSelectionFilter": "/assets?filter=classification=/classifications/turbine:name=15sl-b3d857c0-bb3d-4b82-b61c-199b75c6f1ef<turbine_type"
},
"modelGroupKey": null,
"dataSource": [
],
"customAttributes": {
"KW.START_TIME": 1455733669601,
"KW.END_TIME": 1455733669610,
"vibration.START_TIME": 1455733669601,
"vibration.END_TIME": 1455733669610,
"ATTRIBUTE_1_KEY": "test_attr_key1",
"ATTRIBUTE_2_KEY": "test_attr_key2",
"KW.ATTRIBUTE_1_VALUE_1": "test-val1",
"KW.ATTRIBUTE_1_VALUE_2": "test-val2",
"vibration.ATTRIBUTE_1_VALUE_1": "test-val1",
"vibration.ATTRIBUTE_1_VALUE_2": "test-val2",
"AGGREGATION_TYPE":"interpolation",
"INTERVAL":"1hr",
"MESSAGE_ID": "test-message-id-1",
"bearing temperature final.ATTRIBUTE_1_VALUE_1":"test_write_val1",
"bearing temperature final.ATTRIBUTE_1_VALUE_2":"test_write_val2",
"QUERY_CRITERIA1": {
"start": "${START_TIME}",
"end": "${END_TIME}",
"tags": [
{
"limit": "${LIMIT}",
"order": "${ORDER}"
}
]
},
"START_TIME": 1455733669601,
"END_TIME": 1455733669610,
"LIMIT": 1000,
"ORDER": "desc",
"QUERY_CRITERIA2": {
"messageId": "${MESSAGE_ID}",
"body": [
{
"name": null,
"attributes": {
"${ATTRIBUTE_2_KEY}": "${ASSET_ID}_${FIELD_ID}_${double array.ATTRIBUTE_2_VALUE}",
"${ATTRIBUTE_1_KEY}": "${ASSET_ID}_${FIELD_ID}_${double array.ATTRIBUTE_1_VALUE}"
}
}
]
},
"double array.ATTRIBUTE_2_VALUE": "test_write_attr_val2",
"double array.ATTRIBUTE_1_VALUE": "test_write_attr_val1"
}
}
customAttributes
field of OrchestrationExecutionRequest
. The following sample uses customAttributes
to pass in the value for CONSTANT input port, setting value at runtime for port "abc
".{
"orchestrationConfigurationId": "a7d1c09d-000c-4017-a073-8a3df9058ffc",
"assetId": null,
"assetDataFieldsMap": null,
"assetGroup": {
"dataSourceId": "PredixAsset",
"assetSelectionFilter": "/assets?filter=classification=/classifications/turbine:name=15sl-46606c64-619d-4db0-a059-bc2d879640ca<turbine_type"
},
"customAttributes": {
"CONSTANT_VALUE": "testvalue-for-constant-inputport-abc" }
}
Note the following requirements when passing custom attributes.
- Variable placeholders are case sensitive and must be enclosed by
${..}
. - Variables will have the namespace where defined. Supported namespaces are: "
asset
", "context
", "custom
". At runtime:- The
context
namespace is for the system defined variables. For example, the analytic id for the current orchestration step will replace${context.ANALYTIC_ID}, ${context.analyticId}
. This applies to all the pre-defined system attributes. - The
asset
namespace is for the asset attributes from theassetGroupQuery
result. For example, thesourceKey
attribute in the response fromassetGroupQuery
will replace${asset.sourceKey}
. - The
custom
namespace is thecustomAttributes
defined in the orchestration execution request. A custom attribute value from orchestration execution requestMESSAGE_ID
will replace corresponding${custom.MESSAGE_ID}
.
- The
- Variables can be alphanumeric, and include dots (.), underscores (_), spaces ( ).
- If the parameter does not have a valid namespace, the value will be searched against all the supported namespaces in following order:
custom
,context
,asset
. - Query criteria must be valid JSON.
- If the pre-defined system attributes are used in the query, the system will substitute values automatically.
- Numeric placeholders (e.g.,
$(LIMIT)
) must be double quoted. The system will automatically substitute the placeholder with a numeric value. - Only string and numeric values can be substituted. Boolean (
true
andfalse
) must be double-quoted as a string. - All variables must be specified in
customAttributes
field. Any unsubstituted variables will cause the orchestration to fail. - Dynamic query criteria (
queryCriteria
) can have embedded parametrized system or custom attributes.
Running an Orchestration with One Analytic
The following example walks you through the process to run an orchestration with one analytic.
Before You Begin
- The REST headers for making requests to Analytics services must be properly configured. See Configuring REST Request Headers.
- The analytic must be deployed to Predix platform (you can use a sample analytic). You will need the following information to complete this task.
- analytic catalog entry ID
- analytic name
- analytic version
About This Task
Procedure
Running an Orchestration Using Predix Time Series Tags
To run an orchestration using Predix Time Series tag ids, proceed as follows. The orchestration will communicate with the Predix Time Series service to retrieve and store data for use by the referenced analytics.
Before You Begin
- All referenced analytics hosted by the Analytics Catalog must be deployed to Cloud Foundry and running.
- All referenced analytics must be written to accept input and provide output in the expected format.
- All referenced analytics must have their analytic templates uploaded to the Analytics Catalog.
Procedure
Results
The following is a sample response.
{
"status": "PROCESSING",
"orchestrationExecutionStatus": [
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-null",
"assetId": null
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
}
],
"orchestrationRequestId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3",
"errorResponse": null
}
Running an Orchestration Using Predix Time Series with an Array of Tags
To run an orchestration using Predix Time Series array tag ids, proceed as follows. The orchestration will communicate with the Predix Time Series service to retrieve and store data for use by the referenced analytics.
Before You Begin
- All referenced analytics hosted by the Analytics Catalog must be deployed to Cloud Foundry and running.
- All referenced analytics must be written to accept input and provide output in the expected format.
- All referenced analytics must have their analytic templates uploaded to the Analytics Catalog.
About This Task
Procedure
Running an Orchestration for a Single Asset
To run an orchestration for a single asset, proceed as follows. The orchestration will automatically communicate with both the Predix Asset service to retrieve tags, and the Time Series service to retrieve and store data corresponding to these tags.
Before You Begin
- All referenced analytics hosted by the Analytics Catalog must be deployed to Cloud Foundry and running.
- All referenced analytics must be written to accept input and provide output in the expected format.
- All referenced analytics must have their analytic templates uploaded to the Analytics Catalog.
Procedure
Results
The following is a sample response.
{
"status": "PROCESSING",
"orchestrationExecutionStatus": [
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-/assets/32",
"assetId": "/assets/32 ",
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
}
],
"orchestrationRequestId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3",
"errorResponse": null
}
Running an Orchestration for an Asset Group
To run an orchestration for an asset group, proceed as follows. The orchestration will automatically communicate with both the Predix Asset service to retrieve tags, and the Time Series service to retrieve and store data corresponding to these tags.
Before You Begin
- All referenced analytics hosted by the Analytics Catalog must be deployed to Cloud Foundry and running.
- All referenced analytics must be written to accept input and provide output in the expected format.
- All referenced analytics must have their analytic templates uploaded to the Analytics Catalog.
Procedure
Results
The following is a sample response.
{
"status": "PROCESSING",
"orchestrationExecutionStatus": [
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-/assets/32",
"assetId": "/assets/32 ",
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
},
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-/assets/37",
"assetId": "/assets/37 ",
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
}
],
"orchestrationRequestId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3",
"errorResponse": null
}
Running an Orchestration Using an External Data Source
To run an orchestration for an analytic using an external data source, proceed as follows. The orchestration will automatically communicate with your Custom Data Connector to retrieve and store data from an external source.
Before You Begin
Before executing an orchestration:
- All referenced analytics hosted by the Analytics Catalog must be deployed to Cloud Foundry and running.
- All referenced analytics must be written to accept input and provide output in the expected format.
- All referenced analytics must have their analytic templates uploaded to the Analytics Catalog.
- Your Custom Data Connector service must have been developed and deployed to Predix cloud.
- For Analytics Framework service, see About Analytics Using an External Data Source.
Procedure
Results
The following is a sample response.
{
"status": "PROCESSING",
"orchestrationExecutionStatus": [
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-/assets/32",
"assetId": "/assets/32 ",
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
},
{
"status": "PROCESSING",
"contextId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3-/assets/37",
"assetId": "/assets/37 ",
"errorResponse": null,
"orchestrationStepStatus": [],
"startTime": null,
"endTime": null
}
],
"orchestrationRequestId": "f55ac5ba-40a3-4999-8f61-8bf3ef45ece3",
"errorResponse": null
}