Skip to main content

2.10.1. REST API Integration

Note:

The REST API Integration functionality is available only with the installation of the additional package messaging-external-api.

To configure an integration with an external website, complete the following steps:

  1. Add and configure the desired REST API integration — add a server, then add and configure the desired server methods.
  2. Configure the method call from a business process.
  3. Configure the transformation of received values into process variables.
  4. Configure the transfer of variable values to the attributes of the required document.

2.10.1.1. Configure External APIs​

Configuring an external API consists of the following stages, each of which is mandatory:

  1. Add an External API
  2. Add a Server
  3. Add Methods
  4. Configure Methods
Note:

Before starting the configuration, we recommend reviewing the official API documentation of the service you plan to integrate with, as you will need information about request formats, methods, authorization parameters, and other specific settings.

You can also view a configuration example in the External API Configuration Example section.

2.10.1.1.1. Add an External API​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the External APIs 3 shortcut.

  3. In the toolbar, select + 4.

  4. Fill in the fields 1 using the hints in the table below, then in the toolbar select the Save 2 icon.

FieldDescription
Code*
  • The code must be unique.
  • The code must be short (typically up to 10 characters).
  • Use only Latin letters and digits.
Name*Enter a clear name for display in the platform.
DescriptionEnter a brief description of the external API's purpose.
Note:

Fields marked with * are required.

2.10.1.1.2. Add a Server​

  1. Go to the Servers 1 tab, then select Add Server 2.

Note:

Configure at least one server. If the API is deployed on multiple servers, you can add more.

  1. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Server URL*Paste the base URL of the server, which will be used as a prefix for all API methods.
Example: "https://api.example.com/v1"
Name*Enter a clear name for the server. If this parameter is not set, the default server will be used.
Example: "Test Server"
DescriptionEnter a brief description of the server to help other system users understand the purpose of this API.
Example: "Integration with the test service for document exchange."
Note:

Fields marked with * are required.

  1. Select the Configure button to set the desired authorization type for each server.

  2. In the Authorization Type field, select the authorization type used by the added server 1, then fill in the additional fields according to the selected type 2. For the None type, no additional fields are required — you can proceed to the next step.

    Note:

    For information about the authorization type supported by the server, refer to the official API documentation of the relevant service.

    None

    None — used for public API endpoints that do not require user authentication. This type is typically used by servers with publicly available data, such as currency exchange rates. No additional fields appear for this type.

    Basic

    Basic — one of the simplest authentication methods. Access to the API uses a username + password pair. When a request is made, the system automatically converts these credentials into a special format (Base64) and passes them in the request header: Authorization: Basic {base64(username:password)}

    ⚠️ It is recommended to use this authorization type only with an HTTPS connection, as Base64 is not encryption — it can be easily decoded.

    For this type, fill in the following fields:

    1. In the Login 1 field, enter the username provided by the service you are integrating with. This is typically a separately created technical user (for example, api_user), or your working login in the relevant service (if the API allows it).

    2. In the Password 2 field, enter the password corresponding to the specified login. This can be a regular user password, or a specially generated API password (recommended if the service supports this option).

    Bearer

    Bearer — uses access tokens. The client receives a token after successful authentication and adds it to each request in the header: Authorization: Bearer {token}. For this type, fill in the following field:

    In the Token field, paste the access token you received from the service. The token can usually be found in the API / Integrations / Developers section of your account in the service you are integrating with. Alternatively, you may need to create an API key or Access token in the service.

    Custom Header

    Custom Header — allows passing an authentication key in a custom HTTP request header (for example, X-API-Key: your-api-key). For this type, fill in the following fields:

    1. In the Header Name 1 field, enter the name of the HTTP header required by the service. This value must be taken from the official API documentation of the service.

    2. In the Token 2 field, paste the access key or token provided by the service. The token can usually be found in the API / Integrations / Developers section of your account in the service you are integrating with. Alternatively, you may need to create an API key or Access token in the service.

    Query String Parameter

    Query String Parameter — passes the authentication key as a URL parameter (for example, ?api_key=your-api-key). Although this method is simple to implement, it is considered less secure, as access keys may be stored in server and browser logs. For this type, fill in the following fields:

    1. In the Query String Parameter 1 field, enter the name of the parameter required by the service. The parameter name must be taken from the official API documentation of the service.

    2. In the Token 2 field, paste the access key value provided by the service. The token can usually be found in the API / Integrations / Developers section of your account in the service you are integrating with. Alternatively, you may need to create an API key or Access token in the service.

    OAuth 2.0 Client Credentials

    OAuth 2.0 Client Credentials — a secure authorization mechanism used for service-to-service integration without user involvement. In this case, you do not paste a ready-made token manually. Instead, the system automatically contacts the service to obtain a token using special credentials (Client ID and Client Secret), and then refreshes this token at a defined interval. For this type, fill in the following fields:

    1. In the Token URL 1 field, paste the full URL to which the token request should be sent. This URL can be found in the official API documentation of the service, in the OAuth or Authentication section.

    2. In the Client ID 2 field, enter the Client ID value you received when registering the application or integration in the service.

    3. In the Client Secret 3 field, enter the Client Secret value that was generated together with the Client ID.

    4. In the Refresh Interval (minutes) 4 field, specify how often the system should automatically refresh the access token.

      💡 Recommendation: the interval should be less than the actual token expiration time. If the token is valid for 60 minutes, set the interval to 50–55 minutes.

    5. In the Credential Transfer Method 5 field, select one of the options from the dropdown list, according to the API documentation of the service:

      • Authorization Header — Client ID and Client Secret are passed in the request header.
      • Request Body — Client ID and Client Secret are passed in the body of the POST request.

  3. Select the Save Changes button to save the changes.

  4. In the toolbar, select the Save icon.

