Introduction to Custom Fields Endpoints#

Workiva’s Custom Fields endpoints allow customers to define user-defined data properties for supported object types (such as a Document, Presentation, Spreadsheet, Section, Slide, or Sheet) within the Workiva platform. These capabilities allow additional descriptive metadata to be associated with these objects, permitting enhanced classification, status, filtering, dashboarding, relationships, and other use cases. This guide answers the following questions:

What are some example use cases for custom fields?
How do I enable custom fields for my workspace?
How do I define custom fields?
How do I set values for custom fields?

Before getting started, make sure you have credentials set up.

Example Use Cases#

Custom field definitions and meanings are completely controlled by customers; so the use cases they can accommodate are extremely varied. Here are some high-level examples of how custom fields might be useful:

Classifying and Tracking Documents#

As an example, let’s assume that you have a workspace containing many kinds of documents, including fund prospectus documents. Suppose each prospectus is for a particular fund ID, fund manager, reporting period, and is in a particular phase of a legal team review process. Workiva’s custom fields let you model each of these properties, allowing you to identify specific documents as prospectus documents, and then to further filter and search for documents based on specified properties. Another use of these fields would be to let you build a dashboard that would show all prospectus documents in the workspace and their status. As each contributor to the prospectus progresses through their review process, they can update the appropriate field(s) as they go; these updates are then reflected in the dashboard.

Maintaining Statuses for Automation Triggers#

As another example, let’s suppose you have an annual report that is being written, and each time a section of content in that document is completed, a set of stakeholders needs to be notified so that they can review and sign off on it. You can define a custom field called “status” for document sections, and a “Ready for Review” value that indicates the section is ready for stakeholder review. Other Workiva platform capabilities such as Chains and Integrated Automations can use this status value to drive email notification, review collection, and other customized business processes.

Relating Resources#

Large projects often involve multiple resources in the Workiva platform. A single project may have several spreadsheets that function as data sets for an initiative, a reporting document that provides formal interpretations of the data, and a presentation form of that report for a board of directors. Using custom fields, you can formalize the relationship between these otherwise-independent resources, allowing you to add cross-references between them. This might be done with a shared custom field called “initiative” that is set to the same value on all related resources. Alternatively we might define a “report” custom field for your spreadsheets that allows us to locate and identify the reporting document by its platform identifier.

Enabling Custom Fields#

Custom fields are not enabled by default in Workiva workspaces. The Custom Fields add-on module must be enabled for your workspace; please contact your Workiva account representative to discuss enabling this feature. To define and manage custom fields after the module is enabled a user must be assigned the “Custom Fields Admin” role by a Workspace Administrator.

No specific role is required to set values for custom fields; any users with write permissions for a platform object (such as a Document, Presentation, Spreadsheet, Section, Slide, or Sheet) can set values for its custom fields.

Managing Custom Fields#

Prior to diving into the API, it is important to understand the data model of custom fields.

An object type is a kind of Workiva platform object that supports custom fields, such as Document, Presentation, Spreadsheet, Section, Slide, or Sheet.

A custom field is a workspace-wide data property definition with a schema. Only user-defined custom fields are currently available.

A custom field group is a named collection of custom fields that can be used with one or more object types. At present there are two kinds of custom field groups: Builtin groups, which are defined by Workiva and cannot be modified or deleted, and User-defined groups, which are created by users and can be modified and deleted. Group membership for both group types can be modified and managed by users.

Custom field groups are the mechanism by which custom fields are available for an object type. For example, any fields added to the builtin “All Documents” group will appear for every Document in the workspace. User-defined groups can also be explicitly assigned to individual object records; for example, a specific document could be assigned the user-defined “Fund Prospectus” group; the fields in that group would appear for that document but not for other documents that are not members of that group. See below for an example of assigning custom field groups to the sections within a document.

Taken together, the custom fields, custom field groups, and the memberships of custom fields in custom field groups define the custom schema for a workspace. The following examples illustrate how to GET and PATCH the custom schema for a workspace in order to accomplish common use cases.

Default Custom Fields#

The custom schema for a new workspace initially contains builtin groups for each object type, but no custom fields, as shown by the following GET query

curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/customSchema

