Custom Fields

Endpoints to manage custom field definitions on platform objects

BuiltinCustomFieldGroupProperties

Subtype property for a custom field group defined by the Workiva platform

Properties

Name	Type	Description	Restrictions
description	string	A human-readable description of the group and its purpose	required
id	CustomFieldIdentifier	User-defined unique identifier. A prefix of “Workiva” (case insensitive) is reserved for internal use.	required
name	string	A human-readable display name for the group	required
objectTypes	[ObjectType]	The object types for which use of this group is intended	required, unique
state	CustomFieldGroupState	The state of a custom field group in its usage lifecycle. Active groups are in active use and can be associated with data. Inactive groups are “archived” and can no longer be associated with new data.	required

Example

{
  "description": "Custom fields that apply to every Document",
  "id": "Document",
  "name": "All Documents",
  "objectTypes": [
    "Document"
  ],
  "state": "Active"
}

CustomField

Custom Field is a user-defined field added to a platform Record Type

Properties

Name	Type	Description	Restrictions
id	CustomFieldId	A stable user-defined unique identifier. To indicate logical grouping and avoid collisions with other fields, a dot-delimited naming convention is recommended.	required
schema	CustomFieldSchema	Supported subset of JSON Schema Draft 2020-12 that is supported for use in custom fields.	required

Example

{
  "id": "com.workiva.gsr.legal_entity",
  "schema": {
    "description": "string",
    "enum": [
      null
    ],
    "format": "date-time",
    "maxLength": 0,
    "maximum": 0,
    "minLength": 0,
    "minimum": 0,
    "pattern": "/regex/",
    "reference": {
      "$comment": "string",
      "cardinality": "one",
      "description": "string",
      "field": "/json/pointer",
      "referenceType": "ReadCache",
      "resource": "Document"
    },
    "rhp_position_hint": 0,
    "state": "Draft",
    "title": "string",
    "type": "boolean"
  }
}

CustomFieldGroup

A group of custom fields with related purpose that is intended for use with particular record types. A group has a subtype, either builtin or userDefined. Exactly one of these is always set, and the subtype of a group cannot be changed.

Properties

Name	Type	Description	Restrictions
builtin	BuiltinCustomFieldGroupProperties¦null	Subtype property for a custom field group defined by the Workiva platform
userDefined	UserDefinedCustomFieldGroupProperties¦null	Subtype property for a custom field group defined by a user of the Workiva platform

Example

{
  "builtin": {
    "description": "Custom fields that apply to every Document",
    "id": "Document",
    "name": "All Documents",
    "objectTypes": [
      "Document"
    ],
    "state": "Active"
  },
  "userDefined": {
    "description": "Custom fields relevant to GSR reporting",
    "id": "gsr",
    "modified": {
      "datetime": "2019-10-30T15:03:27Z",
      "user": {
        "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
      }
    },
    "name": "GSR Reporting",
    "objectTypes": [
      "Document",
      "Spreadsheet",
      "Presentation",
      "Section",
      "Sheet",
      "Slide"
    ],
    "state": "Active"
  }
}

CustomFieldGroupState

The state of a custom field group in its usage lifecycle. Active groups are in active use and can be associated with data. Inactive groups are “archived” and can no longer be associated with new data.

Properties

Name	Type	Description	Restrictions
anonymous	string	The state of a custom field group in its usage lifecycle. Active groups are in active use and can be associated with data. Inactive groups are “archived” and can no longer be associated with new data.

Enumerated Values

Property	Value
anonymous	Active
anonymous	Inactive

Example

"Active"

CustomFieldId

A stable user-defined unique identifier. To indicate logical grouping and avoid collisions with other fields, a dot-delimited naming convention is recommended.

Properties

Name	Type	Description	Restrictions
anonymous	string	A stable user-defined unique identifier. To indicate logical grouping and avoid collisions with other fields, a dot-delimited naming convention is recommended.

Example

