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).
2.Populate the method properties (Fig. 2):
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¶mCode2=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 icon in the field or select the [From field “Method address”] option in the [Quick setup] menu (Fig. 3):
2.In the opened parameters list, select necessary request parameters and click [Save] (Fig. 4):
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).
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).
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.
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.
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).
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