Beacon Label Association

Owned by Sebastian Restrepo (Unlicensed)
Last updated: Oct 26, 2018
8 min read

Bluzone now supports Labels. A Label is essentially a key that has a set of possible values. For example, you can have a "Department" Label that can have multiple values, such as "Development" or "Sales".  Labels and Label Values are meant to be associated to Policies and Beacons so that you no longer need to add Beacons to a Policy one-by-one. This guide, will outline how to perform CRUD operations on Labels and Label Values, and how to associate Label Values to Beacons using Bluzone's REST APIs.

Walkthrough

This section of the guide will demonstrate a typical workflow for creating Labels and Label Values and associating those Label Values to Beacons. Note, variables surrounded by "{...}" are project specific, i.e. replace them based on your Project, Beacons, etc. 

Create Label

First, you need to create Labels. Suppose you want to create two Labels: "Department" and "Building". As you can see below, the request payload is simply a list of objects, where each object has a name property. If you wanted to create one Label you would need to pass a list containing a single object.

Request

curl -X POST \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/labels \
  -H 'Accept: application/json' \
  -H 'BZID: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '[
	{
		"name": "Department"
	},
	{
		"name": "Building"
	}
]'

Response

[
    {
        "labelId": 1,
        "projectId": {PROJECT_ID},
        "name": "Department",
        "labelValues": null,
        "dateUpdated": 1540584864274,
        "dateCreated": 1540584864274
    },
    {
        "labelId": 2,
        "projectId": {PROJECT_ID},
        "name": "Building",
        "labelValues": null,
        "dateUpdated": 1540584864279,
        "dateCreated": 1540584864279
    }
]

Retrieve Labels

Request

curl -X GET \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/labels \
  -H 'Accept: application/json' \
  -H 'BZID: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

Response

[
    {
        "labelId": 1,
        "projectId": {PROJECT_ID},
        "name": "Department",
        "labelValues": null,
        "dateUpdated": 1540584864274,
        "dateCreated": 1540584864274
    },
    {
        "labelId": 2,
        "projectId": {PROJECT_ID},
        "name": "Building",
        "labelValues": null,
        "dateUpdated": 1540584864279,
        "dateCreated": 1540584864279
    }
]


Create Label Values

Now that you have create your two "Department" and "Building" Labels you need to specify which values these Labels can assigned. Suppose you have two departments "Software Development" and "Sales, and two buildings "IC - 1" and "IC - 2". Below is an example of how to create Label Values for the two Labels. As you can see, the payload of the request is a list of the four values we want to create. Each item in the list is an object that specifies which Label the Label Value belongs to (using the labelId property) and the value.

Request

curl -X POST \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/labelValues \
  -H 'Accept: application/json' \
  -H 'BZID: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '[
	{
		"labelId": 1,
		"value": "Software Development"
	},
	{
		"labelId": 1,
		"value": "Sales"
	},
	{
		"labelId": 2,
		"value": "IC - 1"
	},
	{
		"labelId": 2,
		"value": "IC - 2"
	}
]'

Response

[
    {
        "labelValueId": 1,
        "labelId": 1,
        "labelName": "Department",
        "projectId": {PROJECT_ID},
        "value": "Software Development",
        "dateUpdated": 1540585112944,
        "dateCreated": 1540585112944
    },
    {
        "labelValueId": 2,
        "labelId": 1,
        "labelName": "Department",
        "projectId": {PROJECT_ID},
        "value": "Sales",
        "dateUpdated": 1540585112946,
        "dateCreated": 1540585112946
    },
    {
        "labelValueId": 3,
        "labelId": 2,
        "labelName": "Building",
        "projectId": {PROJECT_ID},
        "value": "IC - 1",
        "dateUpdated": 1540585112947,
        "dateCreated": 1540585112947
    },
    {
        "labelValueId": 4,
        "labelId": 2,
        "labelName": "Building",
        "projectId": {PROJECT_ID},
        "value": "IC - 2",
        "dateUpdated": 1540585112949,
        "dateCreated": 1540585112949
    }
]

