Overview

The Intelligent Risk Platform manages long-running processes as platform jobs. A platform job is a process that manages, creates, or transforms data resources on the Intelligent Risk Platform.

This includes all catastrophe modelling processes, workflows to geocode locations or look up hazard data, bulk edit operations, and an all processes that import or export exposure or analysis result data.

This page identifies the different types of jobs that can be run on the Intelligent Risk Platform, discusses operations for polling the status of these jobs and retrieving response objects once they are complete, and describes how resource groups are used to allocate and manage tenant resource quotas.

Platform Jobs Types

A platform job is a system-defined task that manages a time-consuming or computationally expensive workflow process.

Many standard Intelligent Risk Platform workflows (e.g. catastrophe modeling, bulk or batch operations, data migration tasks) are managed and processed as platform jobs.

Each Platform API exposes operations for managing different types of platform jobs, i.e. jobs that perform API-specific processes. For example, the Export API provides operations for managing different types of export jobs, e.g. DOWNLOAD_EDM, DOWNLOAD_EXPOSURE_RESOURCE, DOWNLOAD_LOCATION_RESULTS.

For each job type, the table lists the Platform API and the operation or operations that can create jobs of that type:

Some operations can create different types of jobs. For example, the Create Import Job operation may initiate a CEDE_IMPORT, EXPOSURE_BULK_EDIT, MRI_IMPORT, OED_IMPORT, RDM, RDM_DATABRIDGE job depending on parameter values specified. Such operations typically accept a type or jobtype parameter that specifies the job to be submitted.

User-defined workflows

A workflow is a standard and repeatable process that transforms or processes data. A workflow generally consists of multiple subprocesses that are performed in a specific sequence — a pipeline — by which the output of one step is used in the next step of the process.

Intelligent Risk workflows (e.g. cat modeling, data migration) generally comprise multiple API requests that utilize several different API operations.

The Create Batch Job operation enables clients to define and initiate a user-defined workflow jobs consisting of multiple sequenced operations. The user-defined job manages the both the sequencing of operations and the reporting of status of operations and job itself. All job attributes are specified in the request body.

Managing Jobs

Platform APIs expose operations for creating, fetching, and updating different types of platform jobs.

• A Create Job operation creates a platform job that performs a certain task and adds that job to the workflow engine queue for processing.
• A Search Job operation returns a list of jobs submitted using a particular Platform API. These operations typically support the filtering and sorting of platform jobs within a specific API.
• A Get Job operation returns detailed information about a specific task. This operation can be used to poll the status of jobs, debug failed jobs, or to retrieve the output for a completed job.
• An Update Job operation updates the status or priority of a platform job.

Creating Jobs

Most Platform APIs expose one or more operations for creating platform jobs.

In general, these operations do not accept path parameters or query parameters. Most optional and required parameter are specified in the body of the request in JSON format.

Unlike most Platform API operations, all Platform API operations that create platform jobs require that request pass a resource group ID in the x-rms-resource-group-id header parameter.:w

