Entity Service

Last updated
Save as PDF

Read many entities
Read one entity
Read entity details
Update entity details
Read entity links
Read entity tags
Create entity
Update all basic fields an entity
Update specific fields on many entities
Delete entity
Read entity properties
Read custom fields on an entity
Update custom field values on an entity
Read all fieldsets by entity type

GET /entities

Description:

Get many entities by entity type.

Parameters:

type:Three character Entity Type value
first:The index of an array
count:The number of objects to return
updateDateStartDate:(yyyy-mm-dd)
updateDateEndDate:(yyyy-mm-dd)
createDateStartDate:(yyyy-mm-dd)
createDateEndDate:(yyyy-mm-dd)
filter:A filter string created by the POST /filter request.
operableFilter:An operable filter string created by the POST /operablefilter request.
fieldsets:Retrieves custom fields with values for each entity. This is false by default.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tentant-end-point]/api/entities?type=SKI&first=0&count=2
Authorization: (Your Basic Auth)
Accept: application/json;charset=UTF-8

Response:

{
  "first": 0,
  "count": 2,
  "unfilterdCount": 246,
  "entities": [
    {
      "entityDiscriminator": "SKI",
      "bn": "0415000000JN",
      "contentCompletionDate": null,
      "contentStatus": {
        "id": "IDFD",
        "displayableName": "Identified",
        "editName": "1) Identified"
      },
      "description": null,
      "details": null,
      "enterpriseApproval": {
        "bn": "ZZ0M000000FG",
        "name": "Unspecified",
        "label": "Enterprise Approval",
        "description": "Skill Enterprise Approval"
      },
      "lastUpdateDate": "2016-05-20T20:04:39.074+0000",
      "lifecycleState": {
        "bn": "ZZ0M0000006X",
        "name": "In Use",
        "label": "Lifecycle State",
        "description": "Lifecycle State"
      },
      "name": "DLF Skill",
      "updatedByBn": {
        "bn": "040E000004LM",
        "firstName": "Integration",
        "lastName": "Administrator",
        "deleted": false
      },
      "createdByBn": {
        "bn": "040E000004LM",
        "firstName": "Integration",
        "lastName": "Administrator",
        "deleted": false
      },
      "enterpriseApproved": false,
      "displayableName": "DLF Skill",
      "new": false,
      "canDelete": true,
      "canEdit": true,
      "canEditProfileSettings": false,
      "canSendInvite": false,
      "canEditCustomFields": true,
      "isWorkflowEditor": true,
      "canImportLinkedInProfile": false
    },
    ...
  ]
}

GET /entities/{entityBn}

Description:

Get the basic info for an entity.

Parameters:

fieldsets:(true/false)

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/ZZ1500001HXJ
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "entityDiscriminator": "SKI",
  "bn": "ZZ1500001HXJ",
  "contentCompletionDate": null,
  "contentStatus": {
    "id": "IDFD",
    "displayableName": "Identified",
    "editName": "1) Identified"
  },
  "description": "Ability to develop applications within the Microsoft ASP framework",
  "enterpriseApproval": {
    "bn": "ZZ0M000000FG",
    "name": "Unspecified",
    "label": "Enterprise Approval",
    "description": "Skill Enterprise Approval"
  },
  "lastUpdateDate": "2010-10-16T23:29:16.000+0000",
  "lifecycleState": {
    "bn": "ZZ0M0000006X",
    "name": "In Use",
    "label": "Lifecycle State",
    "description": "Lifecycle State"
  },
  "name": "ASP Development",
  "updatedByBn": {
    "firstName": "SYSTEM",
    "lastName": "USER",
    "deleted": false
  },
  "createdByBn": {
    "firstName": "SYSTEM",
    "lastName": "USER",
    "deleted": false
  },
  "enterpriseApproved": false,
  "displayableName": "ASP Development",
  "new": false,
  "canDelete": true,
  "canEdit": true,
  "canEditProfileSettings": false,
  "canSendInvite": false,
  "canEditCustomFields": true,
  "isWorkflowEditor": true,
  "canImportLinkedInProfile": false
}

GET /entities/{entityBn}/details

Description:

Returns the "details" field's information on a given entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/0439000002WH/details
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "bn": "0439000002WH",
  "details": "This is a value in details field."
}

POST /entities/{entityBn}/details

Description:

Updates the "details" field's information on a given entity.

Parameters (body)

bn:(string value)This is the Barometer Number of the details object.
details:(string value)This space accepts plain text and a some HTML tags. The acceptable tags are: "a", "b", "br" "h1", "i", "ol" "ul", and "li".

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8
Content-Type:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/0439000002WH/details
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
  "bn": "0439000002WH",
  "details": "Updated Details"
}