"com.workiva.gsr.legal_entity"

CustomFieldIdentifier

User-defined unique identifier. A prefix of “Workiva” (case insensitive) is reserved for internal use.

Properties

Name	Type	Description	Restrictions
anonymous	string	User-defined unique identifier. A prefix of “Workiva” (case insensitive) is reserved for internal use.	read-only

Example

"gsr.legal_entity"

Custom Field Schema

Supported subset of JSON Schema Draft 2020-12 that is supported for use in custom fields.

Properties

Name	Type	Description	Restrictions
description	string	Human-readable description explaining the field’s purpose
enum	[any]	A list of specific valid values	Minimum items: 1
format	string	(string) Constrains the valid format of a string field. See https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats
maxLength	integer	(string) Inclusive maximum number of characters allowed	Minimum: 0
maximum	integer	(integer, number) Inclusive maximum value	Minimum: 0
minLength	integer	(string) Inclusive minimum number of characters allowed	Minimum: 0
minimum	integer	(integer, number) Inclusive minimum value	Minimum: 0
pattern	string(regex)	(string) Constrains valid strings with an ECMA 262 regular expression
reference	object	Documentation that field values are programmatic references something else at Workiva
reference.$comment	string	A comment to help document the reference.
reference.cardinality	string	Denotes how many resources the value references. Defaults to ‘one’
reference.description	string	A human-readable description
reference.field	string(json-pointer)	The field in the resource the value represents. Required when ReferenceType is ‘ReadCache’	required
reference.referenceType	string	Subtype of the reference	required
reference.resource	string	Kind of resource to which the Platform (User) or ReadCache (Document, Spreadsheet, Presentation, Section, Sheet, Slide) reference refers	required
rhp_position_hint	number	Configurable hint for how a field should be positioned relative to the other fields when rendered in a UI. Fields will be ordered descending with the smallest position first. If a rhp_position_hint is omitted, it will be placed unsorted at the end of the list.
state	CustomFieldState	The lifecycle state of a custom field definition. ‘Draft’ fields are proposed but do not yet accept values. ‘Active’ fields are in use and can accept values. ‘Inactive’ fields are previously-active fields that are now read-only.	required
title	string	Human-readable name for the field	required
type	string	Data type of the custom field	required

Enumerated Values

Property	Value
format	date-time
format	time
format	date
format	duration
format	email
format	idn-email
format	hostname
format	idn-hostname
format	ipv4
format	ipv6
format	uuid
format	uri
format	uri-reference
format	iri
format	iri-reference
format	regex
cardinality	one
cardinality	many
referenceType	ReadCache
referenceType	Platform
resource	Document
resource	Spreadsheet
resource	Presentation
resource	Section
resource	Sheet
resource	Slide
resource	User
type	boolean
type	integer
type	number
type	string

Example

{
  "description": "string",
  "enum": [
    null
  ],
  "format": "date-time",
  "maxLength": 0,
  "maximum": 0,
  "minLength": 0,
  "minimum": 0,
  "pattern": "/regex/",
  "reference": {
    "$comment": "string",
    "cardinality": "one",
    "description": "string",
    "field": "/json/pointer",
    "referenceType": "ReadCache",
    "resource": "Document"
  },
  "rhp_position_hint": 0,
  "state": "Draft",
  "title": "string",
  "type": "boolean"
}

CustomFieldsListResult

Returns a JSON object with data and @nextLink properties. data contains a list of CustomField objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[CustomField]	Custom Field is a user-defined field added to a platform Record Type	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "id": "com.workiva.gsr.legal_entity",
      "schema": {
        "description": "string",
        "enum": [
          null
        ],
        "format": "date-time",
        "maxLength": 0,
        "maximum": 0,
        "minLength": 0,
        "minimum": 0,
        "pattern": "/regex/",
        "reference": {
          "$comment": "string",
          "cardinality": "one",
          "description": "string",
          "field": "/json/pointer",
          "referenceType": "ReadCache",
          "resource": "Document"
        },
        "rhp_position_hint": 0,
        "state": "Draft",
        "title": "string",
        "type": "boolean"
      }
    }
  ]
}