2.10.1.1.3. Add Methods​

  1. Go to the Methods 1 tab, then select Add Method 2.

  2. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
HTTP Method*Select the HTTP method type for the API:
• GET — used exclusively for retrieving data without making changes on the server, passing parameters through the URL. For example, requesting information about a document or getting a list by a specific filter.
• POST — intended for creating new resources on the server, where all required data is passed in the request body.
• DELETE — used to delete a resource, which can be either a physical deletion or a logical one through a status change.
• PUT — used for a full update of an existing resource, completely replacing all its data with new values. Note that fields not listed in the request will be cleared.
• PATCH — allows a partial update of a resource, modifying only the specified fields while leaving the rest unchanged. This is the optimal method for minor changes, such as updating a document status.
Path*Enter the relative URL of the method. May contain parameters in the format {{pathParam}}
Name*Enter a clear name for the method
DescriptionEnter a brief description of the method
Note:

Fields marked with * are required.

2.10.1.1.4. Configure Methods​

  1. Select the Authorize Call 1 checkbox if the server you want to integrate with requires authorization. You can find this information in the official API documentation of the server you are integrating with.

  2. In the Timeout, milliseconds 2 field, enter the desired number of milliseconds.

    This is the time the system waits for a response from the external service or for the completion of an operation. If the server does not respond within the specified time, a "Timeout was reached" error will be returned. You can find this parameter in the official API documentation of the server you are integrating with.

    Note:

    If this parameter is not set, the default value of 30 seconds is used.

  3. If you selected the POST or DELETE method type, in the Request Binding section, select the request body setting according to the instructions in the API documentation of the server:

    • Do not pass body — used when the request does not require data in the body. Useful for simple POST requests where all parameters are passed through the URL.
    • Pass body as is — passes the request body without modifications. Suitable when the data is already formatted as required. Typically used for passing JSON or XML documents.
    • Construct body — allows specifying which fields and in what format will be passed. Useful when you need to collect data from different sources or transform it before sending.

In the Request Binding section, you can configure what information and in what format you send to the server. For example, if you want to get currency exchange rates, here you specify which currencies you are interested in.

  1. In the Request Binding section, select Add.

  2. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
HTTP Request PartSelect from the list the part of the HTTP request where you want to set the request value.
• Path Parameter — for values passed in the URL (for example, /api/resource/{parameter})
• HTTP Header — for values passed in the request headers
• Cookie — for values passed via cookies
Path Parameter*Specify the name of the parameter expected by the external system. This value must match the parameter defined in the method URL template in the format {{parameter_name}}.
Source Type*Select from the list the source from which the system will take the value for the parameter:
• Method Argument — the value will be taken from the method arguments at the time of the call
• Environment Variable — the value will be taken from environment variables
• System Setting — the value will be taken from system settings
• Constant — a fixed value will be used
Method Argument*
field available if you selected "Method Argument" as the source type		Specify the name of the variable in your system whose value will be passed in the request.
Environment Variable*
field available if you selected "Environment Variable" as the source type		Specify the name of the environment variable whose value will be used in the request. Environment variables are configured by the system administrator and may contain, for example, URLs, access keys, and so on.
System Setting*
field available if you selected "System Setting" as the source type		Specify the name of the system setting whose value will be used in the request. System settings are global parameters configured for the entire system.
Value*
field available if you selected "Constant" as the source type		Enter the fixed value that will be used on every method call. For example, if you always need to pass a specific currency code or response format.
Note:

