Workflow Endpoints
Workflow Endpoints and Parameters
To learn more about the objects relations and how to use them in the API, go to the Object Relations section.
For more information about workflows, visit the Workflows help page.
Upload a New Workflow
To upload a new workflow, use the POST {baseURL}/v3/workflows
endpoint.
Parameters
file (file): Required. Select the actual file you want to upload to the system. The media type must be a YXZP file.
name (string): Required. Enter a workflow name. This is the name of the workflow to display in Server UI.
ownerId (string): Required. Enter the ID of the owner.
workerTag (string): Optional. Specify the worker tag defined in the workers to help assign jobs to certain worker nodes. For more information, visit the Worker help page.
districtTags (string): Optional. Submit as JSON formatted array, for example, ["id1", "id2"]. Use districts to group shared, public workflows by tags so that users can easily find them. For more information, visit the Districts help page.
comments (string): Optional. Enter your comments.
isPublic (boolean): Required. Select "true" to make the workflow publicly available. Select "false" to make the workflow private and publicly unavailable.
isReadyForMigration (boolean): Required. Select whether the workflow is ready to be migrated. For more information about the migration from one Server environment to another, see the Enable Workflows for Migration help page.
sourceAppId (string): Optional. Sets the source app id of a workflow. You can use it as the "sourceId" reference for the
POST admin/v1/workflows
endpoint. Providing a pre-existing sourceAppId will result in an invalid request.othersMayDownload (boolean): Required. Specify whether other users may download this workflow.
othersCanExecute (boolean): Required. Specify whether other users can execute this workflow.
executionMode (string): Required. Accepted values are "Safe", "SemiSafe", and "Standard". For more information about the execution mode, see the Safe and Semi-safe Run Modes: Blocked Tools, Events, and Data Connectors help page.
hasPrivateDataExemption (boolean): Optional. Give an exemption to allow a workflow with private data to run. Select "true" to allow an exemption or "false" to deny an exemption. For more information, visit the Workflow Options in Admin page.
workflowCredentialType (string): Required. Accepted values are "Default", "Required", and "Specific".
credentialId (string): Optional. Specify the credentialId for this workflow.
collectionIds (string): Optional. Enter the collectionId(s) where this workflow should be added. Submit as JSON formatted array, for example: ["id1", "id2"].
curl -X 'POST' \ 'http://localhost/webapi/v3/workflows' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere' \ -H 'Content-Type: multipart/form-data' \ -F 'file=@Workflow2.yxzp;type=application/yxzp' \ -F 'name=Workflow2' \ -F 'ownerId=66ebd0896e52ae73b4951072' \ -F 'isPublic=true' \ -F 'isReadyForMigration=true' \ -F 'othersMayDownload=true' \ -F 'othersCanExecute=false' \ -F 'executionMode=Standard' \ -F 'workflowCredentialType=Default'
200: OK
"string"
400: BadRequest
401: Unauthorized
Upload a New Version to an Existing Workflow
To upload a new version to an existing workflow, use the POST {baseURL}/v3/workflows/{workflowId}/versions
endpoint.
Parameters
workflowId (string): Required. Enter the workflow ID for which you want to upload a new version.
file (file): Required. Select the actual file you want to upload to the system as a new version. The media type must be a YXZP file.
name (string): Required. Enter the workflow name. This is the name of the workflow to display in Server UI.
ownerId (string): Required. Enter the ID of the owner.
othersMayDownload (boolean): Required. The default is set to "true".
othersCanExecute (boolean): Required. The default is set to "true".
executionMode (string): Required. Accepted values are "Safe", "SemiSafe", and "Standard". For more information about the execution mode, see the Safe and Semi-safe Run Modes: Blocked Tools, Events, and Data Connectors help page.
hasPrivateDataExemption (boolean): Optional. Give an exemption to allow a workflow with private data to run. Select "true" to allow an exemption or "false" to deny an exemption. For more information, visit the Workflow Options in Admin page.
comments (string): Optional. Enter your comments.
makePublished (boolean): Required. The default is set to "true". The makePublished parameter is a way to control whether the new version of a workflow that you push to Server should be the published version or not. You can set the value to "false" when you push the workflow to Server, and then only you will have the ability to run it.
workflowCredentialType (string): Required. Enter the credential type to be used for this workflow. Accepted values are "Default", "Required", and "Specific".
credentialId (string): Optional. Specify the credentialId for this workflow. For more information about credential endpoints, go to Credential Endpoints.
curl -X 'POST' \ 'http://localhost/webapi/v3/workflows/66ebd18d6e52ae73b4951085/versions' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere' \ -H 'Content-Type: multipart/form-data' \ -F 'file=@Workflow3.yxzp;type=application/yxzp' \ -F 'name=Workflow1_3' \ -F 'ownerId=66ebd0896e52ae73b4951072' \ -F 'othersMayDownload=true' \ -F 'othersCanExecute=true' \ -F 'executionMode=Standard' \ -F 'makePublished=true' \ -F 'workflowCredentialType=Default'
200: OK
{ "id": "string", "sourceAppId": "string", "dateCreated": "2024-09-19T07:33:01.072Z", "runCount": 0, "versions": [ { "versionId": "string", "versionNumber": 0, "dateCreated": "2024-09-19T07:33:01.072Z", "uploadSource": "Designer", "uploadDate": "2024-09-19T07:33:01.072Z", "packageWorkflowType": "App", "published": true, "comments": "string", "runDisabled": true, "executionMode": "Safe", "workflowCredentialType": "Default", "credentialId": "string", "hasPrivateDataExemption": true, "othersMayDownload": true, "othersCanViewHistory": true, "details": { "isAmp": true, "fileName": "string", "author": "string", "copyright": "string", "description": "string", "name": "string", "noOutputFilesMessage": "string", "outputMessage": "string", "url": "string", "urlText": "string" } } ], "name": "string", "ownerId": "string", "workerTag": "string", "districtTags": [ "string" ], "comments": "string", "isPublic": true, "isReadyForMigration": true, "publishedVersionId": "string", "othersMayDownload": true, "othersCanViewHistory": true, "othersCanExecute": true, "executionMode": "Safe", "hasPrivateDataExemption": true }
401: BadRequest
401: Unauthorized
404: Indicates that the workflowId in the path is invalid.
Retrieve All Workflows
To get information about all workflow records, use the GET {baseURL}/v3/workflows/
endpoint.
Parameters
view (string): Optional. Select how you want to display workflow information. Can be left without a value. You can select from the following values: ‘Default’ and ‘Full’. If this parameter is set to 'Default’, then a reduced view object will be returned. When not specified, the ‘Default’ value is used.
name (string): Optional. Enter the name of the workflow in case you want to filter the workflows by name. This is the name of the workflow displayed in Server UI.
ownerId (string): Optional. Enter the ID of the owner in case you want to filter the workflows by their owner.
createdAfter (string): Optional. Enter the date and time after which the workflow was created. Enter the date and time in ISO8601 format.
createdBefore (string): Optional. Enter the date and time before which the workflow was created. Enter the date and time in ISO8601 format.
curl -X 'GET' \ 'http://localhost/webapi/v3/workflows' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere'
200: OK
{ "id": "string", "sourceAppId": "string", "name": "string", "ownerId": "string", "dateCreated": "2024-08-15T11:14:56.965Z", "publishedVersionNumber": 0, "isAmp": true, "executionMode": "Safe" } ]
400: BadRequest
401: Unauthorized
Retrieve a Specific Workflow Record
To get information about a specific workflow, use the GET {baseURL}/v3/workflows/{workflowId}
endpoint.
Note
Non-Curators can use the GET v3/workflows/{workflowId}
endpoint for workflows they have access to. Previously, this endpoint was limited to Curators only.
Parameters
workflowId (string): Required. Enter the workflow ID to get information about this workflow.
curl -X 'GET' \ 'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere'
200: OK
{ "id": "string", "sourceAppId": "string", "dateCreated": "2024-09-05T10:42:53.360Z", "runCount": 0, "versions": [ { "versionId": "string", "versionNumber": 0, "dateCreated": "2024-09-05T10:42:53.360Z", "uploadSource": "Designer", "uploadDate": "2024-09-05T10:42:53.360Z", "packageWorkflowType": "App", "published": true, "comments": "string", "runDisabled": true, "executionMode": "Safe", "workflowCredentialType": "Default", "credentialId": "string", "hasPrivateDataExemption": true, "othersMayDownload": true, "othersCanViewHistory": true, "details": { "isAmp": true, "fileName": "string", "author": "string", "copyright": "string", "description": "string", "name": "string", "noOutputFilesMessage": "string", "outputMessage": "string", "url": "string", "urlText": "string" } } ], "name": "string", "ownerId": "string", "workerTag": "string", "districtTags": [ "string" ], "comments": "string", "isPublic": true, "isReadyForMigration": true, "publishedVersionId": "string", "othersMayDownload": true, "othersCanViewHistory": true, "othersCanExecute": true, "executionMode": "Safe", "hasPrivateDataExemption": true }
401: Unauthorized
404: NotFound
Update an Existing Workflow
To change information about an existing workflow, use the PUT {baseURL}/v3/workflows/{workflowId}
endpoint.
Note
Only Curators can use this API endpoint.
To change the ownerId, the new owner must be in the same subscription as the current owner.
Parameters
workflowId (string): Required. Enter the ID of the workflow you want to update.
updateWorkflowContract (body): Required. Enter the workflow information you want to update.
name (string): Required. Enter the workflow name. This is the name of the workflow to display in Server UI.
versionId (string): Required. Enter the version ID.
makePublished (boolean): Optional. When not specified, the value stays the same as before. The makePublished parameter is a way to control whether the new version of a workflow that you push to Server should be the published version or not. You can set the value to "false" when you push the workflow to Server, and then only you will have the ability to run it.
ownerId (string): Required. Enter the owner ID.
workerTag (string): Required. When there is no workerTag, use "" instead.
districtTags (string): Required. Enter the district tags. Use districts to group shared, public workflows by tags so that users can easily find them. For more information, visit the Districts help page.
comments (string): Required. Enter your comments.
isPublic (boolean): Optional. When not specified, the value stays the same as before.
isReadyForMigration (boolean): Optional. When not specified, the value stays the same as before.
othersMayDownload (boolean): Optional. When not specified, the value stays the same as before. When set to "false" for a public workflow, the workflow will be unusable.
othersCanExecute (boolean): Optional. When not specified, the value stays the same as before. When set to "false" for a public workflow, the workflow will be unusable.
executionMode (string): Optional. Accepted values are "Safe", "SemiSafe", "Standard". For more information about the execution mode, see the Safe and Semi-safe Run Modes: Blocked Tools, Events, and Data Connectors help page.
hasPrivateDataExemption (boolean): Optional. Give an exemption to allow a workflow with private data to run. Select "true" to allow an exemption or "false" to deny an exemption. When not specified, the value stays the same as before. For more information, visit the Workflow Options in Admin page.
workflowCredentialType (string): Optional. Accepted values are "Default", "Required", and "Specific".
credentialId (string): Optinal. Specify the credentialId for this workflow.
Example value of updateWorkflowContract:
{ "name": "string", "versionId": "string", "makePublished": true, "ownerId": "string", "workerTag": "string", "districtTags": [ "string" ], "comments": "string", "isPublic": true, "isReadyForMigration": true, "othersMayDownload": true, "othersCanExecute": true, "executionMode": "Safe", "hasPrivateDataExemption": true, "workflowCredentialType": "Default", "credentialId": "string" }
curl -X 'PUT' \ 'http://localhost/webapi/v3/workflows/66ebd18d6e52ae73b4951085' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere' \ -H 'Content-Type: application/json' \ -d '{ "name": "Workflow_3_4", "versionId": "66ebd18d3d6200007e000d89", "makePublished": true, "ownerId": "66ebd0896e52ae73b4951072", "workerTag": "", "districtTags": [], "comments": "nothing", "isPublic": true, "isReadyForMigration": true, "othersMayDownload": true, "othersCanExecute": true, "executionMode": "Safe", "hasPrivateDataExemption": true, "workflowCredentialType": "Default", "credentialId": "" }'
200: OK
{ "id": "string", "sourceAppId": "string", "dateCreated": "2024-08-15T11:20:45.231Z", "runCount": 0, "versions": [ { "versionId": "string", "versionNumber": 0, "dateCreated": "2024-08-15T11:20:45.231Z", "uploadSource": "Designer", "uploadDate": "2024-08-15T11:20:45.231Z", "packageWorkflowType": "App", "published": true, "comments": "string", "runDisabled": true, "executionMode": "Safe", "workflowCredentialType": "Default", "credentialId": "string", "hasPrivateDataExemption": true, "othersMayDownload": true, "othersCanViewHistory": true, "details": { "isAmp": true, "fileName": "string", "author": "string", "copyright": "string", "description": "string", "name": "string", "noOutputFilesMessage": "string", "outputMessage": "string", "url": "string", "urlText": "string" } } ], "name": "string", "ownerId": "string", "workerTag": "string", "districtTags": [ "string" ], "comments": "string", "isPublic": true, "isReadyForMigration": true, "publishedVersionId": "string", "othersMayDownload": true, "othersCanViewHistory": true, "othersCanExecute": true, "executionMode": "Safe", "hasPrivateDataExemption": true }
400: BadRequest
401: Unauthorized
404: NotFound
Download a Workflow Package
To download a workflow package, use the GET {baseURL}/v3/workflows/{workflowId}/package
endpoint.
Parameters
workflowId (string): Required. Enter the workflow ID for which you want to download the package.
versionId (string): Optional. Enter the specific version ID of a workflow. If no version is provided, then the published version is downloaded.
Note
If the versionID is double-digit, it might reach the size limit and you might get a '414 - URI Too Long' error. In this case, please parse the JSON versionID string and trim it to the most recent version only. This will keep the field length under control.
Request Example: cURL
curl -X GET --header 'Accept: application/octet-stream' --header 'Authorization: Bearer BearerTokenGoesHere' 'http://localhost/webapi/v3/workflows/635a4be7dc6e24bb8ff0/package'
Response Example
200: The download stream of the YXZP file.
400: Invalid VersionId
401: Unauthorized
403: The authenticated user does not have permission to download the workflow, or the workflow is not allowed to be downloaded directly.
404: NotFound
Retrieve Question Information for a Workflow
To get question information for a workflow or an analytic app, use the GET {baseURL}/v3/workflows/{workflowId}/questions
endpoint.
Parameters
workflowId (string): Required. Enter the workflow ID for which you want to retrieve the information.
versionId (string): Optional. Enter the specific version ID of a workflow. If no version is provided, then the published version is used.
curl -X 'GET' \ 'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/questions' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere'
200: OK
[ { "name": "string", "questionType": "string", "description": "string", "value": "string", "multiple": true, "items": [ { "key": "string", "value": "string" } ] } ]
400: BadRequest
401: Unauthorized
403: The authenticated user does not have access to the workflow or questions.
404: NotFound
Get Information about Jobs for a Specific Workflow
To get information about jobs for a specific workflow, use the GET {baseURL}/v3/workflows/{workflowId}/jobs
endpoint.
Note
A job might be returned as Completed even if the query status is Error. This indicates an error occurred during execution, but the workflow was run.
Parameters
workflowId (string): Required. Enter the workflow ID for which you want to retrieve the information.
sortField (string): Optional. Enter the field name that you want to sort your results by.
direction (string): Optional. Specify the sorting order here. Accepted values are “asc” (ascending) and “desc” (descending). If no sorting is specified, the default will be ascending.
offset (string): Optional. Refers to the record you want your results to start with.
limit (string): Optional. Refers to the last record you want your results to end with.
status (string): Optional. The overall status of the job execution. A completed job might still have failed. Accepted values are: "Complete", "Error", "Running", and "Queued".
resultCode (string): Optional. The result code of the execution of a workflow. This indicates a failed workflow, but a successful job. Accepted values are: "Success", "Warning", and "Error".
curl -X 'GET' \ 'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/jobs' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere'
200: OK
[ { "id": "string", "createDate": "2024-08-15T11:29:53.357Z", "status": "Created", "priority": "string", "workerTag": "string", "runWithE2": true } ]
400: BadRequest
401: Unauthorized
404: NotFound
Delete a Workflow
To delete a specific workflow, use the DELETE {baseURL}/v3/workflows/{workflowId}
endpoint.
Note
Only Curators can use this API endpoint.
Parameters
workflowId (string): Required. Enter the workflow ID to delete.
force (boolean): Optional. When not selected, the default value is "false". If a workflow is scheduled, the parameter set to "true" will delete all schedules before deleting it.
curl -X 'DELETE' \ 'http://localhost/webapi/v3/workflows/670ce95bf10214f22a665bc4' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere'
200: OK
400: BadRequest
401: Unauthorized
404: NotFound
Create a New Job
To create a new job and add it to the job execution queue, use the POST /v3/workflows/{workflowId}/jobs
endpoint.
Parameters
workflowId (string): Required. Enter a workflow ID you want to schedule.
contract (body): To create a new job, specify the following parameters:
workerTag (string): Optional. Specify the assigned worker. If not specified, the value will be "none".
credentialId (string): Optional. Specify the credentialId for this workflow.
questions (string): Optional. For an analytic app, specify the questions and answers to run the workflow.
name (string): Optional.
value (string): Optional.
priority (string): Optional. Specify the priority for running the schedule. Choose from the following values: "Low", "Medium", "High", and "Critical". If not specified, the default value will be ‘Low’.
Example value of contract:
{ "workerTag": "string", "credentialId": "string", "questions": [ { "name": "string", "value": "string" } ], "priority": "Default" }
Example of a request to create a job:
curl -X 'POST' \ 'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/jobs' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere' \ -H 'Content-Type: application/json' \ -d '{ "workerTag": "", "credentialId": "", "priority": "Low" }'
200: OK
{ "id": "string", "appId": "string", "createDateTime": "2024-09-05T11:13:04.586Z", "status": "string", "disposition": "string", "outputs": [ { "id": "string", "availableFormats": [ "string" ], "fileName": "string" } ], "messages": [ { "status": 0, "text": "string", "toolId": 0 } ], "priority": "Default", "workerTag": "string", "runWithE2": true }
400: BadRequest
401: Unauthorized
403: The authenticated user does not have access to execute the workflow.
404: NotFound
Transfer Workflows and Schedules to a Specified Owner
To transfer a specific workflow to a specific owner, together with schedules if desired, use the PUT {baseURL}/v3/workflows/{workflowId}/transfer
endpoint.
Note
Only Curators can use this API endpoint.
If any of the workflows require DCM connections, Server connections, or specific run as credentials to run, these items need to be updated before the workflow can run.
If users are not in the same studio and when a workflow is transferred to the new studio, all other users in the new owner's studio will also receive access to the workflow, and all users from the old studio will lose access.
Workflows can only be transferred to a user with the Artisan or Curator role.
If transferring schedules, the new owner must have access to the scheduled workflow, otherwise you won’t be able to transfer that workflow to the new owner.
If transferring schedules, the new owner must have permission to schedule workflows.
If the user is deleted, it returns a list of schedule Ids that will be broken or disabled after transfer.
Parameters
workflowId (string): Required. Specify the Id of the workflow to transfer.
contract (body): Required. Specify the following information:
ownerId (string): Required. Specify the Id of the new owner.
transferSchedules (Boolean): Required. Specify whether the schedules should be transferred to a new owner together with the workflow. Only the schedules owned by the current workflow owner will be transferred to the new owner.
Example value of contract:
{ "ownerId": "string", "transferSchedules": true }
curl -X 'PUT' \ 'http://localhost/webapi/v3/workflows/670ce5cef10214f22a6637a3/transfer' \ -H 'accept: application/json' \ -H 'authorization: Bearer BearerTokenGoesHere' \ -H 'Content-Type: application/json' \ -d '{ "ownerId": "670ceafbf10214f22a666c76", "transferSchedules": true }'
200: OK
400: BadRequest
"string"
401: Unauthorized
403: Forbidden
"string"
404: NotFound
"string"
500: InternalServerError
Objects Relations
If you are uploading a workflow, you can use created objects as follows:
Object created: "workflowId" (for example, "id": "7917969784f84bd09442f66996ecb8f3")
You can use it as:
workflowId if you are adding workflows to a collection.
appId if you are removing workflows from a collection.
workflowId if you are searching for a specific workflow.
workflowId if you are deleting a specific workflow.
workflowId if you are updating an existing workflow.
workflowId if you are uploading a new version of an existing workflow.
workflowId if you are searching for a schedule.
workflowId if you are creating a schedule.
workflowId if you are downloading a workflow package.
workflowId if you want to retrieve question information for a workflow.
workflowId if you want to get info about jobs for a workflow.
Postman Request Examples
GET /v3/workflows/{workflowId}
To know more about Postman requests, visit the How to Use Postman help page.