HTTP Task

Introduction

The HTTP Task allows to submit and store the result of a HTTP call.

Properties

General

Attribute	Type	Description	Category
Model Id	Text	Model Id identifies the element within the process model.	The model id, name and documentation properties can be found on any element. They are used respectively to uniquely identify the HTTP task, to give it a user-friendly name and to add a free-form description.
Name	Text	The name of the element. This is the name displayed in the diagram.
Documentation	Multiline Text	A free-form text that can be used to explain details about the particular element.
Request method	Selection: GET POST PUT DELETE PATCH	Request method to be used in the HTTP call: GET, POST, PUT or DELETE.	Doing an HTTP REST call always consists of a request and a response. Here the request can be configured by configured the method and the URL. For more advanced use cases, it's also possible to configure custom headers and create a body, when using methods like POST or PUT. Typically, you'll want to use an expression to dynamically populate the body in that case.
Request URL	Text	Request URL of the HTTP call. Can contain expressions, e.g., 'http://your-system.example.com/your-endpoint/${someVariable}'.
Request headers	TextArea	Line-separated HTTP request headers.
Request body	TextArea	Request body to be sent, e.g., a JSON file. You can use expressions, e.g., {'clientId': ${clientId}, 'name': ${name}}.
Response variable name	Text	The variable name in which the HTTP response is stored.	Doing an HTTP REST call always consists of a request and a response. Here the handling of the response can be configured. Use the Response variable name to store the response as a process instance variable. As these responses tend to become large, it's often a good idea to store this variable transiently, by checking the Save response as a transient variable flag. Using the Handle status codes it is possible to throw a BPMN error in case of a matching status code in the response. Similarly, the Fail status code will force a runtime exception to be thrown, which will rollback the current database transaction.
Save response as JSON	Boolean	Determines whether the response variable is stored as a JSON variable instead of a String.
Save response as a transient variable	Boolean	Determines whether the response variables should be stored as transient.
Handle status codes	Text with suggestions	List of status codes for which the task will throw BpmnError which can be caught by a boundary error event. Code ranges can be set with an X: Example: 400, 404, 5XX. Status codes in handleStatusCodes override those in failStatusCodes when they are set in both.
Fail status codes	Text with suggestions	List of Http response status codes to fail the request and throw a FlowableException. Code ranges can be set with an X: Example: 400, 404, 5XX.

Multi Instance

Multi instance

Attribute	Type	Description	Category
Multi instance type	Selection: None Parallel Sequential	The type of multi-instance: default is 'None' meaning a single instance is created at runtime. Select either 'Parallel' or 'Sequential' if you want multiple instances to be created.	Multi-instance is used to define the repetition of this HTTP task at runtime. With multi-instance it is possible to have multiple HTTP REST calls, either sequentially after each other or in parallel. For example, when referencing a collection one invocation of the custom logic is executed for each element of that collection.
Collection	Text	References a collection variable (for example a JSON array variable) by its name or using an expression that resolves to a collection.
Element variable	Text	The name of the variable where the currently processed element from the multi-instance collection configured above will be stored (for example, 'invoicePosition'). The element can then be accessed through an expression, e.g., ${invoicePosition}.
Element index variable	Text	The name of the variable where the index of the currently processed item from the multi-instance collection will be stored, for example, 'itemIndex'. The index is a number starting with 0 which is increased with every element that is being created. The index can then be accessed through an expression, e.g., ${itemIndex} further on in the process.
Cardinality	Text	A fixed number or an expression that resolved to an integer that controls the number of instances that will be created. This is typically used when there is no collection available or needed.
Completion condition	Text	An expression that should resolve to a boolean value. When evaluating to true, the remaining activity instances will be removed and the process instance will continue.

Variable aggregation

Attribute	Type	Description	Category
Variable Aggregations	List	Define an aggregation. Each element in this list will result in one aggregation variable.	When having multiple instances of this http task, there is often a need to create an aggregation of the variables created and/or updated in each instance. With variable aggregation, a JSON variable can be created that after all instances have been completed contains the summary of all the used variables. This is needed because typically variables are persisted locally, to avoid clashes on the process instance level. Alternatively, an 'overview' variable can be created while the instances are still unfinished. Each aggregation consists of one or multiple definitions that map instance variables of one instance to the single aggregation variable.