Response:

{
  "bn": "0439000002WH",
  "details": "Updated Details"
}

GET /entities/{entityBn}/links

Description:

Returns the list of links on a given entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/0439000002WH/links
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

[
  {
    "bn": "040V000007PR",
    "name": "Google",
    "url": "https://www.google.com/",
    "displayableName": "Google",
    "new": false
  }
]

GET /entities/{entityBn}/tags

Description:

Returns the list of tag entities on a given entity

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/0439000002WH/tags
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

[
  {
    "bn": "041F000001LZ",
    "details": null,
    "name": "Simplification",
    "entityDiscriminator": "TAG",
    "displayableName": "Simplification",
    "new": false
  }
]

POST /entities

Description:

Create an entity. Some entities may need additional properties in the body to be successfully created.

Parameters (body):

entityDiscriminator:Three character Entity Type value
Name:A string that identifies the entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8
Content-Type:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
  "entityDiscriminator":"TEC",
  "description":"This is a Technology that was created using the REST API.",
  "domain": {"bn": "040M000016WP"},
  "name": "bit Test Technology (API Created)",
  "technologyType": {"code": "TEC"},
  "lifecycleState": {"bn": "ZZ0M0000006X"}
}

Response:

{
  "entityDiscriminator": "TEC",
  "acronym": null,
  "bn": "041H00000V28",
  "contentCompletionDate": null,
  "contentStatus": {
    "id": "IDFD",
    "displayableName": "Identified",
    "editName": "1) Identified"
  },
  "description": "This is a Technology that was created using the REST API.",
  "details": null,
  "domain": {
    "bn": "040M000016WP",
    "name": "Default",
    "label": "Domain",
    "description": "Technology Domain",
    "type": null
  },
  "enterpriseApproval": {
    "bn": "040M000003JB",
    "name": "Unspecified",
    "label": "Enterprise Approval",
    "description": "Technology Enterprise Approval",
    "type": "UNSPECIFIED"
  },
  "lastUpdateDate": "2017-05-09T16:28:22.882+0000",
  "lifecycleState": {
    "bn": "040M000000HT",
    "name": "Tolerate",
    "label": "Lifecycle State",
    "description": "Technology Lifecycle",
    "type": "ACTIVE"
  },
  "name": "bit Test Technology (API Created)",
  "releaseDate": null,
  "retireDate": null,
  "technologyType": {
    "code": "TEC",
    "name": "Technology"
  },
  "technologyVersion": null,
  "updatedByBn": {
    "bn": "040E00003ML7",
    "firstName": "David",
    "lastName": "Lewis-Frazier",
    "deleted": false
  },
  "createdByBn": {
    "bn": "040E00003ML7",
    "firstName": "David",
    "lastName": "Lewis-Frazier",
    "deleted": false
  },
  "url": null,
  "enterpriseApproved": false,
  "displayableName": "bit Test Technology (API Created)",
  "new": false
}

PATCH /entities

Description:

Update basic fields and custom fields for up to 10 entities of the same Entity Type. The fields will be updated for each entity that is provided.

Parameters (body):

bns:An array of BNs that you want to edit. You may edit up to 10 entities per request. All of the entities must have the same entity type.
properties:A JSON object that contains properties and values. The keys custom fields are the Field's fieldId.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8
Content-Type:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
    "bns" : ["ZZ180000001O", "ZZ180000AB48"],
    "properties" : {
        "description" : "new description",
        "systemType" : "Batch Job",
        "fieldTypeTextTextBox" : "new text box",
        "fieldTypeBooleanDropdown" : false,
        "fieldTypeIntegerNumber" : 3,
        "fieldTypeDecimalNumber" : -3.14159,
        "fieldTypeDateTextBox" : "2020-12-12",
        "fieldTypeDateTimeTextBox" : "2020-12-11 14:10:10",
        "fieldTypeTimeTextBox" : "14:38:00",
        "fieldTypeTextSingleSelect" : "value1",
        "fieldTypeTextMultiSelect" : "value1,value 2"
    }
}

Response:

