Context

Owned by Nina Cardillo
10-Jan-2024

Context is implemented as a separate structure with a relationship to already existing entities. The relationship is the following:

Context Type          

Entity

CAMPUSGeozone

BUILDING

Floor Plan

FLOOR

Floor

ROOM

Zone

AREA

Zone/Geozone
Area is represented by either Zone or Geozone depending on its parent.  If it's a child of a Campus, then it's a Geozone.  If it's a child of a Floor or Room, then it's a Zone.  If it's a child of another Area, then it depends on the type of parent of that Area.

Context - Contextual Entity Relationship

When a context is created the CMS makes entities for it and all its children. REST API also supports specifying an already existing entity for a context. In case an entity was created by a context it would have the context name and location. If the created entity is a Floor than it also inherits an image of its context.

If context created without location the CMS can't create an entity for the context. When the context is updated with a location CMS will create a contextual entity.

Updating a context also updates its related entity. The following fields of context propagated to its entity - name, location, image (in case it's a Floor context).

When a context is deleted its contextual entity deleted along with it. All children of the context (with all their entities) removed as well. If Some of the entities can't be removed for some reason meaningful exception will be thrown. One such restriction is that it's prohibited to delete an entity that has devices on itself. Devices should be moved to another entity first. That can be done by assigning them to another context.

Device Assignment

Devices assigned to a context automatically, if the entity they relate to has a context. For example, if a device is located in some geozone and this geozone associated with a context - device considered to be in said context. Search for an appropriate context can go up some levels. E.g. device is in a zone, on some floor in a floor plan that placed in the Geozone A. Neither zone, nor floor plan has an associated context but a geozone A has. So the device considered to be in a context associated with geozone A.

There is a possibility to assign an arbitrary device to a context. It can be an already created device or a device that about to be created. In this case, the CMS finds an entity associated with the requested context and changes the device location to be inside that entity. Then the same automatic device assignment comes to play.

URI Definition

Method

URI and Fields

GET


/iap/context

Returns all contexts. 

The response will be almost the same JSON as the request. Null fields will be explicitly stated and id fields added. 

Sample Response

Expand box to view the response 
{
   {
      "id":7006,
      "contextualEntityId":7005,
      "contextualEntityName":null,
      "name":"campus",
      "description":null,
      "image":{
         "image":null,
         "imageType":null
      },
      "contextLocation":[
         {
            "lat":21.289374355860424,
            "lon":-135.703125
         },
         {
            "lat":53.74871079689897,
            "lon":-135.703125
         },
         {
            "lat":53.74871079689897,
            "lon":-57.65624999999999
         },
         {
            "lat":21.289374355860424,
            "lon":-57.65624999999999
         },
         {
            "lat":21.289374355860424,
            "lon":-135.703125
         }
      ],
      "parentId":null,
      "enabled":true,
      "contextType":"CAMPUS",
      "children":[
         {
            "id":7008,
            "contextualEntityId":7007,
            "contextualEntityName":null,
            "name":"Building",
            "description":null,
            "image":{
               "image":null,
               "imageType":null
            },
            "contextLocation":[
               {
                  "lat":41.24477,
                  "lon":-110.39063
               }
            ],
            "parentId":7006,
            "enabled":true,
            "contextType":"BUILDING",
            "children":[
               {
                  "id":7010,
                  "contextualEntityId":7009,
                  "contextualEntityName":null,
                  "name":"floor",
                  "description":null,
                  "image":{
                     "image":"/9j/4A...cVPip//Z",
                     "imageType":"jpeg"
                  },
                  "contextLocation":null,
                  "parentId":7008,
                  "enabled":true,
                  "contextType":"FLOOR",
                  "children":[

                  ],
                  "customFields":{
                     "floor number":""
                  }
               }
            ],
            "customFields":{

            }
         }
      ],
      "customFields":{

      }
   }
]
/iap/context/{id}

Gets the context for the specified ID.  All of its children are also included.  If the requested context is not top-level it will contain the parentId field with the ID of its parent. 

Context is a recursive data structure.  A parent includes all of its children.  This REST endpoint returns array because it's possible to have several distinct context trees. 

Note:  The image field is a base64 encoded image.  It is shortened in the following sample response.

Example

https://localhost/iap/context/42                                          

Sample Response

Expand box to view the response 
{
   "id":42,
   "contextualEntityId":7007,
   "contextualEntityName":null,
   "name":"Building",
   "description":null,
   "image":{
      "image":null,
      "imageType":null
   },
   "contextLocation":[
      {
         "lat":41.24477,
         "lon":-110.39063
      }
   ],
   "parentId":7006,
   "enabled":true,
   "contextType":"BUILDING",
   "children":[
      {
         "id":7010,
         "contextualEntityId":7009,
         "contextualEntityName":null,
         "name":"floor",
         "description":null,
         "image":{
            "image":"/9j/4AAQ...Pip//Z",
            "imageType":"jpeg"
         },
         "contextLocation":null,
         "parentId":7008,
         "enabled":true,
         "contextType":"FLOOR",
         "children":[

         ],
         "customFields":{
            "floor number":""
         }
      }
   ],
   "customFields":{

   }
}
/iap/context/export

Exports all contexts.

Response

Streaming output of the produced file with all contexts.


POST

/iap/context

Creates a context.  Several contexts can be created at once, provided they all are part of the same tree. 

Can also be used to create children for an already existing context.  The parentId must be specified in this case.

Sample Payload

Expand box to view the payload 
{ 
   "contextType":"CAMPUS",
   "customFields":{

   },
   "children":[
      {
         "contextType":"BUILDING",
         "customFields":{

         },
         "children":[

         ],
         "name":"Building 1",
         "contextLocation":[
            {
               "lat":37.34423323,
               "lon":-99.2323414
            }
         ]
      }
   ],
   "contextLocation":[
      {
         "lat":36.31512514748051,
         "lon":-102.65625
      },
      {
         "lat":48.69096039092549,
         "lon":-102.65625
      },
      {
         "lat":48.69096039092549,
         "lon":-82.265625
      },
      {
         "lat":36.31512514748051,
         "lon":-82.265625
      },
      {
         "lat":36.31512514748051,
         "lon":-102.65625
      }
   ],
   "name":"123"
}
/iap/context/import

Imports contexts.

Request

The file containing the contexts to be imported.


PUT/iap/context

Updates an already existing context. Must contain the ID field for a context that intends to be updated.  Several contexts can be updated at once provided they are all part of the same tree. Can contain new children without an ID field.  CMS treats it as a request to create new contexts.  So if you intend to update Campus and Building at once, each must have an ID field.  If the campus object has an ID field but the building does not, the Campus will be updated and a new Building will be created.  If this new Building has a name that is already used by another Building, an exception with a message will be thrown, and nothing will be updated.

Sample Payload

Expand box to view the payload 
{                                                                                  
   "id":25,
   "contextType":"CAMPUS",
   "customFields":{

   },
   "children":[
      {
         "id":27,
         "contextType":"BUILDING",
         "customFields":{

         },
         "children":[

         ],
         "name":"Building 1 updated",
         "contextLocation":[
            {
               "lat":37.34423323,
               "lon":-99.2323414
            }
         ]
      },
      {
         "contextType":"BUILDING",
         "customFields":{

         },
         "children":[

         ],
         "name":"Building 2 newly created",
         "contextLocation":[
            {
               "lat":38.34423323,
               "lon":-98.2323414
            }
         ]
      }
   ],
   "contextLocation":[
      {
         "lat":36.31512514748051,
         "lon":-102.65625
      },
      {
         "lat":48.69096039092549,
         "lon":-102.65625
      },
      {
         "lat":48.69096039092549,
         "lon":-82.265625
      },
      {
         "lat":36.31512514748051,
         "lon":-82.265625
      },
      {
         "lat":36.31512514748051,
         "lon":-102.65625
      }
   ],
   "name":"updated name of campus"
}


/iap/context/assignDevicesTo/{id}

Assigns devices to the context with the specified ID.

Payload

The payload is an array of device IDs to be assigned.

Request Body Example

[2,3,25]

Success Response

204     No content.                                                              
/iap/context/unassignDevices

Unassigns devices from their contexts. Ids of devices to be unassigned are passed as an array in the request body.

Request Body Example

[42, 68, 70]

Success response:

[68, 42, 70]


DELETE

/iap/context/{id}

Deletes the specified context with all its children and contextual entity.

Response

204     No content.