Lock Service

Lock Service

This API is used for locking objects. Please remember that the API has more possibilities like whether another person can unlock an object, whether the child object should be locked during locking etc

Lock an object


Resource: objects/<object_id>/locks

URL: https://api-stage.bimplus.net/v2/<team_slug>/objects/<object_id>/locks 

Example:https://api-stage.bimplus.net/v2/bimplus/objects/770dbe31-8df0-441a-92de-b464bfdfa0e8/locks

JSON Structure: 

Name

Mandatory / Optional

Type

Description

user

will be ignored

string

The user who performs the lock operation

objects

will be ignored

string

The object ids which are locked. Remember that the child objects under this object will be automatically locked.

Optional query parameters

NameTypeDefault valueDescription
withChildrenbooleantrue

When this query parameter is not set, api call automatically locks the child objects found under this particular object.
This parameter can not be used with "Selection lock", the API will return code 400 Bad Request in such case.
When query parameter is set as :

  • true - api call automatically locks the child objects found under this particular object (default behaviour)
  • false - api call locks the particular object specified by <object_id>
asAdminbooleanfalse

This query parameter can be used only by account owner or project admin, to manipulate locks created by other users.
When query parameter is set as :

  • true - api call will manipulate locks either objects are already locked
  • false - user can modify (set or remove) only locks which has been set by him (default behaviour).



 PUT


Locks an object. Remember that the child objects under this object will be automatically locked.

User can modify (set or remove) only locks which has been set by him or on objects which has not set any lock.
If at least one object is already locked by another user than the user is forbidden to do lock, the return code is 403 Forbidden, Object already locked, without any other info.
To get more information about already locked objects can be used GET method, see Check if an object is locked
When lock operation request has succeeded api call returns standard return code 200 OK.

When a PUT or POST operation on any particular object is performed (eg: PUT objects/<object_id>) then presense of the the lock is checked only on this particular object & the lock is not checked on its parent or children objects.

Selection lock

At selection object lock (eg: PUT objects/{selectionId}/locks) the elements belonging to the selection will be locked.

Selection lock doesn't support children locks, api call with children lock parameter (default is withChildren=true) returns code 400 Bad Request.

If at least one element object (by selection) is locked by another user and the API call doesn't specify query parameter asAdmin=true (default is asAdmin=false), than the user is forbidden to do selection lock, the return code is 403 Forbidden.

If selection contains at least one non-existent element object the return code is 403 Forbidden.


In following example case, we have an selection object '1' with children '1a' and '1b':

{
id: 1,
children:
[
{id: 1a, locked: {…}},
{id: 1b}
]
}

this means selection object has 2 children, one of them is already locked (the one with id: 1a).

Result of the following call:

PUT /v2/my-slug/objects/1/locks

is:

  • 403 Object already locked, when object id:1a is locked with another user as user which is making the call.
    Result doesn't contains any other info.
    To get more details about locking info can be called GET /v2/my-slug/objects/1/locks which will return
    with status code 200 object which holds info about who actually locks objects e.g. :
    {
    { id: 1a, locked: {userId= ….…}}
    }
  • 200 Status OK, when 1a objects is locked by user which is making the call.
    All objects - id:1, id:1a, id:1b are now lockedwith user which is making the call




Authorization: BimPlus 9c1874a62c974dcfa75e0132c423a088
Content-Type: application/json





Status: 200 OK



Lock object with different possibilities (eg: Whether the children should be locked etc)

Check if an object is locked


Resource: objects/<object_id>/locks

URL: https://api-stage.bimplus.net/v2/objects/<object_id>/locks 

Example:https://api-stage.bimplus.net/v2/bimplus/objects/770dbe31-8df0-441a-92de-b464bfdfa0e8/locks


 GET


 Check if an object (including selection) is locked or not. The response contains also the child objects which has been locked & info about the user who has locked it.



Authorization: BimPlus 9c1874a62c974dcfa75e0132c423a088
Content-Type: application/json





Status: 200 OK



[
    {
        "user": {
            "id": "71e0ac3b-fa49-e540-ac2f-8caff3dd72ed",
            "email": "jayaraj.purushothaman@gmail.com"
        }
        "clientid" : "132ecbe-2ac5-4ae1-945d-d38fc3bc1e82",
        "objects": [
            "55c42bbd-7577-4928-aa91-0938ee408a86"
        ]
    }
]



Delete a Lock


Resource: objects/<object_id>/locks

URL: https://api-stage.bimplus.net/v2/objects/<object_id>/locks 

Example:https://api-stage.bimplus.net/v2/bimplus/objects/770dbe31-8df0-441a-92de-b464bfdfa0e8/locks

This call also supports query paramaters "withChildren" and "asAdmin" described above


 DELETE


 Removes the lock from this object.

At selection object unlock (eg: DELETE objects/{selectionId}/locks) the elements belonging to the selection will be unlocked.

Selection unlock doesn't support children locks, call api with children lock parameter (default is withChildren=true) return code 400 Bad Request.

If at least one element object (by selection) is locked by another user and the API call doesn't specify parameter ?asAdmin=true (default is asAdmin=false), than the user is forbidden to do selection unlock, the return code is 403 Forbidden.
See query parameters section in Lock an object .



Authorization: BimPlus 9c1874a62c974dcfa75e0132c423a088
Content-Type: application/json





Status: 200 OK