Call Web Services from the process workflow

Flokzu allows you to connect your processes with external systems via web services to automate information exchange.

Common use cases:

• Data synchronization: Automatically send form information (e.g., a selected candidate) to other company systems (such as HR software).
• Information lookup: Retrieve external data in real-time (e.g., exchange rates or credit scores) and insert them directly into the form.
• Trigger external actions: Execute operations in third-party systems (e.g., processing a payment or creating a user) after an approval in the workflow.

How to invoke a Web Service from the process flow?

To invoke a Web Service from the process flow, the first thing you must do is place a Service Task at the workflow stage where you wish to perform the invocation and select the REST option.

Finally, you must configure the Web Service you wish to invoke with the following steps:

1. Enter the URL and the service type (method) you wish to invoke.
2. Configure the input data to be sent to the Web Service.
3. Configure the output data received from the Web Service, which can be loaded into Flokzu form fields.
4. Configure HTTP Headers (optional).
5. Configure Error Handling.
6. Lastly, you can select the authentication your service uses in the Authentications tab.

1. Configure URL and Method

Type or paste the service URL (endpoint) you wish to invoke and select the method from the list on the right.

If it is necessary to reference the content of a form field in the web service URL, it must be done using mustaches {{Field Name}}.

Supported methods are:

• GET
• PUT
• POST
• PATCH
• DELETE

2. Configure Input Data (Request Body)

For each input parameter, Flokzu allows you to insert the content of your form fields or send literal values. Click on the pencil icon to toggle between the two options.

Parameters will be automatically translated into the request body, except when using the GET method, where they will be sent as queryParam.
Let's look at some examples:

With the GET method, input parameters are sent in the URL. A configuration like the following:

will invoke the following URL:

https://api.myapp.com/v1/service?param1=value_1&param2=value_2

With PUT, POST, PATCH and DELETE methods, a configuration like the following:

will send the following JSON in the request:

{
    "param1": "value_1",
    "param2": "value_2"
}

Customizing the Request Body

It is possible to customize the service call by writing the body directly or by indicating that the parameters should be sent as url-encoded.

RAW

The raw option allows you to write the input JSON directly. Additionally, using mustaches, you can insert the content of a form field directly into the body.

URL-ENCODED

If your service requires data to be sent as url-encoded, select the x-www-form-urlencoded option within the Input Parameters tab. Then you can add the parameter - value pair.

FORM-DATA

Form-data refers to a way of communication between web services where data is sent as key/value pairs. While useful for sending any type of data (text, numbers, booleans), it is also the only mechanism that supports "multipart/form-data" encoding, necessary for sending attachments.

3. Configure Output Data (Response Body)

Flokzu supports two types of responses for services, which you must choose in the Output Data tab:

• RAW: The REST service response must be a valid JSON. You can verify the JSON using the following website: http://jsonviewer.stack.hu/
• BINARY: A file that you can attach to the Attachments Tab or a form field.

RAW

After choosing this option, you must indicate the name of the JSON response parameter you wish to access, and in the right column, the form field where you want to insert that value.

Suppose this is the output JSON:

{
  "name": "JSON example.",
  "description": "This is a JSON example with multiple levels and data within an array.",
  "author": {
    "name": "John Doe",
    "age": 35,
    "active": true
  },
  "values": [10, 20, 30, 30, 40],
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "active": true,
      "roles": [ "admin", "user"]
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com",
      "active": false,
      "roles": [ "user"]
    }
  ]
}

Next we will see how to configure the output parameters to access some of the properties.

BINARY

If the web service you are invoking returns a file in its response, you can attach it to your process instance. After selecting the Binary option, you must choose from the list the field where the attachment will be saved.

4. Configure HTTP Headers

Enter the HTTP Headers (optional), for security purposes, for example.

5. Error Handling

Why configure error handling?

In integrations with external systems, it is common for a service not to respond with a success (200 OK) due to invalid data, lack of stock, or temporary external server downtime. Without error management, the process ignores these technical responses, making it difficult for the business user to know what failed. By configuring Error Handling, you transform a technical failure into actionable information, allowing the process flow to be resilient and self-correcting.

How to configure Error Handling

Within the configuration of your Service Task (REST), you will find the "Error Handling" tab. To activate it, follow these steps:

1. Toggle the "Process errors" switch: By default, it is OFF. When activated, Flokzu will allow the capture of the service response when the HTTP code is an error.
2. Select the Error Type: Choose whether you want to manage 4XX errors (client/data errors, such as a malformed field) or 5XX errors (external server errors).
3. Configure the Mapping Table: Just as with successful responses, define which data from the error JSON you want to save and in which form field.

Obtaining the response HTTP code

In addition to the web service response, Flokzu adds a property flokzu_ws_status that returns the error's HTTP code (e.g., 400, 503). Sometimes this parameter can be useful for configuring subsequent conditional Gateways. To use it, simply add flokzu_ws_status to the mapping table and set a destination field.

Typical use cases

