Documentation

Creatio administration
This documentation is valid for Creatio version 7.15.0. We recommend using the newest version of Creatio documentation.

Setting up web service methods

For each web service that you integrate with Creatio, you can set up calling of the necessary methods. You can set up several methods per web service. You can add the request and response parameters manually or by importing from request or response example by clicking the [Quick setup] button and selecting a type of example (cURL, RAW or JSON) in the pop-up window. Also you can add request parameters from the “Method address” field

Example

According to the “http://fixer.io/” web service documentation, the latest currency exchange rates can be obtained via a simple GET method request to http(s)://data.fixer.io/api/latest endpoint. To have Creatio obtain the currency rate information, we need to implement this method in the [Methods] detail of the [Web services] section.

Note

You can call any number of web service methods within a single process flow by using multiple [Call web service] business process elements and mapping incoming and outgoing parameters between them.

1.Open the setup page of your web service integration and add web service methods by clicking the [+] button on the [Methods] tab (Fig. 1).

Fig. 1 Adding a web service method

scr_web_service_add_method.png 

2.Populate the method properties (Fig. 2):

Fig. 2 Web service method properties

scr_web_service_method_properties.png

FIELD

NOTES

EXAMPLE

Name

Enter the name that will be displayed in the [Which method to call?] field for the [Call web service] business process elements.

Get latest exchange rates

Code

Used for interacting with this parameter in Creatio source code. Usually, it consists of the method name and the “Usr” prefix.

UsrLatest

Method address

Use the web service documentation to determine this value. You can specify a static value, or map it to a “method address parameter” of your request.

For instance, http://fixer.io/ can process two endpoints: “latest” – to return the latest rates and date in text format (such as “2000-01-03”) to return rates for that date.

You can set a specific endpoint, such as “latest”, simply by entering it in this field.

If you need flexible integration, pass endpoint as a “method address parameter”, by specifying that parameter name in curly braces. In the current case, we use the “{endpoint}” parameter.

You can pass several method address parameters, for example: “{parameter1}/{parameter2}”.

{endpoint}

Request type

Type of HTTP method used by request. Standard HTTP methods are supported. The type of request to use is determined in web service documentation.

For example, to retrieve data, such as currency exchange rates use “GET” method.

GET

Content type

Currently, only the JSON content type is supported.

JSON

Response timeout, ms

Time after which Creatio will deem a web service request as timed out. Upon timeout, Creatio will retry the request or return an error, depending on the number of retries available for this service call.

500

Complete address

The method call address is generated automatically. It consists of the web service URI and the method address in the form “?paramCode1=value1&paramCode2=value2”.

This address is displayed for reference.

http://data.fixer.io/api/{endpoint}

Case

Complete address of the method request has the following structure: "Web service URI" + "Method address" + "?" + "A set of request parameters separated with &". For example: http://data.fixer.io/latest?base=USD&symbols=GBP.

After that, you can add the request parameters manually or by importing from examples.

Adding parameters from the “Method address” field

1.Populate the “Method address” field with the web service URL with parameters and click the icn_magic_wand.png icon in the field or select the [From field “Method address”] option in the [Quick setup] menu (Fig. 3):

Fig. 3 Adding parameters from the “Method address field”

scr_web_service_add_method_address.png 

2.In the opened parameters list, select necessary request parameters and click [Save] (Fig. 4):

Fig. 4 An example of method address parameter set

scr_web_service_method_address_parameters.png 

As a result, selected parameters will be added as request parameters. You can modify the settings of parameters (for example, select the “Required” checkbox for the “Access_key”) to adjust them for further using in the [Call web service] business process element.

Adding parameters manually

1.Add request parameters by clicking the [Add parameter] button on the [Request parameters] tab (Fig. 5).

Fig. 5 Setting up request parameters of a web service

scr_web_service_add_method_request_parameter.png 

The following types of request parameters are available:

Method address parameter

Use these parameters as variables to generate the request method address.

Add names of method address parameters, enclosed in curly braces in the [Method address] field of the method. For instance: {parameterName1}/{parameterName2}, etc.

On the actual web service call, these variables will be replaced with actual parameter values of the method address specified for corresponding [Call web service]  element in the process designer. For instance: http://web.service.uri/parameterValue1/parameterValue2. If the parameter value is not specified in the element properties, but the [Default value] field if populated, the default value will be used.

For this parameter type, the [Required] checkbox is selected and non-editable.

Body parameter

This type of parameter is used for sending a data of any type (including collections) in the body of request. Read more >>> 

The parameter is not available for the GET method

Query parameter

The parameter of this type will be added to the request after method address and the “?” character. Read more >>>

Header parameter

This type of parameter is used for generating header section of request. Read more >>>

Cookies parameter

Use parameters of this type to pass cookies in your requests. For example, you can pass an authentication cookie, received earlier. Read more >>>

2.Populate parameter values. If you have set a variable for method address (e.g. {endpoint}), a corresponding method address parameter must be added (Fig. 6).

Fig. 6 Method address parameter settings

scr_web_service_add_method_request_parameter_endpoint.png 

Note

The system settings used in method parameters will be bound to the web service package. This will simplify the transfer of the web service to another system.

Note

If your request parameter is an array, select the “Body parameter” in the [Parameter type] field and “Object” in the data type field. After this, nested parameters will become available. Read more >>>

3.Add the “Base currency” request parameter of the “Query parameter” type for passing the base currency and populate its values (Fig. 7).

Case

By default, the web service will return the exchange rates in relation to Euro. According to the web service description, you can obtain rates in relation to a specific base currency by passing this currency in the “base” parameter of your request.

Fig. 7 “Base currency” query parameter settings

scr_web_service_add_method_request_parameter_currency.png 

Use parameters of different types in the “Parameter type” field to generate web service requests according to the web service documentation. In this case, we set up a single “Query parameter” for passing base currency. Also, we specify the “USD” as the default value of the parameter in the “Default value” field. The value can be set as constant or selected from the system setting. If the field is populated, the “Required” checkbox is automatically cleared and non-editable.

4.Add the “API key” request parameter of the “Query parameter” type for passing your personal access key.  Specify this parameter as required by selecting the “Required” checkbox (Fig. 8).

Note

You will need to register on https://fixer.io/ to obtain your API key.

Fig. 8 “API key” query parameter settings

scr_web_service_add_method_request_parameter_api_key.png 

As a result, Creatio will be able to call methods of this web service using the following request template:

http://data.fixer.io/api/{endpoint}?access_key={your access key}&base={base currency}

The full URL address with parameters is generated in the “Complete address” field according to the added request parameters (Fig. 9).

Fig. 9 Complete address of the web service

scr_web_service_complete_address.png 

The values in curly brackets ({endpoint} and {base currency}) will be specified in the [Call web service] business process element, for instance:

http://data.fixer.io/api/latest?access_key=00000000000000000000000000000000&base=USD

Note

When creating a new web service you can enter a URL with parameters to the mini page and they will be automatically added as request parameters to the created web service.

See also

•Setting up the parsing of the web service response parameters

Did you find this information useful?

How can we improve it?