Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

Getting Started

  1. Last updated
  2. Save as PDF

Contents

Introduction

The bIT REST API enables users to programmatically search for, and manipulate data within barometerIT. This document will walk you through creating an entity, making association to that entity, and searching for your entity within a collection. More information about REST API services and conventions can be found in the "About Integrations" article.

Authorization

Our REST API uses a Basic Authorization string to authorize each request. This string is a combination of your username and password. Tools like Postman can help you generate a valid basic auth string. 

Entity Types

One of the first things our users ask is "how do I create an entity using the REST API?" The first step is figuring out which type of Entity you want to create. The following is a list of the entities and their type alias. The alias is used to define which entity type you are targeting.

{
    "Actors": "ACT",
    "Capabilities": "CAP",
    "Collections": "CIR",
    "Companies": "COM",
    "Connections": "CON",
    "Dashboards": "LYT",
    "Data": "DAT",
    "Demands": "DEM",
    "Deployments": "PHY",
    "Documents": "AST",
    "Markets": "MKT",
    "Organizations": "ORG",
    "People": "PER",
    "Products": "PRD",
    "Reports": "ADQ",
    "Rules": "CRL",
    "Skills": "SKI",
    "Standards": "STA",
    "Strategies": "STR",
    "Systems": "SYS",
    "Tags": "TAG",
    "Technologies": "TEC"
}

For this example we'll be using the Deployment Entity Type "PHY". 

Creating a Deployment Entity

Before we create an instance of a Deployment Entity we need a few basic values. Deployment Entities basic properties are name, domain, entityDiscriminator, lifecycleState, and type. These properties and their values can be found using the /entityproperties/{entityType} request.

Request:

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

Response (truncated):

[
  {
    "bn": "0446000001CT",
    "name": "Domain",
    "description": "Deployment Domain",
    "key": "domain",
    "propertyType": "NUMBERED",
    "formable": true,
    "searchableName": "domain.bn",
    "searchable": true,
    "securable": true,
    "uploadable": true,
    "values": [
      [
        {
          "bn": "040M000002GL",
          "dataListItemType": null,
          "dataListName": "Domain",
          "dataListType": "PHYSICAL_DOMAIN",
          "description": "Deployment Domain",
          "displayableName": "Default",
          "helpContent": null,
          "order": 0
        }
      ]
    ]
  },
  {
    "bn": "0446000001G0",
    "name": "Name",
    "description": "Deployment Name",
    "key": "name",
    "propertyType": "STRING",
    "formable": true,
    "searchableName": "name",
    "searchable": true,
    "securable": true,
    "uploadable": true,
    "values": "STRING"
  },
  {
    "bn": "0446000001CV",
    "name": "Type",
    "description": "Deployment Type",
    "key": "type",
    "propertyType": "NUMBERED",
    "formable": true,
    "searchableName": "type.bn",
    "searchable": true,
    "securable": true,
    "uploadable": true,
    "values": [
      [
        {
          "bn": "040M000002HJ",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Application Server",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002H0",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Data Center",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002H4",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Rack",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002GQ",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Region",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002HN",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "SAN",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002H8",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Server",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002HD",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Virtual Server",
          "helpContent": null,
          "order": 0
        },
        {
          "bn": "040M000002GV",
          "dataListItemType": null,
          "dataListName": "Type",
          "dataListType": "PHYSICAL_TYPE",
          "description": "Deployment Type",
          "displayableName": "Zone",
          "helpContent": null,
          "order": 0
        }
      ]
    ]
  }, 
  ...
]

The key value is the property key and a value's bn is the property value. So an example Deployment type would be. 

"type": {"bn": "040M000002GV"}

Once you have the values for the properties, you can build POST /entities request.

Request:

https://[tenant-end-point]/api/c/entities
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8
 
{
  "entityDiscriminator":"PHY",
  "domain": {"bn": "040M000002GL"},
  "name": "Getting Started Deployment",
  "type": {"bn": "040M000002GV"},
  "lifecycleState": {"bn": "040M000002GB"}
}

