Risk Modeler, March 2022

Changes implemented in the Risk Modeler Account, Portfolio, and Workflow APIs.

Accounts and portfolios

The updated Analyze account service (POST /[v2]/account/process) and Analyze portfolio Analyze portfolio service (POST /[v2]/portfolio/process) now enable clients to define global analysis settings for DLM analyses when they initiate an account or portfolio analysis workflow job.

Global analysis settings define default parameters for the accounts or portfolios in an ALM or DLM analysis job.

Both services now accept a globalAnalysisSettings object that defines franchiseDeductible, minLossThreshold, treatConstructionOccupancyAsUnknown, and numMaxLossEvent attributes. The workflow engine applies these settings to ALM and DLM analysis jobs:

{
  "id" : 1,
  "exposureType" : ACCOUNT,
  "edm" : "RMS EDM SAMPLE",
  "currency" : {
    "code" : "code",
    "scheme" : "scheme",
    "asOfDate" : "2021-05-05 12:14:13",
    "vintage" : "vintage"
  },
  "modelProfileId" : 1,
  "eventRateSchemeId" : 5,
  "treaties" : null,
  "jobName" : null,
  "outputProfileId" : 2,
  "globalAnalysisSettings" : {
    "franchiseDeductible" : false,
    "minLossThreshold" : 1.0,
    "treatConstructionOccupancyAsUnknown" : true,
    "numMaxLossEvent" : 1
  }
}

Although the globalAnalysisSettings object is not required, all four attributes must be defined if it is included in the request.

  • franchiseDeductible: A boolean that determines the deductible type used for all accounts or portfolios in an analysis. If true, the workflow engine uses site-level, franchise deductibles for the accounts or portfolios analyzed. If false, the workflow engine uses standard deductibles for the accounts or portfolios analyzed.
  • minLossThreshold: A number that specifies the threshold for writing losses to the event loss tables generated during analysis. Loss values beneath the specified threshold are not written to the event loss tables. By default, 1.
  • numMaxLossEvent: An integer (up to 5000) that specifies the maximum number of events to write to the loss tables in maximum credible and maximum historical analyses. By default, 1.
  • treatConstructionOccupancyAsUnknown: A boolean value that determines how the workflow engine processes the account or portfolio when it does not recognize the buildingClassScheme or occupanyTypeScheme specified in a location’s buildingAttribute or esbBuildingAttribute. If true, Intelligent Risk Platform assumes an esbBuildingClass value of RMS 0 or esbOccupancyType value of ATC 0. If false, the workflow engine does not analyze locations with unrecognized buildingClassScheme or occupanyTypeScheme values.

Workflows

Start user-defined workflow

The Process user-defined workflow service (POST /v1/workflows/) enables clients to define and initiate a user-defined workflows consisting of multiple sequenced operations. The user-defined workflow manages the both the sequencing of operations and the reporting of status of operations and workflow itself. All workflow job attributes are specified in the request body.

This service supports both account-level or portfolio-level workflows, as defined by the type attribute. The accountWorkflow job type supports two operations: geohaz, and process. The portfolioWorkflow job type supports three operations: geohaz, group, and process.

  • The geohaz operation geohazards the account or portfolio. For accountWorkflow jobs, the operation initiates an account-level GEOHAZ job. For details see Geohazard account (/v2/accounts/{accontId}/geohaz). For portfolioWorkflow jobs, the operation initiates a portfolio-level GEOHAZ job. For details see, (Geohazard portfolio /v2/portfolios/{PortfolioId}/geohaz).
  • The group operation creates an analysis group for portfolio analysis results. For details, see Create analysis group service (/v2/analysis-groups).
  • The process operation analyzes the account or portfolio. For accountWorkflow jobs, the operation analyzes the account. For details, see Analyze account (/v2/accounts/{accoutId}/process). For portfolioWorkflow jobs, the operation analyzes the portfolio. For details, see Analyze portfolio (/v2/portfolios/{id}/process).

The request body specifies a unique name for the workflow job, its type (AccountWorkflow or PortfolioWorkflow), and an array of operations that define the jobs that comprise the workflow :

{
  "type": "PortfolioWorkflow",
  "name": "Sample User Defined Workflow",
  "operations": [{
    "label": "Geohaz1_Job",
    "operation": "geohaz",
    "dependsOn": [],
    "input": { 
      "id":"5", # portfolio ID
      "datasource":"EDM_NAME",
      "layers":[
        {
          "name": "geocode",
          "type": "geocode",
          "engineType": "RL",
          "version": "18.1",
          "layerOptions": {
            "skipPrevGeocoded": false,
            "aggregateTriggerEnabled": "false",
            "geoLicenseType": "0"
            }
         },
         {
            "name": "earthquake",
            "type": "hazard",
            "engineType": "RL",
            "version": "18.1",
            "layerOptions": {
              "skipPrevHazard": false,
              "overrideUserDef": false
            }
         }
      ]
    }
  },
  {
    "label": "Dlm1",
    "exposureType": "portfolio",
    "operation": "process",
    "dependsOn": ["Geohaz1_Job"],
    "input": {
      "id": 5,                
      "edm": "EDM_NAME",
      "currency": {
       "code": "USD",
       "scheme": "RMS",
       "vintage": "RL18",
       "asOfDate": "2020-03-01"
      },
      "modelProfileId": 105,
      "outputProfileId": 1,
      "eventRateSchemeId": 189,
      "treaties": [],
      "treatiesName": [],
      "jobName": "test-User-Defined-Workflow",
      "globalAnalysisSettings": {
        "franchiseDeductible": false,
        "minLossThreshold": "1.00",
        "treatConstructionOccupancyAsUnknown": true,
        "numMaxLossEvent": 1
      }
    }
  }]
}
 

Each operation is identified by four attributes: label, operation, dependsOn, and input:

  • The label attribute uniquely identifies the operation within the workflow. Operations are identified by label value in the in the dependsOn array.
  • The operation attribute identifies the operation type. Account workflow jobs support geohaz and process operations. Portfolio workflow jobs support geohaz, group, and process operations.
  • The dependsOn attribute specifies (by label value) an array of operations to be run before the current operation. Using the dependsOn attribute you can specify the order that operations are executed within a user-defined workflow job. For example, executing a geohaz operation before a process operation, and one or more process operations before a group operation.
  • The input attribute specifies operation-type specific data needed to perform the specified operation. The content of the input attribute corresponds to the content of the Geohazard account /Geohazard portfolio, Create analysis group , or Analyze account / Analyze portfolio services depending on the operation.

Get workflows

The Get workflow or operation Get service (GET /v1/workflows/{requestId}?parent={workflowId}) uses a parent query parameter to enable clients to retrieve an operation within a specified workflow job. Every operation is identified by a unique requestId.

If a workflowId is specified as a query parameter, the requestId 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": []
}