Advanced

Attribute	Type	Description	Category
Optimize for only automatic steps	Boolean	(Advanced setting, only check it if you understand the implications) If checked, this instructs the Flowable engine that the multi-instance only contains automatic tasks and no wait states. In this situation, an asynchronous job is created when the multi-instance activity is entered that keeps checking if all instances are completed and completes the multi-instance. The benefit of this approach is that it is light on resources versus alternatives and doesn't lead to optimistic locking exceptions.

Details

Attribute	Type	Description	Category
Request body encoding	TextArea	Encoding of the request body.	Configures the encoding if the body of the request, if set.
Request timeout	Integer	Request timeout in milliseconds.	The amount of time in milliseconds that the runtime execution engine will wait for the HTTP call to receive a response. Defaults can be configured on the Flowable server configuration level.
Disallow redirects	Boolean	Determines whether HTTP redirects can be redirected.	By default, redirects issued by the receiving side of this HTTP task will be followed. Check this flag if this should not be allowed.
Save request variables	Boolean	Determines whether all request variables are stored. By default, only response related variables are stored as variables.	The Save request variables flag stores all request-related runtime fields such as url, body, headers, encoding, etc. as variables. Note that this could potentially lead to many and large process instance variables. The Save response details does the same, but for all response related fields that are not the actual response in the body, such as status code, headers, etc. Finally, the Variable prefix is a prefix that is put in front of these variables for easier grouping, which is useful when there are different HTTP tasks.
Save response details	Boolean	Determines whether response variables including HTTP status, headers etc. are stored. By default, only the response body is stored as a variable.
Result variable prefix	Text
Ignore exceptions	Boolean	Determines whether exceptions are ignored and stored in the variable indicated in the response variable.	Determines whether exceptions are ignored and stored in the variable indicated in the response variable.

Advanced

Execution

Attribute	Type	Description	Category
Skip expression	Text	If the Skip expression evaluates to true, the flow is taken regardless of any condition. It is required to opt-in to this feature by setting a variable _FLOWABLE_SKIP_EXPRESSION_ENABLED with the Boolean value true on the process instance.	When the Skip expression resolves to true, this service task will not be executed at runtime. The Include in history flag can be used to store the historical entry of this service task when running with a history level that normally would not store the execution of the service task. Note that this flag has no effect when running with history level 'none'.
Include in history	Boolean	When the history level is set to "instance" or "task" level with this property it can be configured if this activity instance should be included in the historic activity data.
Is for compensation	Boolean	Determines whether the activity can serve as a compensation for another activity.	A BPMN transaction is a set of activities that logically belongs together. Transactions can be cancelled through the Cancel End Event and handled through the Cancel Intermediate Boundary Event. The Is for compensation field can be used to indicate that the HTTP task is meant as compensation steps for another activity.
Asynchronous	Boolean	When enabled, the activity will be started as an asynchronous job. The process state is persisted before this element is executed. Then, the process execution will be resumed asynchroneously. This can be used when the execution an activity takes a long time to return the UI to the user quicker in case the user does not need to see the next step immediately. However, if an error occurs before the following wait state, there will be no direct user feedback. Please refer to the documentation for more details.	When making an HTTP task asynchronous, the HTTP REST call will be executed asynchronously in the background. This is useful for example to not block the UI of a user, in case of a slow service that is being called. Choose exclusive to avoid other asynchronous steps of this process instance to run at the same time. When Leave asynchronously is enabled, the activity will be left as an asynchronous job. This means that the activity is ended asynchronously.
Exclusive	Boolean	Determines whether the activity or process is run as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.
Leave asynchronously	Boolean	When enabled, the activity will be left as an asynchronous job. This means that the activity is ended asynchronously, including end execution listeners. Please refer to the documentation for more details.
Leave exclusive	Boolean	Determines whether the activity should leave as an exclusive job. An exclusive job makes sure that no other asynchronous exclusive activities within the same process are performed at the same time. This helps to prevent failing jobs in concurrent scenarios.
Job Category	Text	When set, the underlying generated job will have a Job Category, which will be executed only by Application Servers, where the Process Engine has enabledJobCategories set to this category.
Execute parallel in same transaction	Boolean	Flag indicating that the Http call should be done parallel in the same transaction. This means that when using parallel gateways multiple http tasks are executed in the same time in the same transaction and thus the entire execution of the process / case is faster.	Checking this flag means that the HTTP calls will be done in a separate threadpool. In case of parallel http calls, for example when there are multip HTTP tasks after a parallel gateway, this speeds up throughput as the calls will be done in a truly asynchronous way. The difference with using the asynchronous is that in that case there will be an asynchronous job for each asynchronous HTTP task, while with this flag the current execution is paused until all HTTP tasks with this flag checked are completed in a separate threadpool. It also means that the work isn't spread across different Flowable async executor instances, but rather all on the same machine, which typically is faster.

