Custom-defined fields¶

A custom-defined field is a field that can be added independent of a Pure release. You can read more about custom-defined fields and the process for getting custom-defined fields added to your Pure in the general custom-defined fields documentation.

Custom-defined fields are supported on a subset of the content types available in the Pure API, such as Person. A content type with support for custom-defined fields has a customDefinedFields field that maps from custom-defined field "property name" to a CustomDefinedField object. You access the value of a specific custom-defined field using the value field of the relevant CustomDefinedField object.

The specific type of CustomDefinedField object corresponds to the type of custom-defined field:

Field type	CustomDefinedField type	value field type
Boolean	CustomDefinedFieldBoolean	boolean
Classification	CustomDefinedFieldClassification	ClassificationRefClassificationRef
Date	CustomDefinedFieldDate	string (date)
Decimal	CustomDefinedFieldDecimal	number
String	CustomDefinedFieldString	string

Reading¶

Custom-defined field values are automatically fetched alongside regular fields of content; fetching a content item of a content type that supports custom-defined fields will also fetch values of all custom-defined fields of the content type.

Reading values from custom-defined fields follows the general rules for content access though the API in the case of both regular and sensitive fields:

Field type	API key	User associated with API key
Regular	Must allow read access to field	Any user
Sensitive	Must allow read access to field	Must have rights to modify content item

The customDefinedFields map is always populated with the full set of custom-defined fields that the API key allows access to, even ones where the current content item does not currently specify a value. If a custom-defined field was added after a content item was last saved then its customDefinedFields map will contain an entry with a CustomDefinedField object without a value.

Sample Request URLSample Response

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean"
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Not considered, yet"
    }
   }
}

Writing¶

Custom-defined field values are updated alongside regular fields of content; updates to customDefinedFields will be saved when a content item is created or updated. Only modifications to entries present in the customDefinedFields map will have an effect. Removing an entry from the customDefinedFields map will have no effect.

Writing custom-defined fields values follows the general rules for content access though the API in the case of both regular and sensitive fields:

Field type	API key
Regular	Must allow write access to field
Sensitive	Must allow write access to field

Custom-defined field values are specified on a new content item by adding entries to its customDefinedFields map with a key corresponding to the "property name" of each custom-defined field you want to specify a value for. You must specify a CustomDefinedField map value that fits the type of each field; if the field is boolean-based you must add a map entry with a CustomDefinedFieldBoolean object, etc.

Updating custom-defined field values is a three-step process:

Fetch existing Pure API model object to manipulate its customDefinedFields map.

Sample Request URLSample Response

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean"
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Not considered, yet"
    }
   }
}

Modify the customDefinedFields map to specify a value for the 'happy' field and change the value of the ' reason-for-happiness' field.

Submit the created/updated Pure API model object to the relevant endpoint, such as /persons.

Sample Request URLSample Request BodySample Response Body

https://{your Pure hostname}/ws/api/persons/29492640-5030-4843-91c1-7d85ca997749

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean",
      "value": true
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Great friends"
    }
   }
}

{
  "pureId": 417899,
  "uuid": "29492640-5030-4843-91c1-7d85ca997749",
  "customDefinedFields": {
    "happy": {
      "typeDiscriminator": "Boolean",
       "value": true
    },
    "reason-for-happiness": {
      "typeDiscriminator": "String",
      "value": "Great friends"
    }
   }
}

You can remove a custom-defined field value by specifying a CustomDefinedField object with no value. Re-fetching the content item will then include a map entry for the field where the corresponding CustomDefinedField object has no value.