Fields marked with * are required.

In the Response Parameter Binding section, you can configure how you want to receive individual values from the server response. For example, if the server returns a lot of information but you only need a specific currency exchange rate value.

  1. In the Response Parameter Binding section, select Add.

  2. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Destination Key*Specify the name of the variable in your system where the received value will be saved. The key must be unique within a single method.
Source Type*Select from the list the source from which to take the value in the HTTP response:
• Response Body Field — the value will be taken from the response body (usually JSON or XML)
• Response Property — the value is taken from the system properties of the response
• HTTP Header — the value is taken from the response headers
• Response Cookie — the value is taken from the cookies returned by the server.
Example: sessionId, authToken
Source Key*Specify the exact path to the value according to the selected source type. The format depends on the source type.
Note:

Fields marked with * are required.

You can use the Dataset Binding section when the server returns a list or a table of data. For example, if you are requesting exchange rates for multiple currencies at once, here you configure how to retrieve and store that list.

  1. Enable the Dataset Binding 1 toggle if you want to return the method result as a dataset and apply binding to each row of data.

  2. In the Dataset Binding Root 2 field, specify the path to the array of elements, or leave it empty to use the root array as the element array.

  3. Select Add to add a new data binding field.

  4. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Destination Key*Enter the name of the variable in your system where the received value will be saved.
Example: "rate" for storing a currency exchange rate
Source Type*Select from the list the source from which to take the value in the HTTP response:
• Response Body Field — the value will be taken from the response body (usually JSON or XML)
• Response Property — the value is taken from the system properties of the response
• HTTP Header — the value is taken from the response headers
• Response Cookie — the value is taken from the cookies returned by the server.
Example: sessionId, authToken
Source Key*Specify the exact path to the value according to the selected source type. The format depends on the source type.
Note:

Fields marked with * are required.

In the Error Binding section, you can configure how the system should react if something goes wrong. For example, if the server is unavailable or returned an error, here you specify how to save the information about that error.

  1. Enable the Error Binding toggle if you want to save error information received from the server.

  2. Select Add to configure a new field for error handling.

  3. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Destination Key*Enter the name of the variable in your system where the error information will be saved.
Example: "errorMessage" for the error text
Source Type*Select from the list the source from which to take the error information in the response:
• Response Body Field — the value will be taken from the response body (usually JSON or XML)
• Response Property — the value is taken from the system properties of the response
• HTTP Header — the value is taken from the response headers
• Response Cookie — the value is taken from the cookies returned by the server.
Example: sessionId, authToken
Source Key*Specify the exact path to the error information in the received response.
Example: if the server returns an error in the format {"error": {"message": "Server unavailable"}}, the path would be "error.message"
Note:

Fields marked with * are required.

You can use the Error Dataset Binding section when the server can return multiple errors at once. For example, if you submitted incorrect data in several fields at the same time, here you configure how to save the list of all those errors.

  1. Enable the Error Dataset Binding toggle if you want to receive a list of all errors in the response.

  2. Select Add to configure a new field for processing the list of errors.

  3. Fill in the fields 1 using the hints in the table below, then select the Add 2 button.

FieldDescription
Destination Key*Specify the name of the variable in your system where the list of errors will be saved.
Example: "validationErrors" for storing the list of all validation errors
Source Type*Select from the list the source from which to take the list of errors in the response:
• Response Body Field — the value will be taken from the response body (usually JSON or XML)
• Response Property — the value is taken from the system properties of the response
• HTTP Header — the value is taken from the response headers
• Response Cookie — the value is taken from the cookies returned by the server.
Example: sessionId, authToken
Source Key*Specify the exact path to the list of errors in the received response.
Example: if the server returns errors in the format {"errors": [{"field": "email", "message": "Invalid email"}, {"field": "phone", "message": "Invalid phone"}]}, the path would be "errors"
Note:

Fields marked with * are required.

  1. In the toolbar, select the Save or Save and Close icon.

