Workflows

Understand the RMS workflow engine and workflow jobs.

Overview

A workflow is a standard and repeatable process that manages, transforms, or writes data. Such workflows may consist of multiple subprocesses that are performed in a specific sequence —in a pipeline— by which the output of one step is used in the next step of the process. Such workflows tend to be rather long-running (time-consuming) and thereby pose a problem for RESTful APIs as long-running processes can be blocking.

Workflow job responses

In the Risk Modeler and Data Bridge APIs, long-running processes are managed as workflow jobs that are scheduled and processed by a workflow engine. These APIs return a 202 Accepted response code that enables the workflow engine to manage workflow jobs asynchronously and accept requests for other processes without requiring that connections to persist until the process is completed.

Most requests require little time to complete; the API can immediately return a 200 OK response code that indicates to the client that its request was successful. But in some cases, the client may make a request that initiates a long-running and time-consuming process, e.g. the creation of the core objects, data migration, the running reports, and risk analysis. In such cases, the API adds a workflow job to the workflow engine queue and returns a 202 Accepted response code to the client.

The 202 Accepted response code indicates that a request has been accepted for processing, that the API has added a workflow job to workflow engine queue, and provides the client with a means of tracking the status of the workflow job. The platform does not notify the client when the workflow job is complete. Rather, operations that return the workflowId of the job enabling the client to track the progress of the workflow job.

On submission, an operation that initiates a workflow job returns a 202 Accepted response status code and a URL in the Location response header that specifies ID number of the workflow job.

The Location header of the response returns information about the job including its type, ID, and a URL for retrieving information about the status of the job.

202 ACCEPTED
Location: https://api-euw1.rms-npe.com/riskmodeler/v1/workflows/9050766 

The Location header returns a URL that represents the endpoint Get Workflow or Operation, which accepts a workflowId as a path parameter.

Standard workflows

A standard workflow is a system-defined process that the Intelligent Risk Platform manages as a workflow job on the workflow engine.

The Risk Modeler and Data Bridge APIs expose operations that enable tenants define and initiate workflow jobs. These processes are typically time-consuming and expensive and include creation of the core objects, running reports, or risk analysis.

The table lists workflow job types and the Risk Modeler API operations that may be used to initiate those jobs:

Workflow Job TypeOperations
ALMv1 Analyze aggregate portfolio, v2 Analyze aggregate portfolio
ALM_IMPORTImport exposures from file
ANALYTICS_JOB
BULK_EDITv1 Update exposure
CLIMATE_CHANGEv1 Analyze climate change , v2 Analyze climate change
CONVERT_ACCOUNT_CURRENCYv1 Convert currency by account, v2 Convert currency by account
CONVERT_AGGREGATE_PORTFOLIO_CURRENCYConvert currency by aggregate portfolio
CONVERT_CURRENCY_LOSS_POSTPROCESSORConvert currency by result
CONVERT_EVENT_RATE_LOSSv1 Convert event rates and losses, v2 Convert event rates and losses
CONVERT_PORTFOLIO_CURRENCY v1 Convert currency by portfolio, v2 Convert currency by portfolio
CONVERT_RESULT_CURRENCYv1 Convert currency by result, v2 Convert currency by result
CONVERT_TREATY_CURRENCYConvert currency by treaty
COPY_ACCOUNTv1 Copy account, v2 Copy account
COPY_AGGREGATE_PORTFOLIO v1 Copy aggregate portfolio v2 Copy aggregate portfolio
COPY_PORTFOLIOv1 Copy portfolio v2 Copy portfolio
CREATE_EDMAdminister data source
DATASTORE_OPERATION
DATA_BRIDGE_DATABASE_SYNC
DATA_BRIDGE_NOTIFICATION
DELETE_ACCOUNTv1 Delete account v2 Delete account
DELETE_AGGREGATE_PORTFOLIOv1 Delete aggregate portfolio v2 Delete aggregate portfolio
DELETE_EDMv1 Delete EDM v2 Delete EDM
DELETE_PORTFOLIOv1 Delete portfolio v2 Delete portfolio
DELETE_RDM
DEREGISTER_DATA_BRIDGE_EDM
DETACH_EDM
DLM
DOMAIN_DATA_LOAD
DOWNLOAD_DETACH_EDM
DOWNLOAD_EDM
DOWNLOAD_LOCATION_RESULTS
DOWNLOAD_RDM
DOWNLOAD_RESULTS
EDM2EDM
GEOCODING
GEOHAZv1 Geohazard account, v2 Geohazard account, v1 Geohazard portfolio, v2 Geohazard portfolio
GROUPING
HAZARD
HD
HD_ALM
HD_ALM_GROUPING
HD_ENGINE
HD_GROUPING
HD_LOSS_POSTPROCESSOR
HD_TO_RDM
IMPORT
IMPORT_RDM
LOSS_POSTPROCESSOR_ENGINE
MAP_PERSPECTIVEv1 Convert financial perspectives , v2 Convert financial perspectives
MARGINAL_IMPACTv1 Calculate marginal impact report , v2 Calculate marginal impact report
MRI_EXPORT
MRI_IMPORTImport exposures from file
PATE
PREPARE_EXPOSURE
REGISTER_DATA_BRIDGE_EDMRegister EDMs with Risk Modeler
REPORT_GENERATIONv1 Generate summary report by account, v2 Generate summary report by account, Generate summary report, v1 Generate summary report by portfolio, v2 Generate summary report by portfolio
RERUN_EPv1 Rerun EP analysis , v2 Rerun EP analysis
SIMULATE_LOSSESv1 Simulate PLT analysis , v2 Simulate PLT analysis
UPDATE_RESULTS_COUNT
RENAME_ANALYSISv1 Rename result, v2 Rename result
UPLOAD_EDMUpload EDM
UPLOAD_RDMUpload RDM

