Updating Resources

The Risk & Control Matrix controls and risks are read-only. Issues, action tasks, and assurance projects are updatable as described below; none of them can be created or deleted through the API.

Assurance projects cannot be renamed through the API, but two things about a project can change, each using the update style that fits it:

• The project’s scope documentation (its scopingRationale and the set of attached Workiva files) is updated with PATCH /assuranceProjects/{id}, using a JSON Patch document (RFC 6902, media type application/json-patch+json): an array of operations. This API supports replace on /scopingRationale and /scopingFiles; include an operation only for the field you want to change. /scopingFiles is replace-set (the array you supply becomes the complete attached set, so omitting a file detaches it, and [] detaches all).

• The controls in scope are changed with three behavioral POST operations, because putting a control in or out of scope is an action with downstream side effects (it creates or retires the control’s workpapers), not a simple field edit:

  • POST /assuranceProjects/{id}/scopedControls/addition — add controls by control id.

  • POST /assuranceProjects/{id}/scopedControls/removal — remove scope entries, with a rationale.

  • POST /assuranceProjects/{id}/scopedControls/restoration — restore removed entries, with a rationale.

Remediation issues and action tasks can also be updated. Both use the same JSON Patch document (RFC 6902, media type application/json-patch+json), an array of operations. Only replace is supported. Include one operation per field you want to change; fields without an operation are left unchanged. Each endpoint accepts only the paths below.

• Issues are updated with PATCH /issues/{id}, with at most 100 operations:

  Path	Operations	Value type
  /name	replace	string
  /description	replace	string
  /rootCause	replace	string, null
  /supplementalInformation	replace	string, null
  /severity	replace	string: minor, moderate, high, unassigned
  /soxDeficiency	replace	string: notSet, deficiency, materialWeakness, significantDeficiency
  /auditTeamOwner	replace	user id string
  /businessOwner	replace	user id string, null
  /collaborators	replace	array of user id string, at most 10
  /controls	replace	array of control id string, at most 5
  /processes	replace	array of process id string, at most 5
  /risks	replace	array of risk id string, at most 5
  /targetRemediationDate	replace	date string (YYYY-MM-DD), null
  /customFields/{schemaId}	replace	object with exactly one of stringValue, dateValue, enumValue, or enumValues; null

  A null value clears the paths that list null; the other paths do not accept it. Array values replace the whole list. A custom field is patched by its schema id rather than by replacing the /customFields array, with a value that matches the field’s type; a null value clears it, and other custom fields are left unchanged. An issue’s status and resolution are read-only, and patching /status returns 400.

• Action tasks are updated with PATCH /issues/{issueId}/actionTasks/{id}, with at most 3 operations:

  Path	Operations	Value type
  /name	replace	non-empty string
  /description	replace	non-empty string
  /dueDate	replace	RFC 3339 date-time string

  null is not accepted. The task is due at the end of the /dueDate date (UTC). A due date in the past is allowed, so an overdue date can be synced; the task then has the overdue status. The assignee and status are read-only, and patching them returns 400. An action task that is implemented or cancelled, or whose assigneeStatus is completed or cancelled, can no longer be changed and returns 409.

• An action task’s progress is changed with two behavioral POST operations, because each is an action with its own rules and side effects rather than a field edit:

  • POST /issues/{issueId}/actionTasks/{id}/externalSubmission — mark the task sent because the work is tracked in an external system. The task moves to inProgress (or stays overdue if its due date has passed) and its assigneeStatus becomes inProgress. Workiva does not create a Task Portal task, send the assignee a notification or email, or allow reminders for the task. Retrying is safe: a task already sent this way is returned unchanged. It returns 409 if the task was already sent from Workiva, or is implemented or cancelled.

  • POST /issues/{issueId}/actionTasks/{id}/implementation — mark the task implemented. It is allowed from notSent, inProgress, or overdue; a task that is already implemented is returned unchanged, and a cancelled task returns 409.

All of these require the grc:write scope; everything else requires only grc:read.

Note

Because this is a preview, new operations can be added without a major version bump — see Versioning.