Custom Information

Custom Information stores additional, user-defined metadata for a device. It applies to WEDA Nodes, SubNodes and Custom Devices. Use key-value pairs to add details that matter to your application, such as an installation location or asset tag, without changing the device's registered identity or sensor settings.

Before you start:

• Device: Identify the WEDA Node, SubNode or Custom Device whose metadata you want to maintain. Use that device's own Device ID.
• Access: Use a valid user access token with access to the device's Org. Confirm the intended Org and Device ID before changing labels.
• Examples: Replace https://weda.example.com/central/weda and {deviceId} with your environment and target Device ID.

In WEDA Console: Select the intended Org and find the target under Devices. Confirm its name and Device ID, then use the API operations below to read or maintain its custom information.

Understand Custom Information

Each entry contains a key and a value. Choose stable key names that your application uses consistently. The examples use string values; the bulk PUT also accepts null values and stores them as null, rather than deleting their keys.

An engineer needs to associate a device with its installation location and asset inventory. Use location and assetTag as custom metadata, then read the values back to confirm the labels.

Example key	Example value	Use
location	Tainan_Line1	Describe where the asset is installed.
assetTag	E-0042	Associate the device with your asset inventory.

Custom Information is supplementary metadata. Adding a key called deviceName does not rename the registered device, and adding a location label does not move the device to another Org. Use the device-management operations for registered identity and lifecycle changes, and telemetry configuration for sensor behavior.

Note: Keep a consistent metadata convention

Use the same key spelling across your application and devices. Store numeric-looking labels, such as an asset number, as strings. The examples below manage descriptive labels; they do not define typed sensor values or create DataStreams.

View Custom Information

1. Confirm the target device's Device ID.

2. Call Get Device Custom Info:

   GET https://weda.example.com/central/weda/api/v1/devices/{deviceId}/custom-info
   Authorization: Bearer {userAccessToken}

3. Inspect the returned JSON key-value object. For a device with the example labels, it can look like:

   {
     "location": "Tainan_Line1",
     "assetTag": "E-0042"
   }

4. Keep a copy of the existing labels before an update or deletion, so you can compare the result with the intended change.

Check the result: The API returns 200 OK, and the labels belong to the intended device. If it is unavailable, check the ID, Org access and lifecycle status before assuming that the labels have been deleted.

Add or Update Custom Information

Choose the operation by whether you need to create keys or change one existing entry:

Operation	Use it when	Request body
PUT /custom-info	Add new keys or update several existing keys.	A JSON object of key-value pairs.
PATCH /custom-info/{key}	Change one key that already exists.	An object containing value.

Add or update several labels:

1. Read the current information and choose the keys to change.

2. Call Add or Update Device Custom Info:

   PUT https://weda.example.com/central/weda/api/v1/devices/{deviceId}/custom-info
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   {
     "location": "Tainan_Line1",
     "assetTag": "E-0042"
   }

3. After 200 OK, use GET to confirm the submitted values. New keys are created and existing keys are updated. Keys omitted from this PUT remain unchanged; it is not a replacement of the entire label set.

Change one existing label:

1. Confirm that location exists in the current information.

2. Call Update a Device Custom Info Value:

   PATCH https://weda.example.com/central/weda/api/v1/devices/{deviceId}/custom-info/location
   Authorization: Bearer {userAccessToken}
   Content-Type: application/json
   
   {
     "value": "Tainan_Line2"
   }

3. After 200 OK, read the information again. Confirm that location changed to Tainan_Line2 and that assetTag remains unchanged.

Note: Creating and removing keys

PATCH requires an existing key; a missing key returns 404. Use PUT to create it. Omitting a key from PUT does not remove it, and sending an empty value is not a deletion request. Use DELETE when you intend to remove the entry.

Check the result: The single-key PATCH returns the complete custom-information object. Inspect it and use GET to confirm the intended values, with unrelated labels preserved.

Delete Custom Information

Choose between removing one entry and clearing the device's custom-information set. Read the existing labels first and retain any values your application still needs.

Delete one entry:

1. Confirm that the intended key exists. This example removes only location.

2. Call Delete a Device Custom Info Entry:

   DELETE https://weda.example.com/central/weda/api/v1/devices/{deviceId}/custom-info/location
   Authorization: Bearer {userAccessToken}

3. After 204 No Content, use GET to confirm that location is absent and assetTag remains. A missing key returns 404; check its spelling and the target ID before retrying.

Clear custom information:

1. Confirm the device and review every label that will be removed.

2. Call Delete All Device Custom Info:

   DELETE https://weda.example.com/central/weda/api/v1/devices/{deviceId}/custom-info
   Authorization: Bearer {userAccessToken}

3. After 204 No Content, read the information again and confirm that the custom-information object is empty, {}.

Caution: Check the deletion scope

The path ending in /custom-info/{key} removes one entry. The path ending in /custom-info removes the custom-information set. Review any application that relies on those labels before clearing them. These operations remove descriptive metadata; they do not delete the device, its DataStreams or historical sensor readings.

Check the result: GET confirms the intended keys were removed from the correct device. A 204 response has no response body; use the separate GET for verification.