Using the Asta Vision API to lock and unlock programmes
Before using the Asta Vision API to carry out read and write actions on Asta Powerproject data - on the latest version of a programme - you should use the API to temporarily lock the latest version. This is to ensure that the data is not updated by any other users - either using Asta Powerproject or via the API - while your actions are being carried out. For 'POST' and 'PATCH' operations that relate to Asta Powerproject data, locking the data in this way is required.
Once you have locked a programme, it is given a state of 'Locked to API'. This state is applied to the programme until the programme is unlocked.
Once you have carried out an action on the Asta Powerproject data using the Asta Vision API, you should unlock the programme.
If for any reason it is not possible to unlock a programme using the Asta Vision API, a user to whom the 'Clear API Lock' security rule has been applied can unlock the programme manually.
Using the Asta Vision API to lock the latest version of a programme
To lock the latest version of a programme for editing using the Asta Vision API, you must supply an API access key that specifies a user to which the 'Check In/Out Programme' security rule has been assigned as a header.
To lock the latest version of a programme using the Asta Vision API, use the following 'lock' request:
/programmes/<programme id>/data/lock
Where <programme id> is replaced by the unique identifier of the programme you want to lock. The request must include an API access key that specifies a user to which the 'Check In/Out Programme' security rule has been assigned as a header.
The 'lock' request returns a response that includes a 'lock key'. The response is as follows:
{
"lockKey" : "<programme lock key string>"
}
Where <programme lock key string> is replaced by the lock key that was returned by the 'lock' request.
Using a lock key to access a programme's data while it is locked
In order to read or write to a programme's data using the Asta Vision API while the programme is locked, you must supply the lock key in the header of any API requests, as follows:
X-LockKey: <programme lock key string>
Where <programme lock key string> is replaced by the lock key that was returned by the 'lock' request.
Using the Asta Vision API to unlock the latest version of a programme
To unlock the latest version of a programme that had previously been locked using the Asta Vision API, you must POST a request to the unlock URI:
/programmes/<programme id>/data/unlock
Where <programme id> is replaced by the unique identifier of the programme you want to unlock.
The body of the 'unlock' request must include the lock key and must specify whether a new version of the programme that incorporates your changes should be created when the programme is unlocked, and can optionally include additional parameters, in the following format:
{
“lockKey” : “<programme lock key string>”
“saveChanges” : “<true or false, should a new version be created>”
“versionName” : “<optional new version name>”
“versionDescriptions : “<optional new version description>”
“progressDate : “<optional new version progress date>”
“classificationValue : “<optional new version classification id>”
}
Where:
- <programme lock key string> is replaced by the lock key that was returned by the 'lock' request.
- <true or false, should a new version be created> is replaced by "true" if you want to create a new version of the programme that incorporates your changes when the programme is unlocked; or by "false" if you do not want to create a new version of the programme when unlocking it, thereby discarding any changes that may have been made. Replace this with "false" if you have read, rather than edited, the programme's data while it was unlocked.
- <optional new version name> is replaced by the name that should be applied to the new version that you want to create when the programme is unlocked. Omit this parameter if you are not creating a new version.
- <optional new version description> is replaced by the description that should be applied to the new version that you want to create when the programme is unlocked. Omit this parameter if you are not creating a new version.
- <optional new version progress date> is replaced by the progress date that should be applied to the new version that you want to create when the programme is unlocked. Omit this parameter if you are not creating a new version.
- <optional new version classification id> is replaced by the ID of the revision classification that should be applied to the new version that you want to create when the programme is unlocked. Omit this parameter if you are not creating a new version.
Unlocking a programme manually
If for any reason it is not possible to unlock a programme using the Asta Vision API, a user to whom the 'Clear API Lock' security rule has been applied can unlock the programme manually. To do this:
- Click Projects. The Projects page appears.
- Click the name of the programme that you want to unlock - or the name of the programme's project. The Project page appears, displaying details of the project and its programmes.
- If the project has more than one programme type, click the appropriate programme type hyperlink at the top of the page to view details of the programme that you want to unlock:
If the project has only one programme type, omit this step. - If the programme is currently locked by the Asta Vision API, a 'Clear API Lock' workflow action is displayed against it. Click this workflow action to unlock the programme and make it editable again.
Introduction to the Asta Vision API
Using the API Portal to learn about and construct API requests