After configuring the external API, configure the method call from a business process.

2.10.1.2. External API Configuration Example​

In this section, we will walk through an example of configuring an integration between the Nectainium system and the free and open service MockAPI. For correct integration setup, most parameters will be filled in according to the official mockAPI documentation.

Configuring an external API consists of the following stages, each of which is mandatory:

  1. Add an External API
  2. Add a Server
  3. Add Methods
  4. Configure Methods

2.10.1.2.1. Add an External API​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the External APIs 3 shortcut.

  3. In the toolbar, select + 4.

  4. In the Code 1 and Name 2 fields, enter "text".

  5. In the Description field, enter "mockapi example" 3 to show other users of your system the purpose of this API.

  6. In the toolbar, select the Save 4 icon.

2.10.1.2.2. Add a Server​

  1. Go to the Servers 1 tab, then select Add Server 2.

  2. In the Server URL 1 field, paste the link to the server you want to integrate with. In this case, it is the link that was automatically generated when creating a new project in the mockapi service.

  3. In the Name 2 field, enter a clear name for the added server.

  4. Select the Add 3 button.

  5. Leave the authorization settings unchanged, as our test API does not require additional authentication. In real projects, you will need to configure the appropriate security parameters according to your API server's requirements.

2.10.1.2.3. Add Methods​

In this case, we will add four methods:

  • POST — for creating new records on the server.
  • DELETE — for deleting existing records from the server.
  • GET — for retrieving data from the server.
  • PUT — for fully updating existing records.

  1. Go to the Methods 1 tab, then select Add Method 2.

  2. In the HTTP Method 1 field, select "POST".

  3. In the Path 2 field, enter "/document" (where "document" is the name of the resource/endpoint we created).

  4. In the Name 3 field, enter "document_add". The name is arbitrary, but should reflect the purpose of the method to avoid confusion.

  5. In the Description 4 field, enter "Add document". It is recommended to indicate the main purpose of the method in the description.

  6. Select Add Method again and add the DELETE method.

  7. Fill in all the fields as shown in the screenshot, then select the Add button.

  8. Select Add Method again and add the GET method.

  9. Fill in all the fields as shown in the screenshot, then select the Add button.

  10. Select Add Method again and add the PUT method.

  11. Fill in all the fields as shown in the screenshot, then select the Add button.

2.10.1.2.4. Configure the Added Methods​

To correctly configure the added methods, refer to the API documentation from the official mockAPI website.

