Multi-version quoting

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.

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"
            }
        },
        . . .
    }
}

By default, the initial job and first version are the same, having the same ID value, and this version is selected. Subsequent versions are unselected 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 an unselected state.

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