HTTP (Input agent)

Select template

Loads a template with presets. You get the templates from the Update Center.

URL address suffix

Defines the suffix of the endpoint URL. Example: example.

The question mark icon on the left shows the leading part of the URL. The leading part and the suffix together form the complete URL. The section “Schematic structure of the HTTP address” describes the structure.

API variables

Defines the path parameters of the REST interface. A path parameter is a variable section of the URL. This field appears only in the mode REST web service.

Between two slashes you define exactly one path parameter. The section “Reading path parameters” shows an example.

Allowed HTTP methods

Defines which HTTP methods the input agent accepts. The section “Request body, profile behavior, and profile input data” describes the behavior for each method.

'DELETE' has payload

Controls whether the profile uses the body of a DELETE request as input data. The table in the section “Request body, profile behavior, and profile input data” shows the complete case distinction.

Asynchronous response

Allows several parallel instances of this profile. Lobster sends the response immediately, not after the profile job ends.

This option works only with a fixed response. The checkbox Profile may only run in one instance must not be set for this profile. Lobster then processes the jobs of this profile in a Thread Queue.

Invisible for DMZ

Hides this interface from the DMZ server. The DMZ server then forwards no requests to this profile.

HTTP interface, REST web service, SOAP web service

Defines the mode of the input agent. The section “Modes of the HTTP input agent” describes the modes.

Publish interface (API documentation)

Provides a Swagger/OpenAPI interface description, in JSON or YAML format. The section “Publishing the interface description” describes the details.

Swagger Transformer Version

Defines which version generates the interface description. v1.0 (deprecated) is outdated. Use v2.0.

Open OpenAPI/Swagger app

Opens the OpenAPI/Swagger app in a new browser tab. There you check the interface description and test requests.

Test data for OpenAPI/Swagger app

Opens a dialog with all test files stored in the profile. This field appears only in the mode REST web service.

For each file you select an HTTP method from Allowed HTTP methods. The file is then available in the graphical tool for this method. There you select the file for a request, for example for POST.

Content type of response

Defines the MIME type of the response.

Multipart file key

Defines the name of the multipart that contains the main data. By default, Lobster looks for the part named file.

NOTE: This field takes effect only for multipart requests. It takes effect only if no part named file exists. See also the section “Handling HTTP multipart messages”.

Accept empty HTTP body

Does not treat an empty HTTP body as an error, for example with POST. Lobster then creates a dummy input file with the content body data.

Send response by

Defines the response for the success case. The section “Defining the response for the success case” describes the three variants. You always define the response for the error case in Response on error.

Response on success

Contains the fixed response value for Send response by. You insert a line break with <br>.

Available placeholders: {--jobnr--} or @VAR_JOBNR@ for the job number, {--uuid--} or @VAR_SYS_MESSAGE_ID@ for the message ID. You use phase 3 variables with {--@MYVAR@--} or @MYVAR@. Phase 3 must be active for this.

Response on error

Contains the response for the error case. It applies to both variants in Send response by.

With the placeholder {--Exception--} you return an exception that occurred. If the exception message contains a substring §...§, Lobster replaces the placeholder with this substring. Example: If you call the function throw exception("§Sorry!§") in phase 3, Lobster replaces {--Exception--} with Sorry!.

Alternative placeholders: {--FullStackTraceException--} for the full stack trace, {--ExceptionBase64--} for the exception in Base64.

HTTP error code

Defines the HTTP response status code for the error case.

You find the button More HTTP error codes to the right of the field. There you enter additional codes. You assign each code its own Response on error. The function throw http exception() uses these entries.

WWW Authentication

Defines the access control. You have three options. None: no access control. With channel: access control through one or more HTTP channels. Without channel: access control through directly specified credentials.

For access control you also select the authentication method: BASIC, DIGEST, OAUTH2, or SYSTEM. You read the logged-in user through the system variable MSG_CALL_HTTP_AUTH_USER.

For SYSTEM, Lobster uses the setting forceDigestAuthentication from the configuration file ./etc/startup.xml. For OAUTH2, you also specify an HTTP channel with OAUTH2 configuration. The section Vault provider configuration describes Vault passwords.

User

Contains the user name for the access control. This field appears only with the option Without channel.

Password

Contains the password for the access control. This field appears only with the option Without channel. You use a Vault password through the lock icon.

Mandatory parameters

Access control and Mandatory parameters are in two tabs. Defines which request parameters an HTTP request must contain at minimum. The sections “Request procedure” and “Request parameters” describe the details.

☰ menu to the right of the field URL address suffix

Opens a menu for your own Swagger files. There you create your own interface description. Lobster uses it instead of the automatically generated one. See the section “Publishing the interface description”.

