Integration with OnTask and the applications you
use today

Integration with OnTask and the applications you use today
1
Getting started with a standard integrations with OnTask
1
Bringing Data and Documents in to OnTask
3
API endpoints are used for a standard integration
3
How to get started with the OnTask APIs
4
Get Template Start Form Data
4
Start a Workflow
4
Example ‘Get Template Start Form Data’
5
Example ‘Start a Workflow’
6
Zapier Integrations
7
Triggers available
7
Zapier Event
7
Workflow Instance Started
8
Actions Available
8
Example by field type/format and example value
8
Example Zap
9
Documents and Data from an OnTask workflow instance
14
Manual Exporting
14
Webhooks
14
Integrating Documents to third party solutions- web end points
16
Sample Integration with OnTask
19
Manual Start from OnTask
19
Remote Start from External System
19
Remote Start via API
19
Data Output by Webhook
21



Getting started with a standard integrations with
OnTask

OnTask is a SaaS web-based application that enables anyone to automate the creation, routing,
reviews and approvals of documents and forms. OnTask users build reusable workflow
templates to define various user based and automated steps in a business process. OnTask
allows these templates to be run creating an instance of the workflow template as it existed at
time of launch.

Integration from an application into OnTask will occur at the Group+Workflow Template level.
This allows the significant events or triggers to occur in your application to begin a workflow in
OnTask.

Integration from OnTask back to your application occurs within a workflow template at a
task/step level in our workflow template so that the significant action or trigger to occur when the
documents, forms, and data are ready in OnTask. Some steps ‘wait’ for participant activity so
this allows OnTask to notify when work is done.

Each workflow template is created within an OnTask ‘group’.
​When you create and run workflow
templates, you will do so within the context of a group
​. You can review more on groups here:
https://www.ontask.io/help-center/overview-organizations-groups-members/


To integrate from a third party system, the OnTask system will allow
you to send text fields to the start form of a workflow template and
begin the automated process. OnTask requires every field found on
the Start Form to be supplied before the workflow instance begins. A
user can manually add to the start form however if we are remotely
starting a workflow each field must be ‘sent’ to begin the workflow.

OnTask can also integrate using Zapier which will allow mapping of
start form fields.


To view the Start Form for a workflow template, edit an existing
template or begin the new workflow template creation process. For
assistance creating a template, learn more here:
https://www.ontask.io/help-center/create-new-workflow-template/

Any text can be sent to a workflow to populate documents, forms,
emails or web forms however to do so those fields must be first
added to the start form of the template. The property name for each
field will allow the text values to pass into documents, forms and other
steps in the model. For example, in the screenshot showing Start
Form, Send to Customer, Customer Sign- we can pre-populate the email address and body in
the Send to Customer step. For assistance with this read more here:
https://www.ontask.io/help-center/email-notifications-in-workflow/


Bringing Data and Documents in to OnTask



API endpoints are used for a standard integration

OnTask is producing version 2 of our public facing API and this document focuses on the
abilities provided by our API v2 that will be needed for integration. To use these endpoints, you
will need the Workflow Template ID for the template found in your group and the security token
for the group that owns the workflow template.

When generating the authorization token, be sure to choose at least ‘Start workflow instances’
although ‘All Permissions’ is the most commonly chosen option during development.



For assistance generating a token:
https://www.ontask.io/help-center/generating-a-token-for-api-access/

Obtaining a workflow template id:
Each template has a unique identifier that can be found in two places.


The first place is the last step of the template assistant by selecting ‘<> INTEGRATE INTO
YOUR APP’. In the request body displayed in the window it can be seen as the value for
“wfModelId” (our v1 API name).





The second place the workflow template id can
be found is when any workflow template is Run
and appears in the URL of the workflow.





This unique identifier will be used in the OnTask api endpoints.


How to get started with the OnTask APIs

To obtain the list of required fields for the workflow template and to begin that workflow once the
text values are available we use the following (with our workflow template id in place of the
highlighted placeholder):
Get Template Start Form Data
Get
https://app.ontask.io/api/v2/workflowTemplates/
​:workflowTemplateId
​/startForm