📷

NOTE

  • Some workflow job types may be initiated by multiple operations. For example, v1 and v2 of the Analyze Climate Change operation both initiate a CLIMATE_CHANGE job type.
  • Some operations enable you to initiate multiple types of workflow jobs. For example, the Import Exposures from File operation may initiate either an ALM_IMPORT or MRI_IMPORT job depending on the values specified in the request body.

A Get Workflow or Operation request returns the name, workflow job type, status, and other information about a specific job submitted to the Intelligent Risk Platform.

Custom workflows

A custom workflow is a user-defined workflow that defines a series subprocesses called operations that are processed in order.

The Process custom workflow operation enables you to submit a custom workflow job consisting of multiple operations to the workflow engine for processing.

Custom workflows enable you to define the operations and their sequence with the job. Four types of operations are supported: geohaz, group, process, and batch. Each operation in the workflow is submitted to workflow engine in sequence enabling you to create, geohazard, and process an exposure in a single workflow job. The user-defined workflow manages the both the sequencing of operations within the workflow job and the reporting of operation and workflow status.

Polling workflow job and operation statuses

The Get workflow or operation operation enables you to retrieve information about workflow jobs or operations including the status of the workflow. The operation returns a 202 Accepted response and the ID number of the workflow job.

  • A workflow job is a process that runs on the workflow engine.
  • An operation is a subprocess that runs within a user-defined workflow. Account workflow jobs support geohaz and process operations. Portfolio workflow jobs support geohaz, group, and process operations.

To retrieve information about a workflow job, specify the workflow ID in the endpoint:

curl --request GET \
     --url 'https://{host}/riskmodeler/v1/workflows/5673' \
     --header 'Accept: application/json' \
     --header 'Authorization: XXXXXXXXXX'

To retrieve information about an operation, specify the ID of an operation as a path parameter and the ID of the parent workflow using the parent query parameter:

curl --request GET \
     --url 'https://{host}/riskmodeler/v1/workflows/5673?parent=89993' \
     --header 'Accept: application/json' \
     --header 'Authorization: XXXXXXXXXX'

If a parent workflowId is specified as a query parameter, the id path parameter identifies the requestId of an operation within that workflow.

The response body returns information about the operation in the jobs array:

{
  "userName": "[email protected]",
  "status": "FINISHED",
  "name": "Create Group: New Group from Batch",
  "type": "GROUPING",
  "jobs": [
     {
     "id": "caece2d3-0854-402c-9428-336be01f54c0",
     "status": "Succeeded",
     "name": "GROUPING",
     "input": {
     },
     "output": {
       "groupName": "New Group from Batch",
       "groupDescription": "",
       "analysisId": "68977",
       "currency": "USD",
       "regionPerils": "NAEQ"
       },
       "percentComplete": 100
     }
  ],
  "summary": {
    "analysisId": "68977",
    "groupName": "New Group from Batch",
    "groupDescription": "",
    "regionPerils": "NAEQ",
    "currency": "USD"
  },
  "progress": 100,
  "messages": []
}

The response returns information that will enable you to assess the current status of the specified workflow job or operation.

  • The userName attribute identifies the name of principal, the user or API key that submitted the request.
  • The status attribute indicates the current status of the workflow job. One of QUEUED, RUNNING, FINISHED, FAILED, CANCELLED, PENDING, CANCELLING, or CANCEL_REQUESTED.
  • The name attribute identifies the name of the workflow job. If the workflow job is a standard workflow, the name is determined by the type and the parameters specified in the request. If the workflow job is a custom workflow, the name is specified in the request.
  • The type attribute identifies the workflow job type, e.g. GROUPING, MRI_IMPORT.
  • The jobs attribute defines an array of jobs. Each job object consists of an id, status, name, input, output, and percentComplete.
  • The summary attribute is an object that consists of job-specific data.
  • The progress attribute displays the percent of the job that is complete.
  • The messages attribute is an array of messages.

A successful response returns the Workflow object, which provides detailed information about this workflow job including the submitTime, startTime, type, job details, and its status:

  • QUEUED
  • RUNNING
  • FINISHED
  • FAILED
  • CANCELLED
  • PENDING
  • CANCELLING
  • CANCEL_REQUESTED