[
    {
        "description": "new description",
        "bn": "ZZ180000001O",
				"systemType" : "Batch Job",
				"fieldTypeTextTextBox" : "new text box",
        "fieldTypeBooleanDropdown" : false,
        "fieldTypeIntegerNumber" : 3,
        "fieldTypeDecimalNumber" : -3.14159,
        "fieldTypeDateTextBox" : "2020-12-12",
        "fieldTypeDateTimeTextBox" : "2020-12-11 14:10:10",
        "fieldTypeTimeTextBox" : "14:38:00",
        "fieldTypeTextSingleSelect" : "value1",
        "fieldTypeTextMultiSelect" : "value1,value 2"
    },
     {
        "description": "new description",
        "bn": "ZZ180000AB48",
				"systemType" : "Batch Job",
				"fieldTypeTextTextBox" : "new text box",
        "fieldTypeBooleanDropdown" : false,
        "fieldTypeIntegerNumber" : 3,
        "fieldTypeDecimalNumber" : -3.14159,
        "fieldTypeDateTextBox" : "2020-12-12",
        "fieldTypeDateTimeTextBox" : "2020-12-11 14:10:10",
        "fieldTypeTimeTextBox" : "14:38:00",
        "fieldTypeTextSingleSelect" : "value1",
        "fieldTypeTextMultiSelect" : "value1,value 2"
    }
]

PUT /entities

Description:

Update an entity. Some entities may need additional properties in the body to be successfully updated.

Parameters (body):

entityDiscriminator:Three character Entity Type value
bn:The Barometer Number for the entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8
Content-Type:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
  "entityDiscriminator": "PER",
  "bn": "040E0000DGNZ",
  "firstName": "Jane",
  "lastName": "Eod",
  "emailAddress": "jane.eod@notrealemail.com",
  "status": {
    "code": "ACTIVE"
}

Response:

{
  "entityDiscriminator": "PER",
  "bn": "040E0000DGNZ",
  "serviceAccountBtnText": "Create Service Account",
  "inviteBtnText": "Re-Send Invite",
  "details": null,
  "emailAddress": "jane.eod@notrealemail.com",
  "emailAddressType": {
    "code": "WRK",
    "name": "WRK"
  },
  "externalId": null,
  "firstName": "Jane",
  "lastName": "Eod",
  "lastUpdateDate": "2017-05-09T16:37:44.964+0000",
  "phoneNumbers": [],
  "photoAssetStoreUrl": null,
  "photoSourceType": "NONE",
  "status": {
    "code": "ACTIVE",
    "name": "Active"
  },
  "updatedByBn": {
    "bn": "040E00003ML7",
    "firstName": "David",
    "lastName": "Lewis-Frazier",
    "deleted": false
  },
  "createdByBn": {
    "bn": "040E00003ML7",
    "firstName": "David",
    "lastName": "Lewis-Frazier",
    "deleted": false
  },
  "description": null,
  "displayableName": "Jane Eod",
  "name": "Jane Eod",
  "new": false
}

DELETE /entities/{entityBn}

Description:

Remove an entity using its BN as an identifier.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/040E0000DGNZ
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "successfulEntities": [
    {
      "bn": "040E0000DGNZ",
      "details": null,
      "emailAddress": "jane.eod@notrealemail.com",
      "emailAddressType": {
        "code": "WRK",
        "name": "WRK"
      },
      "externalId": null,
      "firstName": "Jane",
      "lastName": "Eod",
      "lastUpdateDate": "2017-05-09T16:38:58.000+0000",
      "phoneNumbers": null,
      "photoAssetStoreUrl": null,
      "photoSourceType": "NONE",
      "status": {
        "code": "ACTIVE",
        "name": "Active"
      },
      "updatedByBn": {
        "bn": "040E00003ML7",
        "firstName": "David",
        "lastName": "Lewis-Frazier",
        "deleted": false
      },
      "createdByBn": {
        "bn": "040E00003ML7",
        "firstName": "David",
        "lastName": "Lewis-Frazier",
        "deleted": false
      },
      "description": null,
      "entityDiscriminator": "PER",
      "displayableName": "Jane Eod",
      "name": "Jane Eod",
      "new": false
    }
  ]
}

GET /entitytypes/{entityType}/properties

Description:

Returns the list of properties that are available for a given Entity Type. You can filter the list using query parameters, and you're able to chain the query parameters together.

Parameters:

searchable:(boolean) You can use a "searcableName" property to find this object
securable:(boolean) Securable properties can be locked down by the "Field Level Security" feature.
required:(boolean) These fields are required for entity creates and updates.
formable:(boolean) Formable properties can be added to a Remediation Form.
uploadable:(boolean) Uploadable properties can be used in a CSV import.
searchableName:(string) The Searchable Name is value that is unique for property within the Entity Type umbrella.
displayValues:(boolean) Show the possible values for each property. Boolean, Date, and String values can be any valid Boolean, Date, or String respectively.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entitytypes/SYS/properties?formable=true
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response (truncated):

