Modifying Links Using the Target Expression Tab

You can view and modify the link between a source and target element using the Target Expression tab. You can use the Target Expression tab to build a more complex expression between a source and target element as shown in the following sections:

• Editing Links Using the Target Expression Tab
• Adding If-Then-Else Constructs to a Link
• Invoking Functions or Operators in a Query

Editing Links Using the Target Expression Tab

This section describes how to edit the XQuery code of a link using the Target Expression tab.

To Edit the XQuery Code of a Link

1. Open a query in the mapper pane. For instructions see General Steps to Open or Create a Query in the Mapper.
2. In the Design View, select or create a link between a source and target node.

Keep the link selected for the next step.

3. Select the Target Expression tab. (If the Target Expression tab is not visible in WebLogic Workshop, choose View —> Windows —> Target Expression from the menu bar.)

By default the General option is selected and the XQuery code for the link is displayed in the General Expression pane.

4. Select the Target Expression tab. (If the Target Expression tab is not visible in WebLogic Workshop, choose View —> Windows —> Target Expression from the menu bar.)
5. Edit the generated query (the XQuery code).

The query is written in the XQuery language. To learn about the XQuery language supported with WebLogic Integration, see the XQuery 1.0: An XML Query Language Specification - W3C Working Draft 16 August 2002 available from the W3C web site at the following URL:

http://www.w3.org/TR/2002/WD-xquery-20020816/

The WebLogic XQuery engine which is invoked by the Transformation method conforms to the August 16, 2002 draft of the XQuery Specification.

Adding If-Then-Else Constructs to a Link

This section describes how to add if-then-else constructs to a link using the Target Expression tab. When a query is invoked with an if-then-else, the conditions that make up the if expression are evaluated and depending on the result, different values are returned for a target node. For example, if the value of quantity source node is greater than 500 then 4554 is returned as the value of the id target node but if the value of quantity source node is less than or equal to 500, then 5894 is returned as the value of the id target node as shown in the example in the following figure.

Figure : If-Then-Else

In addition to the following procedure for adding a simple if-then-else expression to a link, a more complex example is available. To learn more see Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.

To Add an If-Then-Else Expression to a Link

1. Open a query in the mapper pane. For instructions see General Steps to Open or Create a Query in the Mapper.

For this example, import the files: PurchaseOrder.xsd and Supplier.xsd files (step 2 in General Steps to Open or Create a Query in the Mapper.) If you installed WebLogic Platform in the c:\bea directory, import these files from the c:\bea\weblogic81\workshop\help\doc\en\integration\reffiles\transform\ifThenElse directory.

For this example, select and add the PurchaseOrder.xsd/PurchaseOrder node as an source type (step 4 in General Steps to Open or Create a Query in the Mapper.)

For this example, select and add the Supplier.xsd/Supplier node as an target type (step 4 in General Steps to Open or Create a Query in the Mapper.)

2. In the Design View, select or create a link between a target and source element to add the if-then-else.

For this example, select the PurchaseOrderDoc/quantity source element and drag it to the Supplier/id target node.

Keep the link selected for the next step.

3. Select the Target Expression tab. (If the Target Expression tab is not visible in WebLogic Workshop, choose View —> Windows —> Target Expression from the menu bar.)
4. Select the If Then Else option.

The XQuery if-then-else construct is added to the link. For example, the following XQuery source code segment for the link is replaced:

data($PurchaseOrderDoc/quantity) 

By the following XQuery source code segment for the link:

if (xf:boolean("true")) then
	data($PurchaseOrderDoc/quantity)
else
	() 

5. Click If Condition.

The If Condition pane appears.

6. In this step, you add condition(s) to the if section of the if-then-else.

During run time, when the condition(s) in the if are evaluated and if the if evaluates to true, the then part of the if-then-else is invoked but if the if evaluates to false, the else part of the if-then-else is invoked.

The if section of an if-then-else can be a simple condition that compares a source element and a simple value. The if section of an if-then-else can also be complex—involving multiple conditions.

To create a condition, first populate the left and right side expressions:

• Drag and drop elements from Source pane or the Data Palette into the Left Hand Expression or Right Hand Expression section of the If Condition pane.
• Enter values directly into the Right Hand Expression section of the If Condition pane.
• Drag and drop functions or operators from the Palette into the Left Hand Expression or Right Hand Expression section of the If Condition pane.

After the Left Hand Expression or Right Hand Expression sections for a simple expression are specified, select an operator from the Operator drop-down list and click Add.

For this example, complete the following steps to create a simple condition:

1. From the Source pane, drag the PurchaseOrderDoc/quantity element into the Left Hand Expression section of the If Condition pane.
2. Select the operator: >.
3. In the Right Hand Expression section of the If Condition pane, enter: 500 and click Add.

The condition is added to the if section of the if-then-else.

To create an if section with multiple conditions:

1. Create a simple condition as described previously.
2. Add additional conditions:

Populate the Left Hand Expression and the Right Hand Expression. Select the appropriate operator.