CustomFieldState

The lifecycle state of a custom field definition. ‘Draft’ fields are proposed but do not yet accept values. ‘Active’ fields are in use and can accept values. ‘Inactive’ fields are previously-active fields that are now read-only.

Properties

Name	Type	Description	Restrictions
anonymous	string	The lifecycle state of a custom field definition. ‘Draft’ fields are proposed but do not yet accept values. ‘Active’ fields are in use and can accept values. ‘Inactive’ fields are previously-active fields that are now read-only.

Enumerated Values

Property	Value
anonymous	Draft
anonymous	Active
anonymous	Inactive

Example

"Draft"

CustomFieldV2

Data model for a custom field.

Properties

Name	Type	Description	Restrictions
userDefined	UserDefinedCustomFieldProperties	A custom field defined by a user

Example

{
  "userDefined": {
    "id": "gsr.legal_entity",
    "modified": {
      "datetime": "2019-10-30T15:03:27Z",
      "user": {
        "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
      }
    },
    "schema": {
      "state": "Active",
      "title": "Legal Entity",
      "type": "string"
    }
  }
}

CustomSchema

The complete workspace-wide schema of custom fields, custom field groups, and mapping of custom fields to each group represented as custom field group memberships.

Properties

Name	Type	Description	Restrictions
customFieldGroupMemberships	object	Map from each custom field id to the set of custom field group ids for groups in which it is a member.	required
customFieldGroupMemberships.additionalProperties	any	A set of custom field group ids. The order of items in this set is not significant and should not be relied upon for PATCHing purposes. Callers wishing to remove an item from the list should use the “replace” patch operation to replace the entire list with a new list that omits the item to be removed.
customFieldGroups	object	Map from custom field group ids to their definitions	required
customFieldGroups.additionalProperties	CustomFieldGroup	A group of custom fields with related purpose that is intended for use with particular record types. A group has a subtype, either builtin or userDefined. Exactly one of these is always set, and the subtype of a group cannot be changed.
customFields	object	Map from custom field ids to their definitions	required
customFields.additionalProperties	CustomFieldV2	Data model for a custom field.
revision	CustomSchemaRevision	A schema revision that increases any time the custom fields, groups, or memberships are modified. Revisions should be treated as opaque, except for the purposes of comparing to other revisions to determine which one is more recent.	required

Example

{
  "customFieldGroupMemberships": {
    "gsr.legal_entity": [
      "gsr"
    ],
    "items": false,
    "legal": [
      "Document",
      "Presentation",
      "Spreadsheet",
      "Section",
      "Sheet",
      "Slide"
    ],
    "type": "array",
    "uniqueItems": true
  },
  "customFieldGroups": {
    "Document": {
      "builtin": {
        "description": "Custom fields that apply to every Document",
        "id": "Document",
        "name": "All Documents",
        "objectTypes": [
          "Document"
        ],
        "state": "Active"
      }
    },
    "Presentation": {
      "builtin": {
        "description": "Custom fields that apply to every Presentation",
        "id": "Presentation",
        "name": "All Presentations",
        "objectTypes": [
          "Presentation"
        ],
        "state": "Active"
      }
    },
    "Section": {
      "builtin": {
        "description": "Custom fields that apply to every Section",
        "id": "Section",
        "name": "All Sections",
        "objectTypes": [
          "Section"
        ],
        "state": "Active"
      }
    },
    "Sheet": {
      "builtin": {
        "description": "Custom fields that apply to every Sheet",
        "id": "Sheet",
        "name": "All Sheets",
        "objectTypes": [
          "Sheet"
        ],
        "state": "Active"
      }
    },
    "Slide": {
      "builtin": {
        "description": "Custom fields that apply to every Slide",
        "id": "Slide",
        "name": "All Slides",
        "objectTypes": [
          "Slide"
        ],
        "state": "Active"
      }
    },
    "Spreadsheet": {
      "builtin": {
        "description": "Custom fields that apply to every Spreadsheet",
        "id": "Spreadsheet",
        "name": "All Spreadsheets",
        "objectTypes": [
          "Spreadsheet"
        ],
        "state": "Active"
      }
    },
    "gsr": {
      "userDefined": {
        "description": "Custom fields relevant to GSR reporting",
        "id": "gsr",
        "modified": {
          "datetime": "2019-10-30T15:03:27Z",
          "user": {
            "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
          }
        },
        "name": "GSR Reporting",
        "objectTypes": [
          "Document",
          "Spreadsheet",
          "Presentation",
          "Section",
          "Sheet",
          "Slide"
        ],
        "state": "Active"
      }
    }
  },
  "customFields": {
    "gsr.legal_entity": {
      "userDefined": {
        "id": "gsr.legal_entity",
        "modified": {
          "datetime": "2019-10-30T15:03:27Z",
          "user": {
            "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
          }
        },
        "schema": {
          "state": "Active",
          "title": "Legal Entity",
          "type": "string"
        }
      }
    }
  },
  "revision": 123456789
}

