Working with custom fields

This tutorial will walk you through creating, updating, and reading custom fields against devices and device-templates.

First create a new device-template:
POST /api/v1/devices/templates

Authorization: Bearer [jwt token]
{
  "accountId": "11111111-0000-0000-0000-111111111111",
  "name": "Water Meter 3000"
}

Then, add a custom field to all device-templates. This custom field represents the model number of the devices.
POST /api/v1/devices/templates/custom-fields

Authorization: Bearer [jwt token]
{
  "accountId": "11111111-0000-0000-0000-111111111111",
  "name": "modelNumber",
  "fieldType": "string",
  "required": "false",
  "default": ""
}

Let's read-back the created device-template and see what happened:
GET /api/v1/devices/templates/22222222-1111-3333-1111-222222222222

Authorization: Bearer [jwt token]
Returns:
{
  "id": "22222222-1111-3333-1111-222222222222",
  "created": "2015-06-19T20:41:29.000Z",
  "createdById": "00000000-0000-0000-0000-000000000000",
  "lastModified": "2015-06-19T20:41:29.000Z",
  "lastModifiedById": "00000000-0000-0000-0000-000000000000",
  "version": "xz",
  "accountId": "11111111-0000-0000-0000-111111111111",
  "name": "Water Meter 3000",
  "default": "false",
  "modelNumber": null
}

The new modelNumber fields shows up when we retrieve our device-template. Now we'll retroactively put a value into that field:
PUT /api/v1/devices/templates/22222222-1111-3333-1111-222222222222

Authorization: Bearer [jwt token]
ETag: "xz"
{
  "modelNumber": "WM-3000"
}

Next we'll add a custom field to devices:
POST /api/v1/devices/custom-fields

Authorization: Bearer [jwt token]
{
  "accountId": "11111111-0000-0000-0000-111111111111",
  "deviceTemplateId": "22222222-1111-3333-1111-222222222222"
  "name": "faucetLocation",
  "fieldType": "string",
  "required": "false",
  "default": ""
}

Note that we specified the deviceTemplateId of our Water Meter 3000 device template when creating this new custom field. This means that the custom field will only be available for Water Meter 3000 devices. We could have omitted the deviceTemplateId so that the field applies to all devices, but in this case, let's assume that some of our products do not attach to faucets.

Finally, we can create a new device and specify the new field's value at the same time:
POST /api/v1/devices

Authorization: Bearer [jwt token]
{
  "accountId": "11111111-0000-0000-0000-111111111111",
  "deviceTemplateId": "22222222-1111-3333-1111-222222222222"
  "organizationId": "77777777-6666-6666-6666-77777777",
  "serialNumber": "d812rdfg8",
  "faucetLocation": "Upstairs shower"
}

Realistically, we probably won't know the faucet location when the device is created, so you can always update the field value at a later time.

Working with custom fields