Overview

A job is a long-running process that consumes significant system resources, such as modeling a location, importing exposure data, or updating portfolios in bulk.

The Platform APIs are a collection of APIs that support catastrophe modeling and other workflows on the Intelligent Risk Platform. Each Platform API exposes operations for creating, fetching, and updating different types of platform jobs.

A Platform API will generally support four operations for managing jobs within an API: Create Job, Search Jobs, Get Job, and Update Job.

The following sections describe in general terms how to use Platform API operations to manage the lifecycle of platform jobs.

Creating Jobs

A Create Job operation is an operation that defines and initiates a job on the Intelligent Risk Platform.

In general, every Create Job operation is identified by a name that consists of three parts: the word create, the name of API, and the word job. For example, the Create Model Job is a Model Job API operation that creates different types of catastrophe modeling jobs, e.g. ALM, DLM, and HD jobs.

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}
'

Most Create Job operations require that the client specify the ID number of a resource group in a mandatory x-rms-resource-group-id header parameter. 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.

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 primary jobs, the maximum number of concurrent secondary jobs, and the total number of jobs that the tenant may run during the day. For information see Resource Groups.

A Create Job will return either a 201 Created or 202 Accepted HTTP status code and the URI of a newly created job that has been added to a workflow queue. The client application can use this URI to poll the status of the job during processing. For details, see Polling Jobs

Searching Jobs

Platform APIs support operations that enable tenants to search lists of jobs created using the API. These operations are identified by a name that consists of three parts: the word search, the name of API, and the word jobs, e.g. Search Model Jobs.

In general,Search operations support filtering of response data using query parameters that are appended as query strings to the endpoint of the request.

curl --request GET \
     --url 'https://api-euw1.rms.com/platform/model/v1/jobs?limit=20&offset=0' \
     --header 'accept: application/json'

A filter consists of 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

Search Job operations return high-level information about a list of jobs. For each job, the response may return the jobId, status, type, progress, and other information.

[
  {
    "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": "DLM_model",
    "type": "DLM",
    "progress": 0,
    "priority": "medium",
    "entitlement": "RI-RISKMODELER",
    "resourceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "details": { // details},
    "warnings": [ //warnings]
  },
  {
    "jobId": "55",
    "userName": "[email protected]",
    "status": "FINISHED",
    "submittedAt": "2024-01-01T00:00:00.000Z",
    "startedAt": "2024-01-01T00:00:00.000Z",
    "endedAt": "2024-01-01T00:00:00.000Z",
    "name": "HD_model",
    "type": "HD",
    "progress": 100,
    "priority": "high",
    "entitlement": "RI-RISKMODELER",
    "resourceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "details": { // details},
    "warnings": [ //warnings]
  }
]

A Search Job operation may return different job properties depending on the API. In general, a request will return the following information for each job returned:

Search Jobs by API

The job details returned depend on the operation. In general, the job returned are limited to the jobs created using a specific Platform API. The Search Risk Data Jobs operation return information about risk data jobs only.

Search All Jobs

The Search Tenant Job operation is special in that it returns a list of all jobs initiated by any Platform API. The Search Tenant Jobs operation returns information about all tenant jobs regardless of the Platform API used to create the job.

Uniquely, the Search Tenant Job operation supports the platformOperationType query parameter which supports filtering jobs by operation type. The following platformOperationType values are supported: platform-accumulation, platform-batch, platform-export, platform-geohaz, platform-grouping, platform-import, platform-model, platform-riskdata, platform-rollupo, platform-variation, platfrom-currencyconversion

Getting Jobs

Every Platform API that exposes an operation for initiating a job, also supports operations for "polling" the status of that job. These operations are identified by a name that consists of three parts: the word get, the name of API, and the word job, e.g. Get Model Job.

A Get Job operation is an operation that returns detailed information about a single job. These operations are typically used in polling the status during processing.

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.

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

Responses

The response object returned depends on the API.

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 depend on the API.

Polling Job Status

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

Updating Jobs

Platform APIs support operations for updating the status or priority of a job. These operations are identified by a name that consists of three parts: the word update, the name of API, and the word job, e.g. Update Model Job.

Update Job operations support two primary functions: changing the priority of a job and changing the status of a job.

Platform API operations that support updating the priority and status of jobs.

Changing Job Priority

An Update Job operation can be used to change the priority of a job.

The priority of a job 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). By default, every job added to a job queue is assigned a Medium priority.

This operation enables the client to change the priority of job.

curl --request PATCH \
     --url https://api-euw1.rms.com/platform/riskdata/v1/jobs/578 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "priority": "veryhigh"
}
'

Every job added to a job queue is assigned the same priority: 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.

Cancelling Jobs

An Update Job operation can be used to change the status of a job.

Any 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.

curl --request PATCH \
     --url https://api-euw1.rms.com/platform/riskdata/v1/jobs/jobId \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "CANCELLED"
}
'

In general, a Platform API job can only be cancelled if it has a QUEUED status. 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 cancellation of a job in the workflow queue. For example, the Update Risk Data Job operation supports canceling a variety of risk data jobs.