Advanced options

Attribute	Type	Description	Category
Exception Mappings	List	Define one or more exception mappings to map a technical Java exception to a BPMN error code.	Map technical java exceptions to BPMN error codes that can be caught with a boundary error event.

Listeners

Attribute	Type	Description	Category
Execution listeners	List	Allows invoking custom after certain lifecycle events. Start: Executes after the activity has been started. End: Executes after the activity was completed. Transition: When defined on a sequence flow, executes once the flow is transition is taken.	Execution listeners are used to add logic on certain lifecycle events. Typically it is used to add extra technical logic which shouldn't be visible in the BPMN process model.

Visual

Attribute	Type	Description	Category
Background color	Color	The background color of the element in the diagram.	Visual properties that determine how the HTTP task is shown in the diagram. This has no impact on the runtime execution.
Font size	Selection: 8 9 10 11 12 14 18 20 24 36 48 72	Font size.
Font weight	Selection: Normal Bold	Select the style between bold and normal.
Font style	Selection: Normal Italic	Select the style between italic and normal.
Font color	Color	Select a font color.
Border color	Color	The border color of the element in the diagram.

List Attribute Details

Variable Aggregations

Attribute	Type	Description
Target (Variable / Expression)	Text	The name of the target variable or an expression that gives the variable name
Type	Selection: Default Custom	The type of aggregation. Use 'default' to use the standard behavior of creating an aggregation JSON variable. Use 'custom' to define a delegate expression that will handle the aggregation. Please see the documentation for more information.
Delegate Expression	Text	Define a delegateExpression that will resolve to an instance of VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.
Class	String	A class that implements VariableAggregator (for BPMN) or PlanItemVariableAggregator (for CMMN). This instance will then be responsible for aggregating the variables.
Target variable creation	Selection: Default Create overview variable Store as transient variable	Configures the way the aggregation variable is created. The 'Default' option creates the aggregation variable when all instances of the multi-instance have been completed. Use 'Create overview variable' to create a variable at the start of the multi-instance and keep it up to date during multi-instance exeution. Once all the instances are completed it will create a JSON variable in the same way as for Default target variable creation. Use the 'Store as transient variable' option to have the default behavior, but store the resulting aggregation variable transiently.
Variable Definitions	BasicFormList	property.loopVariableAggregation.definitions.description

Variable Definitions

Attribute	Type	Description
Source (Variable / Expression)	Text	The name of the source variable or an expression that provides the value
Target (Variable / Expression)	Text	The name of the aggregation variable or an expression that resolves to a variable name.

Exception Mappings

Attribute	Type	Description
Error code	Text	The code of an error definition.
Exception class name	Text
Root cause	Text
Include child exceptions	Boolean

Execution listeners

Attribute	Type	Description
Event	Selection: Start End Take	The lifecycle event. The 'Take' event is only available for sequence flow.
Class	Text	Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.
Expression	Text	JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.
Delegate expression	Text	Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.
Fields	List

Fields

Attribute	Type	Description
Name	Text	The name of the element. This is the name displayed in the diagram.
String value	Text
Expression	Text	JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.
String	Text