Docubee API: Start and Manage Workflows Programmatically
Docubee’s API is a set of tools that allows you to interact programmatically with your workflows, instances, and documents.
Before you begin, you’ll need to set up a simple workflow consisting of some web forms and an email step. Then, you’ll need to make an API call to start the workflow with properties you configure in the web forms.
Before You Begin
The first step is to ensure that you have an Docubee account. Once your account is set up, you’ll need to create an API token, then create a simple Docubee workflow.
Setting Up Your API Token
Your API token will be sent as a header to authenticate your requests; this a requirement to use the Docubee API. See Generate API Access Tokens for information on how you can create your own.
For this demo, your token will need to have at least the following permissions:
- Get documents
- Get instance properties
- List instance documents
- List workflows
- Start workflow instances
Setting Up Your Workflow
The workflow you need for this demo is a simple, four task workflow that will demonstrate programmatically starting a workflow, listing a workflow’s properties, listing a workflow’s document, and then downloading that document.
Note: If you’d like an example to help you get started, the workflow (.docubee-workflow file) for this demo is available here. Once downloaded, you can import it using the Docubee Workflow Builder. Find more info about importing workflows here.
If you’d rather start from scratch, follow the steps below to create your own (you can also download the workflow and use it as an example).
- First, create a new workflow and open it in the Workflow Builder. Give your new workflow a name of “API Demo”.
- Next, add a web form task. This web form should feature a single-line text field and an email address field. Set the property name of the text field to User_Name, and the property name of the email address field as User_Email.
- Following the web form task, add an email task. The recipient is the property name of the email address field you configured in step 1, User_Email. The email body should contain at least a “View Task” button.
- Next, you’ll add another web form task following the email task. This web form will need five fields:
- A read-only single-line text field with the same property name as the text field in step 1, User_Name.
- A read-only email address field with the same property name as the email field in step 1, User_Email.
- A single-line text field. Assign this field a property name, User_Favorite_Color, so you can reference it using the API.
- A date picker field. Assign this field a property name, Todays_Date, so you can reference it using the API.
- A file upload field. Assign this field a property name, Document_Upload, so you can reference it using the API.
- Finally, add a complete workflow task as the very last task in the workflow. Click the green “Publish” button near the top right of the Workflow Builder to save and publish your workflow.
Managing Your Workflow With The API
With our workflow created, the next step is to run it with the API. For this demo, we are using Node.js (v14.17.5) with the node-fetch package, and Visual Studio Code.
- To begin, create a new directory on your desktop called ontask-api-demo. Then, open this directory in Visual Studio Code (or your IDE of choice) and run the npm init command (accepting all the default options) in a terminal to create a new node project. Run the npm install node-fetch command to download the node-fetch package.
- Then, create a new file called index.js and a subdirectory called documents within the ontask-api-demo directory. Your directory structure should now look like this:
- Open index.js and add the following code on lines 1 – 6, replacing the apiToken placeholder with your API token.
- You can get the templateId programmatically using the Workflow Templates – List API call (https://docs.ontask.io/#list) and parsing the response body for the templateId. Add the following function on lines 8 – 22.
On line 10-15, the API request to list the available workflows returns an array of workflows which you store in the response variable. On lines 17-19, you parse the workflow data to return the templateId of the workflow that matches the name of the workflow that you set in step three. - Next, you’ll create a function for the Workflow Templates – Start Workflow API call, which will start an instance of the workflow you created earlier. The body of the API request will contain the properties that you created on the start form. Add the following function on lines 24-41.
The body of our request has two parts, User_Name and User_Email, with their corresponding values, a name and an email address. The keys must match the property names of the fields on the start form. Enter your name in the <YOUR-USER-NAME> placeholder, and your email address in the <YOUR-EMAIL-ADDRESS> placeholder.
The User_Email value is where the email from our workflow will be sent. When you send the Start Workflow request, this email address will receive an email with a link to continue the workflow in the browser.
- To call the functions, add the following codes on line 43-49.
Your index.js file should now look like this:
Run node index.js in your terminal to start your demo application. The instanceId, the unique identifier for a workflow instance, will print to the console. You’ll use it in later requests to get instance properties (so copy and paste it in a text editor for now).
You should also see that a new email has been sent to your email address from Docubee.
- After sending our Start Workflow request and receiving an email, you should now go to your email inbox and follow the VIEW TASK link in the email to continue to Docubee. In Docubee, in the web form task, you will see 5 fields. The first two fields are read-only and contain the data you entered with the API, and the other three need to be completed now. Enter some text and a date, and upload a document, then press CONTINUE. When you see the “Complete Workflow” screen, you can leave the page or close the browser window.
- Now that the workflow has been completed in Docubee, let’s use the API to get the values of the fields you entered during the workflow runtime. For this, you’ll use the Workflow Instances – List Properties API. That request looks like this:
The instance Id is the value you returned from step 6. The response from the request looks like this:
The fields and their values entered during the workflow runtime are listed in an object where each key corresponds to a property name configured in the workflow.
You configured another field in our workflow that isn’t in this response: the document upload.
- To list a workflow instance’s documents, you’ll use the Workflow Instances – List Documents API. That request looks like this:
which gives you this response:
The documents array contains an index of an object for each document used in the workflow instance. You can use the documentId from this response to download a document. That Documents – Download API call looks like this:
Note: You will need to update the file extension in this code block if they use something other than a PDF. We have attached a PDF for you to use in this example.
If you make this call from index.js, then the response, your document file bytes, will write to your ontask-api-demo/documents directory.
Final Thoughts
In this demo, you downloaded a document submitted in a web form. However, there are many other sources a document can come from:
- The API can be used to download the document from a fill & sign task, which allows you to pull copies of the completed and signed document.
- The API also gives you the ability to download the .zip archive generated from the create zip file task.
- Using the API, you can download a document that was previously uploaded using our Documents – Upload API.
Related Information
All About Workflows (Quick Reference)
Need more help getting set up? Contact us for assistance from our customer support team.
