2.4.4. Grouping and logical organization (Tags)

Tagging provides a mechanism for client applications to group and organize devices and spaces that reflect the business organization of facilities at the resource owner and resource manager level. By propagating tags across information consumers and providers, it provides an efficient way to query and publish information in the end users’ contexts.

Note

Tagging in FDS Version 2 is oriented toward the information consumers to gain efficiency in the retrieval of the information they need. There are also use cases where tagging could be initiated on the information provider side. These use cases will be addressed in following versions.

2.4.4.1. Definitions

Common definitions

Common definitions

2.4.4.1.1. Web API

Endpoint
The URL to access a service implemented on the server of an information provider with the aim to provide responses to requests sent by a client application

https://soapinc.com/fds/v2/specifications is the endpoint to access the specifications of my soap dispensers

Request

The action to be performed by the endpoint and requested by the client application. The action is identified by a HTTP method and can be

  • GET: to retrieve item information from the provider

  • POST: to let an information consumer create an item managed by the information provider

  • PUT: to modify the content of an item managed by the information provider

  • DELETE: to remove an item managed by the information provider

GET https://soapinc.com/fds/v2/specifications is the request to retrieve the specifications of my soap dispensers

Response
The information supplied by the information provider server in response of the request

The response to the GET https://soapinc.com/fds/v2/specifications is a list of device objects

Query parameters
Parameters added to the end of a request to specify additional information about the response expected by the server of the client application

To get the status of a soap dispenser, add the ‘ids’ query parameter with the device ID for the dispenser

Request header
A set of metadata information about the request provided by the client application that the server uses to manage the response

The authentication token in the request header lets the server assess if this is a valid request

Request body
A set of JSON-formatted data provided as part of the request that contains item information requested by the server of the client application

When defining the location of the soap dispenser, put the device ID in the request body of the POST https://soapinc.com/fds/v2/devices_location request

Response body
A set of JSON-formatted data part of the response that contains the information provided by the server of the information provider

The soap dispenser specifications will be found in the response body of the GET https://soapinc.com/fds/v2/specifications request/

2.4.4.1.2. Tag

Tag
A digital label attached to an entity such as device and/or space that identifies its belonging to a group

The ‘Public Bathroom Faucets’ is a tag for all faucets located in the public bathrooms of the hotel

Tag Type
The intent of the tag. It must be ‘organization_grouping’

The intent of the ‘Public Bathroom Faucets’ tag is to logically organize faucets that need frequent cleaning. Therefore the tag type is organization_grouping

Tag ID
A series of characters that uniquely identify a tag across the digital world

The tag ID of the ‘Public Bathroom Faucets’ tag is ‘fb9e9c4f-3230-4886-bbaf-c141066f7d04’

2.4.4.2. FDS compliance requirements

This section provides the FDS compliance requirements when implementing the tagging endpoints.

2.4.4.2.1. Requirements common to all tag endpoints

  • All endpoints must provide the authorization token in the HTTPS header

  • If a request is unauthorized, the information provider must return

    • a 401 HTTP status code in the response header

    • an error object in the response body with a “unauthorized_request” message

  • If a query parameter name is invalid, the information provider must return

    • a 400 HTTP status code in the response header

    • an error object in the response body with a “invalid_parameter” message

  • if a parameter provided appears more than once in the request, the information provider must return

    • a 400 HTTP status code in the response header

    • an error object in the response body with a “duplicate_parameter” message

2.4.4.2.2. Tag management

These Web API endpoints provide the functionality for information consumers to manage tags on the information provider’s side.

2.4.4.2.2.1. Create a new tag

  • The entity (device or space) information provider must expose the POST request on the tag endpoint to let a client application create a new tag managed on the server side of the information provider

POST https://{Entity Information Provider URL}/fds/v2/tag

  • The request body must contain a tag object

  • If the tag object is not provided in the request body, the information provider must return

    • a 403 HTTP status code

    • an error object in the response body with a “missing_tag” message

  • If the tag object is malformed, the information provider must return

    • a 403 HTTP status code

    • an error object in the response body with a “invalid_tag_object” message

  • When creating a tag on a device information provider the tag object must only contain a list of device IDs that are defined by this provider, and that belong to the resource owner or resource manager

  • When creating a tag on a physical environment information provider the tag object must only contain a list of space IDs that are defined by this provider, and that belong to the resource owner or resource manager

  • When creating a tag on a provider that expose both device and physical environment information the tag object must only contain a list of IDs that can combine device and space IDs defined by this provider, and that belong to the resource owner or resource manager

  • If one or multiple entity IDs do not exist on the information provider side, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_entities” message

  • If the tag already exists on the information provider, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “tag_already_exists” message

  • Successful tag creation must return

    • a 201 HTTP status code in the response header

    • a success object in the response body with a “tag_created” message

The following diagram provides a high level description of the POST tag request:

../../_images/post_tag_endpoint.png

2.4.4.2.2.2. Get the entities associated with a tag

  • The entity (device or space) information provider must expose the GET request on the tag endpoint to provide the content of a tag managed on the server side of the information provider

