Vault Workflows API: Exporting & Importing Workflows

Note: This article is intended for Vault Services use only.

Introduction

Find Workflow Details in Vault Admin

Admins can configure and update workflows from Admin > Configuration > Lifecycles & Workflows > [Lifecycle] > Workflows. To view or edit workflow details, click the workflow name. Note that you must have the Admin: Lifecycles and Workflows permissions to configure and update workflows.

Lifecycle Name

The image above shows the lifecycle name and active status.

Workflow Names

The image above shows all workflows configured on the lifeycle and their names. Notice that two of the workflows have inactive status.

Retrieve Workflow Configuration

Send a GET request to the /api/{VERSION}/objects/workflows/configuration/{LIFECYCLE_NAME}.{WORKFLOW_NAME} endpoint.

Request Parameters

Example Request

$ curl -X GET -H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v12.0/objects/workflows/configuration/general_lifecycle__vs.approval__c

Where general_lifecycle__vs.approval__c is the lifecycle workflow name retrieved from the Admin > Configuration > Lifecycles & Workflows > [General Lifecycle] > Workflows > [Approval] as shown in the images above.

Example JSON Response (abridged)

{
    "responseStatus": "SUCCESS",
    "data": {
        "procDef": {
            "processDefinitionId": null,
            "name": "startApproval",
            "processVersion": null,
            "labels": {
                "en": "Approval"
            },
            "descriptions": {},
            "status": "active",
            "flowType": "standard",
            "lifecycleKey": "general",
            "nodes": [
                {
                    ...
                    ...

The abridged JSON response above shows the workflow configuration fields and field values for the General Lifecycle: Approval workflow.

Possible Errors

On failure, the response displays an error type and message describing the error.

Error Type Error Message Comments
OPERATION_NOT_ALLOWED Workflow export/import feature not turned on. You must enable the Workflow Export & Import feature flag for the vault in VMC. The switch is available in the API Settings area of VMC. It is not visible in the Vault Admin area.
METHOD_NOT_SUPPORTED Request method [{METHOD}] not supported. You must use the HTTP GET method to retrieve workflow configurations.
ATTRIBUTE_NOT_SUPPORTED HTTP Accept [{METHOD}] not supported. You must set the HTTP Request Header Accept to application/json for JSON response format (required).
MALFORMED_URL The resource [{LIFECYCLE_NAME}].[{WORKFLOW_NAME}] does not exist. The requested lifecycle name and/or workflow name could not be found. Verify that your request has been entered correctly and/or go to Vault > Admin > Lifecycles & Workflows and make sure the lifecycle and workflow exists.

Import Workflow Configuration

Send a POST request to the /api/{VERSION}/objects/workflows/configuration endpoint.

Request Parameters

Example Request

$ curl -X POST -H "Authorization: {SESSION_ID}" \
-H "Content-Type: application/json" \ 
--data-binary @"C:\Vault Files\Workflows JSON\gen-lifecycle-app-workflow.txt" \ 
https://myvault.veevavault.com/api/v12.0/objects/workflows/configuration

Example Input (abridged)

    {
        "procDef": {
            "processDefinitionId": null,
            "name": "startApproval",
            "processVersion": null,
            "labels": {
                "en": "Approval"
            },
            "descriptions": {},
            "status": "active",
            "flowType": "standard",
            "lifecycleKey": "general",
            "nodes": [
                {
                    ...
                    ...

On success, Vault performs a validation check on the workflow to ensure that it properly references all steps. If the validation check fails, Vault displays error messages. If the validation check passes, the workflow is added and its status set to “inactive”. You can activate the workflow in the Vault UI or cancel the changes and revert to the previously active workflow.

Known Issues

Importing certain workflow configurations are known to cause specific errors.

Error Code Error Message Step Affected Resolution/Workaround
WFL-FREC-II-11606 Required role cannot be Coordinator. User task In the source vault, edit the “Task Step” by saving with valid “Add Task Assignee to Role” field value.
GEN-FREC-PR-1006 Required attribute [else_rule] is missing. User task In the source vault, edit the “Decision Step” and save with “Else” rule enabled.
GEN-FCRE-II-1027 Invalid component name format. User task. The verdict public key is more than 40 characters long. None. This issue has been addressed by relaxing the public key limit beyond 40 characters.
WFL-FREC-II-11611 Cannot set both verdicts and next lifecycle state. User task -
WFL-FREC-II-11409 Value [San Jose] for attribute [site__v]
is resolved to multiple records
Vault Object records have the same child name with different parent. -
WFL-FREC-II-11301 No tasks with name [outcome_promoPiece_pm_pCHoldRelease
DocumentFromPCHol1418828862820_usertasknode1427233148610] precede this decision"
Decision step -
GEN-FREC-II-1022 value [BASE-baseReviewedApproved] does not resolve to valid active [notification] Notification step (Lifecycles>General Lifecycle>Workflows>Review). In the source vault, edit the “Notification Step” and save with a valid notification template.
WFL-FREC-II-11531 Recipients [originator] must be one of ‘Workflow Owner’,
'Owner’, 'Coordinator’ or value from a user control on the WAD.
Notification step (Lifecycles>General Lifecycle>Workflows>Review). In the source vault, edit the “Notification Step” and save with a valid notification template.
WFL-FREC-II-11511 Value [dueDate136111605945310] is not a valid timer expiration parameter. Timer step In the source vault, edit the “Timer Step” and save with a valid date field.
WFL-FREC-II-11301 No tasks with name [finalOutcome] this decision. Decision step This needs to be updated on the source workflow in the UI.
GEN-FREC-PR-1006 Required attribute [task description] is missing. User task This needs to be updated on the source workflow in the UI.
GEN-FREC-PR-1006 Required attribute[Required Role] is missing. User task This needs to be updated on the source workflow in the UI.
GEN-F-II-1023 Value role does not resolve to a valid [{1}]. User Task, File Upload User Task The role does not exist.
GEN-F-II-1023 Value required does not resolve to a valid [{1}]. User Task, File Upload User Task The required role does not exist.
GEN-F-II-1023 Value every-notification-template does not resolve to a valid [{1}]. User Task, File Upload User Task The notification template for every user should have a valid ID.
GEN-F-II-1023 Value any-notification-template does not resolve to a valid [{1}]. User Task, File Upload User Task The notification template for any user should have a valid ID.
GEN-F-II-1023 Field [{0}] does not exist. Decision Step, Update document field For field condition, the field must exist in the target vault.
GEN-F-II-1023 Value [nextTaskDueDate] does not resolve to a valid [due_date]. User task By editing the task in validation error (just change the description), saving it, activating it, and then export/importing.
GEN-F-II-1023 value [expiration_date__vs] does not resolve to a valid [field]. Update Doucment Field -
GEN-FREC-II-1023 Value [null] does not resolve to a valid [role]. Workflow Start Step Assign to Role field on workflow start step must not be empty.
GEN-FREC-II-1023 Value [promoPiece_pm_fastTrack1429290621016_medicalApproval1358275429896]
does not resolve to a valid [decision_comment_task].
User task By editing the task in validation error (just change the description), saving it, activating it, and then export/importing.
GEN-F-II-1035 Value [{value}] for attribute is invalid. Decision Step Name of VOF record cannot be resolved to a valid VOF record; make sure object is present in the target vault.
GEN-FREC-II-1035 Value [{country}] for attribute [country__v] is invalid. Decision Step Decision step in source vault needs to update via UI.
GEN-FREC-404 Script execution failed : [{0}] is not the base language on Vault [{1}]. - Target base language is different than source base language; Vault base language must be the same.
WFL-F-II-11408 Duplicate record names are not allowed. Decision Step, Update document field. Duplicate VOF names are given.
WFL-F-II-11409 Value [{0}] for attribute [{1}] is resolved to multiple records. Decision Step, Update document field VOF name is resolved into multiple VOF records; VOF object name must be unique.
WFL-F-II-11451 State {0} not valid. Change state Target vault does not contain a referenced state.
WFL-II-11107 Workflow export/import feature not turned on. General Feature flag is not turned on for the vault.
WFL-II-11108 Import version [{0}] does not match target version [{1}] General Import version doesn’t match the version of target vault.
GEN-FREC-PR-1006 Required attribute [else_rule] is missing. Decision step In source vault, edit Decision Step, and save with Else rule enabled.
GEN-FREC-PR-1006 Required attribute [read_and_understood_button_label] is missing. R&U user task In source vault, edit and save read and understand task without making any changes will correct the configuration error.
GEN-FREC-II-11301 No tasks with name [outcome_promoPiece_pm_pCHoldReleaseDocumentFrom
PCHol1418828862820_usertasknode1427233148610] precede this decision.
Decison step -
WFL-FREC-II-11301 No tasks with name [finalOutcome] this decision. Decision step Source workflow needs to update on this via UI.