Process

Create, modify, delete and run processes

Action

When the action was performed, and details about the user who did it.

Properties

Name	Type	Description	Restrictions
dateTime	string(date-time)	Date and time (in UTC) that the user performed the audited action.
user	User	Reference to a platform user.

Example

{
  "dateTime": "2019-10-30T15:03:27Z",
  "user": {
    "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
  }
}

BatchUpdate

A collection of updates to be done as a batch against the Process.

Properties

Name	Type	Description	Restrictions
data	[BatchUpdateItem]	List of updates to apply to the Process as a batch.	required, Minimum items: 0, Maximum items: 3000

Example

{
  "data": [
    {
      "id": "jobId123",
      "newName": "newJobTitle",
      "type": "jobName"
    },
    {
      "id": "groupId123",
      "newName": "newGroupTitle",
      "type": "groupName"
    }
  ]
}

BatchUpdateItem

Represents a single batch update request contained in a larger overall batch update.

Properties

Name	Type	Description	Restrictions
groupNameUpdate	ProcessGroupNameUpdate	A request to update a Group’s name.
jobNameUpdate	JobNameUpdate	A request to update a Job’s name.
type	string	The type of the update being requested.	required

Enumerated Values

Property	Value
type	jobName
type	groupName

Example

{
  "jobNameUpdate": {
    "id": "jobId123",
    "newName": "new job name"
  },
  "type": "jobName"
}

Error

Standard error response returned by the API when a request fails. Provides detailed information about what went wrong including error codes, human-readable messages, and additional context to help diagnose and fix the issue.

Properties

Name	Type	Description	Restrictions
code	string	One of a server-defined set of error codes.	required
details	[ErrorDetail]¦null	An array of details about the error.
documentationUrl	string¦null	Link to some documentation relevant to the issue or endpoint in use.
message	string	A human-readable representation of the error.
meta	object¦null	Contains additional metadata about the failure - ie “jobId”, “argumentName”,etc
meta.additionalProperties	string¦null	Contains additional metadata about the failure - ie “jobId”, “argumentName”,etc
target	string¦null	The target of the error.

Example

{
  "code": "INVALID_ARGUMENT",
  "details": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Field 'title' is required",
      "target": "title"
    }
  ],
  "documentationUrl": "https://developers.workiva.com/workiva-platform/reference/platform-authentication",
  "message": "The provided job id is invalid or does not exist",
  "meta": {
    "argumentName": "title",
    "jobId": "job-abc123"
  },
  "target": "jobId"
}

ErrorDetail

Detailed error information for a specific validation or processing failure. Provides granular error context including error codes, messages, and the specific field or resource that caused the error. Typically used as part of an array of errors in an error response.

Properties

Name	Type	Description	Restrictions
code	string	One of a server-defined set of error codes.
message	string	A human-readable representation of the error.
meta	object¦null	Contains additional metadata about the failure - ie “jobId”, “argumentName”,etc
meta.additionalProperties	string¦null	Contains additional metadata about the failure - ie “jobId”, “argumentName”,etc
target	string¦null	The target of the error.

Example

{
  "code": "VALIDATION_ERROR",
  "message": "Field 'title' is required",
  "target": "title"
}

ProcessGroup

Group of Jobs and other Groups in a Process.

Properties

Name	Type	Description	Restrictions
children	[ProcessGroupChild]	The children of this group. Children can be a job or another group.
created	Action	When the action was performed, and details about the user who did it.
dueDate	string(date)	The due date of the group.
id	string	The Group’s unique identifier
modified	Action	When the action was performed, and details about the user who did it.
name	string	The display name of this Group. On the root Group, this serves as the label for the top-level workflow container and is distinct from the Process-level name field.
ordinal	integer(int32)	The zero-based index representing the location of this group within its parent group	read-only
parallel	boolean	If true, execute jobs in this group in parallel. If false, serial.	required
parent	string¦null	The id of this child’s parent. Not present if the parent is the root group of the Process.
readOnly	boolean	Whether this Group is read-only.	required
revision	integer(int64)	The revision number of the current representation of the Group	read-only
triggerType	string	What triggers a group child to execute.

Enumerated Values

Property	Value
triggerType	whenEligible
triggerType	manual

Example

{
  "id": "root-group-123",
  "name": "Main Workflow",
  "parallel": false,
  "readOnly": false,
  "triggerType": "whenEligible"
}

ProcessGroupChild

Represents a child element within a Group in a process definition (build-time). A group child can be either a Job or another nested Group, creating a hierarchical structure for organizing work. The type field determines which specific child type is present.

Properties

