web sdk custom entity types

Managing custom entity types

Custom entity types are user-defined entity types registered in Security Center. Each custom entity type defines its own name, icons, privileges, supported events, auditable properties, capabilities, and hierarchy rules. The Web SDK provides endpoints to list, retrieve, and delete custom entity type descriptors. Creating or modifying custom entity type descriptors is not available through the Web SDK.

Listing all custom entity types

Retrieve every custom entity type registered in the system.

GET /customEntityType/all

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "Id": "025f7211-622e-4b4d-a155-ca5d69793e09",
        "Name": "AED Unit",
        "NameKey": "CustomEntityTypeName",
        "SingleInstance": false,
        "Capabilities": "CreateDelete, MapSupport, CanBeFederated, IsVisible, MaintenanceMode",
        "Version": {
          "Major": 1,
          "Minor": 0,
          "Build": -1,
          "Revision": -1
        },
        "Icon": null,
        "LargeIcon": null,
        "SmallIcon": null,
        "ResourceManagerTypeName": null,
        "ViewPrivilege": {
          "Id": "0896b350-7225-4a53-8ddc-e8365cae456e",
          "IsGlobalPrivilege": false,
          "IsEntityPrivilege": true
        },
        "AddPrivilege": { "..." : "..." },
        "DeletePrivilege": { "..." : "..." },
        "ModifyPrivilege": { "..." : "..." },
        "SupportedEvents": [],
        "SupportedCustomEvents": [],
        "AuditableProperties": [],
        "HierarchicalChildTypes": [],
        "HierarchicalChildCustomTypes": [],
        "DefaultMapLayerId": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }
}

Response fields

• Id: The unique identifier for the custom entity type
• Name: The display name of the custom entity type
• NameKey: The localization resource key for the type name, or null if not localized
• SingleInstance: true if only one entity of this type is allowed in the system, false if multiple entities are allowed
• Capabilities: Comma-separated list of descriptor capability flags. These flags describe product behavior and UI support; they do not replace Web SDK privilege checks. Possible values include:
  • None: No special capability flag is set.
  • CreateDelete: Entities of this type can be created and deleted from Config Tool.
  • MapSupport: Entities of this type can be placed on maps.
  • CanBeFederated: Entities of this type can be federated to other systems.
  • IsVisible: Entities of this type are visible in the Security Center UI.
  • MaintenanceMode: Entities of this type can be put into maintenance mode.
  • HasRunningState: Entities of this type expose a running state.
• Version: The version of the custom entity type descriptor, with Major, Minor, Build, Revision, MajorRevision, and MinorRevision fields. Build, Revision, MajorRevision, and MinorRevision can be -1 for types versioned only at the Major.Minor level.
• Icon, LargeIcon, SmallIcon: Icon URIs (typically file:/// paths on the server), or null if no icons are defined. These are server-local references, not fetchable client-side URLs.
• ResourceManagerTypeName: The assembly-qualified name of the resource manager for localized strings, or null if not localized
• ViewPrivilege, AddPrivilege, DeletePrivilege, ModifyPrivilege: Privilege descriptors that control access to entities of this type. Each contains the privilege Id and whether it is a global or entity-level privilege.
• SupportedEvents: List of event type names that entities of this type can raise
• SupportedCustomEvents: List of custom event IDs that entities of this type can raise. Values are typically positive integers matching IDs assigned when the custom event was created. Some system-defined types also return negative integers (for example, Automation rule returns [-6]); negative IDs cannot be created through the Web SDK.
• AuditableProperties: List of properties that are tracked for audit purposes. Each entry contains:
  • Path: The path from the root to the audited section (e.g., root/ExpireTimeUtc)
  • Name: The display name of the property
  • NameKey: The localization resource key for the property name, or null
  • Hints: Formatting hints for displaying changes (e.g., Xml, UtcDate, Xml, Collection, Xml)
  • SourceProperty: The source of the audit data in the entity (e.g., Xml)
• HierarchicalChildTypes: List of built-in entity types that are allowed as children in the entity hierarchy
• HierarchicalChildCustomTypes: List of custom entity type GUIDs that are allowed as children
• DefaultMapLayerId: The default map layer for entities of this type

Retrieving a specific custom entity type

Retrieve a single custom entity type by its GUID.

GET /customEntityType/{custom-entity-type-id}

Replace {custom-entity-type-id} with the GUID of the custom entity type descriptor. Rsp.Result contains the same descriptor fields as a single entry from the listing endpoint.

Creating a custom entity

Create an instance of a custom entity type using the standard entity creation syntax. The second argument to NewEntity is the custom entity type GUID.

POST /entity?q=entity=NewEntity(CustomEntity,{custom-entity-type-id}),Name=MyEntity,Guid

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Guid": "{new-entity-guid}"
    }
  }
}

To delete a custom entity instance, use the standard entity deletion endpoint:

DELETE /entity/{entity-guid}

Listing custom entities

To list or search custom entities, use the configuration report:

GET /report/CustomEntityConfiguration?q=Page=1,PageSize=10

To restrict the results to one or more custom entity types:

GET /report/CustomEntityConfiguration?q=CustomEntityTypes@{custom-entity-type-guid},Page=1,PageSize=10,ReturnFields@Name@Description

For the full query options, see Referencing entities.

Deleting a custom entity type

Delete a custom entity type descriptor from the system.

DELETE /customEntityType/{custom-entity-type-id}

Replace {custom-entity-type-id} with the GUID of the custom entity type descriptor to delete.

Important

This operation requires an administrator account. It also fails if entities of the custom type still exist in the system. Delete all entities of the type before removing the type descriptor.

Successful response

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