Configure advanced web service settings

Configure advanced web service settings directly in the related process.

All settings require extra information in the Meta-Inf properties section. Some settings require process parameters as well.

Prerequisites

Create or open the process that you want to modify and expose as a web service. Open the process properties window, and open its Meta-Inf finger tab.

In the Meta-Inf tab, add and close a <httpRestWebServiceProperties> XML tag:

<httpRestWebServiceProperties>
</httpRestWebServiceProperties>

This tag, and its attributes, contains and sets parameters described in this article.

Set HTTP paths and available methods

Web services are invoked with specific paths and HTTP methods. You can define which ones web service deliveries use.

Configure the process

In the process properties Meta-Inf tab, add path and methods attributes to the <httpRestWebServiceProperties> tag as in the following example.

<httpRestWebServiceProperties path="<user/defined/path>"  methods="post patch">
</httpRestWebServiceProperties>

Replace the quoted attribute values with your own. The attributes work as follows:

path

A path on which you can invoke the delivery as a web service, relative to the main invocation path. This path is added to the end of the runtime invocation URL.

methods

A space-separated, lowercase list of HTTP methods you can invoke the delivery with.

For example, this configuration:

configures a delivery that is reached at http://localhost:42200/rest/DeliveryService/3/myDelivery/path/invoke with POST, GET and PATCH methods.

Configure for multiple deliveries

You can configure multiple deliveries with the same path, but with different HTTP methods. This method can help you separate your integration flows into multiple processes.

For example, you could have two processes which have the path customer, but one uses the get method while the other uses post patch. When you invoke the web service, the runtime chooses which flow to execute transparently to the requestor.

Set URL path parameters

Define path parameters to invoke and retrieve them when invoking a web service.

Path parameters get added to the base web service URL. Each time you invoke the web service, process parameters hold the values sent in the URL as the path. You can then use those values in the process as with other similar parameters.

Follow these steps to configure and use your web service to add your own path parameters.

Create process parameters

First, create a process parameter to store the value sent when invoking the web service. Open its properties, and set a default value to avoid problems with URLs that do not set the path parameter.

Screenshot of creating a process parameter to add a URL path parameter

In the Publication finger tab, specify that this is an input parameter.

Configure the parameter path

Choose one of the following two methods to configure how the parameters construct the path:

Method 1: dedicated nodes

This method defines path parameters with one XML tag per path parameter.

In the process properties Meta-Inf tab, add a <urlPartMapper /> tag with urlPartPosition and parameterName attributes, as in the following example:

<httpRestWebServiceProperties>
     <urlPartMapper urlPartPosition="<position_num>" parameterName="<parameter_name>"/>
</httpRestWebServiceProperties>

Replace the quoted attribute values with your own. The attributes are as follows:

urlPartPosition

A number that sets the position of the process parameter in the URL path, starting at 1. In the example at the start of this page, position 1 retrieves the value id, and position 2 retrieves the value 717.

parameterName

The name of the process parameter that receives the value.

You can add more <urlPartMapper /> tags as needed:

<httpRestWebServiceProperties>
    <urlPartMapper urlPartPosition="1" parameterName="My_Url_Parameter_01"/>
    <urlPartMapper urlPartPosition="2" parameterName="My_Url_Parameter_02"/>
    <urlPartMapper urlPartPosition="3" parameterName="My_Url_Parameter_03"/>
</httpRestWebServiceProperties>

Method 2: invocation path mask

This method also defines path parameters using XML, but uses a single XML attribute for multiple path parameters.

In the process properties Meta-Inf tab, add a path attribute to the <httpRestWebServiceProperties> tag as in the following example, and replace <parameter_name> with the name of your process parameter:

<httpRestWebServiceProperties path="user/defined/path/{<parameter_name>}">
</httpRestWebServiceProperties>

You can add other process parameters to the URL. They need to be in curly brackets, separated by a slash. Their position in this URL mask determines their position when invoked.

<httpRestWebServiceProperties path="user/defined/path/{My_Url_Parameter_01}/{My_Url_Parameter_02}/{My_Url_Parameter_03}">
</httpRestWebServiceProperties>

Set HTTP headers

You can customize the delivery behind the web service to collect values of input HTTP headers. The delivery can also return its own output headers at the end of the web service invocation.

Each time you invoke the web service, xDI Runtime processes the HTTP headers. The runtime store input headers in process parameters, and sends output headers from their value in process parameters.

Create process parameters

First, create a process parameter to store the value of your headers. Open their properties, and set a default value to avoid problems with URLs that do not set the path parameter.

Screenshot of creating a process parameter to add an HTTP header parameter

Configure the headers

Set the header names in the process properties Meta-Inf tab by adding one or more <requestHeaderMapper> or <responseHeaderMapper> tags. The tag you choose depends on whether you are configuring input or output headers.

Add headerName and parameterName attributes to the <requestHeaderMapper> and <responseHeaderMapper> tags.

Example 1. Input headers
<httpRestWebServiceProperties>
    <requestHeaderMapper headerName="<header_name>" parameterName="<parameter_name>" />