Configure the POST method: for creating new records on the server.

  1. Select the POST method.

  2. Leave the Authorize Call 1 checkbox unselected, as no additional authentication is required for this request. Based on the MockAPI documentation, the system will use standard access parameters.

  3. Leave the Timeout, milliseconds 2 field empty to use the default value of 30 seconds. This means the system waits for a response from the external service or for an operation to complete within this time. If the server does not respond after 30 seconds, a "Timeout was reached" error will be returned.

  4. Select the Construct body request body binding option to manually define the structure and content of the data that will be sent in the request. This allows you to precisely specify the format and composition of the information sent to the server.

  5. Configure the format in which the method will send information to the server.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select HTTP Header.

    c. In the HTTP Header 2 field, enter the name "Content-Type", as this is where we configure the content format in which we will send information to the server.

    d. In the Source Type 3 field, select Constant to specify a fixed data format value that will not change across different method calls.

    e. In the Value 4 field, enter "application/json" to tell the server that data will be sent in JSON format, which is the standard for REST API communication.

    f. Select the Add 5 button.

  6. Configure the format in which we want to receive information from the server.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select HTTP Header.

    c. In the HTTP Header 2 field, enter the name "Accept", as this is where we configure the content format in which we will receive information from the server.

    d. In the Source Type 3 field, select Constant to specify a fixed data format value that will not change across different method calls.

    e. In the Value 4 field, enter "application/json" to tell the server that its response should be returned in JSON format, which is the standard for REST API communication.

    f. Select the Add 5 button.

  7. Configure the POST method arguments whose values we want to send to the server.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select Request Body Field.

    c. In the Request Body Field 2 field, enter "docType" — according to the external API parameters from the official mockAPI documentation.

    d. In the Source Type 3 field, select Method Argument to specify that the value will be passed dynamically when the method is called.

    e. In the Method Argument 4 field, enter "docType" — an arbitrary value; for convenience we made it identical to the system attribute code.

    f. Select the Add 5 button.

  8. You can view an example of the remaining settings in the screenshot below.

  1. Leave the Response Parameter Binding section empty, as we will retrieve data through the dataset binding settings, which will allow us to better structure the received information.

  2. In the Dataset Binding section, enable the toggle 1, as we want to return the method result as a dataset and apply binding to each row of data.

  3. Leave the Dataset Binding Root 2 field empty, as the server response contains data for a single document rather than an array of documents.

  4. Configure retrieval of the created document's identifier.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "id".
    c. In the Source Type 2 field, select Response Body Field.
    d. In the Source Key 3 field, enter "id".
    e. Select the Add 4 button.

  5. Configure retrieval of the status code for successful document creation.

    a. Select the Add button.

    b. In the Destination Key field, enter "StatusCode" 1.
    c. In the Source Type field, select Response Property 2.
    d. In the Source Key field, select "Status Code" 3.
    e. Select the Add 4 button.

  6. In the Error Binding section, enable the toggle to allow binding the response if the method returns a status code other than 200-299, instead of generating a server error.

  7. Add an attribute to retrieve the response status from the server.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "statusCode".

    c. In the Source Type 2 field, select Response Property, as the status code is a standard property of the HTTP response.

    d. In the Source Key 3 field, select "Status Code" — this field contains the numeric result code of the request.

    e. Select the Add 4 button.

  8. In the Error Dataset Binding section, enable the toggle to return the response properties as a dataset consisting of a single row.

  9. Configure retrieval of the error code for further processing and display to the user.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "errorCode".
    c. In the Source Type 2 field, select Response Property.
    d. In the Source Key 3 field, select "Status Code" — this field contains the numeric result code of the request.
    e. Select the Add 4 button.

  10. Configure retrieval of the error text for informative display of the reason for a failed request.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "errorText".
    c. In the Source Type 2 field, select Response Body Field.
    d. In the Source Key 3 field, enter "msg".
    e. Select the Add 4 button.

Configure the DELETE method: for deleting existing records from the server.

  1. Select the DELETE method.

  2. Leave the Authorize Call 1 and Timeout, milliseconds 2 fields unchanged, the same as in the first method we configured. These settings are typically the same for all methods.

  3. Select the Do not pass body request body binding option, as when deleting data we do not need to pass any additional information — it is sufficient to specify what we want to delete via the URL.

  4. Configure the request parameters to correctly pass the identifier of the element to be deleted.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select Path Parameter.
    c. In the Path Parameter 2 field, enter "id".
    d. In the Source Type 3 field, select Method Argument.
    e. In the Method Argument 4 field, enter "id".
    f. Select the Add 5 button.

  5. Leave the Response Parameter Binding section empty, as the DELETE method does not return any data on successful deletion.

  6. Leave the Dataset Binding section empty, as the DELETE method does not return datasets — it only deletes the specified resource.

  7. Configure the server response handling to correctly process different completion statuses.

    a. In the Error Binding section, enable the toggle 1, as our method returns a status code other than 200-299. This allows us to accept the response instead of generating a server error.

    b. Select the Add 2 button.

    c. In the Destination Key 1 field, enter "statusCode" — this will allow us to save the response status code for further processing.

    d. In the Source Type 2 field, select Response Property.

    e. In the Source Key 3 field, select "Status Code" — this is the standard response field that contains the result of the operation.

    f. Select the Add 4 button.

  8. Leave the Error Dataset Binding section empty, as in the event of an error it is sufficient to retrieve the status code — no additional datasets are expected.

