web sdk custom entity types

Managing custom entity types

Custom entity type descriptors describe entity types registered in Security Center by products, plugins, or custom integrations. 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.
• LargeIcon, SmallIcon: URIs for the large and small icons, or null when an icon is not defined. A file:/// URI identifies a file on the Security Center server.
• 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, such as 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 (for example, Xml, UtcDate, Xml, Collection, Xml).
  • SourceProperty: The source of the audit data in the entity (for example, 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 GUID of the default map layer for entities of this type, or 00000000-0000-0000-0000-000000000000 if no default map layer is specified.

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.

If the type does not exist, the response contains Rsp.Status: "Ok" but omits Rsp.Result.

Creating a custom entity

Create a custom entity with NewEntity(CustomEntity,{custom-entity-type-id}). Replace {custom-entity-type-id} with the Id of the intended type returned by GET /customEntityType/all.

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, send this request:

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.

A successful deletion returns:

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

See also

• The /entity endpoint: The /entity endpoint and shared q= query syntax.
• Referencing entities: Entity discovery, search, and parameter formats.