Response:

{
  "entityDiscriminator": "PHY",
  "acronym": null,
  "bn": "044L00000044",
  "color": "666666",
  "contentCompletionDate": null,
  "contentStatus": {
    "id": "IDFD",
    "displayableName": "Identified",
    "editName": "1) Identified"
  },
  "description": null,
  "details": null,
  "domain": {
    "bn": "040M000002GL",
    "name": "Default",
    "label": "Domain",
    "description": "Deployment Domain",
    "type": null
  },
  "externalId": null,
  "lastUpdateDate": "2017-05-12T17:50:47.436+0000",
  "lifecycleState": {
    "bn": "040M000002GB",
    "name": "Active",
    "label": "Lifecycle",
    "description": "Deployment Lifecycle",
    "type": "ACTIVE"
  },
  "name": "Getting Started Deployment",
  "treeNodeId": null,
  "type": {
    "bn": "040M000002GV",
    "name": "Zone",
    "label": "Type",
    "description": "Deployment Type",
    "type": null
  },
  "updatedByBn": {
    "bn": "040E000004LM",
    "firstName": "Integration",
    "lastName": "Administrator",
    "deleted": false
  },
  "displayableName": "Getting Started Deployment",
  "new": false,
  "parents": 0,
  "children": 0
}

You've created a basic Deployment Entity! The rest of the Deployment properties were set to the default values, and a BN was assigned to the deployment. The BN is the unique identifier for barometer objects. You will use this BN throughout the rest of the tutorial.

Searching a collection

You've created a Deployment, and now you'd like to view other Deployments like it. You can use the GET /entities request to collect that kind of data. This request has a default filter applied that only shows ACTIVE entities. You can apply a custom filter using the data from the /entitytypes/{entityType}/properties request from earlier. 

Make a filter string

The POST /filter request will help you build a filter string that can be passed as a query parameter. These strings are reusable. If you wanted to search for Deployments of a specific Type using the GET /entities request or the GET /association request, you can use the same filter string. In this example you'll create a filter for Deployments with "Any" lifecycleState and a type of "Zone".

Request:

https://[tenant-end-point]/api/c/filter
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
body: {
  "params": [
    {"0446000001CN": []},
    {"0446000001CV": ["040M000002GV"]}
  ],
  "searchString": null
}

Response:

%7B%22params%22%3A%5B%7B%220446000001CN%22%3A%5B%5D%7D%2C%7B%220446000001CV%22%3A%5B%22040M000002GV%22%5D%7D%5D%2C%22searchString%22%3Anull%7D

The params object is a stringified array of params. A param is a property key and array of property values. Now use the filter string that you got from the response as a query parameter in the GET /entities request. 

Request:

https://[tenant-end-point]/api/c/entities?type=PHY&filter=%7B%22params%22%3A%5B%7B%220446000001CN%22%3A%5B%5D%7D%2C%7B%220446000001CV%22%3A%5B%22040M000002GV%22%5D%7D%5D%2C%22searchString%22%3Anull%7D
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "first": 0,
  "count": 10,
  "unfilterdCount": 5,
  "entities": [
    {
      "entityDiscriminator": "PHY",
      "acronym": null,
      "bn": "044L00000044",
      "color": "666666",
      "contentCompletionDate": null,
      "contentStatus": {
        "id": "IDFD",
        "displayableName": "Identified",
        "editName": "1) Identified"
      },
      "description": null,
      "details": null,
      "domain": {
        "bn": "040M000002GL",
        "name": "Default",
        "label": "Domain",
        "description": "Deployment Domain",
        "type": null
      },
      "externalId": null,
      "lastUpdateDate": "2017-05-12T17:50:47.000+0000",
      "lifecycleState": {
        "bn": "040M000002GB",
        "name": "Active",
        "label": "Lifecycle",
        "description": "Deployment Lifecycle",
        "type": "ACTIVE"
      },
      "name": "Getting Started Deployment",
      "treeNodeId": null,
      "type": {
        "bn": "040M000002GV",
        "name": "Zone",
        "label": "Type",
        "description": "Deployment Type",
        "type": null
      },
      "updatedByBn": {
        "bn": "040E000004LM",
        "firstName": "Integration",
        "lastName": "Administrator",
        "deleted": false
      },
      "displayableName": "Getting Started Deployment",
      "new": false,
      "canDelete": true,
      "canEdit": true,
      "canEditProfileSettings": false,
      "canSendInvite": false,
      "canEditCustomFields": true,
      "isWorkflowEditor": true,
      "canImportLinkedInProfile": false,
      "parents": 0,
      "children": 0
    }
  ]
}

