Set up the REST web service integration
Integrate the custom REST services with low-code tools. Creatio will generate and send a request to the web service, receive the response and extract the relevant data. Use the data received from the web service to create or update Creatio records, as well as to set up custom business logic or automation.
Although the general integration setup procedure is the same for all REST services, the details largely depend on the web service specifics.
To set up an integration with a new web service:
- Add the web service and configure its properties and methods.
- Set up the web service authentication (optional step). The authentication setup is similar for both REST and SOAP services.
- Test the integration.
You can start using the integration in custom business processes after that. For instance, you can set up an integration with the “Fixer” web service to update the Currency lookup data via a business process.
Set up an integration with the “Fixer” (https://fixer.io/) REST service to receive the most up-to-date currency exchange rates.
Make sure these parameters are supported:
- “endpoint” – method address parameter. Returns the actual currency exchange rates in real time.
- “access_key” – request parameter. Use it to pass the service access key.
- “symbols” – request parameter. Use it to pass the currency codes. You can specify several comma-separated currency codes.
- “$.base” – response parameter. Contains the base currency value used to calculate the currency exchange rates. Euro is the default base currency.
- “$.date” – response parameter. Contains the currency exchange rate relevancy date.
- “rates” – response parameter. Contains a collection of exchange rates, calculated relative to the base currency. Each exchange rate is a separate nested parameter named after the currency code.
Set up the web service properties and methods
To be able to work with the “Fixer” REST service, sign up on https://fixer.io/ and get the API access key.
Creatio lets you set up web service properties and methods automatically or manually.
Set up the web service properties and methods automatically
-
Go to the Studio workplace and open the Web services section.
-
Click New web service → REST service.
-
Specify the web service address and click OK (Fig. 1).
Set up the web service properties and methods manually
-
Go to the Studio workplace and open the Web services section.
-
Click New web service → REST service.
-
Fill out the fields on the web service properties page (Fig. 2).
Field
Comment
Example
Name
Enter the name that will be displayed in the Which method to call? field of the Call web service business process element.
Currency exchange rates (Fixer)
Code
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrFixer
Web service URI
The complete web service call address will consist of this URI and the settings specified on the method setup page.
Use the same protocol (HTTP/HTTPS) as your Creatio application.
If the web service is located in an unmodifiable package, you can still edit its URI.Retries on call failure
If the web service response returns an error code or times out, Creatio will repeat the request the specified number of times. Keep in mind the response timeout you are going to specify for web service methods when filling out this field.
10
Type
Web service type.
Default value – REST
Package
The package where Creatio will save this web service integration. The list displays the packages the current user can modify.
RestWebServicePackage
noteCreatio saves the web service integrations as configuration items. If a web service configuration item is located in an unmodifiable package, you will only be able to edit its URI. To make other changes to such web service integrations, copy the relevant configuration items to user-made packages.
Set up method calling for each web service integration. You can set up several methods per web service.
noteYou can call any number of web service methods within a single process flow by using multiple Call web service business process elements and passing incoming and outgoing parameters between them.
-
Click to add methods to the Methods tab of the web service integration setup page.
-
Study the web service documentation and fill out the method properties (Fig. 3).
Field
Comment
Example
Name
Enter the name that will be displayed in the Which method to call? field for the Call web service business process elements.
Retrieve the exchange rates
Code
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrLatest
Method address
Use the value specified in the web service documentation.
You can specify a static value use the method address parameters as “variables” to generate a dynamic method address that will depend on the Call web service process element properties. For instance, the “Fixer” web service has a “latest” endpoint that returns the up-to-date currency exchange rates.
If you need more flexibility, pass the endpoint as a method address parameter by specifying the parameter name in curly braces. In this example, we use the “{endpoint}” parameter. You can pass several method address parameters, for example: “{parameter1}/{parameter2}.”/{endpoint}?access_key=d3****************************4b&symbols=USD,GBP,AUD,CAD
Complete address
Creatio automatically generates the complete address. It consists of the web service URI and the method address along with specified parameters and parameter values. The following format is used: “?paramCode1=value1¶mCode2=value2.”
This address is displayed for reference.
The complete address structure is as follows: “Web service URI” + “Method address” + “?” + "A set of request parameters separated by &." For instance:http://data.fixer.io/latest?access_key=****************************&symbols=GBP
.
Specify the web service access key in the “access_key” parameter.
The service will return the exchange rates for the currencies you specify in the “symbols” parameter. For example, use the following request to retrieve the exchange rates for the US dollar and British pound: https://data.fixer.io/latest?symbols=USD,GBP. If you do not pass the “symbols” parameter in the request, the service will return the exchange rates for all supported currencies.http://data.fixer.io/api/{endpoint}?access_key=d3****************************4b&symbols=USD,GBP,AUD,CAD
Request type
The request HTTP method. The standard HTTP methods are supported. The request type you have to use is usually listed in the web service documentation.
For example, use the “GET” method to retrieve the currency exchange rates.GET
Content type
Supports the following types: XML (as of version 8.0.1) and JSON.
JSON
Response timeout, ms
The time frame before Creatio considers a web service request timed out. If the service returns no response or responds with an error message, Creatio will retry the request after this time frame so long as there are retries available for this service call.
By default, “5000”
Use authentication
Use the authentication to access the web service. To enable authentication, set it up on the Authentication detail of the web service integration setup page. Learn more: Web service authentication.
By default, “false”
Set up the request parameters
You can add the request parameters manually or import them from the request example by clicking Quick setup and selecting the example type (cURL, RAW or JSON) in the menu. Also, you can add request parameters from the “Method address” field. For this example, use a GET request to the “/latest” endpoint to get the most up-to-date currency exchange rates.
Creatio uses the method request parameters to generate the endpoint URL for calling the web service.
The number and type of request parameters depend on the web service specifics. You can import the request parameters from the examples or add them manually.
The following request parameter types are available:
Method address parameter | Use these parameters as variables to generate the request method address. |
---|---|
Body parameter | Creatio uses this parameter type to send data of any type (including collections) in the request body. Learn more about the POST request method in Wikipedia. |
Query parameter | Creatio will add this parameter type to the request after the method address and the “?” character. Learn more about this parameter in Wikipedia. |
Header parameter | Creatio uses this parameter type to generate request headers. Learn more about HTTP headers in Wikipedia. |
Cookies parameter | Creatio uses this parameter type to pass cookie files in the requests. For example, you can pass a previously-received authentication cookie. Learn more about cookies in Wikipedia. |
Set up the request parameters automatically
-
Click the quick setup button to the right of the Method address field. Alternatively, click Quick setup at the top of the method setup window and select From field “Method address” (Fig. 4):
-
Select the parameters you need to add to the request in the newly-opened list and click Save (Fig. 5):
This will add the selected parameters to the request. You can modify the parameter settings to adjust them for further use in the Call web service business process element. For example, select the Required checkbox for the “Access_key” parameter.
Set up the request parameters manually
-
Study the web service documentation.
-
Add the request parameters:
-
Click Add parameter on the Request parameters tab.
-
Add the “Endpoint” parameter and fill out its properties (Fig. 6).
Field
Comment
Example
Name
The service parameter name.
Endpoint
Parameter type
The service parameter type.
Method address parameter
Request code
The code used in the request.
endpoint
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrEndpoint
Default value
The default parameter value.
A constant. Value – “latest”
noteCreatio will bind the system settings used during the method parameter setup to the web service package. This streamlines transferring the web service to a different environment.
-
Add the “API key” parameter and fill out its properties (Fig. 7).
Field
Comment
Example
Name
The service parameter name.
API key
Parameter type
The service parameter type.
Query parameter
Request code
The code used in the request.
access_key
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrAccessKey
Required
If selected, the parameter will be required in the Process Designer. If you specify a default parameter value, this checkbox will become unmodifiable.
Selected
Default value
The default parameter value.
Constant
-
Add the “Currencies” parameter and fill out its properties (Fig. 8).
Field
Comment
Example
Name
The service parameter name.
Currencies
Parameter type
The service parameter type.
Query parameter
Request code
The code used in the request.
symbols
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrSymbols
Required
If checked, the parameter will be required in the Process Designer. If you specify a default parameter value, this checkbox will become unmodifiable.
Cleared by default
Default value
The default parameter value.
Constant
-
This will allow Creatio to call the web service via automatically-generated requests. Business processes generate the requests based on the following template:
http://data.fixer.io/latest?access_key={value}&symbols={value}
The values in curly braces are set to the values of the request parameters. For example:
http://data.fixer.io/latest?access_key=d3****************************4b&symbols=USD
Set up the response parameters
The web service can send cURL, RAW, and JSON responses. To use the data retrieved from the web service, set up the response parameters. Creatio will parse the response and pass the data to these parameters. You can add the response parameters automatically or manually.
Set up the response parameters automatically
If the server returns a JSON or RAW response, you can add the response parameters automatically by clicking the Quick setup button.
-
Click Quick setup and select Example in JSON from the “From response example” menu block (Fig. 9).
-
Enter the server’s JSON response (Fig. 10). This code will display in the browser if you go to the URL that calls the web service.
Click Next.
-
This will open a parameter list:
-
“Success” – indicates whether the request was successful.
-
“Timestamp” – an object with a UNIX time stamp that indicates the time when the service collected this data.
-
“Base” – specifies the base currency relative to which the service calculated the exchange rates. For example, "base":"EUR" indicates that the service calculated the exchange rates relative to euro.
-
“Date” – specifies the exchange rate relevancy date. For example, “date:2021-05-26” indicates that the service calculated the exchange rates for May 26, 2021.
-
“Rates” – contains an array of nested parameters. Each nested parameter contains the exchange rate between the base currency and one of the supported currencies.
For example, "rates": {"USD":1.222845,"GBP":0.862279,"AUD":0.635032,"CAD":0.676577} in the response indicates that the service returned the exchange rates for US dollar ("USD": 1.222845), British pound ("GBP": 0.862279), Australian dollar ("AUD":0.635032), and Canadian dollar ("CAD":0.676577).
Specify the parameters you need to add to the response and click Save (Fig. 11):
-
This will add all the selected parameters to the response. You can modify the parameter settings. For example, change the data type of the currency rate to “Decimal” to adjust it for further use.
Set up the response parameters manually
-
Study the web service documentation.
-
Add the response parameters:
-
Go to the Response parameters tab and click Add parameter.
-
Add the “Base currency” parameter and fill out its properties (Fig. 12).
Field
Comment
Example
Name
The service parameter name.
Base currency
Parameter type
The service parameter type.
Body parameter
Path to element (JSONPath)
The value must be in JSON format. For example, JSONPath “$.base” receives the “base” parameter value in the web service response.
$.base
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrBaseCurrency
Data type
The service parameter data type. A parameter with nested elements must have an “Object” data type.
Text
Is array
An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.
Cleared by default
Default value
The default parameter value.
A constant. Value – EUR
-
Add the “Date” parameter and fill out its properties (Fig. 13).
Field
Comment
Example
Name
The service parameter name.
Date
Parameter type
The service parameter type.
Body parameter
Path to element (JSONPath)
The value must be in JSON format. For example, JSONPath “$.date” receives the “date” parameter value in the web service response.
$.date
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrDate
Data type
The service parameter data type A parameter with nested elements must have an “Object” data type.
Date
Is array
An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.
Cleared by default
Default value
The default parameter value.
Constant
-
Add the “RatesAUD” parameter and fill out its properties (Fig. 14).
Field
Comment
Example
Name
The service parameter name.
Rates AUD
Parameter type
The service parameter type.
Body parameter
Path to element (JSONPath)
The value must be in JSON format. For example, JSONPath “$.rates.AUD” receives the “AUD” parameter value in the web service’s response.
$.rates.AUD
Code in Creatio
Used to interact with this web service in Creatio source code. In this case, it consists of the method name and the “Usr” prefix.
UsrRatesAUD
Data type
The service parameter data type A parameter with nested elements must have an “Object” data type.
Decimal
Is array
An array parameter value cannot be set in the process designer’s “Call web service” element. Use the “Script task” element instead. The parameter with an “Object” data type must be an array.
Cleared by default
Default value
The default parameter value.
Constant
noteJSONpath “$.rates.USD” receives the “AUD” parameter value. “AUD” is a nested parameter of the “rates” parameter in the web service response.
-
Set up the response parameters for the other necessary exchange rates in a similar way (Fig. 15).
-
-
Click OK to save the settings.
Set up the “collection” type response and request parameters
A collection (or an array) is a set of elements. Creatio can pass collections to the web service and parse the service responses that contain collections. You can set up both request and response “collection” parameters, provided the web service can receive and/or send arrays.
Collection parameter types:
- Simple collection. You can make any parameter a collection by selecting the “Is array” checkbox in the parameter properties. Simple collections are arrays with data of a single type. Each value is a separate collection element. For example, “1, 2, 3” is a simple array of integer values, “Boston, New York, Chicago” is a simple array of string values, etc.
- Object collection. A root parameter (or an object) that contains nested parameters. Each item in an object collection can have a different parameter type. These collection item parameters are nested within the root parameter. For example, a contact collection can have nested parameters for contact name, date of birth, and age (Fig. 16).
The collection with such a structure would look like this:
Contact name | Birth date | Age |
---|---|---|
John Best | 04/12/1991 | 30 |
Andrew Barber | 04/10/1985 | 36 |
Alice Phillips | 05/12/1989 | 31 |
Creatio can pass collections in web service requests and parse web service responses that contain collections. You can set up both request and response “collection” parameters, provided the web service can receive and/or send arrays.
You can only select the “collection” data type for the “Body parameter” type parameters. This parameter type is not available for GET requests. However, it is available for GET responses.
To set up a collection:
- Study the web service documentation.
- Add the “Receive contacts” method.
- To set up a collection request parameter, specify “Object” in the Data type field. Creatio will select the Is array checkbox automatically (Fig. 17).
That way, the web service “collection” response parameter that receives the contact records from the server will look like this (Fig. 18):
The value of the nested parameter’s JSONPath is a suffix of the root parameter’s JSONPath. For example, if the root parameter has the “$.records” value in the JSONPath field and the “$.records.name” value should be specified for the “Name” nested parameter, you need to specify only “$.records” in the “Path to element” field.
You can use the web service response parameters of the collection type as incoming parameters in the “Call web service” business process element. Learn more: Call web service process element.
Test the REST service integration
Test the integration setup before using the data received from the web service with custom business logic.
Since Creatio version 7.18.0, you can test a REST integration in the UI without creating a test business process.
To test the REST web service integration:
-
Go to the Studio workplace and open the Web services section.
-
Open the page of the web service whose integration you want to test. For example, “Currency exchange rates (Fixer).”
-
Open the “Retrieve the exchange rates” method on the Methods detail of the web service integration setup page.
-
Click Send a test request on the method setup page.
-
Specify the values for the method call parameters.
Parameter
Value
Endpoint
latest
API key
d3****************************4b
Currencies
USD,GBP,AUD,CAD
-
Click Send request (Fig. 19).
As a result of the test request, the web service will send a response. The values of the response parameters are displayed on the Response parameters tab in the corresponding fields (Fig. 19). View the request and response formatted as JSON or raw HTTP on other tabs.
If the web service integration is configured with an error, the test request will result in a response with empty parameter values. In this case, check all of the web service’s settings and try again.
Once you test the web service integration, you can start using the service in custom business processes.
Depending on the web service specifics, you may need to authenticate the service before it becomes available. Read more: Set up the web service authentication.
See also
Getting started with low-code web service integration
Update currency exchange rates with web service integration