web sdk custom fields

Working with Custom Fields

Custom fields allow you to extend Security Center entities with additional properties specific to your business needs. This guide covers creating custom fields, reading/writing values, filtering by custom fields, and important limitations.

What Are Custom Fields?

Custom fields are user-defined properties that can be added to Security Center entities. They allow you to store additional information beyond the standard entity properties.

Common use cases:

• Employee badge numbers
• Department codes
• Building access levels
• Training dates
• Equipment identifiers
• Custom business logic data

Supported Data Types

Custom fields support the following data types:

Data Type	Description	Example Value	Notes
Text	String value	"Engineering"	Default empty string if not set
Numeric	Integer value	12345	Default 0 if not set
Boolean	True/false value	true	Default false if not set
DateTime	Date and time	"2025-01-15T10:30:00+08:00"	ISO 8601 format, supports timezone
Date	Date only	"2025-01-15"	No time component
Decimal	Decimal number	99.99	For currency or precise values
Image	Binary image data	Base64-encoded	Cannot be read via GET
Entity	Reference to another entity	GUID	Links to Security Center entity

Creating Custom Fields

POST /customField/{entityType}/{customFieldName}/{dataType}/{defaultValue}

Creates a new custom field for the specified entity type.

Parameters:

• entityType - Entity type (e.g., Cardholder, Credential, Door)
• customFieldName - Name of the custom field (no spaces or special characters)
• dataType - Data type (Text, Numeric, Boolean, DateTime, Date, Decimal, Image, Entity)
• defaultValue - Default value when not set (optional for Image and Entity types)

Examples:

POST /customField/Cardholder/DepartmentCode/Text/IT
POST /customField/Cardholder/BadgeNumber/Numeric/0
POST /customField/Cardholder/IsContractor/Boolean/false
POST /customField/Cardholder/LastTrainingDate/DateTime/DateTime.Now

Special default values:

• DateTime.Now - Current local time
• DateTime.UtcNow - Current UTC time

Response (success):

{
  "Rsp": {
    "Status": "Ok"
  }
}

Response (error - field already exists):

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "SdkErrorCode": "TransactionFailed",
      "Message": "The property Name is invalid. The property Name should be unique by EntityType, Owner and CustomEntityTypeId"
    }
  }
}

Reading Custom Field Values

There are two methods to read custom field values: dedicated endpoints and entity query syntax.

Method 1: Dedicated Endpoint (Recommended for Single Field)

GET /customField/{entityId}/{customFieldName}

Retrieves the value of a specific custom field for an entity.

Example:

GET /customField/5ba791adf4a94efda6573779c198340a/DepartmentCode

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Value": "Sales"
    }
  }
}

Data type preservation:

• Text fields return strings: "Value": "Engineering"
• Numeric fields return numbers: "Value": 12345
• Boolean fields return booleans: "Value": true
• DateTime fields return ISO 8601 strings: "Value": "2025-01-15T10:30:00+08:00"

Method 2: Entity Query Syntax (Recommended for Multiple Fields)

Custom fields can be queried like standard entity properties using the /entity endpoint.

GET /entity?q=entity={guid},CustomFieldName

Examples:

Read single custom field:

GET /entity?q=entity=5ba791adf4a94efda6573779c198340a,DepartmentCode

Read multiple custom fields:

GET /entity?q=entity=5ba791adf4a94efda6573779c198340a,DepartmentCode,BadgeNumber,IsContractor

Read custom fields and standard properties:

GET /entity?q=entity=5ba791adf4a94efda6573779c198340a,Name,FirstName,LastName,DepartmentCode,BadgeNumber

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "New_Cardholder_6225b1afcdf44f2798ccd531fd2d0320",
      "FirstName": "Test",
      "LastName": "User",
      "DepartmentCode": "Sales",
      "BadgeNumber": 12345
    }
  }
}

Writing Custom Field Values

There are two methods to set custom field values: dedicated endpoints and entity update syntax.

Method 1: Dedicated Endpoint (Recommended for Single Update)

PUT /customField/{entityId}/{customFieldName}/{value}

Sets the value of a specific custom field.

Examples:

PUT /customField/5ba791adf4a94efda6573779c198340a/DepartmentCode/Engineering
PUT /customField/5ba791adf4a94efda6573779c198340a/BadgeNumber/12345
PUT /customField/5ba791adf4a94efda6573779c198340a/IsContractor/true
PUT /customField/5ba791adf4a94efda6573779c198340a/LastTrainingDate/2025-01-15T10:30:00

Value conversion:

• Text: Any string value
• Numeric: Integer string (e.g., "12345")
• Boolean: "true" or "false" (case-insensitive)
• DateTime: ISO 8601 string, or "DateTime.Now", or "DateTime.UtcNow"
• Decimal: Decimal string (e.g., "99.99")

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Method 2: Entity Update Syntax (Recommended for Multiple Updates)

Custom fields can be updated like standard entity properties using the /entity endpoint.

POST /entity?q=entity={guid},CustomFieldName=value

Examples:

Update single custom field:

POST /entity?q=entity=5ba791adf4a94efda6573779c198340a,DepartmentCode=Sales

Update multiple custom fields:

POST /entity?q=entity=5ba791adf4a94efda6573779c198340a,DepartmentCode=Engineering,BadgeNumber=54321,IsContractor=false

