Skip to main content

 

Planview Customer Success Center

Field Services

GET /fields

Description:

Returns all the custom fields that exist in barometerIT.

Headers:

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

Example:

Request:

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

Response:

[
  {
    "bn": "040L000002JQ",
    "dataType": "TEXT",
    "displayType": "TEXT_BOX",
    "controlLevel": "NONE",
    "name": "2015 budget"
  },
  {
    "bn": "040L000002LF",
    "dataType": "TEXT",
    "displayType": "TEXT_BOX",
    "controlLevel": "EDITABLE",
    "name": "Achievement Date"
  },
  {
    "bn": "040L00000303",
    "dataType": "TEXT",
    "displayType": "TEXT_BOX",
    "controlLevel": "VISIBLE",
    "name": "Actual - Budget 2016 (CAPEX)"
  },
  {
    "bn": "040L00000304",
    "dataType": "TEXT",
    "displayType": "TEXT_BOX",
    "controlLevel": "EDITABLE",
    "name": "Actual - Budget 2016 (OPEX)"
  }, ...
]

 

 

GET /fields/{fieldBn}

Description:

Return one custom fields.

Headers:

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

Example:

Request:

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

Response:

{
  "bn": "040L000002JQ",
  "choices": [],
  "dataType": "INTEGER",
  "decimalPlaces": 2,
  "displayType": "MULTI_SELECT",
  "fieldId": "2015budget",
  "fieldLength": 10,
  "helpText": "Enter only numerical values related to the 2015 fiscal year...",
  "controlLevel": "NONE",
  "name": "2015 budget",
  "notes": "This field denotes xyz for our financial team..."
}

 

 

POST /fields

Description:

Create a custom field.

Parameters (body)

  • name: (String)The name of the custom field.
  • choices: (JSON object)These are the choices available for "multi select" and "single select" custom fields.
  • dataType: (String)This is the type of data custom field's values will represent. The possible values are: "BOOLEAN", "DATE", "DATE_TIME", "DECIMAL", "INTEGER", "TEXT", or "TIME"
  • decimalPlaces: (Int)The number of spaces after the decimal point. (Only applicable for decimal custom fields)
  • displayType: (Int)This is the type of data custom field's values will represent. The possible values are: "CHECKBOX", "CURRENCY", "DROPDOWN", "EMAIL", "RADIO_BUTTON", "MULTI_SELECT", "NUMBER", "SINGLE_SELECT", "TEXT_AREA", "TEXT_BOX", or "URL_LINK"
  • fieldId: (String)A field identifier.
  • fieldLength: (String)The number of characters allowed in the field's value.
  • helpText: (String)Text that helps the end user better understand the custom field.
  • notes: (String)Notes for field administrators.

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/c/fields
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
	"choices": [
	    {"displayValue": "Pop","storedValue": "1.00"},
	    {"displayValue": "Candy","storedValue": "1.50"},
	    {"displayValue": "Apple","storedValue": "2.00"}
	],
	"dataType": "DECIMAL",
	"decimalPlaces": "2",
	"displayType": "SINGLE_SELECT",
	"fieldId": "API1",
	"fieldLength": "12",
	"helpText": "Please select a food option.",
	"notes": "This was created using the '/field/create' request.",
	"name": "TEST API Text Field 1"
}

Response:

{
  "bn": "040L000002JQ",
  "choices": [],
  "dataType": "INTEGER",
  "decimalPlaces": 2,
  "displayType": "MULTI_SELECT",
  "fieldId": "2015budget",
  "fieldLength": 10,
  "helpText": "Enter only numerical values related to the 2015 fiscal year...",
  "controlLevel": "NONE",
  "name": "2015 budget",
  "notes": "This field denotes xyz for our financial team..."
}

 

 

PUT /fields/{fieldBn}

Description:

Update a custom field.

