Settings

(1) Select template: You can obtain these templates (with presets) from the Update Center.

(2) URL address suffix: The URL suffix. You can see the leading part of the endpoint URL via the question mark icon on the left. This, together with the suffix, then results in the total URL. For details s ee section " Request procedure" below. Example: "example".

(3) API variables: Only available in mode "REST web service" (7). Path parameters can be specified here. Exactly one path parameter can be defined between the slashes (see screenshot). Each specified path parameter can be read out with a system variable MSG_CALL_HTTP_REST_API_PATH_<name of path parameter> (must be defined). Example and notes:

Field "URL address suffix": "example/".

Field "API variables": "{shop}/{petID}".

HTTP request: "https://<URL/IP Integration Server>/dw/request/example/myshop/4711/something".

Notes:

• Please note that when specifying path parameters, you must enter a slash at the end of the suffix (2), in this case "example/". A leading slash in field (3) is automatically removed after saving the profile!

• Path parameters are mandatory in Swagger/OpenAPI (8). However, if the profile is addressed directly, they are optional.

• See also https://swagger.io/docs/specification/describing-parameters/#path-parameters and https://petstore.swagger.io/.

(4) Allowed HTTP methods: The allowed HTTP methods. Important note: See section "Request body, profile behaviour and profile input data" below.

(5) DELETE has payload: See note in (4).

(6) Asynchronous response: If this checkbox is set, several instances of this profile can work in parallel. The checkbox "Profile may only run in one instance" must not be set then for this profile. Only works with a fixed response (13). The response then takes place immediately and not when the profile job is completed. Note: If this option is set, jobs of this profile are processed in a Thread Queue.

(7) HTTP interface, REST web service, SOAP web service: The mode of the HTTP Input Agent.

(8) Show API to public: If this checkbox is set, the mapping is active, option "REST web service" (7) is set and the profile was saved, a Swagger/OpenAPI interface description is provided in JSON or YAML format. You can also create your own swagger files via (19), which are then used instead of the automatically generated ones. These files have the name "<profile name>.json" or "<profile name>.yaml" and are located in the directory ./conf/openapi. The structure of these files is not described here, please refer to the OpenAPI documentation. Example: "https://localhost/dw/Request/example?api or https://localhost/dw/Request/example?api&yaml".

Additionally, a Swagger/OpenAPI interface description in YAML format will be provided to you in a graphical tool , see link (8). There you can send requests to the interface. See generally section REST API (instructions there). The data for the authentication dialog (also accessible via the cogwheel) can be found in (17). You can combine several such profiles into an overall REST API. See section Main settings (Data Flow).

URL: "http(s)://<URL or IP of the Integration Server>/openapi/?endpoint=<URL suffix>".

Example: "https://localhost/openapi/?endpoint=example".

Important note: If you want to make the interface available via the DMZ server (if available and all forwarding rules are set up), you must change the IP/URL (and if necessary the port) to the IP/URL of the DMZ server in parameter "webServiceUrl" in configuration file ./etc/startup.xml on the inner integration server. This parameter is used to set the server address in the graphical tool (see screenshot below). If it is not correct, the requests will not work.

Important note: The IP/URL (and, if applicable, the port) in parameter "webServiceUrl" (see note above) must also be changed to the public address of the Integration Server if you want to make the graphical tool available externally (i.e. not just on the intranet).

(9) Test file for API: Only available in mode "REST web service" (7). All stored test files are displayed here in a further dialogue. There you can specify for each file for which HTTP method (4) they are available in (8). These are then displayed (left) in (8) and can be selected (right) for a request (e.g. with POST).

(10) Content type of response: The MIME type of the response.

(11) Multipart file key: Optional name for the multipart of the main data. Normally, a part with name "file" is searched for. If the name is not "file", you can enter the alternative part name here. Note: This only applies to multipart requests and if no part with the name "file" was found! See also section "Handling HTTP multipart messages" below.

(12) Accept empty HTTP body: An empty HTTP body (e.g. with POST) is not considered an error.

(13) Send response by: The response for the success case can be defined in three different ways. The response in the event of an error is always defined in (15).

• Fixed response value, see (14).

• Dynamic response value. Use a Response "Custom Class" with class "PassBackDataResponse" or set option "Return data" in a Response "HTTP" or "Message". See also section HTTP Response Chains.

• No content. As the name suggests, the response is empty here. The response status is "204".

(14) Response on success: Fixed response value, see (13). Line breaks can be inserted with "<br>". Note: The placeholders "{--jobnr--}" or "@VAR_JOBNR@" and "{--uuid--}" or "@VAR_SYS_MESSAGE_ID@" are available. Phase 3 variables can also be used with "{--@MYVAR@--}" or "@MYVAR@". Phase 3 must be active for this.

(15) Response on error: Static response that is sent in case of an error, for both cases in (13). Note: You can use the placeholder "{--Exception--}" to return the exception that occurred. If the exception message contains a substring "§...§", then the placeholder is replaced by the substring text. Example: If you call the function "throw exception("§Sorry!§")" in phase 3 of the profile, the placeholder "{--Exception--}" is replaced by the string "Sorry!". Alternatively, the placeholder "{--FullStackTraceException--}" can be used to output the full stack trace.

(16) HTTP error code: The HTTP status code returned in case of an error. The button "More HTTP error codes" on the right can be used to enter further codes with the corresponding "Response on error" (15). These entries can be used by function "throw http exception()" (see description there).

(17) WWW Authentication: Either no access control or access control either via one or more selected partner channels ("Your Access") or with directly specified login data. If access control is used, the authentication method ("BASIC", "DIGEST", "OAUTH2", "SYSTEM") can be selected. See also system variable MSG_CALL_HTTP_AUTH_USER.

