Manage custom properties

📘

Require module

You will need the Custom Fields module to visualize and use custom fields. Check your modules at Admin > Licenses. To obtain this module, contact your IXON account manager or IXON distrubutor.

You can use custom fields (also called custom properties) to add information to your machine, such as a password, or an instruction manual, or more. This article will explain how to manage them via IXON's API endpoints. Check this support article to know more about them before you start.

CustomPropertyList

Please note: the CustomProperty endpoint is the non-list version of CustomPropertyList, and can be used to perform GET action for a single custom property by providing its publicId.

📘

Note about scopeType

This field corresponds to the first part of the Identifier of a custom property, and it's set to com by default when a user creates one, like shown in this picture:

If you see glb as value in the scopeType, ignore it. These are global values set by IXON and are used internally for other features.

MyCompanyCustomPropertyList

Please note: the MyCompanyCustomProperty endpoint is the non-list version of MyCompanyCustomPropertyList, and can be used to perform PATCH and DELETE actions for a single custom property by providing its publicId. It is not possible to perform a POST request with this endpoint.

👍

MyCompanyCustomPropertyList in detail

This endpoint's POST request is used to create a custom field from scratch in Admin > Device settings > Custom fields or Admin > Device settings > Assets, therefore being used for both custom properties of either Agents or Assets.
The following fields can be used in the request body of this request:

Field	Data type	Description	Mandatory
resourceType	string	It consists of the type of resource the custom property belongs to (Agent or Asset).	Yes
resourceVariant	string | null	The Asset type. If the resource is an Agent, this field can be null.	Yes Note: it is not flagged as mandatory, but in case of custom fields belonging to Assets, it needs to be filled or the custom field won't be visible in the interface.
slug	string	It consists of the same value as the name but with an initial capital letter and no spacing. Not visible to the user in the interface.	Yes
name	string	The name of the custom field.	Yes
description	string | null	The description of the custom field.	No
required	boolean	Its default value is false. Cannot be set through the interface, and does not need to be used in the POST request.	No
validation	object	Refer to the information below for more details.	Yes
flags	array	Contains information about visibility of a custom field. If the option "Hide in portal view" is selected, then it will contain hiddenInPortal, otherwise it will be empty.	No

The validatation object is mandatory and checks whether the value of the selected Field type matches with the data type. The field types can be visualized when adding a new custom field:

You can refer to this table to apply the correct validation through the API endpoint request body:

Field type	Data type	Validation fields
Text/JSON	string	{ "validation": { "type": "str" } }
Single option	enum	{ "validation": { "type": "enum", "options": [ "Option1", "Option2" ] } }
Numerical	int	{ "validation": { "type": "int" } }
Boolean	bool	{ "validation": { "type": "bool" } }

How-tos and use cases

In this section you will find step-by-step examples of real use cases concerning the manipulation of custom fields.

How to retrieve all available custom fields

Goal: retrieving a list of custom fields available in a company.

What you will need:

• Your applicationId;
• Your companyId;
• Your bearerToken.

To obtain a list of custom fields, all you only have to follow one single step consisting of sending a GET request to the CustomPropertyList endpoint:

curl --location 'https://portal.ixon.cloud/api/custom-properties' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'

{
  "type": "CustomProperty",
  "data": [
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "glb",
      "resourceType": "Branding",
      "resourceVariant": null,
      "slug": "BrowserTitle",
      "name": "Browser Title",
      "description": "Used the title on your browser",
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": []
    },
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "com",
      "resourceType": "Asset",
      "resourceVariant": "$assetTypePublicId",
      "slug": "InstructionsManual",
      "name": "Instruction Manual",
      "description": null,
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": []
    },
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "com",
      "resourceType": "Asset",
      "resourceVariant": "$assetTypePublicId",
      "slug": "LocalPassword",
      "name": "Local Password",
      "description": null,
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": [
        "hiddenInPortal"
      ]
    }
  ],
  "moreAfter": null,
  "status": "success"
}

There are a few things to point out in this JSON response:

• In the first custom field, you can see that the scopeType value is glb (global). You might see more fields with such a scope type, they are default and we recommend to not manipulate them;

• The minLength and maxLength (minValue and maxValue for int) values are fields used to automatically check the data type of a custom field. For this reason, it is not required to set them in a request body of a POST request. Additionally, the field regex is not used;

• The string hiddenInPortal is used to flag the "Hide in portal view" option. If not present, then it means that the custom field is visible in the portal:

  

How to retrieve a custom field belonging to either Agents or Assets

Goal: retrieving a custom field used in an agent or asset.

What you will need:

• Your applicationId;
• Your companyId;
• Your bearerToken.

Agent

In case you want to retrieve custom fields belonging to agents, you can use the GET request of the AgentList endpoint. All you have to do is retrieving all fields of the custom object in the URL query:

curl --location 'https://portal.ixon.cloud/api/agents?fields=deviceId,custom.*' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'

