Initiates a user-defined workflow consisting of multiple operatons.
A user-defined workflow is a custom workflow that defines and manages the sequencing of multiple operations. Each operation in a user-defined workflow represents an expensive or long-running process that is submitted to the workflow engine as a job for processing.
All parameters are defined in the request body.
Request body
A user-defined workflow may be defined by the name, type, settings, and operations request body parameters.
{
"name": "My Custom Workflow",
"settings": {
"combine-batch-edit-and-geohaz": false
},
"operations": [
{
"continueOnFailure": "true",
"dependsOn": [],
"input": { ... },
"label": "BatchAccount",
"operation": "/v3/exposurebatches?datasource=edmName"
},
{
"continueOnFailure": "true",
"dependsOn": [ "BatchAccout" ],
"input": { ... },
"label": "SummaryReport",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'DemoAccount1')].id}}/summary_report?datasource={{EdmName}}"
},
{
"continueOnFailure": false,
"dependsOn": [ "BatchAccount" ],
"input": [...],
"label": "GeohazAccount",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'DemoAccount1')].id}}/geohaz?datasource={{EdmName}}"
},
{
"continueOnFailure": true,
"dependsOn": ["GeohazAccount"],
"input": {...},
"label": "ProcessAccount",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'DemoAccount1')].id}}/process"
},
{
"continueOnFailure": "true",
"dependsOn": [ "ProcessAccount"],
"input": { ... },
"label": "LocationResults",
"operation": "/v2/exports"
}
]
}
For a complete example of an end-to-end underwriting workflow processes, see Cat Modeling with User-defined Workflows.
The name, and operations parameters are required.
| Attribute | Type | Description |
|---|---|---|
name | String | Unique name of workflow. |
settings | Object | Boolean flags to enable workflow optimization.- If disable-underwriter-reports is true, no Underwriter IQ reports are generated. Only supported for Underwrite IQ principals.- If combine-batch-edit-and-geohaz is true, the workflow supports optimization. |
operations | Array | Two or more Operation objects. Each object defines a batch, geocode, group, or process operation identified by keyword or endpoint. |
Operation object
The Operation object defines an operation --a discreet job-- within the operations array.
An operation may be defined by its continuedOnFailure, dependsOn, input, label, and operation attributes. The input, label, and operation attributes are required.
| Attribute | Type | Description |
|---|---|---|
continuedOnFailure | Boolean | If true, workflow continues if this operation fails. By default, false. |
dependsOn | Array | Operations (by label value) to be run before this operation. |
input | Object | Operation definition. Valid request for the specified operation value (endpoint). The input object matches the request object of the specified endpoint. |
label | String | Unique ID of the operation within the workflow. Enables sequencing of operations within workflows and referencing of operation outputs using operation path variables. |
operation | String | Endpoint of an API resource. Supported endpoints: - /v3/exposurebatches- /v1/accounts/{id}/geohaz- /v2/accounts/{id}/geohaz- /v1/portfolios/{id}/geohaz- /v2/portfolios/{id}/geohaz- /v2/portfolios/{id}/process- /v1/portfolios/{id}/process- /v1/accounts/{id}/process- /v2/accounts/{id}/process- /v1/analysis-groups- /v2/analysis-groups- /v2/exportsEndpoints may include operation path variables |
Operation path variables
An operation path variable is a JSON query string that enables an operation to retrieve data from the output of a previous operation in the workflow.
Operation path variables enable you to specify the portfolio or account exposure that is the subject of an operation. Every operation in a workflow is identified by a unique label. The other operations in the workflow may query the output of an earlier operation by referencing that operation's label.
{
"name": "UIQ Demo Template",
"operations": [
{
"continueOnFailure": "true",
"dependsOn": [],
"input": {...},
"label": "BatchAccount",
"operation": "/v3/exposurebatches?datasource=edmName"
},
{
"continueOnFailure": false,
"dependsOn": ["BatchAccount"],
"input": [...],
"label": "GeohazAccount",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'DemoAccount1')].id}}/geohaz?datasource={{EdmName}}"
},
{
"continueOnFailure": true,
"dependsOn": ["GeohazAccount"],
"input": {...},
"label": "ProcessAccount",
"operation": "/v2/accounts/{{$.ExposureBatch.output.accounts.[?(@.label == 'DemoAccount1')].id}}/process"
},
]
}
The {{$..[?(@.label == 'accountLabel1')].id}} variable defines a query for retrieving the output generated by the accountLabel1 operation. During processing, the workflow engine "expands" this query to retrieve the unique ID number for this account using the path (label.output.id). The path variable is a simple JSON query string enclosed in double curly braces.
Workflow optimization
If the combine-batch-edit-and-geohaz parameter is true, consecutive batch and geohaz operations are combined and processed as a single job, which can greatly reduce the runtime of a user-defined workflow.
To enable workflow optimization, the combine-batch-edit-and-geohaz must be true and the geohaz operation must identify the batch operation as its immediate predecessor in that object's dependsOn array. In the current release, one batch operation may be combined with one geohaz operation.
The following example defines a workflow consisting of three operations. During processing the BatchAccount and GeohazAccount operations are combined and processed together as a single job. The ProcessAccount operation is handled separately as a distinct job.
{
"name": "Optimization Example",
"settings": {
"combine-batch-edit-and-geohaz": true
},
"operations": [
{
"continueOnFailure": "false",
"dependsOn": [],
"input": { ... },
"label": "BatchAccount",
"operation": "/v3/exposurebatches?datasource=datasource"
},
{
"continueOnFailure": false,
"dependsOn": ["BatchAccount"],
"input": [ ... ],
"label": "",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'account-label')].id}}/geohaz?datasource=datasource"
},
{
"continueOnFailure": false,
"dependsOn": [ "GeohazAccount"],
"input": { ... },
"label": "ProcessAccount",
"operation": "/v2/accounts/{{$.BatchAccount.output.accounts.[?(@.label == 'account-label')].id}}/process"
}
]
}
Because the batch and geohaz operations are managed as a single job, the output generated by the GeohazAccount operation is encapsulated within the BatchAccount output. Consequently, the ProcessAccount operation specifies a path variable that refers to the BatchAccount operation when it wants retrieve information about the geocoded account.
Permissions
To perform this operation, a principal must be assigned the appropriate role-based permissions:
Underwriter Technical Underwriter Risk Analyst Portfolio Manager Cat Modeler Yes Yes No No No