CustomSchemaRevision

A schema revision that increases any time the custom fields, groups, or memberships are modified. Revisions should be treated as opaque, except for the purposes of comparing to other revisions to determine which one is more recent.

Properties

Name	Type	Description	Restrictions
anonymous	integer(int64)	A schema revision that increases any time the custom fields, groups, or memberships are modified. Revisions should be treated as opaque, except for the purposes of comparing to other revisions to determine which one is more recent.	read-only, Minimum: 0

Example

123456789

ObjectType

Type of object within the Workiva Platform

Properties

Name	Type	Description	Restrictions
anonymous	string	Type of object within the Workiva Platform

Enumerated Values

Property	Value
anonymous	Document
anonymous	Spreadsheet
anonymous	Presentation
anonymous	Section
anonymous	Sheet
anonymous	Slide
anonymous	Control
anonymous	Risk

Example

"Document"

UserDefinedCustomFieldGroupProperties

Subtype property for a custom field group defined by a user of the Workiva platform

Properties

Name	Type	Description	Restrictions
description	string¦null	A human-readable description of the group and its purpose
id	CustomFieldIdentifier	User-defined unique identifier. A prefix of “Workiva” (case insensitive) is reserved for internal use.	required
modified	Action	When the action was performed, and details about the user who did it
name	string	A human-readable display name for the group	required
objectTypes	[ObjectType]	The object types for which use of this group is intended	unique
state	CustomFieldGroupState	The state of a custom field group in its usage lifecycle. Active groups are in active use and can be associated with data. Inactive groups are “archived” and can no longer be associated with new data.

Example

{
  "description": "Custom fields relevant to GSR reporting",
  "id": "gsr",
  "modified": {
    "datetime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
    }
  },
  "name": "GSR Reporting",
  "objectTypes": [
    "Document",
    "Spreadsheet",
    "Presentation",
    "Section",
    "Sheet",
    "Slide"
  ],
  "state": "Active"
}

UserDefinedCustomFieldProperties

A custom field defined by a user

Properties

Name	Type	Description	Restrictions
id	CustomFieldIdentifier	User-defined unique identifier. A prefix of “Workiva” (case insensitive) is reserved for internal use.	required
modified	Action	When the action was performed, and details about the user who did it	required
schema	CustomFieldSchema	Supported subset of JSON Schema Draft 2020-12 that is supported for use in custom fields.	required

Example

{
  "id": "gsr.legal_entity",
  "modified": {
    "datetime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V0ZVc2VyHzQ4Mjk1OTA4NjYzNjIzNjg"
    }
  },
  "schema": {
    "state": "Active",
    "title": "Legal Entity",
    "type": "string"
  }
}