Start a Workflow
POST https://app.ontask.io/api/v2/workflowTemplates/
​:workflowTemplateId
Content-Type: application/json

All API requests must be made over HTTPS. Calls made over plain HTTP will
fail. API requests without authentication will also fail.Tools such as
Insomnia or Postman can be used to explore these endpoints using your data.



Example ‘Get Template Start Form Data’

Example Header:

Key: authorization
Value:
​{groupApiToken}



Example Response:
{
"workflowOwner":
​"..."
​,
"workflowOwnerData": {
"owningOrgTenantId":
​"..."
​,
"owningOrgName":
​"API Example"
​,
"owningOrgUserId":
​"..."
​,
"owningGroupTenantId":
​"..."
​,
"owningGroupName":
​"My Example Group"
​,
"owningOrgUserConfirmed":
​true
},
"pageDefinition": {
"page": {
"title":
​"Workflow API Example"
​,
"description":
​""
},
"useWaitPage":
​true
​,
"actions": {...},
"elementId":
​"..."
​,
"form": [{
"disabled":
​false
​,
"label":
​"Sender Name"
​,
"size":
​"medium"
​,
"validation": {
"required":
​true
},
"fieldId":
​"2084b4e9-0361-4300-856b-54983f5214ae"
​,
"permissions":
​false
​,
"type":
​"text"
​,
"name":
​"Sender_Name"
}]
}
}

Example ‘Start a Workflow’

Start a workflow instance by making a POST request. The request body consists
of fields on the start form.

POST https://app.ontask.io/api/v2/workflowTemplates/:workflowTemplateId
Content-Type: application/json

Required Token Permission: “Start workflow instances”

Example Body:
{
"wfModelId":
​"{wfModelId}"
​,
"wfData": {
"Sender_Name":
​"{SENDER_NAME}"
​,
}
}

Example Response:
{
"redirectUrl":
​"https://app.ontask.io/workflows/url/to/next/task"
​,
"wfInstanceId":
​"00000000-0000-0000-0000-000000000000"
}


Once the workflow instance has been started, this instance can be viewed by the members of
that group using the OnTask dashboard. For more information about our OnTask dashboard,
read here:
​
​https://www.ontask.io/help-center/overview-of-your-dashboard/