{
  "customFields": {
  },
  "customFieldGroups": {
    "Document": {
      "builtin": {
        "id": "Document",
        "name": "All Documents",
        "description": "Custom fields that apply to every Document",
        "objectTypes": [
          "Document"
        ],
        "state": "Active"
      }
    },
    "Spreadsheet": {
      "builtin": {
        "id": "Spreadsheet",
        "name": "All Spreadsheets",
        "description": "Custom fields that apply to every Spreadsheet",
        "objectTypes": [
          "Spreadsheet"
        ],
        "state": "Active"
      }
    },
    "Slide": {
      "builtin": {
        "id": "Slide",
        "name": "All Slides",
        "description": "Custom fields that apply to every Slide",
        "objectTypes": [
          "Slide"
        ],
        "state": "Active"
      }
    },
    "Presentation": {
      "builtin": {
        "id": "Presentation",
        "name": "All Presentations",
        "description": "Custom fields that apply to every Presentation",
        "objectTypes": [
          "Presentation"
        ],
        "state": "Active"
      }
    },
    "Section": {
      "builtin": {
        "id": "Section",
        "name": "All Sections",
        "description": "Custom fields that apply to every Section",
        "objectTypes": [
          "Section"
        ],
        "state": "Active"
      }
    },
    "Sheet": {
      "builtin": {
        "id": "Sheet",
        "name": "All Sheets",
        "description": "Custom fields that apply to every Sheet",
        "objectTypes": [
          "Sheet"
        ],
        "state": "Active"
      }
    }
  },
  "customFieldGroupMemberships": {
  },
  "revision": 0
}

Defining a Custom Field for all Objects of a Type#

Suppose you want to define a custom field called “Status” for use on all documents in a workspace. To do so you must define the field and add it to the “Document” custom field group through a PATCH request.

curl -X PATCH -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/customSchema

[{
    "op": "add", 
    "path": "/customFields/avikro.status", 
    "value": {
        "userDefined": {
            "schema": {
                "title": "Status",
                "type": "string",
                "state": "Active"
            }
        }
    }
 },
 {
    "op": "add",
    "path": "/customFieldGroupMemberships/avikro.status", 
    "value": ["Document"]
}] 

Here, the first patch operation defines a custom field with the immutable, globally-unique id “avikro.status”. Its schema defines its type as “string”, its title (a mutable display name) as “Status”, and its state as “Active” (enabled for use). The second operation adds the custom field as a member of the builtin “Document” custom field group, which is a group that is automatically assigned to every document in the workspace. Custom field PATCHes are made asynchronously. Read more about Operations in the Operations guide. After the operation completes, your field is now defined and available for use on all documents in the workspace, as shown in the following GET query.

curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/customSchema

{
  "customFields": {
    "avikro.status": {
      "userDefined": {
        "id": "avikro.status",
        "schema": {
          "title": "Status",
          "type": "string",
          "state": "Active"
        },
        "modified": {
          "user": {
            "id": "AAZVc2VyHzU0NTgxMjU0Nw"
          },
          "dateTime": "2024-06-24T21:42:22.23146Z"
        }
      }
    }
  },
  "customFieldGroups": {},
  "customFieldGroupMemberships": {
    "avikro.status": ["Document"]
  },
  "revision": 1720131023973955
}

Using a Custom Field With User-Defined Custom Field Groups#

Suppose you realize that the “Status” field you created in the previous section isn’t quite what you wanted, and you want to change it as follows:

Its display name should be “Legal Review Status”.
Rather than a free-form string, the value should only be one of: “Not Started”, “In Progress”, or “Complete”.
This field should only appear on those documents that require a review by your Legal Team and not on other documents.

You can accomplish this as follows: modify the definition of the custom field, define a new custom field group, and modify the field’s group membership to be in that new group rather than the builtin “All Documents” group. Here’s the PATCH request to accomplish this:

curl -X PATCH -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/customSchema

[{
    "op": "replace", 
    "path": "/customFields/avikro.status/userDefined/schema",
    "value": {
        "title": "Legal Review Status",
        "type": "string",
        "enum": ["Not Started", "In Progress", "Complete"],
        "state": "Active"
    }
 },
 {
   "op": "add",
   "path": "/customFieldGroups/avikro.legalReview/userDefined",
   "value": {
      "name": "Legal Review",
      "description": "Fields to be set by the Legal Team for documents requiring review",
      "objectTypes": ["Document"],
      "state": "Active"
    }
 },
 {
    "op": "test",
    "path": "/customFieldGroupMemberships/avikro.status",
    "value": ["Document"]
 },
 {
    "op": "replace",
    "path": "/customFieldGroupMemberships/avikro.status", 
    "value": ["avikro.legalReview"]
}] 

The first operation in the PATCH modifies the schema properties of your existing custom field. The second operation defines the new custom field group, and the third operation tests the expectation that the field is currently a member of the “Document” group only. If that is the case, the fourth operation then replaces that group list with a list containing only your new group.