</httpRestWebServiceProperties>
Example 2. Output headers
<httpRestWebServiceProperties>
    <responseHeaderMapper headerName="<header_name>" parameterName="<parameter_name>" />
</httpRestWebServiceProperties>

Replace the quoted attribute values with your own. The attributes work as follows:

headerName

The name of the HTTP header being sent or received. For example, Content-Type.

parameterName

The name of the process parameter that receives or sends the value.

You can add more <requestHeaderMapper /> or <responseHeaderMapper /> nodes as needed, all under the same root node:

<httpRestWebServiceProperties>
   <requestHeaderMapper headerName="HeaderName" parameterName="My_HTTPHeader_Parameter_01" />
   <requestHeaderMapper headerName="HeaderName02" parameterName="My_HTTPHeader_Parameter_02" />
   <requestHeaderMapper headerName="HeaderName03" parameterName="My_HTTPHeader_Parameter_03" />
   <responseHeaderMapper headerName="HeaderName" parameterName="My_Output_HTTPHeader_Parameter_01" />
   <responseHeaderMapper headerName="HeaderName02" parameterName="My_Output_HTTPHeader_Parameter_02" />
   <responseHeaderMapper headerName="HeaderName03" parameterName="My_Output_HTTPHeader_Parameter_03" />
</httpRestWebServiceProperties>

Alternate default response value

If you do not need a configurable output value, you can also set a default value directly in the <responseHeaderMapper> tag, in a defaultValue attribute:

<httpRestWebServiceProperties>
  <responseHeaderMapper headerName="HeaderNameWithDefaultValue" defaultValue="<default_value>"/>
</httpRestWebServiceProperties>

Set HTTP response codes

When designing a web service, you can define how the delivery returns an HTTP response code at the end of its session. Each time you invoke the web service, xDI Runtime sends a response code from a value in a process parameter.

Create process parameters

First, create a process parameter to store the value of your desired response code. Open its properties, and set a default value to avoid problems with empty parameters.

Screenshot of creating a process parameter to add an HTTP response code parameter

Configure the response code

Set the response code in the process properties Meta-Inf tab:

  • Add a single <responseCodeMapper> tag.

  • Add a parameterName attribute to the <responseCodeMapper> tag.

<httpRestWebServiceProperties>
    <responseCodeMapper parameterName="<response_code>" />
</httpRestWebServiceProperties>

Replace the quoted parameterName attribute value with the name of the process parameter that holds the response code to send.

The response code is mapped to the parameter value. When the execution ends, the returned code is the value of the parameter at that time.

You can change this value dynamically during execution, for example using scripting functions.

Set HTTP message bodies

You can customize the delivery behind the web service to collect the HTTP message body. The delivery can also return another message body at the end of the web service invocation.

Each time you invoke the web service, xDI Runtime manages the HTTP message body. The runtime store an input body in process parameters, and sends an output body from a value in process parameters.

Use this configuration to retrieve and return raw data, such as plain text.

For structured data, such as JSON or XML, use dedicated metadata objects.

Create process parameters

First, create process parameters to store the value of the HTTP message bodies. Open their properties, and set a default value to avoid problems with empty values.

Screenshot of creating a process parameter to add an HTTP message body parameter

Configure the body

Next, specify the message body.

Specify the message body in the process properties Meta-Inf tab. Add a <requestBodyMapper> tag, a <responseBodyMapper> tag, or one of each. The tags you choose depends on whether you are configuring input or output bodies.

Add parameterName and charset attributes to the <requestBodyMapper> and <responseBodyMapper> tags.

Example 3. Input message body
<httpRestWebServiceProperties>
    <requestBodyMapper parameterName="<message_body" charset="UTF-8"/>
</httpRestWebServiceProperties>
Example 4. Output message body
<httpRestWebServiceProperties>
    <responseBodyMapper parameterName="<message_body" charset="UTF-8"/>
</httpRestWebServiceProperties>

Replace the quoted attribute values with your own. The attributes work as follows:

parameterName

Enter the name of the process parameter to hold the message body.

charset

Sets the character set used for the message body.

You can have only one each of <requestBodyMapper /> or <responseBodyMapper /> tags, all under <httpRestWebServiceProperties>:

<httpRestWebServiceProperties>
    <requestBodyMapper parameterName="requestBody" charset="UTF-8"/>
    <responseBodyMapper parameterName="responseBody" charset="UTF-8"/>
</httpRestWebServiceProperties>

Expose internal data as variables

Not all web service data is visible by default. You can configure web services to expose all information as variables, to help with debugging, or to use in a process.

Go the process properties Meta-Inf tab, and find the <httpRestWebServiceProperties> XML tag. Add an extractRequestInfo="true" attribute to the tag itself:

<httpRestWebServiceProperties extractRequestInfo="true">
    <!-- Add your content here -->
</httpRestWebServiceProperties>

When run with this configuration, the data flow exposes all information sent by the invoker as variables. The variable names depend on the sent information.