REST - Lock
The EWLock operation locks, unlocks, or checks the lock status of a record in the specified KB and table.
- Returns: the lock status.
- Supported Content-Type: application/x-www-form-urlencoded
- Accepts a URL with URL-encoded parameters and record data. For more information about general URL conventions, see REST Interface.
Get the Lock Status of a Record
To get the lock status of a record, make an HTTP GET request with the following parameters:
Parameter | Value | Required | Description |
|---|---|---|---|
$table | The logical name of the table | yes | The table identifier |
id | The table entry id | yes | ID of the entry to check the lock status for |
This is an example URL with the standard authentication using username/password. You can also use other types of authentication, such as an OAuth access token or JWT)
https://yourserver.com/ewws/EWLock?$KB=Demo&$login=*username*&$password=*password*&$lang=en &$table=al_as_agreements&id=18
If the request succeeds, the server then returns a JSON answer with the following keys:
Parameter | Value |
|---|---|
id | Entry ID |
table_id | Numeric system identifier of the table |
locked_by | Login of the user who locked the record |
lock_status | The status of the lock. The following types are possible:
|
lock_expires_in_minutes | Expiration time of the lock, in minutes. This is a countdown of how many minutes remain, not the starting value. |
If the request fails, the server then returns a JSON answer with the error code and description:
Parameter | Value |
|---|---|
error | Error code. See error code descriptions below |
error_description | Returns text describing why the request failed |
The following error codes can be transmitted:
Code | Description |
|---|---|
BAD_REQUEST | The request is missing a required parameter. This could be an invalid parameter value, duplicate parameters, etc. |
UNAUTHORIZED | The client is not authorized to request an authorization code using this method |
FORBIDDEN | The resource owner or server denied the request |
CONFLICT | Requested changes will not be applied due to another user's requested changes |
SERVER_ERROR | The server encountered an unexpected condition that prevented it from fulfilling the request |
Here is an example of a response that could be sent to the client:
HTTP/1.1 200 OK {"id":18,"table_id":2788,"locked_by":"admin","lock_status":"LOCKED","lock_expires_in_minutes":25}
Lock a Record
To lock a record, make an HTTP PUT request with the following parameters:
Parameter | Value | Required | Description |
|---|---|---|---|
$table | The logical name of the table | yes | The table identifier |
id | The table entry id | yes | the record ID |
Here is an example request a client might send. The expiration time of the lock is set by value of global variable lock_expiration_time from Setup > System > Manage Global Variables.
PUT /ewws/EWLock HTTP/1.1 Host: yourdomain.com $KB=Demo& id=18
The server then returns a JSON answer with the keys described in the Get the Lock Status of a Record section above. The JSON answer would show the locked_by user and the lock_status should now be LOCKED.
Here is an example request using a cURL utility:
curl -is -X PUT "https://server_example/ewws/EW ?%24KB=Demo&%24login=admin&%24password=***&%24table=al_as_agreements&%24lang=en&id=18"
Here is an example response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"id":18,"table_id":2788,"locked_by":"admin","lock_status":"LOCKED","lock_expires_in_minutes":25}
Unlock a Record
To unlock a record, make an HTTP DELETE request with the following parameters:
Parameter | Value | Required | Description |
|---|---|---|---|
$table | The logical name of the table | yes | The table identifier |
id | The table entry id | yes | The record ID |
force | Any value | no | This parameter can be added to the request if:
|
Here is an example request:
DELETE /ewws/EWLock HTTP/1.1 Host: yourserver.com $KB=Demo& id=18
The server then returns a JSON answer with the keys described in the Get the Lock Status of a Record section above. The JSON answer should show the locked_by user and the lock_status should now be LOCKED.
Here is an example request using a cURL utility:
curl -is -X DELETE "https://server_example/ewws/EWLock %24KB=Demo&%24login=admin&%24password=***&%24table=al_as_agreements&%24lang=en&id=18"
Here is an example response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"id":18,"table_id":2788,"lock_status":"NO_LOCK"}
Related articles