Read Relationship details

Things in bIT are connected to each other. This next example will show you how to add a contact to your Deployment. You'll need some information about the entities on either end to make an relationship. The /relationshippatterns request takes the entity types for both ends of the relationship and returns the relationshipTypes and qualifiers.

Request:

https://[tenant-end-point]/api/c/relationshippatterns?fromType=PHY&toType=PER
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

[
  {
    "fromType": "PHY",
    "toType": "PER",
    "relationshipType": {
      "name": "Has Contact",
      "type": "HAS_CONTACT"
    },
    "qualifiers": [
      {
        "bn": "040M0000107Z",
        "name": "Administrative"
      },
      {
        "bn": "040M0000109K",
        "name": "Business"
      },
      {
        "bn": "040M000010C5",
        "name": "Primary"
      },
      {
        "bn": "040M000010DR",
        "name": "Technical"
      },
      {
        "bn": "040M000010GC",
        "name": "Vendor"
      }
    ]
  }
]

The relationshipType's Type object defines the type of relationship between the Deployment and the Person/Contact. The Qualifiers supply additional information for the relationship.

Add a contact to a Deployment

To make an association you should use the PUT /relationship/{fromBn}/{relationshipType}/{toBn} request. You'll add a Person entity to the Deployment entity as a contact. 

Request:

https://[tenant-end-point]/api/c/relationship/044L00000044/HAS_CONTACT/040E000004LM?qualifierBn=040M000010C5
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8

Response:

{
    "successfulBns": [
        "044L00000044",
        "040E000004LM"
    ],
    "proposedChangeBns": [],
    "transactionIds": [
        "717734cc6fcd406e9eac6e3f014959d4"
    ]
}

The successfulBns are ones that don't need to be approved by an editor. BNs that are in the proposedChangeBns array need to be approved before they will show up as related.

Reading Systems associated to a Deployment

The last thing you are going to do in this walkthrough is read relationships by entity type. To do this use the request GET /relationships/{from}/{relationshipType}/{to}. This example request will search for any Systems that are related to a Deployment directly.

Request:

https://[tenant-end-point]/api/c/relationships/044L00000044/ANY/SYS
Authorization: Basic {your basic auth}
Accept: application/json;charset=UTF-8

Response:

{
  "first": 0,
  "count": 25,
  "nodes": [
    {
      "name": "Getting Started Deployment",
      "bn": "044L00000044"
    },
    {
      "name": "System Release A Release 4",
      "bn": "ZZ180000000U"
    },
    {
      "name": "API SYS (135904256526400130)",
      "bn": "041800001BJJ"
    }
  ],
  "relationships": [
    {
      "fromBn": "044L00000044",
      "toBn": "ZZ180000000U",
      "relationshipType": "RELATED_TO",
      "qualifier": {
        "name": "Hosts",
        "bn": "040M0000118C"
      },
      "properties": null
    },
    {
      "fromBn": "044L00000044",
      "toBn": "041800001BJJ",
      "relationshipType": "RELATED_TO",
      "qualifier": {
        "name": "Hosts",
        "bn": "040M0000118C"
      },
      "properties": null
    }
  ]
}