Build your Own Workflow Connectors in the ProcessMaker I/O Workflow Microservice

Using Workflow Connectors in a Business Process

Workflow Connectors are used in business processes to connect to third party systems.  Most business processes today need to connect to multiple 3rd party systems to retrieve and/or send data.  ProcessMaker I/O has a very powerful and modern way to build and manage connectors and as such has many of the characteristics of an iPaaS (integration platform as a service such as mulesoft).  Nonetheless, it may also be convenient to connect ProcessMaker to other iPaaS solutions to enhance the ability to manage workflows and rules around larger connector sets.

ProcessMaker I/O is a workflow API microservice.  It is designed to provide an easy way for a developer to add workflow functionality to an enterprise application with little development effort.  ProcessMaker I/O now has a full connector framework to allow an easy way to develop and maintain connectors as part of the ProcessMaker I/O microservice.

Library of Workflow Connectors

ProcessMaker I/O has both a way for developers to create their own workflow connectors and also an existing library of of publicly available connectors that have been built by the ProcessMaker I/O team.  We are constantly adding new workflow connectors, so you should check back frequently to see what new connectors are available.  Also, if you would like to see a specific connector, and it is not on the list, please let us know.  Here is our current library of public connectors.

Using Prebuilt Workflow Connectors in 5 Simple Steps

To use an existing prebuilt connector in your business process, follow these steps:

1. Create a process with a Service Task – You can do this programmatically or use any existing BPMN 2.0 compliant process editor (Adonis, itp-commerce, etc.) to create an exportable process map
2. Configure the connector in the Service Task of your process 
3. Setup the link to the lua script in the `script_url` input parameter
   • As example of this parameter for the Docusign connector is as follows:

`script_url`:https://raw.githubusercontent.com/ProcessMaker/pmio-lua-connectors/master/docusign/docusign.lua

2. Setup the input parameters for the connector – For example for the Docusign connector here are the parameters:

username: {username}

password: {password}

integratorKey: {key}

api_endpoint:login_information

script_url:https://raw.githubusercontent.com/ProcessMaker/pmio-lua-connectors/master/docusign/docusign.lua

base_url:https://demo.docusign.net/restapi/v2/

3.  Setup the output parameters for the connector – For example for the Docusign connector here are the parameters:

“email”:{response.loginAccounts.0.email},
“accountId”:{response.loginAccounts.0.accountId},
“siteDescription”:{response.loginAccounts.0.siteDescription},
“userId”:{response.loginAccounts.0.userId},
“userName”:{response.loginAccounts.0.userName},
“name”:{response.loginAccounts.0.name},
“isDefault”:{response.loginAccounts.0.isDefault}

4. Upload the xml of the process with the configured connector to your ProcessMaker I/O environment

*For each API endpoint you will need to create one Service Task. If you want to use several endpoints, you should add as many Service task as you need per each request API.  Note – there are ways to bundle these connectors to create a single service task, but we will leave that for a later discussion.

The example of a process including a service task with a configured connector (with all the parameters) is here.

If you don’t have a ProcessMaker I/O environment created, do the following:

1. Create a new account if you don’t already have one
2. Otherwise click on the Tab Environments
3. Click Create Environment and follow the instructions provided

If you already have a ProcessMaker I/O environment, please do the following:

1. Launch an environment of ProcessMaker I/O from the Environment Tab
2. Click on Import tab on the top left and upload the process XML (.bpmn) file from your PC

5. Run the process

For the xml with Docusign example the command is the following:

‘curl  https://YOUR_ENV.api.processmaker.io/api/v1/processes/Process/events/Start/webhook’

How to create your own connector

One of the great features of ProcessMaker I/O is that you do not have to wait for our team to create the connectors you want.  You have the ability to create any connector to any 3rd party system very easily.  Any connector you create will need to be uploaded to the ProcessMaker Github repository for our Lua Connectors in order to be run.  

You do not have to be very technical to create a connector, but you will need to have a basic understanding of the authorization methods, API calls, and Lua syntax.  However, if you look at some of our examples, we believe that even a non-technical user can do this quite easily.

Using LUA

Lua is the language we use for creating your connectors.  Lua is a very fun and easy to learn scripting language.  It means “moon” in portuguese – that’s cool.  If you want to learn more about the language, you can read more here.  To use Lua, the first step is to setup Lua on your computer.  If you already have Lua, please check that all required libraries are installed.  Here you can read the detailed tutorial on how to setup Lua and its modules.

Using the API of the 3rd Party Service

Once you have Lua installed, the next step is find the documentation for the API that you plan to connect to.  For example, if you were going to create a connector for Docusign, then you would review the DocuSign API DOCUMENTATION.  You will need to determine which endpoints of the API you want to use for your particular process need.

To get started with the 3rd party API, you will want to do the following:

1. Create a service account or use an existing account
2. Get the authorization details

For example: DocuSign Legacy Header Authentication (https://docs.docusign.com/esign/guide/authentication/legacy_auth.html)

1. Define the Input parameters that you want to use in your connector

For example: Input parameters for DocuSign

* `username` – application user email used to authorize the call

* `password` – user password used to authorize the call

* `integratorKey` – used to integrate and authenticate with the DocuSign platform

* `api_endpoint` – API endpoint URI, e.g. `login_information`

* `base_url` – the url to the service API

Create Your Own Lua Script

The easiest way to do this is to simply copy the script from one of our Lua conector examples.  

Each LUA connector consists from  the next components:

• response – JSON decoded structure received from API response.
• code – HTTP response code.
• headers – headers structure received from API response.

Here is example for the Docusign connector

https://github.com/ProcessMaker/pmio-lua-connectors/blob/master/docusign/docusign.lua

More examples are available in our connectors library.

When all parameters are defined, all components is written, the connector is ready for the testing.

Testing Your Connector

After you develop your connector, you should test it to make sure that everything is working properly.   The easy way to test it is to create a file with the input parameters that are required by the connector.

As example :

input2.txt:

{

 “username”:”your_username”,

 “password”:”your_password”,

 “integratorKey”:”your_integratorKey”,

 “api_endpoint”:”login_information”,

 “baseUrl”: “https://demo.docusign.net/restapi/v2/”

}

Run console mode and input the following command:

`lua docusign.lua <input2.txt`

You should get this response:

{“headers”:{“content-length”:”379″,”strict-transport-security”:”max-age=31536000; includeSubDomains”,”content-type”:”application/json; charset=utf-8″,”date”:”Fri, 09 Feb 2018 13:41:18 GMT”,”connection”:”close”,”x-docusign-tracetoken”:”XXXXX”,”cache-control”:”no-cache”},“code”:200,“response”:{“loginAccounts”:[{“baseUrl”:”https://demo.docusign.net/restapi/v2/accounts/XXXXX”,”email”:”[email protected]“,”accountId”:”XXX”,”siteDescription”:””,”userId”:”XXXXX”,”userName”:”XXXXX”,”name”:”XXXXX”,”isDefault”:”true”}]}}

If you get  “code”:200,  that mean that your connector works correctly!

Publish Your Connector to the Connector Library

1. Create a Github account or use an existing account
2. Create a pull request to the public Github repository and send an email to [email protected]
3. Get approval from PMIO team
4. Find your connector in the PMIO Connectors Library

For the current version only connectors from the Library are available for the usage. We are planning to add possibility to use your own private repository in the future. If you want create Lua connector and keep it on the private repository now, please contact our support team [email protected]

Now your connector is ready for to be used.