• For "SYSTEM", the setting from the configuration file ./etc/startup.xml (→ "forceDigestAuthentication") is used. Is shown on page " Start" .

• If "OAUTH2" is used, you must specify an HTTP channel with OAUTH2 configuration.

(18) Mandatory parameters: Specification of the mandatory request parameters. See sections " Request procedure" and " Request parameters" below for details.

(19) Burger menu right of (2): See (8).

Schematic structure of the HTTP address

To send data to or start a profile using HTTP, you have to use a specific URL. The schematic structure of the URL is

Request body, profile behaviour and profile input data

Depending on which HTTP request method was used and whether the HTTP request has a body with data or not, the Input Agent behaves differently and the profile receives different input data.

Important note: If you use a mapping in your profile, the input data must have a specific format so that no error occurs during parsing. Please bear this in mind when selecting the permitted HTTP methods (4). In this case, for example, you would allow the HTTP method "POST" and expect certain input data in the request body. In this case, it would therefore make no sense to also allow the HTTP method "GET", as the input data that the profile then receives would not match the source structure of the profile, resulting in an error during parsing.

Note: In the following table, it is assumed that the corresponding HTTP method is selected in (4). If the profile receives a request with a method that is not selected in (4), no job is started and the profile returns the response string "Your request could not be processed due to unknown/mismatched parameters" and the response status code "404".

Note: If one of the errors described in this section occurs, the following sections regarding request and response do not apply.

Request procedure

The HTTP servlet is started when the Integration Server is started and responds by default to both the HTTP context "/dw/request" and "/dw/Request".

For an incoming request, the HTTP servlet first looks for the right profile. All active profiles that have an event-driven HTTP Input Agent and whose suffix (2) matches the suffix in the request are considered.

Additionally, the request parameters must match the mandatory request parameters (18). If, for example, you enter value example in (1) and two parameters ("p1=value1", "p2=value2") in the parameter list (18), the URL must look like this.

The first matching profile is started. If the profile requires authentication (17), however, the profile is only started after successful authentication. If other profiles meet the conditions, these profiles will not be considered.

Request parameters

Request headers

Request headers can be read with the system variables MSG_CALL_HEADER_HTTP_<name of header in uppercase letters>. Note: The system variable MSG_CALL_HEADER_HTTP_AUTHORIZATION (header "Authorization") is not set by default. However, you can force this variable to be set with the system property "hub.datawizard.http.copy.allHeader=true".

Further system variables:

• MSG_CALL_HEADER_HTTP_METHOD

• MSG_CALL_HEADER_HTTP_PROTOCOL

• MSG_CALL_HEADER_HTTP_REMOTE_HOST

• MSG_CALL_HEADER_HTTP_URI

• MSG_CALL_HTTP_AUTH_USER

• MSG_CALL_HEADER_HTTP_QUERY

Response procedure

If no profile could be found, or the mandatory parameters do not fit, you will get a corresponding message back.

If a suitable profile was found, the response is sent when the profile was successfully terminated or an error occurred. However, if (6) is set, the response is immediate.

The content of the response is defined by the settings in (13).

Note: Section does not apply if an error occurred in connection with the HTTP method (4). See section "Request body, profile behaviour and profile input data" below.

Response header

If (13) is set and system variables of the form VAR_RESPONSE_HTTP_HEADER_<name of response header> are defined, corresponding response headers are set with the values of the variables. Example: The system variable VAR_RESPONSE_HTTP_HEADER_Test with the initial value "mytest" creates the HTTP response header "Test" with value "mytest". Note: The response header " Content-Length" is ignored, i.e. it cannot be overwritten.

Note: Section does not apply if an error occurred in connection with the HTTP method (4). See section "Request body, profile behaviour and profile input data" below.

Response status

If the profile was executed successfully, the response status is "200". If "Custom class..." is set in (13), the response status "200" can also be overwritten with the system variable VAR_RESPONSE_HTTP_HEADER_RESP_STATUS. If "No content" is set in (13), the response status is "204".

If an error occurred during profile execution, the response status is the value specified in (16) or as set by function "throw http exception()".

If (6) is set, the response status is "200" as soon as the profile has been successfully triggered. The function "throw http exception()" cannot change the response status in this case.

Note: Section does not apply if an error occurred in connection with the HTTP method (4). See section "Request body, profile behaviour and profile input data" below.

Handling HTTP multipart messages

The Input Agent always only reads the first multipart, see (11). But the other parts are not lost. They are stored in system variables.

The name of the second part would be saved in variable MSG_CALL_HTTP_MULTIPART1_NAME and its value in MSG_CALL_HTTP_MULTIPART1_VALUE. The third part in MSG_CALL_HTTP_MULTIPART2_NAME and MSG_CALL_HTTP_MULTIPART2_VALUE, etc. The total number of all parts, including the main part (11), is saved in system variable MSG_CALL_HTTP_MULTIPARTS.

Ideally, you know how many parts you will receive and create the variables accordingly. If this is not possible, you can use a little trick to avoid creating the variables. Simply use system variable MSG_CALL_HTTP_MULTIPARTS (of course you can create this variable beforehand) to find out how many parts were received. You then use this value to iterate over a node and read the respective variable values with function copy field by name(). You can create the name of the variable with functions iteration-level() and concat(a,b,c,d,e,f,g,h, [CR-support i]). Please do not forget that variable MSG_CALL_HTTP_MULTIPARTS contains the total number of all parts. But you can only read from the second part on from the variables.