Name	Type	Description	Restrictions
group	ProcessGroup	Group of Jobs and other Groups in a Process.
job	ProcessJob	A build-time representation of work to be done. The type of action the Job is dictates the type of arguments passed to it. The arguments represent the input to the Job, describing the work to be done. A Job can be built incrementally and only at the time it is attempted to be started, or a call to the Process’ health-check endpoint will it and its arguments be validated.
type	string	The type of group child. The corresponding job or group details will be provided below.	required

Enumerated Values

Property	Value
type	group
type	job

Example

{
  "job": {
    "id": "job-123",
    "triggerType": "whenEligible"
  },
  "type": "job"
}

ProcessGroupNameUpdate

A request to update a Group’s name.

Properties

Name	Type	Description	Restrictions
id	string	The id of the group whose name will be updated.	required, Minimum length: 1
newName	string	The new name for our group.	required, Minimum length: 1

Example

{
  "id": "groupId2342342",
  "newName": "new group name"
}

ProcessJob

A build-time representation of work to be done. The type of action the Job is dictates the type of arguments passed to it. The arguments represent the input to the Job, describing the work to be done. A Job can be built incrementally and only at the time it is attempted to be started, or a call to the Process’ health-check endpoint will it and its arguments be validated.

Properties

Name	Type	Description	Restrictions
action	string	The type of action the Job is performing. Dictates the type of arguments need to be passed to the Job.
arguments	ActionArguments	Container for action-specific arguments for a Job. The type field indicates which specific arguments field contains the data. Only one of the argument fields will be populated based on the action type.
created	Action	When the action was performed, and details about the user who did it.
generated	ProcessGroup	Group of Jobs and other Groups in a Process.
id	string	The Job’s unique identifier
modified	Action	When the action was performed, and details about the user who did it.
ordinal	integer(int32)	The zero-based index representing the location of this Job within its parent group	read-only
parent	string¦null	The id of this Job’s parent. Not present if the parent is the root group of the Process.
readOnly	boolean	Whether this Job is read-only.	read-only
revision	integer(int64)	The revision number of the current representation of the Job	read-only
tags	[TagLink]	The tag link, category, and value information associated with this Job.	read-only, unique
triggerType	string¦null	What triggers a group child to execute.

Enumerated Values

Property	Value
action	sendTask
action	contentRequest
action	certificationApproverGenerated
action	certificationSignerGenerated
action	certificationConditionalApproverGenerated
action	certificationPhaseFinalizerGenerated
action	certification
triggerType	whenEligible
triggerType	manual

Example

{
  "arguments": {
    "sendTaskArgs": {
      "title": "Complete audit review"
    },
    "type": "sendTask"
  },
  "id": "job-xyz789",
  "triggerType": "manual"
}

JobNameUpdate

A request to update a Job’s name.

Properties

Name	Type	Description	Restrictions
id	string	The id of the job whose name will be updated.	required, Minimum length: 1
newName	string	The new name for the targeted job.	required, Minimum length: 1

Example

{
  "id": "jobId2342342",
  "newName": "new job name"
}

Process

Build-time representation of a Process whose work is described by a collection of Jobs contained in its root Group.

Properties

Name	Type	Description	Restrictions
autoClose	boolean	If this process is configured to automatically close once all actions are completed or canceled.	required
businessDateExclusions	[string]	Individual dates that are excluded as business days of this Process. Impacts relative date calculations.	unique
businessDateInclusions	[string]	Individual dates that are included as business days of this Process, regardless of exclusion rules.	unique
businessDaysOfWeek	[string]	The days of the week that are deemed “working days” for this Process. Impacts relative date calculations.	unique
businessEndDate	string(date)	The end date of the business calendar window for this Process. Used with businessStartDate to define the period for relative date calculations. If businessStartDate is provided, businessEndDate must also be provided.
businessStartDate	string(date)	The start date of the business calendar window, used as the anchor for relative date calculations. If provided, businessEndDate must also be provided.
calendars	[string]	A set of calendar ids associated with this process. The events of these calendars are displayed in calendar ux components in Processes.	unique
certAutoApprove	boolean	If certification auto approval is turned on for certification actions on this process.	required
created	Action	When the action was performed, and details about the user who did it.
defaultCertApproverReminders	ReminderData	Configuration for reminder emails that will be sent to participants about incomplete tasks. Supports multiple reminder modes including system defaults, process defaults, custom schedules, or no reminders.
defaultCertSignerReminders	ReminderData	Configuration for reminder emails that will be sent to participants about incomplete tasks. Supports multiple reminder modes including system defaults, process defaults, custom schedules, or no reminders.
dueDate	string(date)	The overall deadline for the Process. This is the process-level due date, independent of the business calendar window defined by businessStartDate and businessEndDate.
id	string	The Process’ unique identifier.	Maximum length: 32, Minimum length: 1
modified	Action	When the action was performed, and details about the user who did it.
name	string	The name of the Process.
processTemplate	string	The id of the ProcessTemplate that this Process was created from.	read-only, Maximum length: 32
relativeDates	boolean	If relative dates are enabled for this process. Enables automatic shifting of dates based on the Process start date and business days configuration.	required
revision	integer(int64)	The revision number of the current representation of the Process	read-only
root	ProcessGroup	Group of Jobs and other Groups in a Process.
sourceProcessRun	string	The id of ProcessRun that this Process was copied from.	read-only, Maximum length: 32