Note the use of the “test” operation prior to modifying the group list! Suppose that while you were making your call, some other employee had also modified the group list for this field. If you were to apply a change such as {"op": "remove", "path": "/customFieldMemberships/avikro.status/0"} to the element at the first index of the list (assuming that it is “Document” at the time the server applies the patch), you would be at risk of unintentionally removing a group added by another user. The test operation ensures that the list is as you expect it to be before you modify it. If it is not, the patch will fail with a “409 - Conflict” status rather than doing something you didn’t intend.

We strongly recommend using the “test” operation whenever modifying lists using a JSON patch.

After the PATCH operation completes, use this GET query to show that the changes have been made:

curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/customSchema

{
  "customFields": {
    "avikro.status": {
      "userDefined": {
        "id": "avikro.status",
        "schema": {
          "title": "Legal Review Status",
          "type": "string",
          "enum": ["Not Started", "In Progress", "Complete"],
          "state": "Active"
        },
        "modified": {
          "user": {
            "id": "AAZVc2VyHzU0NTgxMjU0Nw"
          },
          "dateTime": "2024-06-24T21:43:22.23146Z"
        }
      }
    }
  },
  "customFieldGroups": { 
    "avikro.legalReview": {
      "userDefined": {
        "name": "Legal Review",
        "description": "Fields to be set by the Legal Team for documents requiring review",
        "objectTypes": ["Document"],
        "state": "Active",
        "modified": {
          "user": {
            "id": "AAZVc2VyHzU0NTgxMjU0Nw"
          },
          "dateTime": "2024-06-24T21:43:22.23146Z"
        }
      }
    }
  },
  "customFieldGroupMemberships": {
    "avikro.status": ["avikro.legalReview"]
  },
  "revision": 1720131025823955
}

Assigning Custom Field Groups and Values#

Once you have defined the custom fields and custom field groups the way you want for your workspace, you are ready to use them to interact with your platform content! The GET endpoint allows you to see any custom fields and/or custom field groups associated with it. The PATCH endpoint allows you to assign/update values for the custom fields/groups.

As an example, suppose you have a Document with identifier aa47c476ca47654476bb767d3abb51056a that you would like to assign the “Legal Review” group and mark its “Legal Review Status” field to be “Not Started”. You can do this by using the Document APIs (note the change from /customSchema to /documents in the endpoint paths)!. Similarly, you can interact with the custom fields and groups on Spreadsheets and Presentations by using the corresponding endpoints for those resources. Initially your document does not have any custom fields with values or custom field groups assigned to it, as you can see by this GET query:

curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/aa47c476ca47654476bb767d3abb51056a

{
  "id": "aa47c476ca47654476bb767d3abb51056a`",
  "name": "Important Document",
  "template": false,
  "customFields": {},
  "customFieldGroups": [],
  "created": {
    "dateTime": "2022-03-15T12:19:56Z"
  },
  "modified": {
    "dateTime": "2024-07-04T22:16:20Z"
  }
}

You can assign the “Legal Review” group to the document and set the “Legal Review Status” field to “Not Started” with a PATCH request:

curl -X PATCH -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/aa47c476ca47654476bb767d3abb51056a

[{
    "op": "add", 
    "path": "/customFieldGroups/-", 
    "value": "avikro.legalReview"
 },
 {
   "op": "add",
   "path": "/customFields/avikro.status",
    "value": "Not Started"
 }] 

The first PATCH operation adds the “Legal Review” group to the document. The second operation sets the value of the “Legal Review Status” field to “Not Started”. After the PATCH operation completes, you can see the assignments have been applied through this GET query:

curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/aa47c476ca47654476bb767d3abb51056a

{
  "id": "aa47c476ca47654476bb767d3abb51056a`",
  "name": "Important Document",
  "template": false,
  "customFields": {
    "avikro.status": "Not Started"
  },
  "customFieldGroups": ["avikro.legalReview"],
  "created": {
    "dateTime": "2022-03-15T12:19:56Z"
  },
  "modified": {
    "dateTime": "2024-07-04T22:16:20Z"
  }
}

Assigning Custom Field Groups to Sections, Sheets, and Slides#

Working with Sections, Sheets, and Slides is nearly identical to working with Documents, Spreadsheets, and Presentations. However, an important difference is that all sections of a document share the same list of custom field groups managed using the sectionCustomFieldGroups property on the document itself. For example, to assign the “Legal Review” group to all sections of a particular document, you would PATCH the document as follows:

curl -X PATCH -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/documents/aa47c476ca47654476bb767d3abb51056a

[{
    "op": "add", 
    "path": "/sectionCustomFieldGroups/-", 
    "value": "avikro.legalReview"
 }] 

For additional information, see the Documents, Presentations and Spreadsheets APIs.

Versions

Introduction to Custom Fields Endpoints

Table Of Contents