In ProcessMaker Platform, a Data Connector connects your ProcessMaker Platform assets to a data source. That data source may be one of the following:
A Representational State Transfer (REST, also RESTful) Application Program Interfaces (APIs)
Simple Object Access Protocol (SOAP) via an XML WSDL file
After a Data Connector is created and configured, Process designers can reference the data source via the Data Connector from within their ProcessMaker Platform assets. Each Data Connector is configured with which data source that Data Connector interacts, making it easy for Process designers to interact with technical data sources such as REST(ful) APIs and SOAP services. Incorporating data from external data sources helps you make business decisions from information outside of your ProcessMaker Platform instance.
Below are a few ways to use Data Connectors:
In Screen Builder, use the records in a Collection as Select List control options in a Screen.
In Screen Builder, use the response from a third-party API endpoint as Select List control options in a Screen. See an example.
While modeling a Process, place a Data Connector connector into your Process model to automatically access records from a Collection records or access external data from a third-party data source to incorporate new information into Requests started from your Process. After this external data has been incorporated into Requests, make business decisions based on that data.
Data Connectors use Resources with which to interact with a data source.
Video Demonstration
See how Data Connectors call third-party Application Program Interfaces (APIs), and then use that data in Processes.
Video demonstration of a Data Connector using an API as a data source
What is a Resource?
A Data Connector uses Resources to interact with the data source to which it is configured. In this context, a Resource is configured to specify how the Data Connector interacts with its data source. For a Resource to perform its configured action, the Data Connector must first successfully authenticate with its data source.
If the data source is an API, a Resource calls an endpoint to get, post, put, update, or delete content that the API's endpoint expects. To understand how to successfully interact with that endpoint's method, parameters, and/or potential error codes from that endpoint, refer to that API's documentation provided by the REST(ful) service provider.
If the data source is a Simple Object Access Protocol (SOAP) service, a Resource performs an operation as specified in that SOAP service's XML WSDL file. The WSDL file specifies both how each SOAP operation functions, but also documents that WSDL if the SOAP service provider included XML elements for each operator to its use.
What is a REST Service Method?
How a REST-type Data Connector's Resource interacts with a data source endpoint is called a method. When a Data Connector interacts with a third-party REST(ful) API's endpoint, that endpoint expects a method from which the Data Connector's Resource interacts with that endpoint. A Data Connector may use any of the following methods to interact with a REST(ful) API endpoint:
GET: The GET method retrieves a resource from the data source.
POST: The POST method creates a resource in the data source.
PUT: The PUT method does one of the following:
Update: The PUT method may update data an existing resource in the data source.
Create: The PUT method may create a resource in the data source.
PATCH: The PATCH method partially modifies an existing resource.
DELETE: The DELETE method removes an existing resource from the data source.
A third-party API's endpoint may also expect specific parameters from the Data Connector's Resource to properly interact with that endpoint. Those parameters and their settings ideally are documented in that third-party API's documentation so you understand what an endpoint expects in the interaction. Parameters are added at the end of the base URL used to connect with that data source's endpoint and ideally would also be documented in that third-party API's documentation. How to configure parameter settings to interact with an endpoint/method is outside the scope of this documentation.
View this ProcessMaker API documentation to quickly view how to use our RESTful API without testing API endpoints.
Collections also have Resources with which a Data Connector interacts with records in that Collection. Resources for a Collection use similar methods as do REST(ful) services.
What is a SOAP Service Operation?
A SOAP Web service operation defines how a SOAP action functions. SOAP service operations are defined in that service's XML-formatted WSDL file. To use a SOAP service, it is mandatory to understand how to read XML. A SOAP service's WSDL file not only defines the supported operations and their corresponding parameters, but also document for each operation if the SOAP service provider included it.
See this SOAP Web services tutorial for an introduction to SOAP and how to read a SOAP service's XML WSDL file.
REST Resources for Collections
A Collection automatically creates a Data Connector when it is created. Data Connectors created from a Collection by default have the same name as the Collection that it references.
Data Connectors created from Collections have the following REST Resources to interact with that Collection.
Resource | Purpose | Method |
|---|---|---|
| Get a list of all records in that Collection. | GET |
| Get a record in that Collection by its record id. | GET |
| Create a new record in that Collection. | POST |
| Delete a record from that Collection by its record id. | DELETE |
| Update a record in that Collection by its record id. | PUT |
| Delete all records in that Collection. | DELETE |