Example

{
  "autoClose": true,
  "businessDateExclusions": [
    "2024-12-25",
    "2024-01-01"
  ],
  "businessDateInclusions": [
    "2024-12-28"
  ],
  "businessDaysOfWeek": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "businessEndDate": "2024-12-31",
  "businessStartDate": "2024-01-01",
  "calendars": [
    "calendar-123",
    "calendar-456"
  ],
  "certAutoApprove": true,
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "defaultCertApproverReminders": {
    "mode": "default"
  },
  "defaultCertSignerReminders": {
    "mode": "default"
  },
  "dueDate": "2026-01-01",
  "id": "e7b9920095e342889190b4d7eaeca6fa",
  "modified": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "name": "Q4 2024 Financial Close Process",
  "processTemplate": "9e20a5aeaaf84d5ba676233938ac4222",
  "relativeDates": false,
  "revision": 3,
  "root": {
    "id": "root-group-123",
    "name": "Main Workflow",
    "parallel": false,
    "readOnly": false,
    "triggerType": "whenEligible"
  },
  "sourceProcessRun": "9e20a5aeaaf84d5ba676233938ac4222"
}

ProcessesListResult

Returns a JSON object with data and @nextLink properties. data contains a list of process summary 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	[ProcessSummary]	The list of process summaries.	required

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "autoClose": true,
      "certAutoApprove": true,
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
        }
      },
      "dueDate": "2026-01-01",
      "id": "e7b9920095e342889190b4d7eaeca6fa",
      "modified": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
        }
      },
      "name": "Q4 2024 Financial Close Process",
      "processTemplate": "9e20a5aeaaf84d5ba676233938ac4222",
      "relativeDates": false,
      "revision": 3,
      "run": {
        "completedDate": "2024-12-30T18:30:00Z",
        "created": {
          "dateTime": "2019-10-30T15:03:27Z",
          "user": {
            "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
          }
        },
        "dueDate": "2024-12-31",
        "id": "a1b2c3d4e5f6789012345678",
        "managerUser": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
        "modified": {
          "dateTime": "2019-10-30T15:03:27Z",
          "user": {
            "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
          }
        },
        "name": "Q4 2024 Financial Close Process",
        "process": "e7b9920095e342889190b4d7eaeca6fa",
        "status": "running",
        "statusCounts": {
          "Completed": 5,
          "Running": 3,
          "Waiting": 2
        }
      },
      "sourceProcessRun": "9e20a5aeaaf84d5ba676233938ac4222"
    }
  ]
}

ProcessJSONPatchDocument

A JSON Patch document as defined by RFC 6902. An array of patch operations. Valid “path” and operation (“op”) combinations below:

• /dueDate : “remove” and “replace”
• /businessStartDate : “remove” and “replace”
• /businessEndDate : “remove” and “replace”
• /businessDaysOfWeek : “remove” and “replace”
• /businessDateExclusions : “remove” and “replace”
• /businessDateInclusions : “remove” and “replace”
• /calendarIds : “remove” and “replace”
• /name : “replace”
• /autoClose : “replace”
• /ipmBetaEnabled : “replace”
• /iwmOptOut : “replace”
• /relativeDates : “replace”
• /root/parallel : “replace”
• /root/triggerType : “replace”
• /certAutoApprove : “replace”
• /defaultCertSignerReminders : “remove” and “replace”
• /defaultCertApproverReminders : “remove” and “replace”

Properties

Name	Type	Description	Restrictions
op	string	The JSON Patch operation to perform.	required
path	string	JSON Pointer to the target location.	required
value	any	The value to replace the target with.

Enumerated Values

Property	Value
op	remove
op	replace

Example