Zapier Integrations
Before reading this article, make sure to read up about configuring Zapier
here
​.
Zapier (https://zapier.com/apps/APP/integrations) lets you connect 2,000+ other web
services to your OnTask workflows. Automated connections called Zaps, set up in
minutes with no coding, can automate your day-to-day tasks and build workflows
between apps that otherwise wouldn't be possible.

Each Zap has one app as the **Trigger**, where your information comes from; and
corresponding **Actions** which are apps or Zapier tools that act when the trigger
happens.

Triggers available

OnTask can be used as a trigger or as an action. The following triggers are supported:
1. When a Zapier Event is reached in the workflow
2. Workflow instance started

Zapier Event
A Zapier Event is a trigger that will send data, documents, and forms to other
applications supported by Zapier. When the workflow template reaches a Zapier Event,
property names added to this step will be sent to a “Zap” for Zapier to perform the
actions you will add to each Zap.
To add to a workflow, add a single Zapier event per template. Only one is supported per
workflow. On the right side, click ADD PROPERTY and add the property name of
documents or other fields. Any field with a property name that appears in the workflow
template prior to the Zapier Event task is available for use in a Zapier Event.
Workflow Instance Started
Whether a workflow is started from the OnTask dashboard or started remotely, this
triggering event will notify your Zap that the workflow started. Fields on the starting
webform will be passed to the Zap and can be used in the Zapier automation.
Actions Available
Start a Workflow Instance is available as an OnTask action and this allows for an
application to pass fields to Ontask for use in documents, forms, emails and webforms.
Required fields on the starting web form must be supplied a value by the Zap or the
workflow will not be started.

Example by field type/format and example value

checkbox
Checked
currency
12345
date
06/11/2020
Date_Picker
06/10/2020
date_plus_duration
01/15/2020
date_prepopulate
01/11/2020
email
djones@ontask.io
Multi_Line_Text
test
multiline
test
Multiple_Choice (drop
down)
Option 1
Multiple_Choice_2
(Checkbox)
Not Applicable. Cannot be
Imported. Use Simple
Checkbox.
Multiple_Choice_3
(Radio Button)
Option 1
number
12345
phone_format_1
(999) 999-9999
phone_format_2
999-999-9999
Simple_Checkbox
checked
Single_Line_Text
test
specific_date
01/11/2020
text_box
text
url
https://ontask.io
zip_code_format_1
12345
zip_code_format_2
12345-6789
file_upload
filename.pdf

Note: Passing data to a workflow that is not the correct format for the field or does not
match a value for that field in OnTask will cause the workflow to fail. The Zap History
may say success however the details will show Ontask rejected the request due to
invalid data. Example, multiple choice fields will expect the values entered by the user.
Sending a value that does not exist is not supported.

Example Zap

After configuring your group security access and creating a token to authorize Zapier to
connect to OnTask you are ready to add your first Zap in your Zapier account. Our
recommendation is a paid account with Zapier as only the paid accounts gain access to
features mentioned in this article (e.g. multi-step zaps and filters).
Start with creating a new Zap in Zapier, and choose the app you will use as your trigger
app.


In this example, we will use ‘box’​ (​https://www.box.com/home​) ​and when a document on
box is set to be routed through OnTask, we’ll have Zapier begin a workflow instance for
us.

In most use cases, not every file in ‘box’ should begin a workflow instance. Not every
file needs to be worked on every time.

To make decisions on when to start a workflow and when not to, Zapier offers powerful
tools such as filters.


In this use case, we want to add messages to files and if the message mentions
‘OnTask’ then we will begin a workflow.



The drop down list in the filter will allow you to choose other options from box fields and
the filtering “rule” is only as limited as your imagination and training of your users.
Once the filtering is in place, select OnTask, connect the account as per
https://www.ontask.io/help-center/zapier-integration-with-ontask/​ ​and proceed to
customize which instance you will start when the filter is true.

In this example, we selected a Sales coaching workflow to be started. This template has
fields on a webform as the first step so Zapier will need to send values to those fields. If
a field is not included, the workflow template will not start and Zapier will record this as
an error against the Zap.


Mapping fields in Zapier is very simple. The label or name of the field in the OnTask
workflow template will display in Zapier. We can then map that to the best data value we
have in mind.

Our webform had 4 fields: ‘Customer Name’, ‘Customer Email’, ‘Coaching Choice’ and
‘Payment Option’. Typing a value to map to the OnTask field name will send that value
to the field when the instance is started. So, the typed value in ‘Customer Email’ in our
screenshot (‘djones@ontask.io’) will always be the value for this field when starting an
instance of this workflow.

Choosing a field will show the icon for the product (in this case the box icon) and this
field must have a value entered into box before this Zap attempts to run or it will fail and
an error will show in Zapier for this Zap. Adding a value after this error will not start a
workflow so this will require training or configuration in box to make sure mapped fields
always have the best value to start the workflow. Similarly, changing a value in box after
a Zap has run will not alter the Zap or the OnTask workflow values.

If the value is a value from OnTask, select and an OnTask icon will display. These
values can be considered default starting values and if you would like your OnTask
workflow participants to be able to change these consider designing your workflow
template to have a path to override these fields, then simply present a webform with the
fields available to the best participant for the task.

Coming soon…. When the workflow instance completes or is cancelled in OnTask, our
Zapier integration will offer the ability to work with your data and documents by sending
through a Zap to Zapier compatible products. In the meantime, this does not mean the
data and documents cannot be sent out from OnTask.

Data is available from the workflow instance as a real time data export using Webhooks.
Zapier supports webhooks on their paid versions and we can utilize advanced features
such as multi-step Zaps to perform various tasks with this data. For example, updating
rows in a google or excel online spreadsheet.





Documents and Data from an OnTask workflow instance

Manual Exporting

OnTask’s dashboard also allows the field names/property types to be exported to CSV for use
in spreadsheets or other tools that can read comma separated values, though the field values
remain human readable on each workflow instance as well. Attachments can be manually
obtained as well in the attachments tab.



To automatically obtain documents and data from an OnTask instance, we have webhooks for
data and web end points for documents.

Webhooks
OnTask supports a JSON post step in your workflow template to export data to other systems.
This standard format is known as a webhook.

For additional assistance configuring webhooks, see
​
​Using Webhooks



The data exported is JSON (similar to the data that can be used to launch a workflow).



This data will be sent in real time as the data is collected and can be received by another
application to be used as needed.

For example, OnTask can use webhooks with common SaaS applications like Zapier. Zapier
(zapier.com) is an easy to use visual integrator to connect your applications and automate
workflows. Zapier supports many applications which allows for some creativity on the part of our
OnTask users.






Integrating Documents to third party solutions- web end points
OnTask also supports document exports in workflows and can integrate to sharepoint or
your computer software engineers may want to look into developing their own
integration points using our standard no code Web Endpoints for the document.


To configure this no code step in the workflow template, add the Export Document task
type, select the document to export from the drop down list and supply the details such
as URL destination for this file, method, and any headers (name and value) from the
workflow you would like to pass with the file. These can be values from the workflow
and gives your software engineering team a powerful way to interact with OnTask
documents.






OnTask also supports document exports in workflows and can integrate to sharepoint or
your computer software engineers may want to look into developing their own
integration points using our standard no code Web Endpoints for the document.


To configure this no code step in the workflow template, add the Export Document task
type, select the document to export from the drop down list and supply the details such
as URL destination for this file, method, and any headers (name and value) from the
workflow you would like to pass with the file. These can be values from the workflow
and gives your software engineering team a powerful way to interact with OnTask
documents.

If software engineering resources are not available, consider utilizing Microsoft
sharepoint or contact us at​ ​Support@ontask.io​ ​to inquire about other document storage
capabilities.




Sample Integration with OnTask

Workflows can be manually started from our dashboard or remotely started from an external
system using OnTask’s APIs. Most customers add a button to their CRM system to remotely
start OnTask workflows. This sample uses v1 of the OnTask API.


Manual Start from OnTask
In a manual start, the person starting the workflow would enter the data to be populated onto the
document form by using our start forms. This data is mapped through the workflow modeler to
populate the PDF forms in subsequent steps.


Remote Start from External System
Remote Start via API
A button can be added to your intranet site or CRM system to launch an OnTask workflow via
the API using information from your internal database. The button would call our URLs with
JSON to populate the form data.


URL of OnTask API
https://app.ontask.io/api/v1/workflowInstances

Request Body (data from your database)
{
"wfModelId": "--- ---",
"wfData": {
"Damian": "{first_name}",
"Jones": "{last_name}"
"djones@accusoft.com": "{email}"
"999-999-9999": "{phone_number}"

"123 This street": "{current_street}"
"101": "{current_apt}"
"This City": "{current_city}"
"This State": "{current_state}"
"12345": "{current_zip}"
}
}


That JSON data will then be used to populate the form. When a customer receives an email to
fill out the remainder of the form, they will see the existing data already filled in and then have
the ability to fill in the rest of the fields. Pre-populated fields can be locked or remain unlocked if
the customer needs the ability to correct information.


Data Output by Webhook
The data submitted through the form can then be posted back to the calling system using our
webhooks and APIs.

Standard output
{
"timestamp": "2020-02-10T21:20:40+00:00",
"wfVariables": {
"current_street": "123 This street",
"current_zip": 12345,
"current_apt": 101,
"accusoft_solutions_workflowInitiator": "djones@accusoft.com",
"street": "Allow entry of new information to be exported out by OnTask
API",
"first_name": "Damian",
"email": "djones@accusoft.com",
"current_state": "This State",
"last_name": "Jones",
"accusoft_solutions_workflowInitiatorName": "Damian Jones",
"current_city": "This City",
"phone_number": "999-999-9999"
}
}