Select the appropriate Join Type.

Click Add.

For an example, see Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.

7. Click Then Expression.
8. In the Then Expression section, enter a value or an expression. If you specify an expression, during run time if the If Condition evaluates to true, the expression in the Then Expression section will be evaluated and the resulting value will become the value of the target node. You can build an expression by dragging functions or operators from the Palette and elements from the Source pane or Data Palette into the Edit Then Expression section as shown in Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.)

For this example, replace the following text:

data($PurchaseOrderDoc/quantity) 

With the supplier id value of 4554.

Note: In addition, nested if-then-else constructs can be added to the else expression. To learn more, see Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.

9. Click Apply.
10. Click Else Expression.
11. In the Else Expression section, enter a value or an expression. If you specify an expression, during run-time if the If Condition evaluates to false, the expression in the Else Expression section will be evaluated and the resulting value will become the value of the target node. You can build an expression by dragging functions or operators from the Palette and elements from the Source pane or Data Palette into the Edit Then Expression section as shown in Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.)

For this example, enter 5894 and click Apply.

Note: In addition, nested if-then-else constructs can be added to the else expression. To learn more, see Adding Nested If-Then-Else Expressions with Complex Conditions to a Link.

12. Select the General option, to view the generated if-then-else XQuery source code.
13. To run the query, select the Test View of the XQ file.
14. In the Source Data pane of the Test View, enter or import the desired source XML. To learn more see Testing Maps in the Test View.

For this example, in the Source Data pane of the Test View, select the quantity Node Value field and enter 678.

15. In the Result Data pane, click Test.

If not currently running, the WebLogic Server for the current application will be started. In order for a query to run, the WebLogic Server for the current application must be running.

In the Result Data pane, after the query is run a graphical representation of the target data is displayed.

For this example, in the Result Data pane, the resulting value of Supplier/id element is 4554 because the source quantity was over 500 as shown in the preceding figure.

16. Save the DTF and the XQ file. From the menu bar, choose File —> Save All.

Invoking Functions or Operators in a Query

This section describes how to insert calls to functions or operators into a query using the Target Expression tab.

This section contains the following topics:

• Invoking XQuery Functions or Operators in a Query
• Invoking User Defined Methods in a Query
• Invoking Control Methods in a Query

Invoking XQuery Functions or Operators in a Query

A set of standard W3C XQuery functions and operators are provided in the mapper functionality of WebLogic Integration. When you use the mapper functionality to design a transformation, a query (written in the XQuery language) is generated that does actual data conversion. In the generated query, you can add function calls to this set of standard XQuery functions. For example, as part of your transformation you might want to convert the XML String to uppercase characters.

The procedure below describes how to add a function call to a simple link between a XML String source node and an XML String target node. Adding a function to a more complicated query is described in the Step 3: Mapping Elements and Attributes in the Tutorial: Building Your First Data Transformation.

For listings and detailed descriptions of the XQuery functions and operators available in the mapper functionality of WebLogic Workshop, see XQuery Reference.

In addition to the XQuery functions available in the mapper functionality, a larger set functions is provided. You can manually add invocations to these functions to queries in the Source View of the mapper functionality. For a list of these additional functions, see the XQuery 1.0 and XPath 2.0 Functions and Operators - W3C Working Draft 16 August 2002 available from the W3C web site at the following URL:.

http://www.w3.org/TR/2002/WD-xquery-operators-20020816/

To Add a XQuery Function or Operator Call to a Query

1. Open a query in the mapper pane. For instructions see General Steps to Open or Create a Query in the Mapper.
2. In the Design View of the XQ file, select or create the link to add the function or operator call.

The link between these two nodes becomes green.

Adding a function or an operator to a link means that during run time, as part of the transformation of the data between the source node and the target node, the function will be invoked.

3. In the bottom pane of the Design View, choose the Target Expression tab. (If the Target Expression tab is not visible in WebLogic Workshop, choose View —> Windows —> Target Expression from the menu bar.)

In the General Expression pane, the XQuery code linking the selected target and source node is displayed and is selected. Keep the XQuery code selected for the next step.

4. Click the Delete key.

The text in the General Expression pane is removed.

5. View function and operator folders of the Palette. (If the Palette is not visible in WebLogic Workshop, from the menu bar choose View —> Windows —> Palette.)
6. In the Palette, collapse and expand the folders to find the desired function or operator.

For this example, from the String Functions folder select the upper-case function.

7. In the XQuery Functions pane, select the desired function, and drag it into the General Expression pane.

For this example, the following text is displayed in the General Expression pane, as shown in the following figure.



For the following step, leave the parameter selected (in this example: $string-var) in the General Expression pane as shown in the preceding figure.

8. Select a source parameter using one of the following options:
• From the Source pane of the Design View select a source node and drag-and-drop it over the parameter in the General Expression pane.
• From the Data Palette pane select a source variable and drag-and-drop it over the parameter in the General Expression pane. (If the Data Palette is not visible in WebLogic Workshop, from the menu bar choose View —> Windows —> Palette.)