[
  {
    "op": "remove",
    "path": "/dueDate"
  },
  {
    "op": "replace",
    "path": "/autoClose",
    "value": true
  }
]

ProcessRunSummary

A lightweight summary of a ProcessRun. Does not include the job tree or jobRunMap.

Properties

Name	Type	Description	Restrictions
completedDate	string(date-time)¦null	When the ProcessRun was completed.	read-only
created	Action	When the action was performed, and details about the user who did it.
dueDate	string(date)¦null	When the ProcessRun is due.	read-only
id	string	The ProcessRun’s unique identifier.	read-only
managerUser	string	The userId of the user this ProcessRun runs as.	read-only
modified	Action	When the action was performed, and details about the user who did it.
name	string	The name of the ProcessRun.	read-only
process	string	The Process id that was started that created this ProcessRun.	read-only
status	string	The general execution status of the JobRun. The same set of statuses apply to all JobRuns. For action specific statuses see a JobRun’s action status.	read-only
statusCounts	object¦null	Convenience map of JobRun action statuses to the number of JobRuns with that status. Only populated on individual process retrieval, null on list endpoints.	read-only
statusCounts.additionalProperties	integer(int64)¦null

Enumerated Values

Property	Value
status	waiting
status	running
status	cancelling
status	complete
status	cancelled
status	error
status	errorHold

Example

{
  "completedDate": "2024-12-30T18:30:00Z",
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "dueDate": "2024-12-31",
  "id": "a1b2c3d4e5f6789012345678",
  "managerUser": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
  "modified": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "name": "Q4 2024 Financial Close Process",
  "process": "e7b9920095e342889190b4d7eaeca6fa",
  "status": "running",
  "statusCounts": {
    "Completed": 5,
    "Running": 3,
    "Waiting": 2
  }
}

ProcessSummary

A lightweight summary of a Process with its associated run. Does not include the job tree or detailed configuration fields.

Properties

Name	Type	Description	Restrictions
autoClose	boolean	If this process is configured to automatically close once all actions are completed or canceled.	read-only, required
certAutoApprove	boolean	If certification auto approval is turned on for certification actions on this process.	read-only, required
created	Action	When the action was performed, and details about the user who did it.
dueDate	string(date)¦null	When the Process is due.	read-only
id	string	The Process’ unique identifier.	read-only, Maximum length: 32, Minimum length: 1
modified	Action	When the action was performed, and details about the user who did it.
name	string	The name of the Process.	read-only
processTemplate	string¦null	The id of the ProcessTemplate that this Process was created from.	read-only
relativeDates	boolean	If relative dates are enabled for this process. Only populated on individual process retrieval, defaults to false on list endpoints.	read-only, required
revision	integer(int64)	The revision number of the current representation of the Process.	read-only
run	ProcessRunSummary	A lightweight summary of a ProcessRun. Does not include the job tree or jobRunMap.
sourceProcessRun	string¦null	The id of ProcessRun that this Process was copied from.	read-only

Example

{
  "autoClose": true,
  "certAutoApprove": true,
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "dueDate": "2026-01-01",
  "id": "e7b9920095e342889190b4d7eaeca6fa",
  "modified": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "name": "Q4 2024 Financial Close Process",
  "processTemplate": "9e20a5aeaaf84d5ba676233938ac4222",
  "relativeDates": false,
  "revision": 3,
  "run": {
    "completedDate": "2024-12-30T18:30:00Z",
    "created": {
      "dateTime": "2019-10-30T15:03:27Z",
      "user": {
        "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
      }
    },
    "dueDate": "2024-12-31",
    "id": "a1b2c3d4e5f6789012345678",
    "managerUser": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
    "modified": {
      "dateTime": "2019-10-30T15:03:27Z",
      "user": {
        "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
      }
    },
    "name": "Q4 2024 Financial Close Process",
    "process": "e7b9920095e342889190b4d7eaeca6fa",
    "status": "running",
    "statusCounts": {
      "Completed": 5,
      "Running": 3,
      "Waiting": 2
    }
  },
  "sourceProcessRun": "9e20a5aeaaf84d5ba676233938ac4222"
}

ProcessValidationResults

Process validation result

Properties

Name	Type	Description	Restrictions
errors	[Error]	Set of validation errors found in the process definition.	unique

Example

{
  "errors": [
    {
      "code": "MISSING_REQUIRED_FIELD",
      "message": "Job is missing required 'action' field",
      "meta": {
        "field": "action",
        "jobId": "job-abc123"
      },
      "target": "job-abc123"
    }
  ]
}

User

Reference to a platform user.

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the user	Maximum length: 36

Example

{
  "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
}