The following section provides a comprehensive reference for all the predefined HTTP services that are supplied with iWay Service Manager.
Syntax:
com.ibi.agents.XDAddAttachmentFromFileAgent
Description:
This service adds a new attachment with the contents determined by the contents of a file. This service is convenient to provide binary data without first going through a Java character set encoding. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.
There are also four parameters to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets. For example, a valid value for Content-ID might be <cid>. This service follows the OnSuccess edge upon successful execution, otherwise it follows OnError.
Parameters:
Parameter |
Description |
---|---|
Input Data * |
Path to the file that contains the attachment data. |
Content-Type * |
Value of the Content-Type MIME header. |
Content Description |
Value of the Content-Description MIME header. |
Content-Disposition |
Value of the Content-Disposition MIME header. |
Content-ID |
Value of the Content-ID MIME header. |
MIME Header Namespace |
Special register namespace from which additional MIME headers for the attachment are taken. If no value is specified, no MIME headers are added beyond those generated by the header-specific agent parameters. |
Syntax:
com.ibi.agents.XDAddAttachmentAgent
Description:
This service adds a new attachment with the contents determined by the value of a string expression. The Java Character Set parameter specifies how the Java characters in the string are converted to bytes in the body of the attachment. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.
There are also four parameters available to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets. For example, a valid value for Content-ID might be <cid>. This service follows the OnSuccess edge upon successful execution, otherwise it follows OnError.
Parameters:
Parameter |
Description |
---|---|
Input Data * |
An expression that returns the contents of the attachment. |
Java Character Set |
The character set used to convert from Java characters to an array of bytes. If no value is specified, the default character set will be used. |
Content-Type * |
Value of the Content-Type MIME header. |
Content Description |
Value of the Content-Description MIME header. |
Content-Disposition |
Value of the Content-Disposition MIME header. |
Content-ID |
Value of the Content-ID MIME header. |
MIME Header Namespace |
Special register namespace from which additional MIME headers for the attachment are taken. If no value is specified, no MIME headers are added beyond those generated by the header-specific agent parameters. |
Syntax:
com.ibi.agents.XDAttachOps
Description:
This service performs operations on document attachments.
Parameters:
Parameter |
Description |
---|---|
Operation * |
Determines which operation should be performed on this document. Select one of the following options from the drop-down list:
|
Attachment Number |
For operations on a specific attachment, which one, base 0. If a value is specified, this parameter takes precedence over the Content-ID parameter. |
Content-ID |
For operations on a specific attachment, the Content-ID of the attachment. This parameter is ignored if a value for the Attachment Number parameter is specified. Although the specification of the Content-ID header requires the value to be enclosed in angle brackets, you must not use the angle brackets in this property. |
Syntax:
com.ibi.agents.XDAttachmentToDocAgent
Description:
This service finds an attachment and makes it the body of the document. The attachment can be selected by index or by Content-ID. If the Attachment Number is specified, it takes precedence over the Content- ID. The attachment index is base 0. If present, the Content- ID must NOT contain the surrounding angle brackets.
For example, the value cid for the Content-ID parameter will match an attachment with a Content-ID header equal to <cid>. The Header Namespace is the special register namespace where MIME headers for the selected attachment will be stored. The attachment will be stored as bytes if the Keep Document Flat parameter is enabled. Otherwise, the attachment will be parsed as XML. If the attachment is itself a Multipart, then the document will contain the parse of the Main Body Part and the other parts will appear as document attachments.
The MIME headers of the Main Body Part will be saved as registers in the Main Body Part Header Namespace. This is needed to keep them distinct from the Multipart headers. The Delete Attachment parameter determines what to do with the selected attachment when it is not a Multipart: the attachment can be preserved or deleted. This service follows OnSuccess upon successful execution, otherwise, it follows fail_notfound if the attachment cannot be found, or it follows fail_operation if there is another error.
Parameters:
Parameter |
Description |
---|---|
Attachment Number |
The number of the attachment to be retrieved. If specified, it takes precedence over the Content-ID. |
Content-ID |
The Content-ID of the attachment to be retrieved. This value is ignored if the attachment number is specified. |
Header Namespace |
Special register namespace where MIME headers for the selected attachment will be stored. |
Main Body Part Header Namespace |
If the current attachment is itself a Multipart, this is the special register namespace where the MIME headers for the main body part will be stored. |
Keep Document Flat |
Determines whether to keep the body of the document as an array of bytes. This parameter is set to false by default. |
Delete Attachment |
Determines whether to delete the attachment after it becomes the body of the document. This parameter is set to false by default. |
Topics: |
Syntax:
com.ibi.agents.XDCorsAgent
Description:
This service implements the server-side processing of Cross-Origin Resource Sharing (CORS) as described in http://www.w3.org/TR/cors/.
Normally, browsers forbid cross-origin requests for security reasons. CORS specifies a mechanism that allows browsers to make cross-origin requests to resources that opt in to provide access. CORS defines a set of HTTP headers and the rules to process them. Most common browsers implement CORS natively. It is expected that the user agent making the request will be a browser. The CORS service implements the server-side rules to respond to CORS requests received by an nHTTP listener.
If the request is simple (such as GET, HEAD, or POST), then the user agent (for example, the browser) can make the request directly. The user agent adds the Origin header to indicate which site is asking for this resource. The syntax of an origin is:
scheme "://" host [ ":" port ]
The same syntax is used to configure the allowed origins in the service.
If the request is not simple, then the user agent must send a pre-flight request before the actual request to authorize it. The pre-flight request is an OPTIONS request for the same URL. The Access-Control-Request-Method header indicates the method of the actual request (for example, PUT). The optional Access-Control-Request-Headers header indicates which headers will be used in the actual request. Depending on the response of the pre-flight request, the user agent can abort or make the actual request following the same rules as a simple request.
The CORS service analyzes the request, and depending on its configuration, will report one of the following results:
In accordance with the specification, the CORS service adds the CORS response headers only if the request is allowed. The new headers appear as Special Registers (SREGs) in the Response Header Namespace.
The CORS service sets the output document of an OPTIONS request to a zero-length byte array. This will return an empty body with Content-Length equal to 0. This is the most appropriate result, but an application can modify the output document afterwards if necessary. For other requests, the CORS service returns the input document as the output document. Unlike the headers, the output document will be the same irrespective of the actual outcome (allowed, notallowed, or notcompliant).
The nHTTP listener must be configured carefully to make CORS processing possible. The OPTIONS Handling property must be set to event. This instructs the listener to pass the request to the channel instead of responding directly. The Request Header Namespace and the Response Header Namespace must not be none, and they must be different from each other. This makes the request headers available to the CORS service, and allows the response headers be sent with the response. Of course, the Excluded Headers property should not list the CORS headers. The HTTP Response Code must be 200 for a CORS pre-flight response. The Authentication Scheme and the Authentication Realm properties should be considered carefully. CORS is a mechanism used to relax security. It does not replace the need for user credentials to protect sensitive data.
Parameters:
The following table describes the parameters for the Cross-Origin Resource Sharing Service.
Parameter |
Description |
---|---|
Allowed Origins |
List of origins that are allowed access to the resource. Leave empty or enter * to allow all origins. The syntax of an origin is: scheme "://" host [ ":" port ] This property is used to validate the Origin header in the request and influences the value of the Access-Control-Allow-Origin header in the response. The return value of the Access-Control-Allow-Origin header will be * if the Allowed Origins is * and Supports Credentials is false. |
Allowed Methods |
Comma-separated list of HTTP methods that are supported by the resource. Leave empty to allow all methods. This is used to validate the Access-Control-Request-Method header in the pre-flight request and to initialize the Access-Control-Allow-Methods header in the pre-flight response. |
Supported Headers |
Comma-separated list of HTTP header field names that are supported by the resource. Leave empty to claim support for all headers. This is used to validate the Access-Control-Request-Headers header in the pre-flight request and to initialize the Access-Control-Allow-Headers header in the pre-flight response. |
Exposed Headers |
Comma-separated list of HTTP header field names of headers (other than the simple response headers) that the resource might use and can be exposed. This is used to initialize the Access-Control-Expose-Headers header in the response of the actual request. |
Supports Credentials |
Indicates whether the resource supports user credentials in the request. This is used to initialize the Access-Control-Allow-Credentials header in the response. Notice the return value of the Access-Control-Allow-Origin header will never be * for a resource that supports credentials. |
Max Age |
Specifies the amount of seconds the user agent (for example, the browser) is allowed to cache the result of the pre-flight request. The value 0 means unbounded. This is used to initialize the Access-Control-Max-Age header in the response of the pre-flight request. |
Edges:
The edges returned are described in the following table.
Edge |
Description |
---|---|
success |
The message was successfully analyzed. The cors Special Register contains the result. |
fail_parse |
An iFL expression could not be evaluated. |
fail_operation |
The service is not executing a request received by an nHTTP listener. |
Special Registers:
The following table describes the Special Register (SREG) that is assigned upon a successful execution.
Special Register |
Description |
---|---|
cors |
The outcome of analyzing the request. This will be one of the following values:
Note: These values are lowercase and do not contain any spaces. |
The following examples show the result of executing the Cross-Origin Resource Sharing Service on various HTTP requests. The following table lists the parameter values for the Cross-Origin Resource Sharing Service that are used by the examples.
Parameter |
Value |
---|---|
Allowed Origins |
http://host1.com http://host2.com:8080 |
Allowed Methods |
GET,POST |
Supported Headers |
ReqHdr1,ReqHdr2,ReqHdr3 |
Exposed Headers |
RespHdr1,RespHdr2 |
Supports Credentials |
true |
Max Age |
30 |
Example 1
This HTTP request is missing the Origin header. When analyzing this request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com
Example 2
Since the Allowed Origins is not empty or *, the origin must match exactly one of the listed origins. When analyzing this request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host.com
Example 3
When analyzing this request, the service would set the cors Special Register to allowed and return success. The output document is the input document.
GET /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.com Access-Control-Expose-Headers: RespHdr1,RespHdr2 Access-Control-Allow-Credentials: true
Example 4
This pre-flight request is missing the Access-Control-Request-Method header. When analyzing this pre-flight request, the service would set the cors Special Register to notcompliant and return success. No response headers would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com
Example 5
The actual request method HEAD is not allowed. When analyzing this pre-flight request, the service would set the cors Special Register to notallowed and return success. No response headers would be added. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: HEAD
Example 6
The header names in Access-Control-Request-Headers are all supported headers. When analyzing this pre-flight request, the service would set the cors Special Register to allowed and return success. The output document is a zero-length byte array.
OPTIONS /app/page1 HTTP/1.1 Host: example.com Origin: http://host1.com Access-Control-Request-Method: GET Access-Control-Request-Headers: ReqHdr1,ReqHdr2
The following response headers will be added:
Access-Control-Allow-Origin: http://host1.com Access-Control-Allow-Methods: GET,POST Access-Control-Allow-Headers: ReqHdr1,ReqHdr2,ReqHdr3 Access-Control-Allow-Credentials: true Access-Control-Max-Age: 30
Syntax:
com.ibi.agents.XDAttachmentFromDocAgent
Description:
This service adds a new attachment with the contents determined by the input document. The attachment headers are specified with user parameters. The name and value of the user parameter become the name and value of the header. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets.
For example, a valid value for Content-ID might be <cid>. The Attachment Type parameter specifies the attachment Content-Type. If the Attachment Type is omitted, a Content-Type is chosen based on the document data:
The optional Attachment Name parameter controls the name sub-parameter of the Content-Type header. The Content-Type name can also be given directly in the Content-Type header value if desired.
The Body Result parameter specifies what to return in the output document: keep copies the input document to the output document, empty returns an empty document instead. This service follows OnSuccess upon successful execution, otherwise it follows the fail_attach edge.
Parameters:
Parameter |
Description |
---|---|
Attachment Name |
The name of this attachment, for example, file name. |
Attachment Type |
The MIME type. If no value is specified, the attachment type is generated based on the data format. |
Body Result |
Specify how to handle the body of this document by selecting one of the following values from the drop-down list:
|
Syntax:
com.ibi.agents.XDCookieAgent
Description:
This service adds a cookie to the HTTP responses, enabling them to retain stateful information.
Parameters:
Parameter |
Description |
---|---|
Cookie Name (required) |
The name of the cookie. |
Cookie Value |
The value of the cookie, which must comply with RFC 6265. |
Path Attribute |
Value of the Path attribute in the generated cookie. The value / matches any path. |
Domain Attribute |
Value of the domain attribute in the generated cookie. Leave empty to match the originating server. |
Max-Age Attribute |
Value of the Max-Age attribute in the generated cookie. This indicates the maximum lifetime of the cookie, represented as a number of seconds. Leave blank to omit the attribute which lets the user agent determine when the cookie expires. |
Secure Attribute |
Whether to add the Secure attribute in the generated cookie. Automatically adds the attribute if the listener is secure. Select one of the following options from the drop-down list:
|
HTTPOnly Attribute |
Whether to add the HttpOnly attribute in the generated cookie.
|
Syntax:
com.ibi.agents.XDHTTPEmitAgent
Description:
This service is a general HTTP emitter for use within the service stack. The document is posted using HTTP to a designated server.
Parameters:
Parameter |
Description |
---|---|
Configuration Parameters for HTTP Emit Agent Service |
|
Target URL (required) |
Specify a URL to post this information. |
Action Method |
Select one of the following methods from the drop-down list:
|
Request content type |
This overrides content type of a request. Select one of the following options from the drop-down list:
|
User ID |
User ID for Basic Authentication challenges. |
Password |
Password for Basic Authentication challenges. |
Response timeout value in seconds |
Seconds to wait for response before signaling error. |
IP Interface Host |
Local IP Interface from which the outgoing IP socket originates. |
IP Interface Port |
Local IP Port from which the outgoing IP socket originates. |
Relay Inbound Content Type |
If set to true, relay headers as received (content type). False is the default. |
Set TCP No Delay |
If set to true, disables Nagle's Algorithm on the client socket. This will result in faster line turnaround at the expense of an increased number of packets. |
Proxy |
|
Proxy |
If set to true, emit through proxy server. False is the default. |
Proxy URL |
URL of the proxy server. |
Proxy User ID |
User ID for proxy challenges. |
Proxy Password |
Password to access the proxy server. |
HTTPS |
|
Secure Connection |
True to use a secure connection. You may need to configure the Keystore under HTTPS section of the system properties if client authentication is required. Note, if keystore is configured in system properties make sure it has the CA certificate or the client certificate of the server you're connecting to. If keystore is not configured in system properties default truststore located under JRE_HOME/lib/security/cacerts will be used. False is the default. |
Use 128-bit Encryption |
True to use 128-bit encryption. False is the default. |
Security Protocol |
Select one of the following security protocols from the drop-down list:
|
Agent Specific Parameters |
|
Return (required) |
Return from this agent. Select one of the following options from the drop-down list:
|
Use Preemitters |
If set to true, preemitters will be used for this emit. True is the default. |
Response Wrapper Tag |
The tag name with which to wrap the response if the response is non-XML and must be XML |
Response Base64 Encoded |
If set to true, the response will be Base64 encoded. Falseis the default. |
Response Data Format |
Format of the response, default is XML
|
The result of the post appears in the <native> section of the <emitstatus> result. If the Return parameter value is STATUS, the status message is always generated. If it is RESPONSE (the default) the actual information returned from the POST is emitted, except in the cases of an error in which case the status information is emitted. The POST is considered successful if the POST can reach its destination and a 200 status is received. A successful return response is considered to be XML if the first character is a <. Otherwise, a flat document is created.
Example:
The following is an example of configuration settings for an HTTP Emit service object in iIT Designer:
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener as the inlet and a File emitter as the outlet to examine the messages that are received by the listener. Your HTTP listener configuration settings would look similar to the following example, where an HTTP port and a document root are specified.
After you deploy and start the channel with the HTTP listener and File emitter, you can test run your process flow, which contains an HTTP Emit service object. You must supply an incoming document with the appropriate content (for example, HTML):
<html> <head> <title>my iWay http</title> </head> <body> Testing HTTP Emit Service! </body> </html>
If the service runs successfully, you will receive this HTML document in the output folder that is specified by your File emitter. The HTTP listener channel picks up the document that is emitted by the HTTP Emit service.
Syntax:
com.ibi.agents.XDNHttpEmitAgent
Description:
Emits nHTTP messages to a client without interrupting a configured business process. For more information, see the iWay Service Manager Protocol Guide.
Parameters:
Parameter |
Description |
---|---|
Configuration Parameters |
|
Target URL (required) |
URL that is used to post this information. |
HTTP Client Provider (required) |
HTTP client Provider that is used to manage connections for this emitter. |
Cookie Store Name |
Allows thread-specific management of cookies. If not specified, a cookie store global to the HTTP Client provider will be used. |
Action Method |
Select one of the following supported methods from the drop-down list:
|
Request Content Type |
Overrides content type of response. Select one of the following options from the drop-down list:
|
User ID |
User ID for Basic Authentication challenges. |
Password |
Password for Basic Authentication challenges. |
Domain |
Domain for NTLM authentication challenges. Note that to use NTLM, you must enable connection persistence. |
Request Header Namespace |
Special register namespace from which HTTP headers for the outgoing request will be taken. Choose Default Namespace to send HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
|
Request Main Part Header Namespace |
Special register namespace from which MIME headers for the outgoing request will be taken. Provide a prefix to control the request Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers. |
Response Header Namespace |
Special register namespace into which HTTP headers from the incoming response will be saved. Choose Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be created.
|
Excluded Headers |
A comma delimited list (case insensitive) of headers that should not be sent with the request, even if they are found in the request header namespace. |
Ask for Compressed Response |
If set, requests will set the Accept-Encoding header to indicate that that the client can accept a compressed response, as described in RFC-2616. If the response has a compressed content encoding, the client will automatically inflate.
|
Compress Request |
If set, the request entities will be compressed using the selected encoding and the content-encoding header will be set accordingly.
|
Release Connection Immediately |
If set to true, then the connection will be released to the connection pool immediately. This is the default. If set to false, then the connection identifier is stored in the httpclient-key special register and the HTTP Client Manager agent must be called later to release the connection explicitly. The main reason to retain the connection is to reuse it for streaming of other services. |
Maximum HTTP Client Manager Delay |
Maximum time the HTTP Client Manager can take to handle a particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds. |
Try Expect/Continue Handshake? |
If set to true, the client will send the HTTP Expect: 100-continue header and await HTTP 100 response before sending the request body. The default is false. |
Chunk Encoded Request? |
If set to true, request entity will be sent with chunk encoding. The default is false. |
Maximum Request Size |
Maximum size, after compression, of a request entity that can be sent with this emitter. A value of 0 means no maximum and if no value is specified, the parameter defaults to 256KB. |
Maximum Response Size |
Maximum size of a response entity that can be received by this emitter. 0 means no maximum and blank will default to 256KB. |
TCP Properties |
|
Persistence |
If set to true, ask the server to maintain the connection. The default is false. |
Response Timeout value in Seconds (required) |
The value in seconds to wait for a response before generating an error. |
Agent Specific Parameters |
|
Return (required) |
URL to post this information to, for example, http://thehost:9876. Choose:
|
Preemitter |
If set to true, (default) the preemitters will not run. |
Response Wrapper Tag |
The tag name with which to wrap the response if the response is non-XML and must be XML. |
Response Base64 Encoded |
If set to true, the response will use Base64 encoding. False is the default. |
Syntax:
com.ibi.agents.XDHTTPReadAgent
Description:
This service reads an HTTP source using HTTP GET and returns a result. The GET facility input accepts a URL in the incoming document and issues an HTTP GET through that URL. The transform business service and standard output can accept and operate upon this output. It is presumed that some output is returned, otherwise an error is generated.
In a use case scenario, the HTTP Read service can be part of an architecture for a web search engine, similar to the Google search engine. The service could be used to traverse or spider the contents of webpages for indexing purposes.
Parameters:
Parameter |
Description |
---|---|
URL Tag Name |
TTag (element) name in input document containing the URL. Do not use if URL parm is used. |
URL |
URL for the read. Used if the tag (element) name is omitted |
Access Timeout |
Timeout in milliseconds for the access; applies if greater than 0. |
The input document might be the following assuming that the tagname parameter is set to inurl:
<?xml version="1.0"?> <inurl>http://localhost:1234/xmlone.xml</inurl>
Example:
The following is an example of configuration settings for an HTTP Read service object in iIT Designer:
A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener. Your HTTP listener configuration settings would look similar to the following example, where an HTTP port and a document root are specified.
After you deploy and start the channel with the HTTP listener, you can test run your process flow, which contains an HTTP Read service object. You must ensure that the file name you supply within the <Test> tag of your incoming document is valid and is also contained within the document root folder specified for your HTTP listener configuration settings. A sample HTTP read incoming document can have the following format:
<Test>http://localhost:1234/index1.htm</Test>
If the service ran successfully, you will receive the contents of index1.hml as the output from the service. For example:
Syntax:
com.ibi.agents.XDReSTRouteAgent
com.ibi.agents.XDReSTRouteReviewer
iIT Service Object:
http: HTTP ReST Routing Service
Description:
This service routes a Representational State Transfer (ReST) request to a process flow based on the request method and path. An HTTP ReST Routing Reviewer (com.ibi.reviewer.XDReSTRouteReviewer) is also provided, which shares the same parameters as the service.
The main purpose of these components is to identify a process flow to execute, given a URI path and the type of the HTTP request. The name of the process flow will be stored in a special register (SREG). In addition to this routing function, some elements in the URI path, and all keys and values in the URI query string, will be stored as SREGs. This functionality will be made available as a service for use within a process flow, but also as a reviewer. This allows for earlier execution in the processing stage to allow conditional routing to handle the execution of the identified process flow.
The service uses an XML document whose structure corresponds to the elements in the path. This XML document has the following structure:
<route> <verb type="GET"> <step type="literal" value="master"> <step type="literal" value="vendor"> <step type="regex" value="[0-9]+" flow="vendorRequest" sreg="true"> <step type="literal" value="item" flow="vendorAllItemsRequest"> <step type="regex" value="[0-9]+" flow="vendorItemRequest" sreg="true"> <sreg name="extrareg1" value="something"/> <sreg name="extrareg2" value="somethingelse"/> <step type="literal" value="allproperties" flow="vendorItemAllProperties"/> </step> <step type="default" flow="VendorItemUnknownRequest"/> </step> </step> </step> <step type="default" flow="UnknownMasterRequest"/> </step> </verb> </route>
A schema will follow for this XML document.
In this section, the individual components of the URI path are called path elements and the <step> elements in the XML document are called steps.
Each step can match a path element. How a step is matched to a path element depends on its type (as indicated by the type attribute of the step element).
The search process starts at the verb node that corresponds to the type of the HTTP request. For the first element in the path, each step child node of the verb node is checked to see if it matches the path element. The first step that matches is taken. This is repeated for the second path element, looking at the step children of the first step, and so on, until the final path element is reached.
Note: The order of step nodes in the routing XML document is very important.
Consider the following example, which shows a path element "1234" and two step nodes:
<step type="regex" value="[0-9]+" flow="generalIntRequest"/> <step type="literal" value="1234" flow="specific1234Request"/>
In this scenario, the regex step is always taken, since it is seen first and also matches 1234, even though the literal step is an exact match.
If a step has the sreg attribute set to true, a Special Register (SREG) will be created using the previous path element as the SREG name and the current path element as the SREG value.
When the final path element is reached, the value of the flow attribute for the last step found is the name of the process flow to be executed. If, for any path element, no matching step can be found, the service will return the fail_notfound edge.
For example, using the document above, consider that the following URI is provided:
/master/vendor/1428/item/2345/allproperties
In this scenario, the target register is set to vendorItemAllProperties and the following SREGs are set:
Additional SREGs to set for the final step can be specified by adding <sreg> nodes as children of the step node. For example, consider the following URI:
/master/vendor/1234/item/2345
The target register would be set to vendorItemRequest, the SREGs as shown above, and the following additional SREGs would be set:
If the incoming URI includes a query string, the service will store the key-value pairs in the query string as SREGs. Query string parameters will not be used in the route search.
To facilitate debugging, the XML schema will include two additional attributes:
Step Attributes:
Attribute |
Description |
---|---|
type |
The type of attribute value:
|
value |
A compare value of type in the type attribute. |
flow |
Name of a process flow if this is the final step (iFL allowed). |
sreg |
If true, then a Special Register (SREG) will be created using the value of the previous path element as the key and this value of the current path element as the register value. |
role |
The user must have this role to descend on this step. |
name |
A node name used in tracing. |
Inputs:
The service is agnostic as to the input. The service operates on the incoming URL.
Outputs:
If a process flow is found for this path, then the input will be output. In any other case, the output will either be the input document or an iSM status/error document, as determined by the Output Type parameter for this service.
Parameters:
Parameter |
Description |
---|---|
Route File Path (required) |
The path to the XML file describing the route. The file is loaded when the service is first executed and remains in effect until the listener is restarted. |
ReST Verb (required) |
The HTTP verb (DELETE, GET, POST, or PUT). In nHTTP this is in the SREG called reqType. |
URI (required) |
The URI of the incoming HTTP request. In nHTTP, this is stored in the SREG called url. This may include a path and a query string. Note: This is slightly different from the Object parameter in the prototype service. |
Flow Name Register (required) |
An SREG of this name will be created with the name of the process flow to run. |
Route Namespace |
SREG namespace prefix to use when creating SREGs from path steps, including the process flow name register. Applies to the routing portion of the URL. |
Query Namespace |
SREG namespace prefix to use when creating SREGs from the query string portion of the URL. Defaults to the same as the Route Namespace. Using a separate namespace can allow these registers to be passed and managed as a group. |
Output Type |
Determines in the event of a routing error, what document should be output from this service. Select one of the following document types:
|
Edges:
Parameter |
Description |
---|---|
Success |
A process flow was located. |
fail_notfound |
No process flow was located. |
fail_parse |
Unable to process configuration parameters, which is most likely an iFL error. |
fail_route |
Other failure specific to this agent (for example, unable to locate or parse the routing file). |
fail_security |
A role does not match, meaning that this user is not permitted to use this URL (security trigger flow runs in iSM Version 6.1.9). |
ReST Process Flow Message:
When a non-POST verb in encountered by nHTTP, a default message is generated. The schema for this message is located in the following directory:
<iwayhome>/etc/manager/extensions/iwxnhttp/misc/doc
From time to time, iWay Software may add additional, non-conflicting elements to this schema in future releases.
The input document to the process flow holds the parsed information from the arriving HRRP input, including all headers and the URL split up for use.
For example (spacing for display purposes only):
<http user="auto" type="GET"> <parms> <parm name="ibse-port">9000</parm> <parm name="Host">clientbox:10000</parm> <parm name="Connection">Keep-Alive</parm> <parm name="pdm">0</parm> <parm name="version">1.1</parm> <parm name="Accept-Language">en-AU</parm> <parm name="action">user.req?user=999999999&account=1234567890123456&tranid=tid1234</parm> <parm name="Accept">text/html, application/xhtml+xml, */*</parm> <parm name="User-Agent">Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)</parm> <parm name="url">/user.req?user=999999999&account=1234567890123456&tranid=tid1234</parm>
<parm name="ip">127.0.0.1</parm> <parm name="source">hostname unknown</parm> <parm name="Accept-Encoding">gzip, deflate</parm> <parm name="reqType">GET</parm> </parms> <body /> <url secure="false"> <host>clientbox</host> <port>10000</port> <path>/user.req</path> <query>user=999999999&account=1234567890123456&tranid=tid1234</query> <queryparms> <parm name="user">99999999</parm> <parm name="account">1234567890123456</parm> <parm name="tranid">tid1234</parm> </queryparms> <incomingurl> http:clientbox:1000/user=999999999&account=1234567890123456&tranid=tid1234 </incomingurl> </url> <version>1.1</version> </http>
Using an XML iterator, the process flow can easily step through the <queryparms>, or using standard XSLT, can extract a specific URI value as required. All registers set in the channel are housed in the <http/parms> elements and can be extracted if required.
The user (source of the message) can be authenticated using standard nHTTP services, avoiding the need to do so within the executing process flow.
iWay Functional Language (iFL) Support:
The iFL language used within iSM provides facilities to support RESTful services. Key functions for this support are listed and described in the following table:
Function |
Description |
---|---|
_urlparse() |
Parses a URL into its component parts, including searching for specific keywords in the query section of the URI. |
_token() |
Enables extraction of specific portions of the URI as required. |
The information extracted by the iFL is represented in the incoming document. The iFL simply makes it possible to look at the URL directly.
For more information on _urlparse() and _token(), see the iWay Functional Language Reference Guide.
Route Step XML Schema Document:
<?xml version="1.0" encoding="UTF-8"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.iwaysoftware.com/RouteStep" xmlns:tns="http://www.iwaysoftware.com/RouteStep" elementFormDefault="qualified"> <complexType name="sregType"> <annotation> <documentation> Represents a special register to create if its parent step matches the last path element. </documentation> </annotation> <attribute name="name" type="string" use="required"></attribute> <attribute name="value" type="string" use="required"></attribute> </complexType> <complexType name="stepType"> <annotation> <documentation> Represents one step in the URI path for looking up the route. The lookup process attempts to match elements in the path to steps. </documentation> </annotation> <choice minOccurs="0" maxOccurs="unbounded"> <element name="sreg" type="tns:sregType"/> <element name="step" type="tns:stepType"/> </choice> <attribute name="type" use="required"> <simpleType> <restriction base="string"> <enumeration value="literal"></enumeration> <enumeration value="ci_literal"></enumeration> <enumeration value="regex"></enumeration> <enumeration value="default"></enumeration> </restriction> </simpleType> </attribute> <attribute name="value" type="string" use="optional"> <annotation> <documentation> When type is 'literal', the value attribute holds a literal that must match the path element. Type "ci_literal" is similiar, but ignores case when matching the path element. When type is 'regex', this attribute holds a regular expression to match the path element. When type is 'default', this attribute is not used. </documentation> </annotation>
</attribute> <attribute name="flow" type="string" use="optional"> <annotation> <documentation> The flow to run for this URI path. Will be set into the target special register. </documentation> </annotation> </attribute> <attribute name="sreg" type="boolean"> <annotation> <documentation> If true, the value of this path element will be saved as a special register, with key as the value of the previous path element. </documentation> </annotation> </attribute> <attribute name="name" type="string" use="optional"> <annotation> <documentation> Use the name attribute to identify this step in debug tracing. </documentation> </annotation> </attribute> <attribute name="role" type="string" use="optional"> <annotation> <documentation> Optionally, the role required to the flow that would be run if this were the final element in the URI path. Assumes that the user has been authenticated by an iSM auth realm. </documentation> </annotation></attribute> </complexType> <complexType name="verbType"> <annotation> <documentation>Matches the ReST verb or HTTP method for the current request.</documentation> </annotation> <sequence> <element name="step" type="tns:stepType" minOccurs="1" maxOccurs="unbounded"></element> </sequence> <attribute name="type" use="required"> <simpleType> <restriction base="string"> <enumeration value="GET"></enumeration> <enumeration value="POST"></enumeration> <enumeration value="PUT"></enumeration> <enumeration value="DELETE"></enumeration> </restriction> </simpleType> </attribute> </complexType> <complexType name="routeType"> <sequence> <element name="verb" type="tns:verbType" minOccurs="1" maxOccurs="4"></element> </sequence> <attribute name="verbose" type="boolean" use="optional"></attribute> </complexType> <element name="route" type="tns:routeType"></element> </schema>
This service is used to terminate the session. The following table lists and describes its parameter.
Parameter |
Description |
---|---|
Expire Cookie |
Determines how the termination is to be effected. If set to false, it removes the session information from the server. No further action is taken. If set to true, in addition to removing the session information, it sends an instruction to the client to delete the JSESSIONID cookie itself. |
The service returns the input document on the success edge.
As a good practice, you can use this service when the application has completed the session, so as to reduce server resources.
Syntax:
com.ibi.agents.XDOAuth1Agent
Description:
This service creates the HTTP Authorization header for OAuth 1.0a as specified in RFC5849. This RFC describes a 3-legged protocol where the user authorizes the client application to access a protected resource hosted by a service provider.
The OAuth 1.0 Authentication supports a variant called the 0-legged protocol where the request is signed without the user credentials. The signature is computed using just the consumer key and the consumer secret. These credentials are obtained once when the application programmer registers his client application with the service provider during development. This service assumes the consumer secret is a private key.
Parameters:
The following table lists and describes the parameters for the OAuth 1.0 Authentication service.
Parameter |
Description |
---|---|
HTTPS URL |
Request URL used in the computation of the Signature Base String. |
HTTP Method |
HTTP Method used in the computation of the Signature Base String. Selecting POST will also cause the current document to be hashed to produce the oauth_body_hash. |
Header Namespace |
Special register namespace where the Authorization HTTP header is stored. If not supplied, the default namespace will be used. |
Client ID |
The consumer key of the client credentials. |
KeyStore Provider |
Provider for the keystore containing the client private key. |
Private Key Alias |
Alias of the private key within the keystore. |
Private Key Password |
Password for the private key. If left blank, the password for accessing the keystore will be used. |
The OAuth Authentication service only creates the Authorization header. The HTTP request must be sent in a separate step, usually with the NHTTP Emit service.
The HTTPS URL and HTTP Method parameters are used in the Signature Base String. They must match the Target URL and Action Method of the NHTTP Emit service. The URL scheme must be HTTPS because an SSL connection is needed to protect the information that is passed in clear. Choosing the POST method also instructs the service to compute a hash of the entity body to be part of the signature. This algorithm was specified by Google in its OAuth Request Body Hash extension.
The Authorization header will be stored in the specified Header Namespace. This parameter should match the Request Header Namespace in the NHTTP Emit Agent. This will ensure that the header is sent with the request. It is possible to use different namespaces, as long as the Authorization register is copied to the Request Header Namespace before the request is sent.
The Client ID is the consumer key supplied by the service provider when the developer registered the client application with the service provider. This serves as the user name for the client application. The service provider uses the client ID to retrieve the public key to validate the signature.
The KeyStore Provider is the name of the provider that holds the client private key. The Private Key Alias and Private Key Password are the Alias and Password for the private key. This key is used as the consumer secret when signing the Authorization header.
The output document is the same as the input document.
For the POST method, the document contains the same data but it will be stored as bytes if it was not already. This is to guarantee the document will not be altered before it is sent because any change to the document would invalidate the signature.
Edges:
The following table lists and describes the edges that are returned by the OAuth Authentication service.
Edge |
Description |
---|---|
success |
The Authorization header was successfully created. |
fail_parse |
An iFL expression could not be evaluated. |
fail_operation |
The operation could not be completed successfully. |
Example 1
This example shows the creation of an OAuth 1.0a Authorization header for a GET method. The following table lists the parameter values for the service.
Parameter |
Value |
---|---|
HTTPS URL |
|
HTTP Method |
GET |
Header Namespace |
hdrns |
Client ID |
DKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G 3a14KmEa7f96b5e!414a78536b4a6f6272634a41446e 4566483851625a7a413d |
KeyStore Provider |
keyprov |
Private Key Alias |
key1 |
Private Key Password |
key1pass |
This assumes key1 is the alias of a private key entry in the KeyStore provider keyprov. The service will compute the following Signature Base String. The oauth_nonce and oauth_timestamp will obviously change each time the service executes.
GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fatms%2Fv1%2Fat m&Country%3DUSA%26Format%3DXML%26PageLength%3D10%26PageOffset%3D0 %26PostalCode%3D46312%26oauth_consumer_key%3DDKB0vGSHs4r1Vv308yObMj4QhhJ kIMP5G3a14KmEa7f96b5e%2521414a78536b4a6f6272634a41446e4566483851625a7a41 3d%26oauth_nonce%3D180284899533025%26oauth_signature_method%3DRSA SHA1%26oauth_timestamp%3D1396020436%26oauth_version%3D1.0
The service will store the following header value in the hdrns. Authorization special register. The oauth_signature changes every time the service is executed because the oauth_nonce and oauth_timestemp varies.
OAuth oauth_signature="JjBI1gi5EMHwcihnCyK0RX7UzCC2SCtplutEjUgUXaI2nhGd4IR3L7b WMtpJKkyUnR667lpkI7zqbM3oR3CHc2%2FgxPerD%2FSDGibHTAcTHCfV9%2F0xBVzv%2Fzo 1egU4CEqjZGSeIAeJKQYOflKSrfX8ken0MsXwXv5s9TLQuO8pRPwCfrqgrmVa%2FHhlzRxU7 pEv2kpJn4opG3Cvn01aKlotztxG8u476aEydFq03emqjVh8GMArtGDt8RhJqisJ0OB9SsaWU K%2FsV%2BQtvghmX7G0pyQ6hLJUa3NSqlINU2k19cLOhUEnylDVD62sTZGrPe9%2B3zKLj%2 BX77eGLFKrDqOxk9w%3D%3D",oauth_version="1.0",oauth_nonce="18028489953302 5",oauth_signature_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv30 8yObMj4QhhJkIMP5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e456648385 1625a7a413d",oauth_timestamp=" 1396020436"
If the Request Header Namespace is hdrns in the NHTTP Emit service, this will add the following HTTP header to the HTTP request.
Authorization: OAuth oauth_signature="JjBI1gi5EMHwcihnCyK0RX7UzCC2SCtplutEjUgUXaI2nhGd4IR3L7b WMtpJKkyUnR667lpkI7zqbM3oR3CHc2%2FgxPerD%2FSDGibHTAcTHCfV9%2F0xBVzv%2Fzo 1egU4CEqjZGSeIAeJKQYOflKSrfX8ken0MsXwXv5s9TLQuO8pRPwCfrqgrmVa%2FHhlzRxU7 pEv2kpJn4opG3Cvn01aKlotztxG8u476aEydFq03emqjVh8GMArtGDt8RhJqisJ0OB9SsaWU K%2FsV%2BQtvghmX7G0pyQ6hLJUa3NSqlINU2k19cLOhUEnylDVD62sTZGrPe9%2B3zKLj%2 BX77eGLFKrDqOxk9w%3D%3D",oauth_version="1.0",oauth_nonce="18028489953302 5",oauth_signature_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv30 8yObMj4QhhJkIMP5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e456648385 1625a7a413d",oauth_timestamp="1396020436"
Example 2
This example shows the creation of an OAuth 1.0a Authorization header for a POST method. The following table lists the parameter values for the service.
Parameter |
Value |
---|---|
HTTPS URL |
|
HTTP Method |
POST |
Header Namespace |
hdrns |
Client ID |
DKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G3 a14KmEa7f96b5e!414a78536b4a6f6272634a41446e4 566483851625a7a413d |
KeyStore Provider |
keyprov |
Private Key Alias |
key1 |
Private Key Password |
key1pass |
The following input document is the parsed XML document:
<ns2:TerminationInquiryRequest xmlns:ns2="http://mastercard.com/termination"><AcquirerId>1996 </AcquirerId><TransactionReferenceNumber>1</TransactionReferenceNumber> <Merchant><Name>TEST</Name><DoingBusinessAsName>TEST </DoingBusinessAsName><PhoneNumber>5555555555</PhoneNumber> <NationalTaxId>1234567890</NationalTaxId><Address><Line1>5555 Test Lane </Line1><City>TEST</City><CountrySubdivision>XX</CountrySubdivision> <PostalCode>12345</PostalCode><Country>USA</Country></Address> <Principal><FirstName>John</FirstName><LastName>Smith</LastName> <NationalId>1234567890</NationalId><PhoneNumber>5555555555</PhoneNumber> <Address><Line1>5555 TestLane</Line1><City>TEST</City><CountrySubdivision>XX </CountrySubdivision><PostalCode>12345</PostalCode><Country>USA </Country></Address><DriversLicense><Number>1234567890</Number> <CountrySubdivision>XX</CountrySubdivision></DriversLicense></Principal> </Merchant></ns2:TerminationInquiryRequest>
The service will compute the following Signature Base String. Notice the extra attribute oauth_body_hash compared to Example 1.
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Ffraud% 2Fmerchant%2Fv1%2Fterminationinquiry&Format%3DXML%26PageLength%3D10% 26PageOffset%3D0%26oauth_body_hash%3Dh3%252BhLMkT%252B3pBvRolKEc95fobEB8 %253D%26oauth_consumer_key%3DDKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G3a14KmEa7f 96b5e%2521414a78536b4a6f6272634a41446e4566483851625a7a413d%26oauth_nonce %3D180286176383600%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp %3D1396020438%26oauth_version%3D1.0
The service will store the following header value in the hdrns Authorization special register. The oauth_signature, oauth_nonce, and oauth_timestamp will change every time the service is executed.
OAuth oauth_signature="GSgJ6wUiYDznurpspn2ztn9PZeuXIBy4LZZHOSuMQrQ8OskwdWdaX0i UXfNELxEQUniy6z5b2c06yVCut4XoYtV5XJaYnoG78bqkJ3LLVBqZ%2Brv%2F%2FTbIQmz0c enMAinlR09QeduIHV7gPGqd%2FBi9Rkj%2BHnxI5bLNGn0nQoOie%2BSNUAPCjnn2Ydoj44l Sufmur6N2U7paJAuEIfp3VANbLwCI%2Bts5EBr3ecCn7eEqbuQMzs8hW2c%2FdzZqoOvyEda O86SVcTX9vT5XI8V%2FRluupobCRy8xSuxubnCJrf5USfT%2FB5rudqNkHW0%2BmtE8hxVLI L9v2dKPSRxtqsU75GsrgA%3D%3D",oauth_body_hash="h3%2BhLMkT%2B3pBvRolKEc95f obEB8%3D",oauth_version="1.0",oauth_nonce="180286176383600",oauth_signat ure_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv308yObMj4QhhJkIMP 5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e4566483851625a7a413d", oauth_timestamp="1396020438"
The output document is the same as the input but the data is now stored as bytes.
If the Request Header Namespace is hdrns in the NHTTP Emit service, this will add an Authorization header to the HTTP request.
Syntax:
com.ibi.agents.XDOAuth2Agent
Description:
This service emits an HTTPS request authenticated by OAuth 2.0 using the credentials of a Google service account.
OAuth 2.0 is described in RFC6749 and RFC6750. It is an authorization framework that enables an application to obtain access to an HTTP resource. The role of the client and the resource owner are separate. The client does not use the resource owner credentials. Instead, it requests an access token from a trusted authorization server. The client presents the token together with the request to the resource server which grants access if the token is valid.
The OAuth 2.0 Authentication service manages the creation and renewal of access tokens by communicating with the authorization server. If it obtains a valid access token, it incorporates the token with the outgoing HTTPS request to make the authenticated call.
When OAuth 2.0 is used interactively, the user is often redirected to a consent screen to enter his credentials. Since the iSM service operates in a server-to-server scenario, there is no consent screen involved. Instead, the client provides its credentials with the private key associated with a Google service account. The authorization server will be accessed at the same location as the resource server.
When obtaining a token, the client must specify the scope of the access requested. For example, there could be a scope for read-only and another for read-write permissions. It is also possible to request multiple scopes in a single access token.
The scopes are not standardized. The resource servers are free to define the scopes that make sense for their application. The documentation of the resource server API will make it clear which OAuth 2.0 scopes it supports. It remains the responsibility of the application designer to request and use the appropriate scopes.
Parameters:
The following table lists and describes the parameters for the OAuth 2.0 Authentication service.
Parameter |
Description |
---|---|
HTTP Client Provider |
HTTP Client provider that manages connections for this emitter. |
Destination URL |
URL where the request will be addressed. The URL should be fully specified, including the HTTPS scheme. |
HTTP Method |
POST sends the current document as a request entity. GET and HEAD will send a request to the configured URL. |
Content Type |
Content type for the HTTP request to be sent by this emitter. |
Request Header Namespace |
Special register namespace from which HTTP headers for the outgoing request will be taken. Select Default Namespace to send the HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers. |
Response Header Namespace |
Special register namespace into which HTTP headers from the incoming response will be saved. Select Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here. |
Scopes |
Determines which services the application requests access to. Select one from the list or enter a space-separated list of scopes. |
Project ID |
Value of the x-goog-project-id header. |
Service Account Email |
Email address of the service account. |
KeyStore Provider |
Provider for the keystore containing the service account private key. |
Private Key Alias |
Alias of the service account private key within the keystore. |
Private Key Password |
Password for the private key. If left blank, the password for accessing the keystore will be used. |
The HTTP Client provider can be defined on the pooling providers page in the iWay Service Manager console. Google recommends that OAuth 2.0 should always be used with HTTPS, therefore the HTTP Client provider should specify an SSLContext Provider.
The authenticated request will be sent to the Destination URL. The service will access the authorization server at the same location to obtain access tokens. The HTTP method specifies the type of request: GET, PUT, POST, HEAD, PATCH or DELETE. The Content Type parameter specifies the content type of the authenticated request.
If additional headers are needed, they can be declared as HDR registers in the Request Header Namespace. The default value is none, which means there is no Request Header Namespace and no extra headers are added.
The headers of the HTTP response are stored as special registers in the specified Response Header Namespace.
The Scopes parameter specifies the access scope requested from the authorization server. The access token returned will grant those scopes. For example, if the scope in the token is read-only-access and a write operation is attempted, the resource server will reject the call because the scope is not sufficient. The scopes are application specific. For more information, see the resource server API documentation to learn which scopes it supports.
The Project ID is optional. When present, it specifies the value of the x-goog-project-id header. In the cloud platform of Google, a Project consists of a set of users, a set of APIs, and billing, authentication, and monitoring settings for those APIs.
The Service Account Email acts like a user name for a service account. It looks like an email address but there is no actual email involved. The credential for the service account is a private key. The KeyStore Provider is the name of the iSM keystore provider that holds the private key. The Private Key Alias and the Private Key Password are the alias and password of the private key entry within the Keystore.
Edges:
The following table describes the edges that are returned by the OAuth 2.0 Authentication Service.
Edge |
Description |
---|---|
Success |
The request message was successfully sent and the response received. |
fail_parse |
An iFL expression could not be evaluated. |
fail_operation |
The operation could not be completed successfully. |
Example:
This example shows how to retrieve a document from the Google Cloud Storage using the OAuth 2.0 Authentication Service.
Google Cloud Storage is a service to store data in the cloud and retrieve it later. It has a RESTful API, authenticated with OAuth 2.0. The equivalent of a file is called an object. Objects are stored in folders called buckets. Buckets are like directories, except they are not hierarchical. Every bucket exists in a single namespace shared by all users of the service. The slash ( / ) character is invalid in a bucket name but is accepted in an object name.
The Google Cloud platform supports multiple varieties of credentials. For server to server applications, a service account must be used. This is a name associated with a public key. The client proves his identity by encrypting with the private key which is kept secret. Service accounts are tied to a specific Google project. They are created in the Google Developer Console. Google chooses the service account name and creates the public-private key pair automatically. The private key is downloaded at the time the service account is created.
The Google Developer Console may change without notice. Proceed with the following steps:
From the following website, https://console.developers.google.com:
298643775104-81neakmsco3agrv956tl8inu8ci7oedl@developer.gserviceaccount.com
The following information will be available:
keytool -import -trustcacerts -file GIAG2.cer -alias giag2 -keystore GIAG2.jks -storepass secret -storetype JKS
The following table lists the parameters and values of the Keystore provider.
Parameter |
Value |
---|---|
Name |
giag2 |
Description |
Google Internet Authority G2 |
Keystore |
Path to GIAG2.jks |
Keystore Password |
secret |
Keystore type |
JKS |
KeyStore JCE Provider |
SUN |
Parameter |
Description |
---|---|
Name |
cloudkey |
Keystore |
Path to the keystore containing the service account private key. |
Keystore Password |
The keystore password chosen by Google, for example, notasecret. |
Keystore type |
PKCS12-DEF |
KeyStore JCE Provider |
BC |
Parameter |
Description |
---|---|
Name |
GoogleSSL |
Keystore Provider |
Not used but required. You can enter giag2 |
Truststore Provider |
giag2 |
Security Protocol |
TLS |
Parameter |
Description |
---|---|
Name |
GoogleClient |
SSL Context Provider |
GoogleSSL |
Parameter |
Description |
---|---|
HTTP Client Provider |
GoogleClient |
Destination URL |
URL of the object in the Google Cloud Storage. |
HTTP Method |
GET |
Scopes |
|
Project ID |
The Google Project ID. |
Service Account Email |
The service account email address chosen by Google. |
KeyStore Provider |
cloudkey |
Private Key Alias |
privatekey |
Private Key Password |
Password chosen by google, for example, notasecret. |
The Destination URL can take one of the following forms:
For example, if the bucket name is mybucket-example-com, and the object name is root.xml, the destination URL can be one of two equivalent URLs:
This instance of the OAuth 2.0 Authentication Service accepts any input document since the GET method does not send a request entity in the body of the message. The output document will be the contents of the object found in the Google Cloud Storage or an error document.
Syntax:
com.ibi.agents.XDWSHttpClientAgent
Description:
This service executes a web service through an HTTP Client provider and allows a transformation to be applied to the response document.
Parameters:
Parameter |
Description |
---|---|
End point (required) |
The location where the web service has been deployed. |
SOAP Action |
Value of the SOAPAction header for HTTP. |
Content-Type |
Value of the Content-Type MIME Header. The default value is text/xml |
User ID |
User ID for Basic Authentication challenges. |
Password |
Password for Basic Authentication challenges. |
Timeout |
The timeout value in seconds. The default value is 0 |
Header |
The header of the web service message. This value can be a file name, transform, or actual data with SREG, XPATH, and so on. |
Body |
The body of the web service message. Can be a file name, transform, or actual data with SREG, XPath, and so on. The default value is _flatof(false) |
Fault Transform |
Transformation to apply when a web service fault occurs. |
Strip SOAP Envelope |
If set to true, then the SOAP envelope from the response document is removed. By default, this parameter is set to false. For more information on the behavior and usage of this parameter, see the description that follows this table. |
Response Transform |
Transformation to apply for the web service response document. |
HTTP Client Provider (required) |
The HTTP Client provider that manages connections for this web service agent. |
Strip SOAP Envelope Parameter
The Strip SOAP Envelope parameter moves namespaces to the payload node when a SOAP response is received. For example, assume that the target web service returns the following message to the service:
<?xml version="1.0" encoding="UTF-8" ?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:somens="http://somens.com"> <SOAP-ENV:Body> <somens:payload>Hello</somens:payload> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
If set to true, then the Strip SOAP Envelope parameter cuts the child of the <SOAP-ENV:Body> element, which in this example, is <somens:payload>. The result is not, by itself, a well-formed XML document because the xmlns attribute that declares the somens namespace prefix is lost during the cut.
Enabling the Strip SOAP Envelope parameter causes the service to ascend the XML tree looking for namespace declarations and copies these attributes to the payload node. For example, after the SOAP envelope is removed, the response document has the following structure:
<somens:payload xmlns:somens="http://somens.com">Hello</somens:payload>