• Document Validation: If an identity validation service returns a 400 error because the document is invalid, you can capture the error message and redirect the flow to a user task so the requester can correct the data.
• Banking Integration: In the event of a 500 error from a bank, you can capture the status, automatically notify the IT team, and schedule a process retry after a waiting period.
• Stock Management: If an inventory API responds that there is no stock, the error message can be displayed directly on the form so the approver can make an informed decision.

Mapping Best Practices

1. Use hidden fields for codes: Map technical error codes (like INVALID_API_KEY) to hidden fields and use descriptive messages for fields that the end user will see.
2. Define alternative paths in the Workflow: Whenever you configure error handling, use an Exclusive Gateway immediately after the Service Task to evaluate the value of flokzu_ws_status.
3. Simple JSON Path mapping: Use dot notation (e.g., response.error_details[0].description) to reach the exact data. Ensure the destination field in Flokzu matches the data type you expect to receive (Text, Number, etc.).
4. Do not ignore the Error Monitor: Although the process now captures the error and continues, the failure will still be recorded in the Flokzu Error Monitor for technical auditing.

6. Configure Authentications

Finally, if your service has a security mechanism, you can select the authentication your service uses in the Authentications tab.

Execution Behavior

In Flokzu, Service Tasks are executed synchronously. This means that when the flow reaches this step, the process stops and waits for the response from the external system before moving to the next stage.

The behavior of the process engine will depend on the result of the invocation and your configuration:

1. Successful Response (Range 200-299)

• The mapping defined in the Output Data tab is applied.
• The flokzu_ws_status parameter will always return the numeric code 200.

2. Error Response (Codes 4XX or 5XX)

In case of error, the behavior varies depending on whether you have activated Error Handling:

If Error Handling is ENABLED:

• The Output Data tab is completely ignored.
• Only the mapping configured in the Error Handling tab is applied.
• To obtain the error code (e.g., 404), you must explicitly map flokzu_ws_status within this tab.

If Error Handling is DISABLED (Default behavior):

• The mapping of Output Data fields is ignored.
• Exception: The flokzu_ws_status parameter will be processed if it was configured in Output Data, returning the corresponding error code (e.g., 500) so you can use it in subsequent gateways.

7 . Service with callback

A REST Service Task can be configured to work asynchronously through a callback. This option allows you to integrate external services that require more processing time and cannot provide an immediate response.

Unlike a synchronous service, where Flokzu waits for the response during the same execution, with a service with callback the instance waits for the external system's response without blocking the user or keeping an active execution running.

When to use it?

A service with callback is useful when the external system may take longer to process a request, for example:

• Generating complex documents.
• Processing large files.
• Running AI analysis.
• Performing verifications or validations that require more time.

For operations that require an immediate response, continue using the standard synchronous configuration.

Configuration

To use a service with callback:

1. Configure the REST Service Task as asynchronous by enabling the Service with callback (wait for response) option.
2. Keep the input, output, and other service parameters configured according to the integration requirements.

Once configured, the REST Service Task will work asynchronously and wait for the external service response before continuing the process flow.

When Flokzu sends the request to the external service, it automatically includes in the headers the information required to identify the instance and validate the subsequent response:

• X-Flokzu-Correlation-Id: identifier used to associate the response with the corresponding instance and REST Service Task.
• X-Flokzu-Callback-Signature: signature used to validate the communication.

These values are automatically generated by Flokzu and do not need to be configured manually.

Initial response and callback

The external service must initially respond to the request within 15 seconds with HTTP 200 status code. This response only confirms that the request was successfully received and must not include the final processing result.

Once the processing is completed, the external service must send the response to Flokzu through a callback request to the following endpoint:

• POST: https://app.flokzu.com/flokzuopenapi/api/callback/{correlationId}?sig={signature}
• The correlationId and signature previously sent in the request headers must be added as parameters.

The callback request must include the final service response in JSON format. Flokzu will use this information to complete the mapping configured in the Output Data of the REST Service Task. Once configured, the REST Service Task will work asynchronously and wait for the external service response before continuing the flow.

Instance behavior

While waiting for the external service response:

• The instance is not blocked for the user.
• The user can continue working with other instances or log out.
• The instance can be searched or edited through API.

When the external service sends the response, Flokzu processes the received information, updates the fields configured in the Output Data, and continues the process execution through the output path defined in the REST Service Task.

Timeout

To prevent an instance from waiting indefinitely due to an issue with the external service, Flokzu automatically adds an interrupting timer with a maximum waiting time of 30 days. This timer cannot be removed or modified. If the response does not arrive within that period, the instance continues through the output configured in the timer. The administrator can add additional timers to define shorter waiting times and configure specific behaviors according to the process requirements.

What if I want to integrate with an app that doesn't support Web Services?

If you want to integrate with other apps, and these doesn't support Web Services, you can do it as well. Simply place a Service Task in the workflow, then select 'Zapier' and follow the steps to integrate Flokzu and Zapier. Once the integration is set up, you'll be able to connect Flokzu with more than 1,000 apps (Facebook, Google Drive, Gmail, SalesForce, etc).

Updated on: 27/08/2026