Optimistic Locking

Overview

This article describes how to interact with Jamf Pro API endpoints that utilize optimistic locking. Please see the chart below to identify endpoint and operation combinations that require the use of optimistic locking as well as the version in which the endpoint was introduced.

Endpoint	Operation	Version Introduced	Field Name
/v1/mobile-device-prestages	PUT	10.13.0	versionLock
/v1/mobile-device-prestages	POST	10.13.0	versionLock
/v1/mobile-device-prestages/{id}/scope	PUT	10.14.0	versionLock
/v1/mobile-device-prestages/{id}/scope	POST	10.14.0	versionLock
/v1/mobile-device-prestages/{id}/scope	DELETE	10.14.0	versionLock
/v1/computer-prestages	POST	10.14.0	versionLock
/v1/computer-prestages/{id}	PUT	10.14.0	versionLock
/v1/computer-prestages/{id}/scope	PUT	10.14.0	versionLock
/v1/computer-prestages/{id}/scope	POST	10.14.0	versionLock
/v1/computer-prestages/{id}/scope	DELETE	10.14.0	versionLock
/v2/mobile-device-prestages	PUT	10.25.0	versionLock
/v2/mobile-device-prestages	POST	10.25.0	versionLock
/v2/mobile-device-prestages/{id}/scope	PUT	10.25.0	versionLock
/v2/mobile-device-prestages/{id}/scope	POST	10.25.0	versionLock
/v2/mobile-device-prestages/{id}/scope	DELETE	10.25.0	versionLock
/v2/computer-prestages	POST	10.25.0	versionLock
/v2/computer-prestages/{id}	PUT	10.25.0	versionLock
/v2/computer-prestages/{id}/scope	PUT	10.25.0	versionLock
/v3/computer-prestages	GET	10.47.0	versionLock
/v3/computer-prestages	POST	10.47.0	versionLock
/v3/computer-prestages/{id}	GET	10.47.0	versionLock
/v3/computer-prestages/{id}	PUT	10.47.0	versionLock
/v3/computer-prestages/{id}	DELETE	10.47.0	versionLock

Purpose

Optimistic locking is a mechanism that prevents concurrent operations from taking place on a given resource. Jamf Pro does this to safeguard resources and workflows that are sensitive to frequent updates, ensuring that one update has completed before any additional requests can be processed.

How To

In order to interact with one of the above endpoints, which requires the use of optimistic locking, the client consuming the API will first need to perform a GET to the same endpoint. That response will include the "Field Name" described in the table above (e.g. versionLock). To successfully update a resource your request body must include the current value of the "Field Name". If a modification has occurred between the time you performed the GET and your attempted update, the value you supply will be invalid and an error will be returned indicating that the resource you're attempting to update has been updated by another process.

Creating new resources via the POST operation also requires that a value of 0 be passed to "Field Name".

Examples

Below is an example of a request body with the minimal fields required to successfully POST a new mobile device prestage, as of Jamf Pro v10.25.0, using the endpoint: /v2/mobile-device-prestages

{
  "enrollmentSiteId": -1,
  "displayName": "Example Device Prestage",
  "supportPhoneNumber": "",
  "supportEmailAddress": "",
  "department": "",
  "authenticationPrompt": "",
  "profileUUID": "",
  "deviceEnrollmentProgramInstanceId": 1,
  "versionLock": 0,
  "siteId": -1,
  "locationInformation": {
    "username": "",
    "realname": "",
    "phone": "",
    "email": "",
    "room": "",
    "position": "",
    "departmentId": -1,
    "buildingId": -1,
    "id": -1,
    "versionLock": 0
  },
  "purchasingInformation": {
    "id": -1,
    "appleCareId": "",
    "poNumber": "",
    "vendor": "",
    "purchasePrice": "",
    "lifeExpectancy": 0,
    "purchasingAccount": "",
    "purchasingContact": "",
    "leaseDate": "1970-01-01",
    "poDate": "1970-01-01",
    "warrantyDate": "1970-01-01",
    "versionLock": 0,
    "leased": false,
    "purchased": true
  },
  "names": {
    "assignNamesUsing": "Default Names",
    "prestageDeviceNames": [],
    "deviceNamePrefix": "",
    "deviceNameSuffix": "",
    "singleDeviceName": "",
    "manageNames": false,
    "deviceNamingConfigured": false
  },
  "supervised": true,
  "multiUser": false,
  "allowPairing": true,
  "configureDeviceBeforeSetupAssistant": false,
  "autoAdvanceSetup": false,
  "mandatory": true,
  "mdmRemovable": true,
  "requireAuthentication": false,
  "keepExistingSiteMembership": false,
  "keepExistingLocationInformation": false,
  "maximumSharedAccounts": 10,
  "preventActivationLock": false,
  "enableDeviceBasedActivationLock": false,
  "defaultPrestage": false,
  "sendTimezone": true,
  "timezone": "America/Chicago"
}

Below is an example of a minimal request body to update scope of a mobile device prestage via PUT or POST to /v2/mobile-device-prestages/{id}/scope

{
    "serialNumbers": [
        "SERIALNUMBER",
        "SERIALNUMBER2"
    ],
    "versionLock": "1"
}

Below is an example of a request body with the minimal fields required to successfully POST a new computer prestage, as of Jamf Pro v10.25.0, using the endpoint: /v2/computer-prestages

{
  "displayName": "Example Computer Prestage",
  "mandatory": false,
  "mdmRemovable": true,
  "supportPhoneNumber": "",
  "supportEmailAddress": "",
  "department": "",
  "defaultPrestage": false,
  "enrollmentSiteId": -1,
  "keepExistingSiteMembership": true,
  "keepExistingLocationInformation": true,
  "requireAuthentication": false,
  "authenticationPrompt": "",
  "preventActivationLock": true,
  "enableDeviceBasedActivationLock": false,
  "deviceEnrollmentProgramInstanceId": 1,
  "autoAdvanceSetup": true,
  "locationInformation": {
    "username": "",
    "realname": "",
    "phone": "",
    "email": "",
    "room": "",
    "position": "",
    "departmentId": -1,
    "buildingId": -1,
    "id": -1,
    "versionLock": 1
  },
  "purchasingInformation": {
    "id": -1,
    "leased": true,
    "purchased": true,
    "appleCareId": "",
    "poNumber": "",
    "vendor": "",
    "purchasePrice": "",
    "lifeExpectancy": 0,
    "purchasingAccount": "",
    "purchasingContact": "",
    "leaseDate": "2019-01-01",
    "poDate": "2019-01-01",
    "warrantyDate": "2019-01-01",
    "versionLock": 1
  },
  "installProfilesDuringSetup": true
}

Below is an example of a minimal request body to update scope of a computer prestage via PUT or POST to /v2/computer-prestages/{id}/scope

{
  "serialNumbers": [
    "SERIALNUMBER",
    "SERIALNUMBER2"
  ],
  "versionLock": 1
}