GET https://{Entity Information Provider URL}/fds/v2/tag

  • The endpoint must provide the query parameters:

parameter

Type

Description

tag_id

string

  • The ID of the tag to query

  • Required

  • If no query parameter is provided in the request, the information provider must return

    • a 400 HTTP status code in the response header

    • an error object in the response body with a “missing_parameter” message

  • If the tag does not exist on the information provider side, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_tag” message

  • Successful tag retrieval must return

    • a 200 HTTP status code in the response header

    • the tag object containing all the entity IDs associated with this tag

The following diagram provides a high level description of the GET tag request:

../../_images/get_tag_endpoint.png

2.4.4.2.2.3. Delete a tag

  • The entity (device or space) information provider must expose the DELETE request on the tag endpoint to to let a client application delete a tag managed on the server side of the information provider

DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>

  • The endpoint path must specify a valid tag ID already created on the provider side through a previous POST request

  • If the tag ID has not been previously created, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_tag” message

  • The information provider must remove any association of entities to this tag and remove any reference to this tag

  • Successful tag deletion must return

    • a 200 HTTP status code in the response header

    • a success object in the response body with a “tag_deleted” message

The following diagram provides a high level description of the DELETE tag/<tag_id> request:

../../_images/delete_tag_endpoint.png

2.4.4.2.3. Tag content management

These Web API endpoints provide the functionality for information consumers to manage the content of existing tags on the information provider’s side.

2.4.4.2.3.1. Associate new entities to an existing tag

  • The entity (device or space) information provider must expose the PUT request on the tag/<tag_id>/entities endpoint to let a client application associate new entities to an existing tag managed on the server side of the information provider

PUT https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

  • The endpoint path must specify a valid tag ID already created on the provider side through a previous POST request

  • If the tag ID has not been previously created, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_tag” message

  • The request body must contain a tag_entities object containing an array of entity ids

  • When associating a tag to additional devices on a device information provider the array must only contain a list of device IDs that are defined by this provider, and that belong to the resource owner or resource manager

  • When associating a tag to additional spaces on a physical environment information provider the array must only contain a list of space IDs that are defined by this provider, and that belong to the resource owner or resource manager

  • When associating a tag to additional devices and spaces on a provider that expose both device and physical environment information the array must only contain a list of IDs that can combine device and space IDs defined by this provider, and that belong to the resource owner or resource manager

  • The list of entity IDs provided can include IDs that have already been associated with this tag. In this case, the provider must return a success response, even if no action is required for these entities

  • If one or multiple entity IDs do not exist on the information provider side, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_entities” message

  • Successful entities association must return

    • a 200 HTTP status code in the response header

    • a success object in the response body with a “entities_associated” message

The following diagram provides a high level description of the PUT tag/<tag_id>/entities request:

../../_images/put_tag_entities_endpoint.png

2.4.4.2.3.2. Remove associations between entities and a tag

  • The entity (device or space) information provider must expose the DELETE request on the tag/<tag_id>/entities endpoint to let a client application remove the entities association to an existing tag managed on the server side of the information provider

DELETE https://{Entity Information Provider URL}/fds/v2/tag/<tag_id>/entities

  • The endpoint path must specify a valid tag ID already created on the provider side through a previous POST request

  • If the tag ID has not been previously created, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_tag” message

  • The request body must contain a tag_entities object containing an array of entity ids

  • All IDs in list of entity IDs provided in the request must already be associated with this tag. If one or multiple IDs are not associated with the tag, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_associations” message

  • The list of entity IDs provided can include IDs that have no association with this tag. In this case, the provider must return a success response, even if no action is required for these entities

  • it is possible that the client application provides the entire list of entity IDs associated with this tag in the request. In that case the information provider must maintain a reference to this tag, even if no entities are currently associated with it.

  • If one or multiple entities IDs do not exist on the information provider side, the information provider must return

    • a 403 HTTP status code in the response header

    • an error object in the response body with a “invalid_entities” message

  • Successful removal of entities association must return

    • a 200 HTTP status code in the response header

    • a success object in the response body with a “entities_removed” message

The following diagram provides a high level description of the DELETE tag/<tag_id>/entities request:

../../_images/delete_tag_entities_endpoint.png

2.4.4.3. Workflow

This section provides a guideline and best practice to manage tags.

2.4.4.3.1. Define a tag

The typical purpose of a tag is to access information that relate to a group of devices and potentially spaces that make sense for the end users of a client application. Therefore, in order to define a tag, the client application should know the entities (devices/spaces) to manage on behalf of the resource owner or manager, and should know how to organize these entities together. Then it can notify each information provider about this logical organization.

../../_images/tag_creation_workflow.png

2.4.4.3.2. Modify a tag

A series of changes can periodically happen throughout the operation of a facility that would require to change which devices or spaces belong to a group. For example, devices can be removed, added, or replaced. When changes happen, the client application should

  • identify the tag representing the group being modified,

  • identify the devices and/or spaces being added or removed and the information providers they belong to

  • notify these information providers of the changes

../../_images/tag_modification_workflow.png

2.4.4.4. Use case example

Note

Join FDS to get access to examples and use cases.