Edit a REST-Type Data Connector

Edit how to authenticate and interact with a SOAP data source for a Data Connector.

Edit Configuration for a Data Connector's REST Data Source

Follow these steps to edit the configuration settings how a Data Connector authenticates with a REST data source:

1. View your Data Connectors. The Data Connectors tab displays.

2. 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.

3. 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.

   • From the Category drop-down menu, select one or more Data Connector Categories to associate with this Data Connector. In doing so, Data Connector Categories may be sorted from the Data Connectors page. To remove a Data Connector Category that is currently selected, click theicon for that selection or press Enter when the drop-down is visible. This is a required setting.

   • 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.

   • 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.

     • Basic Auth: Select the Basic Auth option to send only username and password credentials as authentication when connecting to the REST-type data source. See Edit Basic Auth Settings.

     • 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. REST-type Data Connectors that connect to Collections use Bearer Token authorization method. See Edit Bearer Token Settings.

     • 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 register this Data Connector with the REST data source host. After registering, that host provides the redirect URI, Client ID, and Client Secret for this Data Connector. See Edit Auth 2.0 Password Settings.

     • OAuth 2.0: Select the OAuth 2.0 option to connect to a REST Web service or data source that uses the OAuth 2.0 authorization protocol. To use OAuth 2.0, register this Data Connector (client application) with the third-party REST Web service or data source to generate a client ID, client secret, access token URL, refresh URL and redirect URI. See Edit OAuth 2.0 Settings.

4. If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.

Edit Basic Auth Settings

Follow these steps to configure basic authentication settings after selecting the Basic Auth option from the Authentication section:

1. View your Data Connectors. The Data Connectors tab displays.

2. 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.

   

3. In the User setting, enter or edit the username that authenticates with the REST data source host.

4. In the Password setting, enter or edit the password that authenticates with the REST data source host.

5. 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.

6. If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.

Edit Bearer Token Settings

Follow these steps to configure bearer token settings after selecting the Bearer Token option from the Authentication section:

1. View your Data Connectors. The Data Connectors tab displays.

2. 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.

   

If an access token has already been entered into this Data Connector, it displays in the Token setting.

1. 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:

     1. 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.

     2. 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:

     1. Copy the access token from the third-party data source.

     2. In the Token setting, paste the access token.

2. 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.

3. If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.

Edit Auth 2.0 Password Settings

Follow these steps to configure Auth 2.0 password settings after selecting the Auth 2.0 Password option from the Authentication section:

1. View your Data Connectors. The Data Connectors tab displays.

2. 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.
   

3. 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.

4. In the Client ID setting, enter the Client ID the REST data source host provides after you register this Data Connector with that host.

5. In the Client Secret setting, enter the Client Secret the REST data source host provides after you register this Data Connector with that host.

6. In the User setting, enter or edit the username that authenticates with the REST data source host.

7. In the Password setting, enter or edit the password that authenticates with the REST data source host.

8. 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.

9. If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.

Edit OAuth 2.0 Settings

Follow these steps to configure OAuth 2.0 settings after selecting the OAuth 2.0 option from the Authentication section:

1. View your Data Connectors. The Data Connectors tab displays.

2. 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.
   

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. In the Login URL setting, enter the login URL.

   

9. After the Login URL setting detects a valid URL, the Authorize User button appears. Click this button to complete the authorization procedure.

10. 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.

11. If no other changes are necessary, click Save. The following message displays: The Data Connector was saved.

Add Resources to a REST Data Connection

Follow these steps to add a Resource to a REST-type Data Connector:

1. View your Data Connectors. The Data Connectors tab displays.

2. Click the menu, and then select the Edit option for the REST-type Data Connector to add a Resource. The Configuration tab displays.

3. Click the Resources tab. Resources configured for this Data Connector display.

   

4. Click the +Resource button. The Create Resource screen displays.

   

5. 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.

6. 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.

7. From the Category drop-down menu, select one or more Data Connector Categories to associate with this Resource. In doing so, Data Connector Categories may be sorted from the Data Connectors page. To remove a Data Connector Category that is currently selected, click theicon for that selection or press Enter when the drop-down is visible. This is a required setting.

8. 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.

9. 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.

10. Click Add. A new Resource is created. Additional settings display to configure this Resource.

    

11. Do one of the following:

    • Optionally, add parameters to this Resource. The parameter(s) are sent to the REST data source's endpoint when this Resource interacts with that endpoint. See Add Resource Parameters.

    • Optionally, add headers to this Resource. The header(s) are sent to the REST data source's endpoint when this Resource interacts with that endpoint. See Add Resource Headers.

    • Optionally, add a body to this Resource. The body is sent to the REST data source's endpoint when this Resource interacts with that endpoint. See Add a Resource Body.

Add Resource Parameters

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.

Follow these steps to add parameters to a REST-type Data Connector's Resource:

