Optimistic Locking
Learn about optimistic locking and what endpoints require the use of this feature.
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
}
Updated 9 months ago