Skip to main content
Planview Customer Success Center

Entity Service

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
  }
]