Update attributes

This endpoint allows you to programatically add or update app attributes, custom fields, or app owners.

Prerequisites

  • Querying the Attributes APIs involves sending an access_token as part of the Authorization header. For instructions on how to generate an access token, see Authorization.

Endpoint

POST https://public-api.productiv.com/push/v1/batch/attributes
Required Scope https://api.productiv.com/apps.write

Request headers

Parameter Value
Content-Type application/json
Authorization Bearer access_token

Request body

Every request should have a list of objects with the following properties in the body:

Property Datatype Description
applicationId string Unique identifier for the app being updated, obtained from the App List API
attributes array List of Attribute objects, see definition below.
customFields array List of CustomField objects, see definition below. Note that new custom fields currently cannot be configured through the API
appOwners array List of AppOwner objects, see definition below. Note that this creates new app owners for the app, the existing ones will not be affected. To remove app owners, use the DELETE version of this endpoint.

Example request body

[
  {
    "applicationId": "productiv",
    "attributes": [
      {
        "name": "notes",
        "value": "note for productiv"
      }
    ],
    "customFields": [
      {
        "name": "num_of_something",
        "value": 123
      }
    ],
    "appOwners": [
      {
        "type": "Legal",
        "email": "email@domain.com"
      }
    ]
  }
]

Response

If the request is successful, a JSON response is returned. The JSON object contains the following parameters:

Parameter Datatype Description
NumSuccessfulUpdates number Number of successfully processed updates
FailedUpdates array List of FailedUpdate objects (see definition below)
ResponseTimeMs number Time taken by the server to process the request in milliseconds

Example Response

{
  "NumSuccessfulUpdates": 10,
  "FailedUpdates": [
    {
      "applicationId": "productiv",
      "attributes": [
        {
          "name": "name",
          "value": "!@#$%^^&*()",
          "reason": "Name contains invalid characters."
        }
      ],
      "customFields": [
        {
          "name": "cost center",
          "value": "123 - New York",
          "reason": "123 - New York is not a valid value for the cost center custom field"
        }
      ],
      "appOwners": [
        {
          "type": "IT",
          "email": "owner",
          "reason": "owner is not a valid email"
        }
      ]
    }
  ],
  "ResponseTimeMs": 1000
}

Objects

This section describes the objects referenced above in the Request and Response schema.

Attribute

Property Datatype Description
name string Identifier for the attribute being updated. The following are currently supported: appStatus, appRationale, labels, notes. Note that updates might take up to an hour to reflect in the product.
value any Value to set the attribute to. The type depends on the name, more details below. Note that for DELETE requests value must be undefined.

The value structure will vary depending on which name you are updating.

name Datatype value Description
appStatus string Can be one of: ["approved", "not approved", "in review", "retired"]
appRationale string Free-form text
labels array List of string labels. WARNING: This will replace any labels already configured for the app.
notes string Free-form text

CustomField

Property Datatype Description
name string Name for the custom field being updated, referred to as FieldName in the app list and app details responses. Must be present if key is not present. Either name or key must be present, but not both.
key string Key for the custom field being updated, referred to as FieldKey in the app list and app details responses. Must be present if name is not present. Either name or key must be present, but not both.
value any Value to set the custom field to. See CustomFieldValue object below. Note that for DELETE requests value must be undefined.

CustomFieldValue

Custom fields can be one of the following types: singleselect, multiselect, text, number, date, currency, hyperlink. The datatype for value above depends on the type of custom field you are trying to edit.

Type Datatype Description
singleselect string The value must be one of the allowed values as configured in the product for the custom field.
multiselect array List of strings. Each value must be one of the allowed values for the field as configured in the product for the custom field.
text string Free-form text
number number Number
date string YYYY-MM-DD format
currency object See Currency object below
hyperlink object See Hyperlink object below

Currency

Property Datatype Description
currencyCode string ISO 4217 currency code
amount number Amount
Property Datatype Description
label string Label for the hyperlink
url string URL for the hyperlink

AppOwner

Property Datatype Description
type string Type of owner to set. Can be one of ["Finance", "Security", "IT", "Legal", "Functional", "Vendor", "Procurement", "Other"]
email string Email of the user to set as the app owner

FailedUpdate

Property Datatype Description
applicationId string Unique identifier for the application that could not be updated
attributes array List of FailedUpdateAttribute objects (defined below)
customFields array List of FailedUpdateCustomField objects (defined below)
appOwners array List of FailedUpdateAppOwner objects (defined below)

FailedUpdateAttribute

Property Datatype Description
name string Identifier for the attribute being updated
value any Value the attribute could not be set to
reason string Reason for the update failure

FailedUpdateCustomField

Property Datatype Description
name string Identifier for the custom field being updated
value any Value the custom field could not be set to
reason string Reason for the update failure

FailedUpdateAppOwner

Property Datatype Description
type string Type of app owner to set
email string Email of the user that could not be set as the app owner
reason string Reason for the update failure