1. Add or view the Resource for the Data Connector to which to add parameters. The Configuration tab displays basic configuration settings for that Data Connector.

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Editicon for the Resource to add a parameter.

4. Click the Params tab.
   

5. Click the +Param button. The Add screen displays to add a parameter for this Resource.
   

6. In the Key setting, enter the REST data source's endpoint key name to which to pass data.

7. 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.

8. 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.

9. Click Save.

10. Click Save again in the Params tab to save the recent changes.

Add Resource Headers

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.

"Content-Type: application/json"

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:

1. Add or view the Resource for the Data Connector to which to add a header. The Configuration tab displays basic configuration settings for that Data Connector.

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Headers tab.
   

4. Click the +Header button. The Add screen displays to add a header for this Resource.
   

5. In the Key setting, enter the key for the header request option.

6. In the Default setting, enter the value for that key. This setting supports mustache syntax to specify its value from a Request variable.

7. 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.

8. Click Save.

9. Click Save again in the Headers tab to save the recent changes.

Add a Resource Body

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.

Follow these steps to add a body to a REST-type Data Connector's Resource:

1. Add or view the Resource for the REST-type Data Connector to which to add a body. The Configuration tab displays basic configuration settings for that Data Connector.
   

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Body tab.
   

4. 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.

5. Click Save.

Test a Resource in a Data Connector

After adding a Resource to a Data Connector, test it to determine if the Resource successfully makes a request to the data source endpoint successfully.

Follow these steps to test a REST-type Data Connector's Resource:

1. Add or view the Resources for the REST-type Data Connector to test. The Configuration tab displays basic configuration settings for that Resource.

2. Click the Response Body tab.

   

   Resource response in the Data Browser canvas

3. Verify that the URL to call the Resource's configured method is accurate.

4. 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.

5. 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.

   

   Resource response in the Data Browser canvas

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.

View or Edit a Resource in a Data Connector

Follow these steps to view or edit a REST-type Data Connector's Resource:

1. View your Data Connectors. The Data Connectors page displays.

2. Click the menu, and then select the Edit option for the REST-type Data Connector to add a Resource. The Configuration tab displays.

3. Click the Resources tab. Resources configured for this Data Connector display.

4. Click the Edit iconfor the Resource to view or edit. The Configuration tab displays the configuration settings for the Resource.

5. 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.

6. Do one of the following:

   • Optionally, add or edit parameters to this Resource. The parameter(s) are sent to the REST data source's endpoint when this Resource interacts with that endpoint.

   • Optionally, add or edit headers to this Resource. The header(s) are sent to the REST data source's endpoint when this Resource interacts with that endpoint.

   • Optionally, add or edit a body to this Resource. The body is sent to the REST data source's endpoint when this Resource interacts with that endpoint.

Edit a Resource Parameter

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.

Follow these steps to edit parameters to a REST-type Data Connector's Resource:

1. Add or view the Resource for the REST-type Data Connector to which to edit parameters. The Configuration tab displays basic configuration settings for that Data Connector.

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Editicon for the Resource to edit its parameter.

4. Click the Params tab. Parameters for this Resource display.

   

5. Click the Editicon for the parameter to edit. The Edit screen displays to edit a parameter for this Resource.
   

6. In the Key setting, edit the REST data source's endpoint key name to which to pass data.

7. 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.

8. 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.

9. Click Save.

10. Click the Deleteicon to delete a parameter. A caution message displays.
    

11. Click Confirm to delete the parameter.

12. Click Save again in the Params tab to save the recent changes.

Edit a Resource Header

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.

"Content-Type: application/json"

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:

1. View the Resource for the REST-type Data Connector to which to add a header. The Configuration tab displays basic configuration settings for that Data Connector.

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Editicon for the Resource to edit its request header.

4. Click the Headers tab. Headers for this Resource display.

   

5. Click the Editicon for the header to edit. The Edit screen displays to add a header for this Resource.

6. 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.

7. Click Save.

8. Click the Deleteicon to delete a header. A caution message displays.
   

9. Click Confirm to delete the header.

Edit a Resource Body

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.

Follow these steps to edit the body of a REST-type Data Connector's Resource:

1. Add or view the Resource for the REST-type Data Connector to which to edit its body. The Configuration tab displays basic configuration settings for that Data Connector.

2. Click the Resources tab. Resources for that Data Connector display.

3. Click the Editicon for the Resource to edit its request body.

4. Click the Body tab.
   

5. 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.

6. Click Save.

Delete a Resource from a Data Connector

Follow these steps to delete a Data Connector's Resource:

1. View your Data Connectors. The Data Connectors page displays.

2. Click the menu, and then select the Edit option for the Data Connector to delete a Resource. The Resources tab displays.

3. Click the Delete iconfor the Resource to delete. A message displays to confirm deletion of the Resource.

4. Click Confirm.