curl --request POST \
     --url https://api-euw1.rms.com/platform/model/v1/jobs \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-rms-resource-group-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
     --data '
{ // Body Paramerters}
'

A header parameter is a parameter passed in an HTTP request header that specifies information about the client making the request or about the requested resource. Platform APIs require that client applications specify the ID number of a resource group in the x-rms-resource-group-id header parameter in every request that creates a model job or non-model job.

The Intelligent Risk Platform manages and tracks all job-related resource quotas via resource groups. The resource group manages and tracks the number of jobs that the tenant runs. It defines the maximum number concurrent of model jobs, the maximum number of concurrent non-model jobs, and the total number of jobs that the tenant may run during the day. For information see Resource Groups.

Workflow Engine Queue

On success, operations that create platform jobs returns a 202 Accepted response and adds a job to the workflow engine queue. The Location response header specifies the job ID as part of a URL that you can use to track the status of the job.

API requests that create platform jobs typically return a 202 Accepted HTTP status code and a URI that enables polling of the job status.

Each Platform API exposes distinct resources for tracking the status of API jobs. Platform jobs have their own namespace but are globally identifiable. For example, An import job is identifiable with its URI: /platform/import/v1/jobs/123 ; And the job 123 is also globally unique (Operations at tenant level is scheduled for future release

Viewing Lists of Jobs

Most Platform APIs expose an operation for returning lists of jobs.

These operations return jobs created and managed using a specific Platform API. For example, the Search Risk Data Jobs operation returns a list of jobs created using Risk Data API operations. There is no operation that supports viewing jobs across Platform APIs.

These operations generally support response filtering and sorting using query string parameters. A filter defines a single expression that defines a property, a condition (a property value), and an operator (e.g. = or LIKE). The filter keyword also supports comparison operators, logical operators, list operators, and identity operators. The same query string supports sorting and pagination of results. To learn more, see Filtering and Pagination

The properties returned depend on the Platform API. In general, the response returns metadata about each job including its ID, status, and progress.

[
  {
    "jobId": "54",
    "userName": "[email protected]",
    "status": "QUEUED",
    "submittedAt": "2024-01-01T00:00:00.000Z",
    "startedAt": "2024-01-01T00:00:00.000Z",
    "endedAt": "2024-01-01T00:00:00.000Z",
    "name": "string",
    "type": "string",
    "progress": 0,
    "priority": "medium",
    "entitlement": "RI-RISKMODELER",
    "resourceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "details": {
      "resources": [
        {
          "uri": "string"
        }
      ],
      "summary": "string"
    },
    "warnings": [
      {
        "message": "string"
      }
    ]
  }
]

The properties returned by a Search Job operation differ by API. In general, a Get Job request will return the following information about a job:

These operation supports response filtering based the value of a subset of properties. Depending on the property, you may use a combination of comparison operators, list operators, and logical operators. To learn more, see Response Filtering.

Search job operation return information only about platform jobs created using that API, e.g. the Search Risk Data Job operation returns information about platform jobs created using Risk Data API operations only. There is no Platform operation that returns a list of all platform jobs across all Platform APIs.

Viewing Job Details

Get Job operations detailed information about a specific job.

For example, the Get Risk Data Job operation returns information about a single job created using Risk Data API operations. The response returns metadata about that job including its ID, status, and progress:

{
  "jobId": "string",
  "userName": "string",
  "status": "QUEUED",
  "submittedAt": "string",
  "startedAt": "string",
  "endedAt": "string",
  "name": "string",
  "type": "string",
  "progress": 0,
  "details": {
    "resources": [
      {
        "uri": "string"
      }
    ],
    "summary": "string"
  },
  "tasks": [
    {
      "taskId": "string",
      "guid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "jobId": "string",
      "status": "QUEUED",
      "submittedAt": "string",
      "createdAt": "string",
      "name": "string",
      "percentComplete": 0,
      "priorTaskGuids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "output": {
        "summary": "string",
        "errors": [
          {
            "message": "string"
          }
        ],
        "log": {
          "additionalProp": "string"
        }
      }
    }
  ]
}

The properties returned by a Search Job operation differ by API.

Polling Jobs

Every Platform API that exposes an operation for initiating a job, also supports operations for "polling" the status of that job.

Polling is a technique that enables applications to make non-blocking requests that is useful when the application needs to use services that require long-running processes, such as Intelligent Risk Platform jobs.

API requests that create platform jobs typically return a 202 Accepted HTTP status code and a URI that enables polling of the job status.