[
    {
        "bn": "464600000362",
        "name": "Details",
        "description": "System Details",
        "key": "details",
        "propertyType": "STRING",
        "formable": true,
        "searchableName": "details",
        "searchable": true,
        "securable": false,
        "uploadable": false,
        "values": "STRING"
    },
    {
        "bn": "0446000000LL",
        "name": "System Type",
        "description": "System Type",
        "key": "systemType",
        "propertyType": "NUMBERED",
        "formable": true,
        "searchableName": "systemType.bn",
        "searchable": true,
        "securable": true,
        "uploadable": true,
        "values": [
            {
                "bn": "ZZ0M000000CN",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Composite",
                "helpContent": null,
                "order": 1
            },
            {
                "bn": "ZZ0M000000CP",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Custom Application",
                "helpContent": null,
                "order": 2
            },
            {
                "bn": "ZZ0M000000CQ",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Custom Database",
                "helpContent": null,
                "order": 3
            },
            {
                "bn": "ZZ0M000000CR",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Infrastructure",
                "helpContent": null,
                "order": 4
            },
            {
                "bn": "ZZ0M000000CS",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Batch Job",
                "helpContent": null,
                "order": 5
            },
            {
                "bn": "ZZ0M000000CT",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Module",
                "helpContent": null,
                "order": 6
            },
            {
                "bn": "ZZ0M000000CV",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Modified Packaged Application",
                "helpContent": null,
                "order": 7
            },
            {
                "bn": "ZZ0M000000CW",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Package Application",
                "helpContent": null,
                "order": 8
            },
            {
                "bn": "ZZ0M000000CX",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Package Database",
                "helpContent": null,
                "order": 9
            },
            {
                "bn": "ZZ0M000000CZ",
                "dataListItemType": null,
                "dataListName": "System Type",
                "dataListType": "SYSTEM_TYPE",
                "description": "System Type",
                "displayableName": "Process",
                "helpContent": null,
                "order": 10
            }
        ]
    }, ...
]

GET entities/{entityBn}/fieldsets/{fieldsetBn}

Description:

View a fieldset and its fields that are on an entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/041800000L2R/fieldsets/040I000000K9
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "bn": "040I000000K9",
  "expanded": true,
  "fields": [
    {
      "bn": "040L00000341",
      "choices": [
        {
          "bn": "040P0000DF6Z",
          "displayValue": "one point one",
          "storedValue": "1.1"
        },
        {
          "bn": "040P0000DJZ1",
          "displayValue": "two point two",
          "storedValue": "2.2"
        },
        {
          "bn": "040P0000DJZ2",
          "displayValue": "three point three",
          "storedValue": "3.3"
        }
      ],
      "dataType": "DECIMAL",
      "decimalPlaces": 2,
      "displayType": "MULTI_SELECT",
      "fieldId": "dlf-1",
      "fieldLength": 12,
      "controlLevel": "EDITABLE",
      "name": "DLF Decimal Multi",
      "values": [
        "040P0000DF6Z"
      ]
    }
  ],
  "name": "DLF Fieldst"
}

POST entities/{entityBn}/fieldsets/{fieldsetBn}

Description:

Update field values that are on an entity.

Parameters (body)

entityBn:(String)The Barometer Number for the entity.
fields:(JSON Object)The field object you'd like to change. This JSON object includes the fieldBn and a values array of value objects.
fieldsetBn:(String)The Barometer Number for the fieldset on an entity.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/json;charset=UTF-8
Content-Type:application/json;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entities/041800000L2R/fieldsets/040I000000K9
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
  "entityBn": "041800000L2R",
  "fields": [
    {
      "fieldBn": "040L00000341",
      "values": [{"value":"040P0000DJZ1"}, {"value":"040P0000DJZ2"}]
    }
  ],
  "fieldsetBn": "040I000000K9"
}

Response:

[]

GET /entitytypes/{entityType}/fieldsets

Description:

Get all fieldsets contained on a given entity type.

Headers:

Authorization:(Your Basic Auth String)
Accept:application/plain;charset=UTF-8

Example:

Request:

https://[tenant-end-point]/api/entitytypes/DEM/fieldset
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

[
  {
    "bn": "040I000000H9",
    "expanded": true,
    "fields": [
      "040L000002KJ"
    ],
    "helpText": "",
    "name": "Financial Suites",
    "notes": "",
    "locationBn": "001700000065",
    "orderVal": 0
  }
]

Contents

GET /entities

GET /entities/{entityBn}

GET /entities/{entityBn}/details

POST /entities/{entityBn}/details

GET /entities/{entityBn}/links

GET /entities/{entityBn}/tags

POST /entities

PATCH /entities

PUT /entities

DELETE /entities/{entityBn}

GET /entitytypes/{entityType}/properties

GET entities/{entityBn}/fieldsets/{fieldsetBn}

POST entities/{entityBn}/fieldsets/{fieldsetBn}

GET /entitytypes/{entityType}/fieldsets