Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Create a new Data Connector that can be referenced from any ProcessMaker Platform asset.
Follow these steps to create a new Data Connector:
Click the +Data Connector button. The Create Data Connector screen displays.
In the Name setting, enter the name of the Data Connector. Data Connector names must be unique in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
In the Description setting, enter the description of the Data Connector.
From the Connection Type drop-down menu, select with which service type the Data Connector uses to connect with the data source:
REST Service: Select the REST Service option to connect using a REST service.
SOAP Service: Select the SOAP Service option to connect using a SOAP service.
From the Authentication Type drop-down menu, select how the Data Connector authenticates with the data source:
REST authentication types:
No Auth: Select the No Auth option to not send authorization details when connecting to the data source. Note that there is no security using this option.
Basic Auth: Select the Basic Auth option to send only username and password credentials as authentication when connecting to the data source. Configure your credentials after the Data Connector is created.
Bearer Token: Select the Bearer Token option to send an access token when connecting to the data source as authentication. The access token is an opaque string that represents the authorization that allows the Data Connector to access the third-party data source. Data Connectors that connect to Collections use Bearer Token authorization method.
Auth 2.0 Password: Select the Auth 2.0 Password option to use Password grant type as part of the OAuth 2.0 authentication protocol to connect to the data source. In doing so, first get an access token from the data source host, and then use that token to authenticate future connections directly to that data source. Configure the OAuth 2.0 authentication credentials after the Data Connector is created.
SOAP authentication types:
Password: Select the Password option to authenticate using a Web Service Description Language (WSDL) URL, username, password, and optionally a proxy port.
Local Certificate: Select the Local Certificate option to authenticate using a Privacy Enhanced Mail (PEM) file from which to authenticate with the connecting SOAP service.
WSDL File: Select the WSDL File option to authenticate using a WSDL and its corresponding XSD file(s) that define authentication for the connecting SOAP service.
From the Debug Mode toggle key, enable or disable debug mode for the Data Connector.
Click Save. The following message displays: The Data Connector was created.
See one of the following topics based on the connection type for this Data Connector:
Understand what a Data Connector is and how Process designers can interact with a data source from within their ProcessMaker Platform assets such as Screen Builder and Process Modeler.
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
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.
See how Data Connectors call third-party Application Program Interfaces (APIs), and then use that data in Processes.
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.
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.
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.
Data Connectors created from Collections have the following REST Resources to interact with that Collection.
Manage your Data Connector Categories.
Data Connector Categories can be in active or inactive status. Following is a description of each status:
Active: Active Data Connector Categories can have Data Connectors or Resources assigned to them.
Inactive: Inactive Data Connector Categories cannot have Data Connectors or Resources assigned to them.
Follow these steps to view Data Connector Categories:
Log on to ProcessMaker Platform.
Click the Designer option from the top menu. The Designer Welcome Screen displays.
Click the Categories tab. The Data Connector Categories display.
The Categories tab displays the following information in tabular format about Data Connector Categories:
Name: The Name column displays the name of the Data Connector Category. The Data Connector Category named Generated is the default Category. Data Connectors that are automatically created when a Collection is created are assigned the Generated Category by default.
Status: The Status column displays the status of the Data Connector Category. Below is a description of each status:
Active: Active Data Connector Categories can have Data Connectors assigned to them. The Data Connector Category named Generated is active by default.
Inactive: Inactive Data Connector Categories cannot have Data Connectors assigned to them.
# Data Connectors: The # Data Connectors column displays how many Data Connectors in your organization have been assigned to that Data Connector Category.
Modified: The Modified column displays the date and time the Data Connector Category was last modified. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Created: The Created column displays the date and time the Data Connector Category was created. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
If no Data Connector Categories exist, the following message displays: No Results.
Use the Search setting to filter Data Connector Categories by their names.
​Control how tabular information displays, including how to sort columns or how many items display per page.
In the Category Name setting, enter the name of the new Data Connector Category. The Data Connector Category name must be unique from all other Data Connector Category names in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
From the Status drop-down menu, select one of the following options for the Data Connector Category's status:
Active: Active Data Connector Categories can have Data Connectors assigned to them.
Inactive: Inactive Data Connector Categories cannot have Data Connectors assigned to them.
This is a required setting.
Click Save.
Follow these steps to search for a Data Connector Category:
Enter in the Search setting the text to filter Data Connector Categories by name.
As you enter text into the Search setting, Data Connector Categories display that match your entered text.
If there are no search results, the following message displays: No Results.
Edit the following information about the Data Connector Category as necessary:
In the Category Name setting, edit the name of the new Data Connector Category. The Data Connector Category name must be unique from all other Data Connector Category names in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
From the Status drop-down menu, select one of the following options for the Data Connector Category's status:
Active: Active Data Connector Categories can have Data Connectors assigned to them.
Inactive: Inactive Data Connector Categories cannot have Data Connectors assigned to them.
This is a required setting.
Click Save.
Deleting a Data Connector Category cannot be undone.
Click Confirm. The following message displays: The category was deleted.
Edit how to authenticate and interact with a SOAP data source for a Data Connector.
In the User setting, enter the client username that authenticates with the connecting SOAP service. This is a required setting.
In the Password setting, enter the client password that authenticates with the connecting SOAP service. This is a required setting.
From the Local WSDL File setting, click the Select File button, and then select the WSDL file from which to authenticate with the connecting SOAP service. A new WSDL file replaces a previously configured PEM file. This is a required setting.
From the Local XSD File setting, click the Select File button, and then select the XSD file(s) that correspond with the WSDL file. After adding a local XSD file, optionally use any of the following buttons for that XSD file:
From the Location setting, optionally enter a custom URL to the connecting SOAP service different than that configured in the local WSDL file. If the Location setting contains a value, this value supersedes the URL configured in the WSDL file.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to provide a Web Service Description Language (WSDL) file for SOAP authentication after selecting the WSDL File option from the Authentication section:
In the Service URL setting, enter the SOAP service HTTP URL from which the SOAP service monitors for incoming requests. Ensure that the service URL references the Web Service Description Language (WSDL) file that describes the SOAP service, such as http://www.URL.asmx?WSDL
. This is a required setting.
From the Local Certificate File setting, click the Select File button, and then select the Privacy Enhanced Mail (PEM) file type from which to authenticate with the connecting SOAP service. A new PEM file replaces a previously configured PEM file. This is a required setting.
From the Passphrase setting, optionally enter the password to access the selected local certificate file.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to provide a local certificate file for SOAP authentication after selecting the Local Certificate option from the Authentication section:
In the Service URL setting, enter the SOAP service HTTP URL from which the SOAP service monitors for incoming requests. Ensure that the service URL references the Web Service Description Language (WSDL) file that describes the SOAP service, such as http://www.URL.asmx?WSDL
. This is a required setting.
In the User setting, enter or edit the username that authenticates with the SOAP service. This setting is required.
In the Password setting, enter or edit the password that authenticates with the SOAP service. This setting is required.
From the Password Type setting, select with which type of password the SOAP service authenticates:
None: Select the None option to not send the password to the SOAP service. ProcessMaker does not recommend this practice since there is no security with the SOAP service.
Password Text: Select the Password Text option to send a plain-text password to the SOAP service.
Password Digest: Select the Password Digest option when the password is a MD5 (Message Digest) value to be transmitted to the SOAP service. Digest authentication has an advantage over basic authentication in that it does not send a plain-text password over the network. The server then uses this digest value for password comparisons.
In the Proxy Host setting, enter or edit the proxy host that the SOAP service uses.
In the Proxy Port setting, enter or edit the port that the proxy host monitors for connections.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to configure basic authentication settings after selecting the Password option from the Authentication section:
The SOAP tag displays to indicate the Data Connector authenticates with a SOAP data source.
The Debug Mode icon displays to indicate whether debug mode is enabled.
Edit the following information about the SOAP-type Data Connector as necessary:
In the Name setting, edit the name of the Data Connector. Data Connector names must be unique in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
In the Description setting, edit the description of the Data Connector.
In the Authentication section, from the Method drop-down menu, select how the REST-type Data Connector authenticates with the data source:
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
In the Name setting, enter the name of this Resource. The ProcessMaker Platform asset that references this Resource displays the Name setting value. For example, a Resource with the name Get Values
displays that name when configuring a Select List control to use this Data Connector to indicate the Resource's operation. Therefore, provide a concise but relevant name for this Resource so other Process designers understand its function. This is a required setting.
In the Description setting, enter a description of this Resource. Descriptions do not display from ProcessMaker Platform assets when configuring them with a Data Connector.
From the Operation drop-down menu, select which Web service operation this Resource performs. The WSDL file or Web service configured for this Data Connector specifies which operations are available from this drop-down menu.
Do one of the following:
Optionally, view the parameter(s) for the operation configured for a Resource. Understanding the following for each parameter helps inform how to correspond Request data with a Web service operation's parameter(s):
Understand what the operation's parameters are to map them to Request data in the Data Connector connector.
Understand which parameter(s) are required or optional, and therefore plan how to map parameter response data to Request data.
Understand what each parameter's data type is.
Follow these guidelines to view the Web service operation parameter(s) for a SOAP-type Data Connector's Resource:
Click the Params tab. The Params tab displays the following for informational purposes only:
Operation: Below the Operation label displays the name of the Web service operation configured for this Resource.
Parameters: Below the Web service operation name are the parameter(s) for that operation. If the operation has no parameters, [empty] displays below the operation name. Parameters indicate whether they are required are optional using the following icons:
Optionally, browse the WSDL's XML schema. Click the Web service operation name to display a search field with browsing functions. Follow these guidelines:
In the search field, enter the name of the service operation to locate in the WSDL's XML schema. Use the following syntax to search for an operations name: name="OperationName"
where OperationName
is the operation name to find. Search by using the Match Case, Match Whole Word, or Use Regular Expression options.
Use the Previous Match option to browse for the previous instance of the search results.
Use the Next Match option to browse for the next instance of the search results.
Use the Find in Selection option to locate the search result in the current selection.
Testing a Resource only verifies that Resource's availability, but does not validate the Data Connector's proper authentication to the SOAP Web service. SOAP Web services can have diverse authentication responses and only by using that service's operations this can responses be identified. SOAP Web services do not follow a standard error responses or authentication settings. Therefore, unless the service provider documented responses or expected errors in the WSDL file, only by using that service's operations can responses be determined.
Follow these steps to test a SOAP-type Data Connector's Resource:
Click the Response Body tab.
Do one of the following:
Perform the Web service operation to receive its response: Click the Send button.
Send sample Request data with the call to the Web service operation: In the Test Request JSON panel, enter the sample Request data to be added to the body of the request to the Web service operation, and then click the Send button.
If the Resource successfully performs the Web service operation, the operation's response displays in the Response Body tab. Above the Test Request JSON panel displays the data source response status, response time, and size display.
To search the response body, enter into the search field that is above the response body the text to locate, and then click Search.
Follow these steps to view or edit a SOAP-type Data Connector's Resource:
Edit the following settings as necessary:
In the Name setting, edit the name of this Resource. The ProcessMaker Platform asset that references this Resource displays the Name setting value. For example, a Resource with the name Get Values
displays that name when configuring a Select List control to use this Data Connector to indicate the Resource's operation. Therefore, provide a concise but relevant name for this Resource so other Process designers understand its function. This is a required setting.
In the Description setting, edit the description of this Resource. Descriptions do not display from ProcessMaker Platform assets when configuring them with a Data Connector.
Do one of the following:
Follow these steps to delete a Data Connector's Resource:
Click Confirm.
Edit how to authenticate and interact with a REST data source for a Data Connector.
Edit the following information about the REST-type Data Connector as necessary:
In the Name setting, edit the name of the Data Connector. Data Connector names must be unique in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
In the Description setting, edit the description of the Data Connector.
In the Authentication section, from the Method drop-down menu, select how the REST-type Data Connector authenticates with the data source:
No Auth: Select the No Auth option to not send authorization details when connecting to the REST data source. Note that there is no security using this option. No further authentication configured is required.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to configure basic authentication settings after selecting the Basic Auth option from the Authentication section:
In the User setting, enter or edit the username that authenticates with the REST data source host.
In the Password setting, enter or edit the password that authenticates with the REST data source host.
Verify that this REST-type Data Connector authenticates using SSL certification. If the Enable SSL certificate verification toggle key is enabled, the Data Connector connects to the data source host using HTTPS protocol for a secure connection. The Enable SSL certificate verification toggle key is enabled by default.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
If you are configuring this REST-type Data Connector to interact with (make requests to) the Application Programming Interface (API) associated with your ProcessMaker Platform instance, first generate an API token for the user account that contacts our API before starting this procedure. See Generate an API Token, and then follow that procedure in a new Web browser tab or window so the Configuration tab in this Data Connector remains accessible. Note that your user account must have appropriate permissions to generate an API token.
Follow these steps to configure bearer token settings after selecting the Bearer Token option from the Authentication section:
If an access token has already been entered into this Data Connector, it displays in the Token setting.
If this Data Connector requires a new access token, do one of the following:
Use the access token to interact with (make requests to) our API associated with your ProcessMaker Platform instance:
Ensure that the access token for the user account that contacts our API is copied. If not, see Generate an API Token before continuing. Follow that procedure in a new Web browser tab or window so the Configuration tab in this Data Connector remains accessible.
In the Token setting, paste the generated API token copied from the user account.
Use the access token to interact with (make requests to) a third-party data source:
Copy the access token from the third-party data source.
In the Token setting, paste the access token.
Verify that this Data Connector authenticates using SSL certification. If the Enable SSL certificate verification toggle key is enabled, the Data Connector connects to the REST data source host using HTTPS protocol for a secure connection. The Enable SSL certificate verification toggle key is enabled by default.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to configure Auth 2.0 password settings after selecting the Auth 2.0 Password option from the Authentication section:
In the URL Token setting, enter the redirect Universal Resource Identifier (URI) that the REST data source host provides after you register this Data Connector with that host.
In the Client ID setting, enter the Client ID the REST data source host provides after you register this Data Connector with that host.
In the Client Secret setting, enter the Client Secret the REST data source host provides after you register this Data Connector with that host.
In the User setting, enter or edit the username that authenticates with the REST data source host.
In the Password setting, enter or edit the password that authenticates with the REST data source host.
Verify that the Enable SSL certificate verification toggle key is enabled so that the Data Connector connects to the REST data source host using HTTPS protocol for a secure connection. SSL certification is required using Password grant type as part of Auth 2.0 authentication protocol. The Enable SSL certificate verification toggle key is enabled by default.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
Follow these steps to configure OAuth 2.0 settings after selecting the OAuth 2.0 option from the Authentication section:
In the Client ID setting, enter the client ID provided by the REST Web service or data source host. Client ID is a unique identifier generated during this Data Connector's application registration process. This is a required setting.
In the Client Secret setting, enter the client secret provided by the REST Web service or data source host. The Client Secret is generated during the application registration process and is known only to the client application and the data source host. This is a required setting.
In the Access Token URL setting, enter the access token URL. The Data Connector uses this URL to connect to the REST data source and obtain an access token. This is a required setting.
In the Refresh URL setting, enter the refresh URL. Since access tokens are valid for a limited period of time, the refresh URL is used to refresh the access token without requiring the user to log on again to the REST data source. This is a required setting.
In the Login URL setting, enter the login URL.
After the Login URL setting detects a valid URL, the Authorize User
button appears. Click this button to complete the authorization procedure.
Verify that the Enable SSL certificate verification toggle key is enabled so that the Data Connector connects to the REST data source host using the HTTPS protocol for a secure connection. The Enable SSL certificate verification toggle key is enabled by default.
If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.
In the Name setting, optionally edit the default name of this Resource that specifies the method that this Resource interacts with that REST data source's endpoint. The ProcessMaker Platform asset that references this Resource displays the Name setting value. For example, a Resource with the name Get Values
displays that name when configuring a Select List control to use this Data Connector to indicate the Resource's purpose. Therefore, provide a concise but relevant name for this Resource so other Process designers understand its function. List is the default purpose for a new Resource. This is a required setting.
In the Description setting, enter a description of this Resource. Descriptions do not display from ProcessMaker Platform assets when configuring them with a Data Connector.
From the Method drop-down menu, select the method how this Resource interacts with the REST data source from one of the following options:
GET: The GET method retrieves data from the REST data source.
POST: The POST method creates data in the REST data source.
PUT: The PUT method does one of the following:
Update: The PUT method updates data in the REST data source if the specified endpoint's value exists in the data source.
Create: The PUT method creates data in the REST data source if the value does not exist that corresponds with the specified endpoint.
PATCH: The PATCH method partially modifies data in the REST data source that corresponds with the specified endpoint.
DELETE: The DELETE method removes data from the REST data source that corresponds with the specified endpoint.
In the URL setting, enter the URL and any required/optional parameters to interact with that REST data source's endpoint. If configuring this Resource to make a request (contact) to the ProcessMaker Platform API, understand how to make a request with your ProcessMaker Platform API instance, and then consult our API documentation to understand any parameters for the endpoint to which this Resource interacts. The URL setting supports mustache syntax to reference the value of a Request variable as the URL and/or parameter setting. To understand any required or optional parameters for a third-party REST data source's endpoint, consult that data source's documentation.
Do one of the following:
A Resource may send Request data as parameters when that Resource connects to the REST data source's endpoint so that the endpoint may process that Request data prior to its response.
Do not send Request data to a data source other than our API. A third-party data source cannot recognize the Request data.
Follow these steps to add parameters to a REST-type Data Connector's Resource:
In the Key setting, enter the REST data source's endpoint key name to which to pass data.
In the Default setting, enter an initial value for that REST data source's endpoint key. This setting is not required by default, and it supports mustache syntax to specify its value from a Request variable.
Select the Required setting if this key requires a value. If the Default setting contains mustache syntax to derive its value from a Request variable, then the referenced Request variable must exist in the Request data and must not be empty. This setting is not selected by default.
Click Save.
Click Save again in the Params tab to save the recent changes.
A header is part of the REST-type Data Connector Resource's interaction with a data source's endpoint that contains metadata regarding that interaction. A header is included when a Resource makes a request to (contacts) the REST data source endpoint; likewise, the endpoint includes a response header that is included when that endpoint responds to that request. Headers are used to provide information to both the Data Connector and the data source. Headers can be used for many purposes, including authentication and providing information about the body content of the request/response.
Headers are key-value pairs that are separated by a colon (:
). For example, the Content-Type
header option below indicates to the data source to expect the Resource's content to be JSON.
See this list of header options that may be used in a Resource's header.
Each header option added to a Resource is included in the request when the Resource makes its request to the REST data source.
Follow these steps to add a header to a REST-type Data Connector's Resource:
In the Key setting, enter the key for the header request option.
In the Default setting, enter the value for that key. This setting supports mustache syntax to specify its value from a Request variable.
Select the Required setting if this key requires a value. If the Default setting contains mustache syntax to derive its value from a Request variable, then the referenced Request variable must exist in the Request data and must not be empty. This setting is not selected by default.
Click Save.
Click Save again in the Headers tab to save the recent changes.
A body is part of the Data Connector Resource's interaction with a REST data source's endpoint that contains data or a message of that interaction.
A body is not required for Resources that use the GET method since the GET method receives data from the data source but does not send content. A body can be used when using POST and PUT methods.
Follow these steps to add a body to a REST-type Data Connector's Resource:
Enter the body to send when this Resource makes its request to the data source. In doing so, select how to encode that request body for the receiving server using one of the following options:
JSON: Select the JSON option to encode the request body as application/json
. Encoding in JSON preserves the data types of the values as long as they are valid JSON data types. An example of JSON request body data is: {"Name": "John Smith", "Age": 23}
. The JSON option is the default.
Form Data: Select the Form Data option to send the request body as application/x-www-form-urlencoded
. An example of form data is: Name=John+Smith&Age=23
.
Click Save.
Follow these steps to test a REST-type Data Connector's Resource:
Click the Response Body tab.
Verify that the URL to call the Resource's configured method is accurate.
Do one of the following:
Call the data source endpoint to receive its response: Click the Send button.
Send sample Request data with the call to the data source endpoint: In the Test Request JSON panel, enter the sample Request data to be added to the body of the request to the data source endpoint, and then click the Send button.
If the Resource successfully interacts with the data source endpoint, the endpoint's response displays in the Response Body tab. Above the Test Request JSON panel displays the data source response status, response time, and size display.
To search the response body, enter into the search field that is above the response body the text to locate, and then click Search.
Follow these steps to view or edit a REST-type Data Connector's Resource:
Edit the following settings as necessary:
From the Method drop-down menu, select the method how this resource interacts with the REST data source from one of the following options:
GET: The GET method retrieves a resource from the REST data source.
POST: The POST method creates a resource in the REST data source.
PUT: The PUT method does one of the following:
Update: The PUT method may update data an existing resource in the REST data source.
Create: The PUT method may create a resource in the REST data source.
PATCH: The PATCH method partially modifies an existing REST data resource.
DELETE: The DELETE method removes an existing resource from the REST data source.
In the URL setting, enter the URL and any required/option parameters to interact with that data source's endpoint. If configuring this Resource to make a request (contact) to our Application Programming Interface (API), understand how to make a request with your ProcessMaker Platform API instance, and then consult the our API documentation to understand any parameters for the endpoint to which this Resource interacts. The URL setting supports mustache syntax to reference the value of a Request variable as the URL and/or parameter setting. To understand any required or optional parameters for a third-party data source's endpoint, consult that data source's documentation.
In the Name setting, edit the name for this Resource and how it interacts with that data source's endpoint. The value the Name setting contains displays from the ProcessMaker Platform asset when configuring the data source from that asset. For example, if a Process designer configures a Select List control to use this Data Connector, this Resource would display the Resource's purpose entered into this setting. Therefore, provide a concise but relevant purpose for this resource so other Process designers understand its function. List is the default purpose for a new Resource.
In the Description setting, edit the description of this Resource.
Do one of the following:
A Resource may send Request data as parameters when that Resource connects to the REST data source's endpoint so that the endpoint may process that Request data prior to its response.
Do not send Request data to data source other than our API. A third-party data source cannot recognize the Request data.
Follow these steps to edit parameters to a REST-type Data Connector's Resource:
Click the Resources tab. Resources for that Data Connector display.
In the Key setting, edit the REST data source's endpoint key name to which to pass data.
In the Default setting, edit an initial value for that REST data source's endpoint key. This setting is not required by default, and it supports mustache syntax to specify its value from a Request variable.
Select the Required setting if this key requires a value. If the Default setting contains mustache syntax to derive its value from a Request variable, then the referenced Request variable must exist in the Request data and must not be empty. This setting is not selected by default.
Click Save.
Click Confirm to delete the parameter.
Click Save again in the Params tab to save the recent changes.
A header is part of the REST-type Data Connector Resource's interaction with a REST data source's endpoint that contains metadata regarding that interaction. A header is included when a Resource makes a request to (contacts) the data source endpoint; likewise, the endpoint includes a response header that is included when that endpoint responds to that request. Headers are used to provide information to both the Data Connector and the data source. Headers can be used for many purposes, including authentication and providing information about the body content of the request/response.
Headers are key-value pairs that are separated by a colon (:
). For example, the Content-Type
request header option below indicates to the data source to expect the Resource's content to be JSON.
See this list of header options that may be used in an Endpoint's request header.
Each header option added to a Resource is included in the request header when the Resource makes its request to the data source.
Follow these steps edit a header for a REST-type Data Connector's Resource:
Click the Resources tab. Resources for that Data Connector display.
Edit the following settings as necessary:
In the Key setting, edit the key for the header request option.
In the Value setting, edit the value for that key. This setting supports mustache syntax to specify its value from a Request variable.
Select the Required setting if this key requires a value. If the Default setting contains mustache syntax to derive its value from a Request variable, then the referenced Request variable must exist in the Request data and must not be empty. This setting is not selected by default.
Click Save.
Click Confirm to delete the header.
A body is part of the REST-type Data Connector Resource's interaction with a REST data source's endpoint that contains data or a message of that interaction.
A body is not required for Resources that use the GET method since the GET method receives data from the data source but does not send content. A body can be used when using POST and PUT methods.
Follow these steps to edit the body of a REST-type Data Connector's Resource:
Click the Resources tab. Resources for that Data Connector display.
Edit the body to send when this Resource makes its request to the data source. In doing so, select how to encode that request body for the receiving server using one of the following options:
JSON: Select the JSON option to encode the request body as application/json
. Encoding in JSON preserves the data types of the values as long as they are valid JSON data types. An example of JSON request body data is: {"Name": "John Smith", "Age": 23}
. The JSON option is the default.
Form Data: Select the Form Data option to send the request body as application/x-www-form-urlencoded
. An example of form data is: Name=John+Smith&Age=23
.
Click Save.
Follow these steps to delete a Data Connector's Resource:
Click Confirm.
Download to view debugging logs using a third-party log viewer when debugging Data Connectors.
Add a Data Connector as an asset to a Project. Any members of that Project may then use that asset toward the goals of that Project.
Follow these steps to add a Data Connector to a Project:
Optionally, select the Use a copy of this asset option to use a copy of this Data Connector as the Project asset instead of the original. When selecting this option, any revisions made to the original Data Connector do not affect yours in your Project(s), and vice versa. Consider this option a best practice to use, especially if you intend to make changes from the original Data Connector that may not be an asset in any Project.
Click Add. The Data Connector is added as an asset to the selected Project(s).
From the Project drop-down menu, optionally select the Project(s) that this Data Connector becomes an asset. This setting only displays Projects of which you are a member. To remove a Project that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible.
View this to quickly view how to use our RESTful API without testing API endpoints.
Click the Data Connectors icon from the left sidebar. The Data Connectors tab displays all Data Connectors in the Data Connectors page.
Click the +Category button. The Create Category screen displays.
Click the menu, and then select the Edit Category option for the Data Connector Category to edit. The Edit Category screen displays.
Click the menu, and then select the Delete Category option for the Data Connector Category to delete. A message displays to confirm deletion of the Data Connector Category.
Verify that this SOAP-type Data Connector uses a WSDL file to authenticate with the data source.
Click the Download XSD File buttonto download the selected XSD file to your computer or local network.
Click the Delete XSD File buttonto delete the selected XSD file.
Click the View XSD File buttonto view the selected XSD file in a separate browser window.
Verify that this SOAP-type Data Connector uses a local certificate file to authenticate with the data source.
Verify that this SOAP-type Data Connector uses password authentication to authenticate with the data source.
Click the menu, and then select the Edit option for the Data Connector to edit. The Configuration tab displays with the following indicators:
From the Project drop-down menu, optionally select the Project(s) that this Data Connector becomes an asset. This setting only displays Projects of which you are a member. To remove a Project that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible.
Click the menu, and then select the Edit option for the SOAP-type Data Connector to edit. The Configuration tab displays.
Click the Resources tab. Resources configured for this Data Connector display.
Click the +Resource button. The Create Resource screen displays.
Click Add. A new Resource is created.
Required: Theicon displays to indicate the parameter is required.
Optional: Theicon displays to indicate the parameter is optional.
No parameters: Below the Web service operation displays Parameters [empty] if that operation does not have any parameters. Below is an example.
WSDL XML: To the right-side of the Web service operation name and parameter(s) is the WSDL's XML schema. Highlighted in the XML schema is the name of the operation where its XML specification begins. Below is an example.
Enable the tree toggle to see the tree representation of JSON as a data model to understand the different structural elements within it. To navigate in the Data Browser canvas, see Data Browser.
Click the menu, and then select the Edit option for the SOAP-type Data Connector to view or edit. The Configuration tab displays.
Click the Resources tab. Resources configured for this Data Connector display.
Click the Edit iconfor the Resource to view or edit. Settings for the Resource display.
Click the menu, and then select the Edit option for the Data Connector to delete a Resource. The Configuration tab displays.
Click the Resources tab. Resources configured for this Data Connector display.
Click the Delete iconfor the Resource to delete. A message displays to confirm deletion of the Resource.
Click the menu, and then select the Edit option for the Data Connector to edit. The Configuration tab displays the REST tag to indicate the Data Connector authenticates with a REST data source.
From the Project drop-down menu, optionally select the Project(s) that this Data Connector becomes an asset. This setting only displays Projects of which you are a member. To remove a Project that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible.
Click the menu, and then select the Edit option for the Data Connector to edit. Verify that this REST-type Data Connector uses basic authentication to authenticate with the data source.
Click the menu, and then select the Edit option for the Data Connector to edit. Verify that this REST-type Data Connector uses a bearer token to authenticate with the data source.
Click the menu, and then select the Edit option for the Data Connector to edit. Verify that this REST-type Data Connector uses Auth 2.0 password grant type to authenticate with the data source.
Click the menu, and then select the Edit option for the Data Connector to edit. Verify that this REST-type Data Connector uses OAuth 2.0 grant type to authorize with the Web service or data source.
The Redirect URI setting displays the URL to be used during the application registration process. After the authorization process is complete, users are redirected to this URL. Use the copy iconto copy this URL.
Click the menu, and then select the Edit option for the REST-type Data Connector to add a Resource. The Configuration tab displays.
Click the Resources tab. Resources configured for this Data Connector display.
Click the +Resource button. The Create Resource screen displays.
Click Add. A new Resource is created. Additional settings display to configure this Resource.
Click the Resources tab. Resources for that Data Connector display.
Click the Editicon for the Resource to add a parameter.
Click the Params tab.
Click the +Param button. The Add screen displays to add a parameter for this Resource.
Click the Resources tab. Resources for that Data Connector display.
Click the Headers tab.
Click the +Header button. The Add screen displays to add a header for this Resource.
Click the Resources tab. Resources for that Data Connector display.
Click the Body tab.
Enable the tree toggle to see the tree representation of JSON as a data model to understand the different structural elements within it. To navigate in the Data Browser canvas, see Data Browser.
Click the menu, and then select the Edit option for the REST-type Data Connector to add a Resource. The Configuration tab displays.
Click the Resources tab. Resources configured for this Data Connector display.
Click the Edit iconfor the Resource to view or edit. The Configuration tab displays the configuration settings for the Resource.
Click the Editicon for the Resource to edit its parameter.
Click the Params tab. Parameters for this Resource display.
Click the Editicon for the parameter to edit. The Edit screen displays to edit a parameter for this Resource.
Click the Deleteicon to delete a parameter. A caution message displays.
Click the Editicon for the Resource to edit its request header.
Click the Headers tab. Headers for this Resource display.
Click the Editicon for the header to edit. The Edit screen displays to add a header for this Resource.
Click the Deleteicon to delete a header. A caution message displays.
Click the Editicon for the Resource to edit its request body.
Click the Body tab.
Click the menu, and then select the Edit option for the Data Connector to delete a Resource. The Resources tab displays.
Click the Delete iconfor the Resource to delete. A message displays to confirm deletion of the Resource.
When a Data Connector's debug mode is enabled, indicated by the icon, that Data Connector accumulates log data into a log file. The most recent logs are at the top of the log data.
Click the Download icon to download a selected Data Connector's log file.
After , use a third-party log viewer such as to view that Data Connector's logs.
Click the Delete Log icon to delete a selected Data Connector's log file. The Caution screen displays to confirm the deletion of the Data Connector's log file.
Adding a to a adds that Process as an asset to that Project. Any Project member may then use that asset toward the goals of that Project.
. The Data Connectors tab displays.
Click the menu, and then select the Add to Project option. The Add to a Project screen displays.
From the Select Project drop-down, select to which Project(s) this Data Connector becomes an asset. To remove a Project that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible.
Resource
Purpose
Method
ListAll
Get a list of all records in that Collection.
GET
GetRecord
Get a record in that Collection by its record id.
GET
CreateRecord
Create a new record in that Collection.
POST
DeleteRecord
Delete a record from that Collection by its record id.
DELETE
UpdateRecord
Update a record in that Collection by its record id.
PUT
TruncateCollection
Delete all records in that Collection.
DELETE
View the Data Connectors in your organization.
ProcessMaker Platform displays all Data Connectors in one location. This makes it easy to manage Data Connectors.
Follow these steps to view all Data Connectors in your organization:
Log on to ProcessMaker Platform.
Click the Designer option from the top menu. The Designer Welcome Screen displays.
Do one of the following:
The Data Connectors tab displays the following information in tabular format about Data Connectors:
Name: The Name column displays the name of the Data Connector. If a Collection is created, the automatically created Data Connector that connects to that Collection has the same name as that Collection.
Connector Type: The Connector Type column displays with which authentication method the Data Connector uses to connect to its data source. It can be REST or SOAP.
Modified: The Modified column displays the date and time the Data Connector was last modified. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Created: The Created column displays the date and time the Data Connector was created. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
If no Connectors exist, the following message displays: No Data Available.
Control how tabular information displays, including how to sort columns or how many items display per page.
Optionally debug a Data Connector if it does not authenticate properly or to test it.
Follow these steps to create a new Data Connector:
Enter in the Search setting the text to filter Data Connectors using any of the following criteria:
Name: Filter by the Data Connector name that displays in the Name column.
Description: Filter by the Data Connector description that displays in the Description column.
As you enter text into the Search setting, Data Connectors display that match your entered text.
If there are no search results, the following message displays: No Data Available.
Delete a Connector from being referenced from any ProcessMaker Platform asset.
When a Data Connector is deleted, ProcessMaker Platform assets that use that Data Connector are not affected. However, that Data Connector can no longer be referenced from other ProcessMaker Platform assets.
Deleting a Screen from the Data Connectors page cannot be undone.
Follow these steps to delete a Data Connector:
Click Confirm. The following message displays: The Data Connector was deleted.
From the Assets pane in the Designer Welcome Screen, mouse-hover over the Data Connectors icon, and then select View All Data Connectors.
Click the Data Connectors icon from the left sidebar. The Data Connectors tab displays all Data Connectors in the Data Connectors page.
Debug: Indicates whether debug mode for a Data Connector is enabled or disabled. The icon indicates debug mode is enabled. Click the icon to enable debug mode for the selected Data Connector. Debug mode is disabled by default.
Click the menu, and then click the Edit icon .
Click the icon to toggle debug mode for a selected Data Connector. The icon changes to to indicate debug mode is enabled.
. The Data Connectors tab displays.
Click the menu, and then select the Delete option for the Data Connector to delete. The Caution screen displays to confirm the deletion of the Data Connector.