Configure the GET method: for retrieving data from the server.

  1. Select the GET method.

  2. Leave the Authorize Call 1 and Timeout, milliseconds 2 fields unchanged, the same as in the first method we configured. These settings are typically the same for all methods.

  3. Specify to the system how to substitute the specific document identifier in the URL.

    a. In the Request Binding section, select the Add button.

    b. In the HTTP Request Part 1 field, select Path Parameter.
    c. In the Path Parameter 2 field, enter "id".
    d. In the Source Type 3 field, select Method Argument.
    e. In the Method Argument 4 field, enter "id".
    f. Select the Add 5 button.

  4. Specify to the server the format in which we want to receive the response.

    a. In the Request Binding section, select the Add button.

    b. In the HTTP Request Part 1 field, select HTTP Header.

    c. In the HTTP Header 2 field, enter "Accept".

    d. In the Source Type 3 field, select Constant to specify a fixed data format value that will not change across different method calls.

    e. In the Value 4 field, enter "application/json" to tell the server that its response should be returned in JSON format, which is the standard for REST API communication.

    f. Select the Add 5 button.

  5. Configure retrieval of the response body from the server.

    a. In the Response Parameter Binding section, select Add.

    b. In the Destination Key 1 field, enter "Body".
    c. In the Source Type 2 field, select Response Property.
    d. In the Source Key 3 field, select "Body".
    e. Select the Add 4 button.

  6. In the Dataset Binding section, enable the toggle 1, as we want to return the method result as a dataset and apply binding to each row of data.

  7. Leave the Dataset Binding Root 2 field empty, as the server response contains data for a single document rather than an array of documents.

  8. Add the attributes that need to be retrieved from the server response for further processing in the system. You can view an example of the added attributes in the screenshot.

  9. In the Error Binding section, enable the toggle to allow binding the response if the method returns a status code other than 200-299, instead of generating a server error.

  10. Add an attribute to retrieve the response status from the server.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "statusCode".

    c. In the Source Type 2 field, select Response Property, as the status code is a standard property of the HTTP response.

    d. In the Source Key 3 field, select "Status Code" — this field contains the numeric result code of the request.

    e. Select the Add 4 button.

  11. Leave the Error Dataset Binding section empty, as in the event of an error it is sufficient to retrieve the status code — no additional datasets are needed.

Configure the PUT method: for fully updating existing records.

  1. Select the PUT method.

  2. Leave the Authorize Call 1 and Timeout, milliseconds 2 fields unchanged, the same as in the first method we configured. These settings are typically the same for all methods.

  3. Select the Construct body request body binding option to configure the data transfer format.

  4. Configure the Content-Type header to define the data format.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select HTTP Header.

    c. In the HTTP Header 2 field, enter the name "Content-Type", as this is where we configure the content format in which we will send information to the server.

    d. In the Source Type 3 field, select Constant to specify a fixed data format value that will not change across different method calls.

    e. In the Value 4 field, enter "application/json" to tell the server that data will be sent in JSON format, which is the standard for REST API communication.

    f. Select the Add 5 button.

  5. Configure the format in which data will be received from the server.

    a. In the Request Binding section, select Add.

    b. In the HTTP Request Part 1 field, select HTTP Header.

    c. In the HTTP Header 2 field, enter the name "Accept", as this is where we configure the content format in which we will receive information from the server.

    d. In the Source Type 3 field, select Constant to specify a fixed data format value that will not change across different method calls.

    e. In the Value 4 field, enter "application/json" to tell the server that its response is expected in JSON format.

    f. Select the Add 5 button.

  6. Specify the HTTP PUT method settings for updating a document via the external API.

    a. In the Request Binding section, select the Add button.

    b. In the HTTP Request Part 1 field, select Path Parameter.

    c. In the Path Parameter 2 field, enter "id".

    d. In the Source Type 3 field, select Method Argument.

    e. In the Method Argument 4 field, enter "id".

    f. Select the Add 5 button.

  7. Configure the method arguments. You can view an example of the PUT method settings in the screenshot.

  8. Leave the Response Parameter Binding section empty, as the PUT method typically does not return data after updating a resource — it only confirms the success of the operation via a status code.

  9. In the Dataset Binding section, enable the toggle 1 to return the method result as a dataset and apply binding to each row of data.

  10. Leave the Dataset Binding Root 2 field empty, as the response contains data for a single updated resource rather than an array of data.

  11. Add the attributes that need to be retrieved from the updated resource for further processing in the system. You can view examples of the added attributes in the screenshot below.

  12. In the Error Binding section, enable the toggle to allow binding the response if the method returns a status code other than 200-299, instead of generating a server error.

  13. Add an attribute to retrieve the response status from the server.

    a. Select the Add button.

    b. In the Destination Key 1 field, enter "statusCode".

    c. In the Source Type 2 field, select Response Property, as the status code is a standard property of the HTTP response.

    d. In the Source Key 3 field, select "Status Code" — this field contains the numeric result code of the request.

    e. Select the Add 4 button.

  14. Leave the Error Dataset Binding section empty, as in the event of an error it is sufficient to retrieve the status code — no additional datasets are needed.