{
  "type": "Agent",
  "data": [
    {
      "publicId": "$agentPublicId",
      "name": "IX3 Router - Scrap Mixer",
      "deviceId": "$deviceMACAddress",
      "custom": {
        "glbStarUsers": null,
        "comLocalPassword": null,
        "comInstructionsManual": null
      }
    },
    {
      "publicId": "$agentPublicId",
      "name": "SecureEdge Pro - Scrap Grabber",
      "deviceId": "$deviceMACAddress",
      "custom": {
        "glbStarUsers": null,
        "comLocalPassword": null,
        "comInstructionsManual": null
      }
    }
  ],
  "moreAfter": null,
  "status": "success"
}

Asset

In case your machines are assets, you will have to use the GET request of the AssetList endpoint. Again, you will be retrieving all fields of the custom object in the URL query:

curl --location 'https://portal.ixon.cloud/api/assets?fields=name,description,resourceVariant.*,parent.publicId,custom.*' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'

{
    "type": "Asset",
    "data": [
        {
            "publicId": "$assetPublicId",,
            "name": "Aluminium Heat Measurer",
            "description": "Measures heat.",
            "resourceVariant": {
                "publicId": "$assetTypePublicId",
                "name": "Scrap metal measurer",
                "order": 2000
            },
            "parent": {
                "publicId": "$parentAssetPublicId",
                "reference": {
                    "name": "Asset"
                }
            },
            "custom": {
                "comComInstructionsManual": "$linkToInstructionsManual"
            }
        },
        {
            "publicId": "KxWcZIBlMkTM",
            "name": "Aluminium Metrics",
            "description": "Measurements for aluminium.",
            "resourceVariant": {
                "publicId": "$assetTypePublicId",
                "name": "Scrap metal measurer",
                "order": 2000
            },
            "parent": null,
            "custom": {
                "comComInstructionsManual": "$linkToInstructionsManual"
            }
        }
    ],
    "moreAfter": null,
    "status": "success"
}

How to create a new custom field

Goal: creating a new custom field for an agent and assigning a value to it.

What you will need:

• Your applicationId;
• Your companyId;
• Your bearerToken;
• The publicId of one or more Agents.

Step 1 - Create the custom field

To create a new custom property, you will need to send a POST request to the MyCompanyCustomPropertyList endpoint. This is the only endpoint that handles the creation of custom properties from scratch:

curl --location 'https://portal.ixon.cloud:443/api/companies/me/custom-properties' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'
     --data '
[
  {
    "validation": {
      "type": "str"
    },
    "resourceType": "Agent",
    "slug": "AlarmInstructions",
    "name": "Alarm Instructions"
  }
]
'

{
  "type": "CreateResponse",
  "data": [
    {
      "publicId": "$newCustomFieldPublicId"
    }
  ],
  "moreAfter": null,
  "status": "success"
}

For more details about the fields in this request body, please refer to this previous section.

Step 2 - Assign a value to the new custom field

The Identifier (visible in IXON's Portal view) of a custom field is available to all Agents or Assets, but it won't necessarily have a value as you can see here:

How can we emulate pressing the "Edit" button with the API?

In our specific case we want to assign a value to two different agents at the same time. To do this, we will use the AgentList endpoint's PATCH request:

curl --location --request PATCH 'https://portal.ixon.cloud/api/agents' \
		 --header 'Api-Application: $applicationId' \
  	 --header 'Api-Company: $companyId' \
  	 --header 'Api-Version: 2' \
  	 --header 'accept: application/json' \
  	 --header 'authorization: Bearer $bearerToken' \
  	 --data '
[
  {
    "custom": {
      "comAlarmInstructions": "Press the red button twice to stop the alarm sound."
    },
    "publicId": "$agentPublicId"
  },
  {
    "custom": {
      "comAlarmInstructions": "Twist the handle to stop the alarm sound."
    },
    "publicId": "$agentPublicId"
  }
]
'

{
    "type": "Null",
    "data": null,
    "status": "success"
}

As you can see, we have modified the value of comAlarmInstructions in two different agents at the same time. The same can be done for assets with AssetList's PATCH request with the same request body structure as the one above, provided that you have the needed assets' publicId.

🚧

Important note on newKey

If you choose to test this with the help of IXON's Endpoint documentation, you might see something like this after expanding the custom object in the body params:

This can potentially cause confusion, as the newKey string is NOT "new" and does NOT consist of a new custom field's identifier, but instead it consists of the existing identifier that you want to assign a value to or change the value of, such as comInstructionsManual, and New Value will consist of the value that you want to assign to it. You cannot possibly ask the endpoint to change the value of a key that does not exist.

No verbs of this endpoint, including PATCH, can create a new custom field. MyCompanyCustomPropertyList is the only endpoint that can create a new custom field as mentioned in Step 1, and the value of theIdentifier (in this case newKey) is generated upon creation of the custom field.
This is how custom should look like in a valid PATCH request: