Loading ...
Customer ...
Other
OnTask Experts documentation
83
0
Try Now
Log In
Pricing
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": "--- <insert guid of workflow template here>---", "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" } }