Parameters (body)

  • bn: (String)The Barometer Number for the custom field.
  • name: (String)The name of the custom field.
  • choices: (JSON object)These are the choices available for "multi select" and "single select" custom fields.
  • dataType: (String)This is the type of data custom field's values will represent. The possible values are: "BOOLEAN", "DATE", "DATE_TIME", "DECIMAL", "INTEGER", "TEXT", or "TIME"
  • decimalPlaces: (Int)The number of spaces after the decimal point. (Only applicable for decimal custom fields)
  • displayType: (Int)This is the type of data custom field's values will represent. The possible values are: "CHECKBOX", "CURRENCY", "DROPDOWN", "EMAIL", "RADIO_BUTTON", "MULTI_SELECT", "NUMBER", "SINGLE_SELECT", "TEXT_AREA", "TEXT_BOX", or "URL_LINK"
  • fieldId: (String)A field identifier.
  • fieldLength: (String)The number of characters allowed in the field's value.
  • helpText: (String)Text that helps the end user better understand the custom field.
  • notes: (String)Notes for field administrators.

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/c/fields/040L000002JQ
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
  "bn": "040L0000003B",
  "choices": [],
  "dataType": "BOOLEAN",
  "decimalPlaces": 2,
  "displayType": "DROPDOWN",
  "fieldId": "fieldTypeBooleanDropdown",
  "helpText": "A field used for various type-handling completeness tests.",
  "name": "Test Boolean Dropdown EDITED"
}

Response:

{
  "bn": "040L0000003B",
  "choices": [],
  "dataType": "BOOLEAN",
  "decimalPlaces": 2,
  "displayType": "DROPDOWN",
  "fieldId": "fieldTypeBooleanDropdown",
  "helpText": "A field used for various type-handling completeness tests.",
  "name": "Test Boolean Dropdown EDITED"
}

 

 

DELETE /fields/{fieldBn}

Description:

Delete a custom field.

Headers:

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

Example:

Request:

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

Response:

{
  "successfulEntities": [
    {
      "bn": "040L0000035B",
      "decimalPlaces": 2,
      "description": null,
      "displayType": "URL_LINK",
      "enterpriseFieldName": "1234 url",
      "valueType": "TEXT",
      "lastUpdateDate": "2017-05-10T14:03:05.000+0000",
      "length": 3000,
      "name": "1234 URL",
      "notes": null,
      "numberUom": null,
      "updatedByBn": {
        "bn": "040E00003ML7",
        "firstName": "David",
        "lastName": "Lewis-Frazier",
        "deleted": false
      },
      "controlLevel": "EDITABLE",
      "storedValueType": "TEXT",
      "freeForm": true,
      "displayableName": "1234 URL",
      "new": false
    }
  ]
}

 

 

GET /fieldpermissions/{fieldBn}

Description:

View the field permissions for a custom field.

 

Headers:

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

Example:

Request:

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

Response:

{
  "permissions": [
    {
      "bn": "042V0000FPRF",
      "fieldBn": "040L00000359",
      "controlLevel": "EDITABLE",
      "principalBn": "000300000000"
    }
  ]
}

 

 

POST /fieldpermissions

Description:

Upsert a field permissions for a custom field.

Parameters (body)

  • fieldBn: (String)The Barometer Number for the custom field.
  • controlLevel: (String)The access level for the field. These are the acceptable values: "EDITABLE", "VISIBLE".
  • principalBn: (String)A Person BN or a User Role BN that will be granted the permission.

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/c/fieldpermissions
Authorization: Basic {your basic auth}
Content-Type: application/json;charset=UTF-8
Accept: application/json;charset=UTF-8

{
 	"fieldBn": "040L00000359",
  	"controlLevel": "EDITABLE",
	"principalBn": "00030000000C"
}

Response:

{
  "message": "\"040L00000359\" was successfully set to \"EDITABLE\" for \"00030000000C\"."
}

 

 

DELETE /fieldpermissions/{fieldpermissionBn}

Description:

Delete a field permissions for a custom field.

 

Headers:

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

Example:

Request:

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

Response:

{
  "message": "OK: 042V0000FPRH was successfully removed."
}