Field URL address suffix

example/

Field API variables

{shop}/{petID}

HTTP request

https://<URL/IP Integration Server>/dw/request/example/myshop/0814/something

MSG_CALL_HTTP_REST_API_PATH_shop

myshop

MSG_CALL_HTTP_REST_API_PATH_petID

0814

MSG_CALL_HTTP_PATH_DATA

myshop/0814/something

MSG_CALL_HEADER_HTTP_URI

/example/myshop/0814/something

HTTP interface

This is the standard mode. The input agent accepts requests through the URL from URL address suffix, in this case https://localhost/dw/Request/example. The fields API variables and Test data for OpenAPI/Swagger app are missing in this mode.

REST web service

The input agent works as a REST interface. It also accepts requests with an appended path. Example: With the URL https://localhost/dw/Request/example it also accepts https://localhost/dw/Request/example/orders.

Lobster stores the additional suffix /orders in the system variable MSG_CALL_HTTP_PATH_DATA. In all other respects, the input agent behaves as in the mode HTTP interface. The fields API variables and Test data for OpenAPI/Swagger app are also available.

In this mode an additional button appears. It opens a dialog where you store sample response files through the context menu. The graphical tool shows these files only if the checkbox Show response data is set there.

SOAP web service

The input agent works as a SOAP web service. The sections Profile as SOAP web service (static response) and Profile as SOAP web service (dynamic response) describe the details.

Fixed value

Lobster sends the value from the field Response on success.

'Custom class' or 'Return data' in the response path of the profile

Use a response path Custom class with the class PassBackDataResponse. Alternatively, set the option Return data in a response path HTTP or Message. See also the section HTTP response chain.

No return value

Lobster sends an empty response with the response status code 204.

<protocol>

http or https. See also the section Adding an HTTPS listener.

<server> and <port>

DNS name or IP address of the Integration Server, optionally with the port number. Use the values that you configured for the HTTP listener or the HTTPS listener. You can omit the default ports 80 for HTTP and 443 for HTTPS.

A firewall can broker external access through port forwarding. In this case, use the parameters of the external connection. For access through a DMZ server, the external connections of the DMZ server apply.

<URL context>

For a profile with an event-driven input agent HTTP, normally /dw/request. To trigger a profile with a time-driven input agent, normally /dw/trigger.

You change the default settings system-wide in the configuration file ./etc/startup.xml.

<URL suffix>

The value from the field URL address suffix.

<query>

Additional call parameters. Structure: ?name1=value1&name2=value2

GET

A GET request normally has no body data. Lobster ignores existing body data. Because a profile requires input data, Lobster generates a dummy string. The content depends on the document type of the profile.

• XML: <body_data/>

• JSON: {"body": "data"}

• All others: body data

POST

If the request contains body data, this data is the input data of the profile. That is the normal case.

If the request contains no body data, the checkbox Accept empty HTTP body decides:

• Checkbox set: The profile receives the dummy string, as with GET.

• Checkbox not set: Lobster starts no job. The profile returns the response Your request could not be processed due to empty body with the response status code 500.

PUT

Like POST.

HEAD

Like GET.

DELETE

If the request contains no body, the checkbox 'DELETE' has payload decides:

• Checkbox not set: The profile receives the dummy string, as with GET.

• Checkbox set: Lobster starts no job. The profile returns the response Your request could not be processed due to empty body with the response status code 500.

If the request contains a body, the same checkbox decides:

• Checkbox not set: The profile receives the dummy string, as with GET.

• Checkbox set: The body data is the input data of the profile.

PATCH

Like POST.

Parameter name

The name of the HTTP request parameter that must be present. You can use system constants.

To allow several values for one parameter, create the parameter name several times.

Value

Expected value of the parameter. If you enter a value, the parameter in the request must have exactly this value.

With the symbol * you allow any value. The parameter then only has to be present. You can use system constants. You specify regular expressions with the prefix regex: or regex2:.

The profile ran successfully.

200

In Send response by, Custom class is set.

200. You overwrite this value with the system variable VAR_RESPONSE_HTTP_HEADER_RESP_STATUS.

In Send response by, No return value is set.

204

An error occurred during profile execution.

The value from HTTP error code. Alternatively the value that the function throw http exception() sets.

The option Asynchronous response is set.

200, as soon as Lobster has successfully triggered the profile. The function throw http exception() can then no longer change the response status.

Second part

MSG_CALL_HTTP_MULTIPART1_NAME

MSG_CALL_HTTP_MULTIPART1_VALUE

Third part

MSG_CALL_HTTP_MULTIPART2_NAME

MSG_CALL_HTTP_MULTIPART2_VALUE