For this example, the following text is displayed in the General Expression pane, as shown in the following figure.



9. Repeat step 8 until all the parameters in the function or operator are assigned.
10. Click Apply.

During run time for this example, the upper-case function will convert all the characters of the $quoteDoc/name element to upper case.

11. Save the DTF and the XQ file. From the menu bar, choose File —> Save All.

Invoking User Defined Methods in a Query

This section describes the following tasks:

• To Add a User Method to a Transformation File
• To Add a Java User-Defined Method Call to a Query

To Add a User Method to a Transformation File

A User method is a user-defined Java method that can be called from a query (written in the XQuery language). You can add User Methods to a Transformation file and then add invocations to these User methods in queries. Adding a User method to a Transformation file is described in Create a User Defined Java Method to Invoke From the Join Query in Step 4: Mapping Repeating Elements—Creating a Join in the Tutorial: Building Your First Data Transformation.

To Add a Java User-Defined Method Call to a Query

Before you can add a Java user-defined method call to a query, the method must already have been created in the Transformation file. For instructions, see To Add a User Method to a Transformation File.

Calling a User method from a query is described in Call the calculateTotalPrice User Method From the Query task the in Step 4: Mapping Repeating Elements—Creating a Join in Tutorial: Building Your First Data Transformation.

You may want to add an exception path to the node in the business process which calls the Transformation file. To learn more, see Getting the TransformException Fault Code Programmatically.

Warning: The User method you call from the query should contain only stateless functionality.

Note: You cannot call a User method which returns a void from a query.

Invoking Control Methods in a Query

To Add a Control Function Call to a Query

1. Create or open an existing business process project and application that contains the query stored as a method in the Transformation file.

For instructions on creating a new business process project and application, see Creating a Business Process Application.

To open an existing application:

1. From the WebLogic Workshop menu bar, choose File —> Open —> Application.
2. In the Open Workshop Application dialog box, browse for the desired application and click Open.
2. Import your schemas into your application. For instructions, see Importing Schemas.
3. Create or open the Transformation file.

For instructions on creating a new Transformation file, see Creating a Transformation File and a Transformation Method.

To open an existing Transformation file:

1. In the Application tab, browse and select a Transformation file. (If the Application tab is not visible in WebLogic Workshop, choose View —> Application from the menu bar.)
2. Double-click the Transformation file (ends in the .dtf extension).
4. Add an instance of a control to the Transformation file:
1. In the Controls section of the Data Palette, select Add —> Control_Name, where Control_Name represents the name of the control to add.
2. Follow the steps in the Insert Control dialog box and click Create.

To learn more, see Working with Java Controls.

An instance of the control is created and a representation of the controls appears in the graphical representation of the Transformation file.

5. Select input source schema(s) and the output target schema. For instructions, see To Select the Source and Target Types and To Change the Selected Source or Target Parameters
6. Create or select a Transformation method from a Transformation file.

For instructions on creating a method in a Transformation file, see To Add a Transformation Method to Transformation File.

To select an existing method, in the Design View of the Transformation file:

1. Right-click the arrow representing the method.
2. From the drop-down menu, select Goto XQuery Document.

The mapper pane is displayed.

7. Open the XQ file that contains the transformation in the Design View.
8. In the Design View, select the link to add the function call.

The link between these two nodes becomes green.

Adding a function to a link means that during run time, as part of the transformation of the data between the source node and the target node, the function will be invoked.

9. In the bottom pane of the Design View, choose the Target Expression tab. (If the Target Expression tab is not visible in WebLogic Workshop, choose View —> Windows —> Target Expression from the menu bar.)

In the General Expression pane, the XQuery code linking the selected target and source node is displayed.

10. In the Palette, expand the Controls Functions folder. (If the Palette is not visible in WebLogic Workshop, from the menu bar choose View —> Windows —> Palette.)
11. In the Palette, collapse and expand the folders to find the desired function.
12. In the Palette, select the desired function, and drag it into the General Expression pane.

Warning: When you select a Control in Palette all the functions in a Control are listed. You should however, only use the Control functions in queries with look-up, read-only stateless functionality. For example, a query could call a read-only function, which accepts as a parameter a record id and returns the string associated with the record id. This read-only function does not change or add any values in the database. It just reads a values from the database. Control functions that are stateful should not be called from queries. For example, a Database control function that adds a record to the database should not be called from a query. Functions that are stateful or modify the database should be called from the business process directly.

13. Select a source parameter using one of the following options:
• From the Source pane of the Design View select a source node and drag-and-drop it over the parameter in the General Expression pane.
• From the Data Palette pane select a source variable and drag-and-drop it over the parameter in the General Expression pane. (If the Data Palette is not visible in WebLogic Workshop, from the menu bar choose View —> Windows —> Palette.)
14. Click Apply.

During run time, the query will invoke the selected function from the control.

15. Save the DTF and the XQ file. From the menu bar, choose File —> Save All.