Update custom fields and standard properties:

POST /entity?q=entity=5ba791adf4a94efda6573779c198340a,FirstName=Jane,DepartmentCode=Marketing,BadgeNumber=99999

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Deleting Custom Fields

DELETE /customField/{entityType}/{customFieldName}

Deletes a custom field definition. This removes the custom field from all entities of the specified type.

Example:

DELETE /customField/Cardholder/OldFieldName

Response:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Important

Deleting a custom field removes it from all entities. This operation cannot be undone.

Filtering by Custom Fields

Custom fields can be used as filters in EntityConfiguration reports.

Syntax

GET /report/{EntityType}Configuration?q=CustomFields@CustomField(customFieldGuid,value)

Parameters:

• customFieldGuid - GUID of the custom field (not the field name)
• value - Value to filter by

Important

You must use the custom field's GUID, not its name. Custom field GUIDs can be obtained by querying an entity with the custom field set (see example below).

Examples

Filter cardholders by single custom field:

GET /report/CardholderConfiguration?q=CustomFields@CustomField(952ae0f6-dba6-401e-ae08-d152cf89ee1f,IT)

Filter by multiple custom fields (logical AND):

GET /report/CardholderConfiguration?q=CustomFields@CustomField(952ae0f6-dba6-401e-ae08-d152cf89ee1f,IT)@CustomField(26f00b38-a5b5-4a5b-afc0-7379166b0099,true)

Returns only entities where DepartmentCode = "IT" AND IsContractor = true.

Combine with entity type filter:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,CustomFields@CustomField(952ae0f6-dba6-401e-ae08-d152cf89ee1f,Sales)

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {"Guid": "984c7ac2-6c76-44c0-be2d-1de009b2a259"},
      {"Guid": "631d3540-e293-469f-8a64-22b282cd7fd0"}
    ]
  }
}

Obtaining Custom Field GUIDs

To get a custom field's GUID, query any entity that has the custom field defined:

GET /entity/{entity-guid}
Accept: text/json

In the JSON response, look for the CustomFields array:

{
  "CustomFields": [
    {
      "Guid": "952ae0f6dba6401eae08d152cf89ee1f",
      "Name": "DepartmentCode",
      "EntityType": "Cardholder",
      "ValueType": "Text"
    }
  ]
}

Custom Field Properties

When retrieving entity data, each custom field includes the following properties:

Core properties:

• Name (string) - Custom field name
• Guid (GUID) - Unique identifier for the custom field
• EntityType (enum) - Entity type this field applies to
• ValueType (enum) - Data type (Text, Numeric, Boolean, etc.)
• Value (varies) - Current value for this entity
• DefaultValue (varies) - Default value when not set

Configuration properties:

• Mandatory (boolean) - Whether field is required
• Unique (boolean) - Whether values must be unique
• IsEncrypted (boolean) - Whether values are encrypted
• ShowInReports (boolean) - Whether field appears in reports
• GroupName (string) - UI grouping name
• GroupPriority (int) - Display order in UI
• Owner (GUID) - Owner entity GUID
• CustomEntityTypeId (GUID) - For custom entity types

Limitations and Important Notes

1. Image fields cannot be read via GET

   • Attempting to read Image custom fields returns error: "SdkErrorCode": "InvalidOperation", "Message": "Getting a value on an image custom fields is not supported."
   • Image fields must be accessed through other mechanisms

2. Field names with spaces or special characters have limitations

   • Custom fields CAN be created with spaces in names via /customField endpoints
   • However, they CANNOT be accessed using the q= query syntax (e.g., /entity?q=entity={guid},Field Name will fail)
   • Recommendation: Use camelCase or underscore naming for maximum compatibility
   • Examples: DepartmentCode, Badge_Number, EmployeeID

3. Custom field names are case-insensitive

   • DepartmentCode and departmentcode refer to the same field
   • However, it's recommended to use consistent casing for readability

4. Default values are applied at creation time

   • When you create a custom field with a default value, existing entities receive that value
   • New entities created after the custom field exists will also receive the default value

5. DateTime filtering not supported in Web SDK queries

   • You cannot filter custom fields by DateTime values using the /entity endpoint query syntax
   • DateTime filtering IS supported in EntityConfiguration reports

6. Custom field GUIDs required for filtering

   • Report filters require the custom field GUID, not the name
   • Custom field names cannot be used in CustomField() filter syntax

7. Value type enforcement

   • Setting an invalid value for a data type returns an error
   • Example: Setting "abc" for a Numeric field returns: "Could not convert abc based on Numeric."

Choosing the Right Method

When to use dedicated endpoints (/customField/...)

• Reading or writing a single custom field value
• Simple CRUD operations on custom field values
• Creating or deleting custom field definitions
• Direct access without querying other entity properties

When to use entity query syntax (/entity?q=...)

• Reading multiple custom fields at once
• Combining custom fields with standard entity properties
• Batch operations across multiple entities
• When custom field access is part of larger entity query

When to use report filtering

• Finding entities by custom field values
• Complex queries with multiple conditions
• Generating entity lists based on custom criteria
• Reporting and analytics scenarios

See Also

• Entity Operations - General entity CRUD operations
• Referencing Entities - Entity queries and filtering