alterThing

The "alterThing" action modifies an existing object to represent a sensor, device, equipment, server, software application, etc.
 

Request examples

Minimal

{
 "action": "alterThing",
 "params": {
   "id": 1,
   "newThingName": "My New Device Name"
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"  
}
 
 

Maximal

{
 "api": "",
 "action": "alterThing",
 "params": {
   "id": 2,
   "newThingName": "Changed Name",
   "status": "inactive",
   "manufacturer": "Changed Manufacturer",
   "model": "Changed Device Model",
   "serialNumber": "Changed Serial Number",
   "thingType": "Changed Device Type",
   "purpose": "Changed Device Purpose",
   "location": "Changed Device Location",
   "lifecycleLabels": ["out-of-warranty", "deprecated"],
   "hostnames": [ "ChangedHostname","unchangedHostName"  ],
   "description": "Changed description.",
   "metadata": { "myProperty": "myValue" },
   "photo": "ffd8ffee002141646f62650064400000000103001003020306",
   "binaryFormat": "hex"
 },
 "responseOptions": {
   "binaryFormat":   "base64",
   "dataFormat":     "objects",
   "numberFormat":   "string",
   "variantFormat":  "variantObject"
 },
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "requestId": "1",
 "debug": "none" 
}
 
 

 

Response examples

Minimal

{
 "result": {
   "id": 1,
   "thingName": "My New Device Name",
//...use the values for "My Device" in the response to describeThings...
 },
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "errorCode": 0,
 "errorMessage": ""
}
 
 

Maximal

{
 "result": {
   "id": 2,
   "thingName": "Changed Name",
//...use the values for "Changed Name" in the response to describeThings...
 },
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "requestId": "1",
 "errorCode": 0,
 "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  Optional with default of "hex" string One of the following: "base64", "hex", or "byteArray".

description

 The "description" property describes objects such as code packages, labels, or things. The server indexes this field with a full-text index so that you can search for any word or phrase. You cannot use this property for filtering in the Thing API. Optional with default of "unknown"  string 1 to 512 bytes 

hostnames

The "hostnames" property specifies zero or more hostnames assigned to the device. Each item in the array should be a different hostname. 

 

Note The API allows the same hostname to be assigned to many things.

 

When you use the "alterThing" action, omit the "hostnames" property to leave host names unchanged or specify a complete set of hostnames. The action does not allow you to change one hostname at a time.

 

The Thing API implements the "hostnames" property using the Label API. 

  • The API stores and manages hostnames in the label group, "faircom/hostnames".
  • An API client can retrieve a list of all hostnames by using the "listLabels" action with "partialGroupFilter": "faircom/hostnames".
  • An API client should use the Thing API's "hostnames" property to manage the host names assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.
 Optional with default of [] string Array of user-defined hostnames. Each hostname is a string from 0 to 64 bytes. Values are managed in the Label API with the group of "faircom/hostnames".

id

The "id" property is a unique identifier automatically generated by the server. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create an object such as a label or thing and stores it in the table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property. You can use the "id" or "thingName" properties to identify and look up a thing.

 Automatically generated by the server integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API

lifecycleLabels

 The "lifecycleLabels" property assigns zero or more lifecycle labels to a thing. You can use it for fast lookups and filtering. Optional with default of [] array of strings "archived"
"acquired"
"deprecated"
"decommissioned"
"disposed"
"end-of-life"
"out-of-warranty"
"operational"
"testing"
"unknown"

location

The "location" property specifies the item's location. A thing may have one location. 

 

This API uses the Label API to manage manufacturers.

  • It uses the label group, "faircom/edge/location". 
  • An API client can use the "listLabels" action to retrieve the location list. 
  • An API client can use the "alterLabel" action to rename a location label.
  • An API client can use the "createLabel" action to create a location label.
  • An API client can use the "changeLabel" action to delete a location label, but the API client must first use the "listThings" action with the "locationFilter" property to ensure the label is unused.
 Optional with default of "unknown" string

1 to 64 bytes

Values are managed in the Label API with the group of "faircom/edge/location".

manufacturer

The "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. You can use it to do exact lookups and filtering.

 

This API uses the Label API to manage manufacturers.

  • It uses the label group, "faircom/thing/manufacturer". 
  • An API client can use the "listLabels" action to retrieve the manufacturer list. 
  • An API client can use the "alterLabel" action to rename a manufacturer label.
  • An API client can use the "createLabel" action to create a manufacturer label.
  • An API client can use the "changeLabel" action to delete a manufacturer label, but the API client must first use the "listThings" action with the "manufacturerFilter" property to ensure the label is unused.
     
 Optional with default of "unknown" string 1 to 64 bytes

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

model

The "model" property specifies a thing's model. A thing may have one model. Many things can share the same model number.

 

This API uses the Label API to manage models.

  • It uses the label group, "faircom/thing/model". 
  • An API client can use the "listLabels" action to retrieve the model list. 
  • An API client can use the "alterLabel" action to rename a model label.
  • An API client can use the "createLabel" action to create a model label.
  • An API client can use the "changeLabel" action to delete a model label, but the API client must first use the "listThings" action with the "modelFilter" property to ensure the label is unused.
 Optional with default of "unknown" string 1 to 64 bytes

newThingName

The "newThingName" property specifies a new unique name of a thing. If present, it must be a unique thing name.

  • It cannot be the empty string "". 
  • It applies to the "alterThing" action.
 Optional with default of "" string 1 to 64 bytes

photo

 The "photo" property contains a photo of a thing. You cannot use it for lookups and filtering. Optional with default of null string containing a binary value Up to 2 GB

purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

The Thing API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.

Optional with default of "". Defaults to

"unknown" in the Thing API 

 string 1 to 64 bytes

serialNumber

 The "serialNumber" property specifies a thing's serial number. Typically a serial number uniquely identifies a thing, but things from different manufacturers may have the same serial numbers. You can use it to do partial lookups and filtering. Optional with default of "unknown" string 1 to 64 bytes

status

The "status" property indicates an items status. When set to "inactive", an item is no longer in active use. Setting an item to "status": "inactive", functions similarly to deleting an item without making the deletion permanent.

 

When the "status" property is omitted or set to null, API actions set the "status" property to "active". Thus, when you create an item, it defaults to being active. When you list items, the action defaults to returning active items.

 

To create, alter, and list inactive items, set the "status" property to "inactive".
Use a delete action to permanently delete an item.

 Optional with default of "active" string enum

"active"

"inactive"

thingType

The "thingType" property specifies the thing's type, which is a generic description of what the thing is, such as "plc". A thing may have one type. 

 

This API uses the Label API to manage types.

  • It uses the label group, "faircom/thing/type". 
  • An API client can use the "listLabels" action to retrieve the type list. 
  • An API client can use the "alterLabel" action to rename a type label.
  • An API client can use the "createLabel" action to create a type label.
  • An API client can use the "changeLabel" action to delete a type label, but the API client must first use the "listThings" action with the "thingTypeFilter" property to ensure the label is unused.
 Optional with default of "unknown" string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API 

thingName

 The "thingName" property specifies the unique name of a thing. It cannot be the empty string "". string 1 to 64 bytes

 

Was this article helpful?

Give feedback about this article

Related Articles