After you have defined the business service, you can configure the Web Services transformation in a mapping to access or transform data from a web service. The requirements and available options depend on whether you are connecting the Web Services transformation to one source object or to more than one source object.
Configuring the transformation
When you configure the web services transformation, you connect a source object, configure properties for the transformation, map incoming fields to requested fields for the web service, and map the response to output fields to create one or more success groups. Data Integration creates a fault group automatically but you can choose whether to map it to the output fields.
1Create a mapping and add the source objects you want to work with.
2Add a Web Services transformation to the canvas.
3Connect the source to the Web Services transformation.
4Select the business service and operation in the Web Service tab.
5On the Request Mapping and Response Mapping tabs, create the field mappings between the source fields and the web service request.
6On the Output Fields tab, review the success groups, fault group, and field details. You can edit the field metadata, if needed. The success groups contain the SOAP response from the web service. The fault group contains SOAP faults with the fault code, string, and object name that caused the fault to occur.
7Define the advanced properties.
8Save and run the mapping.
For additional information about the mapping process, see the following sections:
Advanced properties
The following table describes the properties available for the Web Services transformation from the Advanced tab:
Property
Description
Cache Size
Memory available for the web service request and response. If the web service request or response contains a large number of rows or columns, you might want to increase the cache size. Default is 100 KB.
Allow Input Flush
The mapping task creates XML when it has all of the data for a group. When enabled, the mapping task flushes the XML after it receives all of the data for the root value. When not enabled, the mapping task stores the XML in memory and creates the XML after it receives data for all the groups.
Note: You cannot select the option to allow input flush if you are connecting to multiple source objects.
Transaction Commit Control
Control to commit or roll back transactions based on the set of rows that pass through the transformation. Enter an IIF function to specify the conditions to determine whether the mapping task commits, rolls back, or makes no transaction changes to the row. Use the transaction commit control if you have a large amount of data and you want to control how it is processed.
Note: You cannot configure a transaction commit control if you are connecting to multiple source objects.
Mapping incoming fields
When you define the request mapping, you can configure relationships between more than one source object. You configure relationships between the response mapping and the output fields separately.
When you map incoming fields, note the following guidelines:
•If you need to apply an expression to incoming fields, use an Expression transformation upstream of the Web Services transformation.
•To ensure that a web service request has all the required information, map incoming derived type fields to fields in the request structure.
You can map the incoming fields to the request mapping as shown in the following image:
Drag each incoming field onto the node in the request structure where you want to map it.
Working with multiple source objects
If you have multiple sources, note the following requirements:
•Any source fields you want to designate as primary key and foreign key must use the data type Bigint or String. If needed, you can edit the metadata in the Source transformation.
Note: If the Bigint data type is not available for a source, you can convert the data with an Expression transformation upstream of the Web Services transformation.
•Ensure that the source data is sorted on the primary key for the parent object and sorted on the foreign key and primary key for child objects.
•Map one of the fields or a group of fields to the recurring elements. In the incoming fields, you can see where each recurring element is mapped.
•Map at least one field from each child object to the request structure.
•You must map fields from the parent object to fields in the request structure that are higher in the hierarchy than fields from the child object.
•For child objects, select a primary key and a foreign key.
- On the Incoming Fields tab, select the source object you want to designate as the parent object.
- Right-click on an incoming field in the tree to designate the primary key and foreign key.
- For the foreign key, specify the parent object.
•Do not choose a foreign key for the parent object.
Mapping outgoing fields
On the Response Mapping tab, you map the response structure to the output fields you want to use. You can choose relational or denormalized format for the output fields.
When you choose Relational, the transformation generates the following output groups:
•One output group for the parent element.
•One output group for each element in which the cardinality is greater than one.
•FaultGroup, if it is supported by the connection type you are using.
When you choose Denormalized, the transformation generates the following output groups:
•Output group for the parent element. In denormalized output, the element values from the parent group repeat for each child element.
•FaultGroup, if it is supported by the connection type you are using.
Right-click the node in the node of the response where you want to map the response to output fields. You can choose to map all descendants or only the immediate children, as shown in the following image:
Transaction commit control
The transaction commit control lets you control commit and roll back transactions based on a set of rows that pass through the transformation.
Enter an IIF function to specify the conditions to determine whether the mapping task commits, rolls back, or makes no transaction changes to the row. When the mapping task issues a commit or roll back based on the return value of the expression, it begins a new transaction.
Note: You cannot configure a transaction commit control if you are connecting to multiple source objects.
Use the following syntax for the expression:
IIF (condition, value1, value2)
Use the following built-in variables when you create a transaction control expression:
•TC_CONTINUE_TRANSACTION. The mapping task does not perform any transaction change for this row. This is the default value of the expression.
•TC_COMMIT_BEFORE. The mapping task commits the transaction, begins a new transaction, and writes the current row to the target. The current row is in the new transaction.
•TC_COMMIT_AFTER. The mapping task writes the current row to the target, commits the transaction, and begins a new transaction. The current row is in the committed transaction.
•TC_ROLLBACK_BEFORE. The mapping task rolls back the current transaction, begins a new transaction, and writes the current row to the target. The current row is in the new transaction.
•TC_ROLLBACK_AFTER. The mapping task writes the current row to the target, rolls back the transaction, and begins a new transaction. The current row is in the rolled back transaction.
If the transaction control expression evaluates to a value other than commit, roll back, or continue, the mapping is invalid.
Example
You want to use transaction commit control to write order information based on the order entry date. You want all orders entered on a given date to be committed to the target in the same transaction.
You create a field named New_Date and populate it by comparing the order date of the current row to the order date of the previous row. If the orders have different dates, then New_Date evaluates to 1.
You then use the following expression to commit data when the mapping task encounters a new order date:
When you review incoming fields and request fields, you might want to reduce the number of fields that appear on the page.
You can view and locate fields using the following methods:
Expanding and collapsing nodes
To display the parent and child nodes in a tree, you can expand all nodes. To display only the parent nodes, collapse the nodes. Use the Expand All Nodes and Collapse Nodes icons on the Request Mapping or Response Mapping tabs.
Searching for fields
To search for a particular field, type the field name in the Search text box.
Filtering the fields
You can filter the incoming fields view to show all fields, keys, mapped fields, or unmapped fields. You have a similar option in other tree views:
View the field and field mapping details
For each node in a hierarchy, you can view the field and field mapping details. Right-click on the node to show the properties:
Clear the field mappings and keys
In the Request Structure tree, you can clear the mapping, clear the keys, or map and unmap selected fields:
Pass-through fields
Pass-through fields are response fields that you do not need for the current transformation but you might want to use later in the mapping.
For example you might only need the primary key from a source object for the Web Service transformation. However, you might want to use the other fields in the source object in a downstream transformation.
Incoming fields and response fields pass through the Web Services transformation to the success groups and fault group. However, when the mapping contains multiple sources, only the fields from the primary source pass through. The source that is connected to the Web Service transformation first is the primary source. For example, in the following image, NewSource is the primary source and NewSource1 is the secondary source:
Because NewSource1 is a secondary source, fields from this source do not pass through to the success groups and fault group.
To determine the source of a field in the Success or Fault group, choose the Incoming Fields tab. The Origin column shows the source for each field.