2.10.1.3. Test the Added Method​

  1. In the navigation panel, select the Studio 1 workspace.

  2. Select the Integration 2 shortcut group, then select the External APIs 3 shortcut.

  3. Select the record whose method you want to test 4.

  4. Go to the Methods tab.

  5. In the methods menu, select the method you want to test 1, then select the Call 2 button.

  6. In the request body field 1, enter the required parameters, then select the Call 2 button.

    Note:

    The request body field may differ depending on the method settings you specified in the Request Binding section.

  7. In the Dataset field, you can view the result of the request. The table will display the fields with values configured in Dataset Binding, or the data will be displayed as plain text according to the settings you specified in the Response Parameter Binding section.

  8. Go to the Method Return Parameters tab to view the data in JSON format returned by the method.

2.10.1.4. Call a Method and Process the Results​

In this section, you will learn how to call the method you configured in the previous sections, and how to work with the received data.

This procedure has three main stages:

  1. Call the method: after calling the method, you will receive the server response in JSON format.

  2. Transform the received data: you can convert the server response from JSON format into process variables.

  3. Transfer the transformed data to the document attributes.

Note:

You can perform these actions for all or only some of the configured methods, depending on your needs.

To complete all three stages, follow the steps below:

  1. Navigate to the document type whose data you are passing in the method:

    a. In the navigation panel, select the Studio 1 workspace.
    b. Select the Document Types 2 shortcut.
    c. Select the required document type 3.

  2. Add a process to transform the received data into process variables and then transfer them to the document attributes.

    a. In the open document type, go to the Processes 1 tab.
    b. Select the Create Process 2 button.

    c. Fill in the fields 1 using the hints in the table below, then select the Create 2 button.

FieldDescription
Code*
  • The code must be unique.
  • The code must be short (typically up to 10 characters).
  • Use only Latin letters and digits.
Name*The display name of the process definition
Definition TypeSelect the definition type "BPMN 2.0"
Note:

Fields marked with * are required.

  1. Add a service task to perform the method call.

    Note:

    Before configuring the method call, test the added method.

    a. In the tools menu, select the icon 1, and place the element at the desired position in the process diagram 2.

    b. In the context menu, select the icon.

    c. In the context menu, select Service Task.

    d. Go to the settings menu, expand the General 1 section, then in the Name 2 field, enter the desired task name, for example, "Get Document".

    e. Expand the Implementation 1 tab, then in the Template 2 field, select "Call External API Method".

    f. In the External API 3 field, select from the list the external API whose method results you want to process.

    g. In the Method 4 field, select from the list the method whose results you want to process.

  2. Parse the data: add a script task to the process to convert the received JSON data into variables.

    a. In the tools menu, select the icon 1, and place the element at the desired position in the process diagram 2.

    b. In the context menu, select the 1 icon, then select Script Task 2.

    c. Go to the settings menu, then expand the General 1 section.
    d. In the Name field, enter the desired task name, for example, "Process Input Data" 2.

    e. In the task context menu, select the icon .

    f. Select "+" 1, then Inline Script 2.

    g. In the text field 1, enter the function execution.getVariable('variableName'), then below it enter the rest of the parsing script, depending on the type of data received as a result of the method execution.

  3. Add a service task to configure the transfer of variables to the document attributes.

    a. In the tools menu, select the icon 1, and place the element at the desired position in the process diagram 2.

    b. In the context menu, select the 1 icon, then select Service Task 2.

    c. Go to the settings menu, then expand the General 1 section.
    d. In the Name 2 field, enter the desired task name, for example, "Transfer Data".

    e. Expand the Implementation 1 tab, then in the Template 2 field, select "Update Entity".
    f. In the Entity 3 field, select the required entity.

    g. In the Entity Attributes section, select "+" to add the document (or other entity) attributes to which you want to transfer the received data.

  4. Add an end event to complete the process.

    a. In the tools menu, select the icon 1, and place the element at the end of the process diagram 2.

  5. Add flows between the added tasks to show the sequence of events in the process.

    a. Select one of the added elements 1, then in the context menu select the icon 2.

    b. Select the second element to which you want to connect the previous element.

    c. Repeat these steps for the remaining objects in the process.


  6. Save the business process and deploy it.

    a. In the toolbar, select the Save or Save and Close icon 2.
    b. In the top panel, select Deploy.

    c. Select the Yes button to confirm the deployment.

After the process runs, you will receive the processed results.

For more details, see the Camunda documentation.