HTTP (Input Agent)
(1) You can obtain these templates (with presets) from the Update Center.
(2) 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.
(3) 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".
|
System variable |
Value |
|
MSG_CALL_HTTP_REST_API_PATH_shop |
myshop |
|
MSG_CALL_HTTP_REST_API_PATH_petID |
4711 |
|
MSG_CALL_HTTP_PATH_DATA |
myshop/4711/something |
|
MSG_CALL_HEADER_HTTP_URI |
/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) The allowed HTTP methods. Important note: See section "Request body, profile behaviour and profile input data" below.
(5) See note in (4).
(6) 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) The mode of the HTTP Input Agent.
|
HTTP interface |
The standard mode. HTTP requests are received via the URL described in (2), in this case "https://localhost/dw/Request/example". The options (3) and (9) are not available here. |
|
REST web service |
The Input Agent acts as REST interface. So if like here, the URL of the Input Agent is "https://localhost/dw/Request/example", a request "https://localhost/dw/Request/example/orders" would be accepted as well. The additional request suffix "/orders" would then be stored in system variable MSG_CALL_HTTP_PATH_DATA. Otherwise, the Input Agent behaves in the same way as in mode "HTTP interface", with the additional options (3) and (9).
Another button appears for this option, which opens a dialogue in which you can store sample response files for (8) via the context menu. However, these are only displayed in (8) if checkbox "Show response data" is set there.
See also (9). |
|
SOAP web service |
The Input Agent acts as a SOAP web service. See section SOAP web services. |
(8) 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) 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) The MIME type of the response.
(11) 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) An empty HTTP body (e.g. with POST) is not considered an error.
(13) 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) 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) 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) The HTTP status code returned in case of an error. The button 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) 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) Specification of the mandatory request parameters. See sections " Request procedure" and " Request parameters" below for details.
(19) 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
|
<protocol>://<server>:<port><URL context>/<URL suffix><query> |
|
Placeholder |
Description |
|
<protocol> |
"http" or " https" . See also section " Adding an HTTPS listener" . |
|
<server> and <port> |
Here the DNS name or IP address of the Integration Server and optionally the port number as configured for the HTTP listener and/or HTTPS listener are expected. The default ports ("80" for HTTP and "443" for HTTPS) do not have to be specified. If a firewall provides external access to the inside via port forwarding, the parameters of the external connection must be used when accessing from outside. If a DMZ server is used, the external connections of the DMZ server are valid for access. |
|
<URL context> |
Normally, "/dw/Request" is used when accessing a profile with an event-driven Input Agent "HTTP" and "/dw/trigger" is used to trigger a profile with a time-driven Input Agent. However, these default settings can be modified in configuration file ./etc/startup.xml. <Call name="addServletContext"> |
|
<URL suffix> |
Is configured in the profile in the Input Agent. |
|
<query> |
Here you can specify additional request parameters. Formal structure: "?name1=value1&name2=value2". |
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.
|
HTTP method in request |
Description |
|
GET |
There is normally no body data for a GET request (and if it exists, it is ignored). However, as a profile requires input data, a dummy string is generated for this case. This is generated depending on the document type used in the profile. XML - <body_data/> JSON - {"body": "data"} <all others> - body data |
|
POST |
If the POST request contains body data (normal case), the body data is the input data of the profile. If the POST request does not contain any body data, the behaviour of the profile depends on checkbox (12):
|
|
PUT |
Like "POST". |
|
HEAD |
Like "GET". |
|
DELETE |
If the DELETE request does not contain a body,
If the DELETE request does contain a body,
|
|
PATCH |
Like POST. |
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".
|
http://<URL/IP Integration Server>/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.
|
http://<URL/IP Integration Server>/dw/request/<suffix> |
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.
|
http://<URL/IP Integration Server>/dw/request/example?p1=value1&p2=value2 |
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
Defining mandatory request parameters
You can determine which parameters at least have to be contained in the respective HTTP request. The following screenshot shows an example of how to set the HTTP request parameters.
(1) Name of the HTTP request parameter that must be contained. Note: You can use system constants . Note: If you want to allow multiple values for a parameter, you can create the parameter name multiple times.
(2) If a value is entered in this field, then the affected parameter must have exactly this value in the HTTP request. If the symbol "*" is entered in this field instead of a value, the parameter can have any value. This way, you can specify that the relevant parameter only has to be in the request but does not have to have a specific value. Note: You can use system constants and regular expressions with prefix " regex:" or " regex2:".
The following HTTP requests are accepted in the example.
|
...?param1=value1¶m2=value2¶m3=value3¶m4=value4 |
|
...?param1=value1¶m2=value2¶m3=value3¶m4=valueX |
|
...?param1=value1¶m2=value2¶m3=value3¶m4=valueX¶m5=value5 |
The following HTTP requests are not accepted.
|
...?param1=value1¶m2=value2¶m3=value3 |
|
...?param1=value1¶m2=value2¶m3=valueX¶m4=valueY |
If there are several profiles with the same URL suffix for an incoming HTTP request and an appropriate HTTP request parameter definition, these profiles are equally prepared to accept the request. In this case, the first profile that fits will be used.
Reading HTTP request parameters
You can access the values of HTTP request parameters via variables with the following syntax.
|
MSG_CALL_<name of the parameter in capital letters> |
For example, the parameters "param1" and "param2" of the following HTTP request can be accessed via the variables MSG_CALL_PARAM1 and MSG_CALL_PARAM2.
|
http://192.168.213.64:8080/dw/trigger/example?param1=value1¶m2=value2 |
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.