Each Platform API exposes distinct resources for tracking the status of API jobs. Platform jobs have their own namespace but are globally identifiable. For example, An import job is identifiable with its URI: /platform/import/v1/jobs/123 ; And the job 123 is also globally unique (Operations at tenant level is scheduled for future release

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

Changing Job Priority

Every job in a job queue is assigned a priority that indicates its relevant importance compared to the other jobs in that job queue. One of Very High, High, Medium, Low, Very Low. In general, a job with a lower priority (e.g. Very Low) is run later than a job with a higher priority (e.g. Very High).

Every job added to a job queue is assigned the same priorty: Medium. This means that the Scheduler does not take the priority of a job into account when it schedules a job for processing. In general, jobs are processed in the order submitted using a best-effort, FIFO policy. The Scheduler will also take the tenant's resource quota into account.

Most Platform APIs offer an operation for updating the priority jobs in the workflow queue. For example, the Update Risk Data Job operation supports updating the priority of jobs.

Principals assigned to a group with the Portfolio Manager or Cat Modeler role can change the priority of jobs.

Canceling Jobs

A job can be canceled if its current status is QUEUED. Once canceled, the job progresses through the following job statuses in order: CANCEL_REQUESTED, CANCELING, CANCELED.

A subset of Risk Data API jobs can be canceled if it has a PENDING or RUNNING job status: ALM, BATCH, CLIMATE_CHANGE, CONVERT_RESULT_CURRENCY, DLM, HD, DOWNLOAD_RDM.

A canceled job does not count against the tenant’s entitlement resource quota.

Most Platform APIs expose an operation that supports the cancelation of a job in the workflow queue. For example, the Update Risk Data Job operation supports canceling a variety of risk data jobs.

Retrieving Job Data

On job completion, the Get Job operation retrieves information about the resources created, updated, or deleted by the job. This data may be returned in the response package of the Get Job request or downloaded from a URL provided in the body of that response package.

The typical response object of a FINISHED job returns metadata about the job (e.g. the name, status, and type of the job), logging of job subprocesses and tasks (e.g. jobs, messages), and updated resources (e.g. the output object):

{
  "userName": "[email protected]",
  "status": "FINISHED",
  "name": "ExBatchEdit",
  "type": "EXPOSURE_BATCH_EDIT",
  "progress": 100,
  "priority": "medium",
  "entitlement": "RI-RISKMODELER",
  "resourceGroupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "jobs": [],
  "summary": {},
  "output": {},
  "messages": []
}

The data returned in the response object depends on the type of the job.

jobs array

The Bulk Edit operation returns a jobs array that logs the status of job subtasks and processes.

For each subtask, the response returns the task ID, status, name,

{
  "userName": "[email protected]",
  "status": "FINISHED",
  ...,
  "jobs": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "taskId": 1,
      "status": "Succeeded",
      "name": "EXPOSURE_BATCH_EDIT",
      "percentComplete": 100,
      "continueOnFailure": false
    }
  ],
  "summary": {...},
  "output": {...},
  "messages": []
}

The tasks array is returned by operations that initiate BULK_EDIT job, i.e. the Risk Data API. These operations define user-defined workflows.

Every batch job may consist of multiple tasks that are linked together into a user-defined workflow. These tasks are performed in order according to rules specified in request body of the batch job. Each task in the user-defined workflow is identified by a system-defined task ID.

The jobs array contains information about the tasks within the job.

summary object

A Get Job response may return a summary object.

The summary object contains summary data about the resources that were created in the job.

For example, the Bulk Edit operation returns a summary object that contains summary statistics for each type of resource edited in the job.

{
  "userName": "[email protected]",
  "status": "FINISHED",
  ...,
  "jobs": [...],
  "summary": {
    "Treaties": "Inserted: 0, Updated: 0, Deleted: 0",
    "Policies": "Inserted: 100, Updated: 0, Deleted: 0",
    "databaseName": "xxxxxxxxxxxxxxxxxxxxxxx",
    "InputType": "Plain JSON",
    "stepPolicies": "Inserted: 0, Updated: 0, Deleted: 0",
    "Locations": "Inserted: 1000, Updated: 0, Deleted: 0",
    "Portfolios": "Inserted: 10, Updated: 0, Deleted: 0",
    "Accounts": "Inserted: 100, Updated: 0, Deleted: 0"
  },
  "output": {...},
  "messages": []
}

output object

A Get Job response may return an output object.

The output object contains the data returned by the job. In this case, the resources inserted, updated, or deleted by the job, or -- depending on the size of the response-- a link from which this resource data can be downloaded.

For example, the Bulk Edit operation returns standard job metadata (e.g. the name, type, and status), a jobs array, summary object, and an output object, which contains the data returned by the job.

{
  "userName": "[email protected]",
  "status": "FINISHED",
  ...,
  "jobs": [...],
  "summary": {...},
  "output": {
    "downloadLink": "https://rms-tenants-xxx-xxx.amazonaws.com/xxx/import/EXPOSURE_BATCH_EDIT/outputs/xxx",
    "stepPolicies": [...],
    "treaties": [...],
    "portfolios": [...],
    "policies": [...],
    "locations": [...],
    "accounts": [...],
    "referDownloadLink": true
  },
  "messages": []
}