Multi-version quoting

Multi-version quoting is a PolicyCenter feature that is available on submission, policy change, renewal, and rewrite policy transactions. Within a single policy transaction, multiple quotes can be generated and compared. The Job API supports this functionality. For details on multi-version quoting and other policy transactions in PolicyCenter, see the Application Guide.

Multi-version quoting is supported through the following Job API endpoints:

  • /job/v1/jobs/{jobId}/versions
  • /job/v1/jobs/{jobId}/versions/{versionId}
  • /job/v1/jobs/{jobId}/change-version
  • /job/v1/jobs/{selectedJobId}?jobVersion={unselectedJobId}

Multi-version quoting and side-by-side quoting

Side-by-side quoting is a feature of the PolicyCenter user interface in which multiple quotes for the same submission are shown next to each other at the same time. You can use the multi-version quoting endpoints to generate a similar user interface presentation in a third-party application. The caller application needs to make multiple calls to retrieve the quote of each version. This information can then be presented at the same time in whatever manner suits the caller application.

Job version properties

By default, a job has one version from the moment it is created, and that version is in selected state. To access the job versions, callers can submit a GET request to the /job/v1/jobs/{jobId}/versions collection.

The following code block shows the response payload of a GET request to the /versions collection of a newly created job, which contains one version:

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "id": "pc:401",
                "name": "Version #1",
                "number": 1,
                "selected": true,
                "status": {
                    "code": "Draft",
                    "name": "Draft"
                }
            },
            . . .
        }
    ],
    . . .
}

The attributes field contains the following properties:

  • id : The ID value of the version. The first version of a job will have the same ID value as the job itself.
  • name : A human-readable string that can be used to identify the job version.
  • number : The 1-based index number of the version in the versions collection. The property is syntactic sugar, providing a handle that applications can use when iterating over a versions array.
  • selected : A Boolean value indicating the selected state of the version.
  • status : A typekey value indicating the job status. Jobs are in Draft status from time of creation, or in Quoted status once a quote has been generated.

Other than name, these properties are read-only values.

Creating a new job version

A caller can create a new version of a job by submitting a POST request to the /job/v1/jobs/{jobId}/versions endpoint. At minimum, the request payload must contain data and attributes properties, and the latter can be empty:

{
  "data": {
    "attributes": { }
  }
}

Optionally, the caller can provide a name for the version:

{
  "data": {
    "attributes": {
        "name": "My new version"
     }
  }
}

On creation, the new job version is in Draft status, it is not selected, and the version number is incremented by one. The ID value is specific to the version.

{
    "data": {
        "attributes": {
            "id": "pc:402",
            "name": "My new version",
            "number": 2,
            "selected": false,
            "status": {
                "code": "Draft",
                "name": "Draft"
            }
        },
        . . .
    }
}

Selecting a job version

By default, the initial job and first version are the same, having the same ID value, and this version is selected. Subsequent versions are deselected by default.

A caller can select a job version by submitting a POST request to the /job/v1/jobs/{jobId}/change-version endpoint. The request payload must specify the version to be selected:

{
  "data": {
    "attributes": {
      "selectedVersion": {
        "id": "pc:402"
      }
    }
  }
}

In the payload above, the selectedVersion.id value is set to the ID value of the job version that was created in the previous section. This job version will now be selected, and the all other job versions will be in a deselected state.

Working with job versions

A job version that is selected and in Draft status can be modified or quoted through the /job/v1/jobs/{selectedJobId} endpoints.

Alternatively, a caller can modify or quote an deselected job version that is in Draft status by applying the jobVersion query parameter to the request. These calls have the following patterns:

  • /job/v1/jobs/{selectedJobId}?jobVersion={unselectedJobId}
  • /job/v1/jobs/{selectedJobId}/{businessAction}?jobVersion={unselectedJobId}

Typically, each version is modified until considered done and then quoted. The quoted versions can then be offered for side-by-side comparison. To further modify a quoted version, a caller can apply the /make-draft business action to that version, make the modification, and then re-quote.