Retrieve Label Values

Request

curl -X GET \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/labelValues \
  -H 'Accept: application/json' \
  -H 'BZID: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache'

Response

[
    {
        "labelValueId": 1,
        "labelId": 1,
        "labelName": "Department",
        "projectId": {PROJECT_ID},
        "value": "Software Development",
        "dateUpdated": 1540585112944,
        "dateCreated": 1540585112944
    },
    {
        "labelValueId": 2,
        "labelId": 1,
        "labelName": "Department",
        "projectId": {PROJECT_ID},
        "value": "Sales",
        "dateUpdated": 1540585112946,
        "dateCreated": 1540585112946
    },
    {
        "labelValueId": 3,
        "labelId": 2,
        "labelName": "Building",
        "projectId": {PROJECT_ID},
        "value": "IC - 1",
        "dateUpdated": 1540585112947,
        "dateCreated": 1540585112947
    },
    {
        "labelValueId": 4,
        "labelId": 2,
        "labelName": "Building",
        "projectId": {PROJECT_ID},
        "value": "IC - 2",
        "dateUpdated": 1540585112949,
        "dateCreated": 1540585112949
    }
]


Associate Beacon-Label Values

Finally, lets associate these labels to a Beacon. Suppose you have a Beacon that belongs to the "Software Development" Department and is in Building "IC-1". There are two methods for applying Labels to Beacons:

Method 1

For this method, the payload of the request is simply a list of labelValueId (20 and 22) . If successful, the response will be the LabelValue objects associated to the IDs.

Request

curl -X PUT \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/devices/beacons/{BEACON_ID}/_labelValues \
  -H 'BZID: {API_KEY} \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '[
    1, 3
]'

Response

[
    {
        "labelValueId": 3,
        "labelId": 2,
        "labelName": "Building",
        "projectId": 10,
        "value": "IC - 1",
        "dateUpdated": 1540585113000,
        "dateCreated": 1540585113000
    },
    {
        "labelValueId": 1,
        "labelId": 1,
        "labelName": "Department",
        "projectId": 10,
        "value": "Software Development",
        "dateUpdated": 1540585113000,
        "dateCreated": 1540585113000
    }
]


Method 2

Alternatively, you can update the Beacon directly using our existing API.

Request

curl -X PUT \
  https://bluzone.io/portal/papis/v1/projects/{PROJECT_ID}/devices/beacons/{BEACON_ID} \
  -H 'Accept: application/json' \
  -H 'BZID: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "deviceId": {BEACON_ID},
    "projectId": {PROJECT_ID},
    ... // other properties are omitted for sake of brevity 
    "labelValues": [
        {
            "labelValueId": 1,
            "labelId": 1,
            "value": "Software Development"
        },
        {
            "labelValueId": 3,
            "labelId": 2,
            "value": "IC - 1"
        }
    ]
}'

Response

{
    "deviceId": {BEACON_ID},
    "projectId": {PROJECT_ID},
    ... 
    "labelValues": [
        {
            "labelValueId": 3,
            "labelId": 2,
            "labelName": "Building",
            "projectId": 10,
            "value": "IC - 1",
            "dateUpdated": 1540585113000,
            "dateCreated": 1540585113000
        },
        {
            "labelValueId": 1,
            "labelId": 1,
            "labelName": "Department",
            "projectId": 10,
            "value": "Software Development",
            "dateUpdated": 1540585113000,
            "dateCreated": 1540585113000
        }
    ]
}


List of REST APIs

To get started quickly with the Labels we recommend importing our Postman collection. To import the collections simply navigate to Postman > "Import" from the top menu > "Import From Link" > Paste in link: https://www.getpostman.com/collections/2ee42c456b3dc13a5587. Note, you will need to update the variables to reflect your own project parameters.