Composer User's Guide
CHAPTER 11
Actions are the atomic units of work in all Composer components. They are responsible for the control flow and logical constructs that make custom applications possible. As you might expect, some actions are used more than others, and certain design patterns reoccur frequently in Web Service applications created with Composer. This chapter discusses some of the actions and design patterns you're most likely to encounter when using Composer.
The exteNd Composer design-side installation includes a few sample projects, one of which is called ActionExamples.spf. The project contains sample documents called InvoiceBatch*.xml. This chapter's examples are based on using the InvoiceBatch template as Input to XML Map components.
If you'd like to follow along as you read the examples, you can open ActionExamples.spf from the Composer File menu. The file is located in:
..\exteNdComposer\Samples\ActionExamples\ActionExamples.spf
You can find other Action Model examples like the ones in this chapter in the Tutorial project.
One of the powerful tools in exteNd Composer is element mapping. You can map elements between DOM trees with different structures, allowing you to pass data between XML documents.
NOTE: For a summary of the basic mapping behavior in Composer, see the table Map Type.
Many of the element mappings you create with Composer will be between leaf elements (terminal nodes) of two DOMs. For instance, you might map a product SKU in the Input Part to a product part number in the Output Part. When the service executes, the transfer between the two Parts takes place and the SKUs from the input XML document are written to the part numbers in the output XML document.
One method of mapping two leaf elements is to select them in the Input and Output panes of the XML Map Component Editor and add a Map action.
NOTE: By default, Composer's Map actions transfer element data, but not attribute data.
To map leaf elements using the Action menu:
Select a line in the Action Model pane where you want to place the Map action. The new Map action will be inserted below the line you selected.
In the Input pane, expand the Input Part until you see the leaf element you want to map.
When the Map dialog box appears, click OK. The mapping from input element to output element is created automatically.
You can also use Composer's drag and drop feature to map an input leaf element to an output leaf element, as explained next.
To map leaf elements using drag and drop:
Select a line in the Action Model pane where you want to place the Map action. The new map action will be inserted below the line you selected.
In the Input pane, expand the Input Part until you see the leaf you want to map.
In the Output pane, expand the Output Part until you see the leaf you want to map.
While holding the left mouse button down, drag the Input leaf element on top of the Output leaf element.
Release the mouse button. The Map action appears in the Action Model pane.
The second way you can map elements is to map a parent element to the target Part. When a parent element is mapped, all of its child elements and their attributes are included in the mapping. For instance, suppose you select a parent element named Line_Item, and it has child elements that include Item_SKU, Item_Description, Item_Quanity, and Item_Cost. Suppose you map the Line_Item element to an element in the Output Part named PO_Line. The resulting map action transfers the Line_Item element and all its child nodes to the PO_Line element in Output, retaining the original branch's structure.
NOTE: The default mapping behavior of Composer's Map action can be overridden. See
To map a parent element and all its children:
Select a line in the Action Model pane where you want to place the Map action. The new Map action will be inserted below the line you selected.
In the Input pane, expand the Input Part until you see the parent element you want to map.
You can also use Composer's drag and drop feature to map an input parent element to an output parent element, as explained in To map leaf elements using drag and drop:.
The third way to map elements is to map a parent element without its descendant elements. In essence, you are mapping the high-level data and ignoring the data and its descendants. For instance, if you map an element named Invoice and it contains descendant elements, the Output Part will only receive data pertaining to the invoice element.
To map a parent element without its child elements:
NOTE: Since the default Map action behavior is to transfer descendant elements, you need to create and apply an ECMAScript method to the element name to map only the element.
Select a line in the Action Model pane where you want to place the Map action. The new Map action is inserted below the line you selected.
In the Input pane, expand the Input Part until you see the parent element you want to map. Select it.
When the Map dialog box appears, select Expression and click the Expression builder button in the Source.
Type the following in front of the XPath fragment: Input.XPath("
Type the following at the end of the XPath fragment: ").toString()
The following illustration shows a Map action for a parent element without its child elements.
There will be times when you want to map two elements that have different formatting. For instance, the element leaf in the Input DOM might be formatted with four numbers and uppercase characters (1234CAT) while the output element leaf might be formatted with lowercase characters and six numbers (cat001234).
Composer provides three methods for transforming element formatting so data can be mapped appropriately between DOMs. The three methods are all available from the Map Action:
The Content Editor allows you to change the format and content of the input element to match that required by the output element. Using the Content Editor, you can slice the input data into small parts, move the parts to different locations relative to one another, add new parts, omit some parts, and apply functions to individual parts.
From the Action menu, select New Action then Map. The Map dialog box appears.
Click the checkbox beside the Content Editor button. This enables the Content Editor button.
Click the Content Editor button. The Content Editor appears.
Optionally click the New Sample button and enter a sample string.
In the Sample field, move the top slider to the position where you want the first cut to take place and the bottom slider to the position where you want the end cut to take place. The sliders determine how to take a substring from the input data.
Click Apply. The substring is copied to the Result field as a separate object.
Repeat steps 6 through 8 for each part of the sample you want, in the result in the order you want. In this way, you can build a new string out of portions (substrings) of the original input.
To change the
format of an object in the Result field:
Click Modify. The Content Region Modify dialog box appears.
NOTE: The Start Cut at Character(s) field displays that character in the string where the first cut will take place. The first Occurrence field displays when the cut will take place. In the previous illustration, the first cut will take place at the first occurrence of the letter T. The End Cut at Character(s) field displays that character in the string where the last cut will take place. The second Occurrence field displays when the cut will take place. The Offset field displays the number of characters from the beginning of the original string where the object will start. The Length fields displays the length of the object.
The Script Expression field supports the ECMAScript expression builder. Any content region created by the Content Editor can have the full functionality of the expression builder applied to it.
NOTE: The %r is a local variable representing the content region to which you would like to apply a function. For example, if you want to apply the uCase() function to the content region, you would write the Script Expression as: uCase(%r).
You can assign a constant to an object by highlighting it, checking the Constant box, and typing a constant string.
When you are finished mapping string formats with the Content Editor, click OK to save the changes and close the Content Editor.
Mapping with Code Tables allows you to automatically transform one set of codes used in the Input Part into another set of codes used on the Output Part. In order for you to transform elements with Code Tables, you must have already created Code Tables and Code Table Maps.
To transform elements with Code Tables:
From the Action menu, select New Action then Map. The Map dialog box appears.
You might come across situations where the Content Editor is not sufficient to transform element format structures. For instance, you might want to extract the month number from a date format (i.e. 5/23) and convert it to the month name (May 23). You can perform custom transformations by creating ECMAScript and XPath custom functions and applying them to element expressions.
Composer comes with a library of sample custom script functions organized in the following categories:
You can import a category of functions from the \exteNd\Samples\CustomScripts subdirectory.
To apply an ECMAScript custom function to an XPath expression:
From the Action menu, select New Action then Map. The Map dialog box appears.
Use the pick-lists to navigate to the custom script function you want and double click.
Edit the expression as necessary to make it syntactically correct.
NOTE: When transforming element data within a Map action using a function, make sure that the result of the function returns a fully qualified DOM element name.
If you want to transform an element's data outside of a Map action, use the Function action. See The Function Action.
"Userfunc:" is a bridge Novell extension method that allows you to use ECMAScript function on XPath expressions. XPath also has limited set of native functions categorized as Node-set, String, Boolean, and Number. These functions do not require the use of the userfunc: keyword. For more information, refer to the "XML Path Language(XPath)" doc provided in the exteNd/Docs/XPath directory.
In the chapter on Advanced Actions, you read about the three Repeat actions and how they are used to perform iterative processing within an Action Model. This section further explains the Repeat actions and shows how they are used to read, map, and write data Input and Output Parts.
The Repeat action has three types of loops. They are:
XML allows multiple instances of an element in a document. The number of instances can vary from document to document. For instance, you might receive an XML document containing invoices on a daily basis. Each day the XML document has a different number of invoices. Not knowing how many instances of the invoice are in the XML document poses a problem if you want to transfer the invoice number from each invoice in the input XML document to an output XML document. The Repeat for Element action solves this problem.
The Repeat for Element action allows you to mark an element that occurs multiple times. The action then sets up a processing loop that executes one or more actions for each instance of the marked element until no more exist. In the example above, the processing loop would contain a single Map action to transfer the invoice number.
The Repeat for Element processing loop allows you to process more than one action. In the simplest case, the repeat loop might only contain one Map action that transfers the value of the current instance from the Input DOM to the Output DOM. You can also set multiple actions in the processing loop: a Map action to transfer the current value and a Log action that writes to a file, creating an audit of each transfer.
The first step in adding a Repeat for Element action is to position the cursor in the Action Model pane where you want the repeat processing to take place.
To add a Repeat for Element action:
Select a line in the Action Model pane where you want to place the For Element Repeat action. The new action is inserted below the line you selected.
In the Input DOM, select the first instance of the element that repeats.
Using the context menu, select Repeat for Element. The Repeat for Element dialog box appears.
Accept the default XPath, or select Expression, and type in a valid expression.
Check the Always create new output elements box if you have repeating actions which should add new elements rather than updating existing ones.
Once the Repeat For Element action is created, you can add a Map (or any other) action within the loop. For instance, to simply transfer the invoice number element from an input XML document to an output XML document, define a Map action as shown in the following illustration:
Notice the use of the repeat alias as the XPath context. The alias is defined in the Repeat action and resolves to an actual DOM name and path.
The Source field specifies that data from the location in the Input Part (seINVOICES/INVOICEHEAD/INVOICENO) will be transferred to a location in the Output Part (teMYINVOICES/INVOICENO).
The Repeat for Element action and the Map action should appear in the Action Model pane as shown in the next illustration.
The format of an XML document that you receive is not always the format that will meet the requirements of your business process. For instance, an XML document might contain invoices from different sellers. The data is received as individual invoices, but in the context of a business-to-business transaction, you might need to summarize the data and send the summary data to a manager, and at the same time, send the invoice data to the Accounts Payable department.
A Repeat For Group action allows you to re-structure your data and establish a framework to calculate aggregates on your data. Grouping allows you to select a repeating element in your Input Part and create fewer elements based on the unique values across all instances (siblings) of that repeating element. Instead of multiple seller elements across the invoices (some with the same seller value), you end up with one element for each unique seller value in our Output Part.
The Repeat For Group action sets up a processing loop that executes for each unique value in the group. Once you have one element per seller, you can add Map actions to the processing loop to calculate how many invoices each seller had. You can also list the individual invoice numbers beneath each seller. By combining a Repeat For Group processing loop with Map commands, you can create a new XML document whose structure and data are different from the original.
To create an action Repeat For Group, you need to complete these three tasks:
Select the element in the Input Part on which you want to repeat.
Click the right mouse button and select Declare Group. The Declare Group Info dialog box appears.
In the Group Name field, type in the alias name you wish to use to reference the group by in your Map actions.
If you want to create multiple group levels, select a group in the Parent Group field.
The Group Elements/Attributes field specifies the full name of the element you selected. If you wish, you can add other elements to this list, thus creating groups based on the concatenation of two or more values in different elements.
Click OK to save the group. A Declare Group line appears in the Action Model.
Once you have created a group based on an Input Part element, you can create a Repeat For Group action.
To create the Repeat for Group action:
Select a line in the Action Model where you want to place the Repeat for Group action. The new action is inserted below the line you selected.
From the Action menu, select New Action>Repeat then Repeat for Group. The Repeat for Group dialog box appears.
The Source fields specify the basis for the processing loop. Select the group you wish to use as the basis for the loop.
The optional Where Script Expression field allows you to selectively omit some repeating elements from the group processing. Type an expression, or click the Expression Builder button, and write an ECMAScript expression that determines which elements participate in the group.
The optional Target fields allow you to specify the position in the Output Part to place data mapped within the Repeat for Group action. Give the Target an alias, select a Part and specify an XPath. This alias is used as the target context for Map actions within the loop.
Once the Repeat for Group action is created, you can add one or more Map actions within the loop. The following illustration shows a Map action using groups as the Input and Output Part elements.
Notice the use of the dot. It indicates the current location, which is whatever the context "sgTHESELLERNAME" resolves to (defined in a Declare Group action earlier in the Action Model).
The Repeat for Group action and the Map action should appear in the Action Model pane as shown in the next illustration.
The Repeat While action creates a processing loop based on any criteria you wish to define. This gives you a different kind of flexibility in creating repeat loops than do the Repeat for Element and Repeat for Group actions, both of which base their looping on data in a document or DOM.The Repeat While action allows you to base your processing loop on any valid XPath or ECMAScript expression.
For example, you could base the execution of your loop on an ECMAScript expression that looks at the system clock to determine when to break out of the loop. In another example, you could base your loop on the existence of files in a directory. In this case, the actions within the loop will process the files and the loop will only break when no more files are present.
To create a Repeat While action, you need to perform the following tasks:
Select a line in the Action Model where you want to place the Repeat While processing loop. The loop is inserted below the line you selected.
From the Action menu, select New Action>Repeat then Repeat While. The Repeat While dialog box appears.
The While Script Expression field is where you type an ECMAScript expression. When it evaluates to false, the execution of the loop will stop. You can also press the Expression Builder button and type an expression or select from a list of pre-written expressions.
The Index Variable field allows you to create a name for a loop counter. This counter is incremented each time the loop executes. You can capture its value in the While Expression to further control the loop processing.
Optionally, you can enter Target information. Enter an alias and select either XPath and a DOM element, or Expression and type in a valid expression. You can also click the Expression Builder button and build an expression.
Once the Repeat While processing loop is created, you can add one or more Map actions within the loop. The following illustration shows a Repeat While loop with two Map actions.
The aggregate calculations include the following examples which can be found in the component named: [008] aggregate calculations in the Action Examples project.
Suppose you have a component that is handling the processing of invoices, and you want to calculate the sum of line item totals (before taxes) across all invoices.
A simple ECMAScript expression using an XPath syntax does the trick. Create a Map action and select the Expression radio button for Source. Type the following ECMAScript expression:
$Input.XPath("//LINETOTAL").sum()
For the Target, select Output, and specify an XPath to receive the result:
MYINVOICEBATCH/LINEITEMTOTALa.
The Source expression uses the XPath // pattern symbol to select all Input nodes regardless of parentage labeled LINETOTAL, and then applies a Novell aggregate method: sum().
NOTE: Because no XML template was specified for the Output, it will be built dynamically (i.e, if a Map Action does not find the element specified in the "Map To" control, it will be created).
Here is an example of what the action looks like:
Suppose you have a component that is handling the processing of invoices, and you want to find the highest total of the invoice amounts.
To find the maximum of an element across multiple INVOICEs, you can specify the "max" method in a Source specification. This establishes the context for the max() function. Then you can continue the specification down to the point of the DOM tree where the element you are interested in finding the max of resides "TOTALS.INVOICETOTAL."
Here is an example of what the action looks like:
Continuing with the previous invoice example, suppose you want to select the one invoice that matches the highest total.
To look across all INVOICEs but only select one of them, you can specify the "where" method in a Source specification, (the where method implies that you will be processing each INVOICE). The specification continues by comparing TOTALS\INVOICETOTAL for each INVOICE against the "max" of all the TOTALS.INVOICETOTALs. The max is found and compared against the value of each INVOICE. Once the match is found, the specification continues to retrieve the INVOICENO.
Here is an example of what the action looks like:
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...