        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
SAP Connect User's Guide
CHAPTER 4
An action is similar to a programming statement in that it takes input in the form of parameters and performs specific tasks. (For general information on actions, please see the chapters in the Composer User's Guide devoted to Actions. This discussion assumes you are familiar, already, with Composer's basic actions.) Within the SAP Component Editor, as with other Composer component editors, a set of instructions for processing XML documents or communicating with non-XML data sources can be created at design time and stored (for later deployment) in an Action Model. The Action Model contains the business logic needed to perform all data mapping, data transformation, data transfer between databases and XML documents, and data transfer within components and services.
An Action Model is made up of a list of actions. All actions within an Action Model work together. As an example, one Action Model might contain individual actions that read invoice data from a disk, retrieve data from an inventory database, map the result to a temporary XML document, make a conversion, and map the converted data to an output XML document.
The Action Model mentioned above would be composed of several discrete actions. These actions would:
Open a document and perform an SAP Function action to retrieve data from an SAP database
Convert a numeric code using a Code Table and map the result to an Output XML document.
Composer SAP Connect allows both inbound and outbound calls to SAP's BAPIs or other RFC-enabled Function Modules (RFMs) from Composer and the runtime environments. Composer SAP Connect uses the Java Connector libraries to call SAP's BAPI and RFMs.
The SAP Component editor contains all the core functionality of exteNd Composer's XML Map Component editor. It has two additional actions relevant only to the SAP Component editor:
The SAP Function action's dialog is composed of three tabs: SAP Function, SAP Request and SAP Response.
The SAP Function Tab validates the function name to ensure that this function exists in the SAP system to which it is currenly connected. If the function name is valid, it is displayed in the Search for Function text field and can be selected in the Functions list.
If the entered function name is invalid, the entry, "No function found", is displayed in the Function list. If another type of error occurs during validation, such as a communications error, the entry "Error searching for function" displays in the Functions list. The SAP Request and SAP Response tabs are enabled when you double click on a valid function name in the Function list.
To
Add an SAP Function Action:
From the Action Menu, click on New Action>SAP Function or RMB click in the Map Action pane, New Action>SAP Function.
The first tab to appear in the dialog, is the SAP Function tab. When the dialog displays, the SAP Request and SAP Response tabs are disabled and the Functions list is empty.
Click on the Search button to obtain a complete listing of functions (as shown). To filter the search results, you may specify the search criteria. To do so, enter an SAP function prefix followed by the wild card character (*) (e.g. RFC*) to search for a type of SAP function. After entering the search string, click the Search button. The list of functions that match the search criteria are listed. Use the scroll bar to find the function, and doubleclick on that choice. The wild card character can be used for any part of a literal string (e.g. *FC, *FC*, RFC*, etc.)
If no functions match the search criteria, then a single entry, "No function(s) found" displays in the Functions list. If you enter an empty string, then the search uses the wild card character (*), by default.
If a search is successful, the search string is saved. Saved search strings are used to filter the list of functions when the user creates subsequent SAP Function actions.
After a successful search, the user may select an SAP function by double clicking on it. Selecting an SAP function will set the Selected function label and will enable the SAP Request and SAP Response tabs which can then be viewed and edited.
By default, the Use NEP for mapping checkbox is selected. You should select the Use NEP for mapping option if you want to map any data from an Input XML document to SAP Request fields displayed within the Native Environement Pane. Selecting the Use NEP for mapping option will enable all other controls on the SAP Request tab.
If you do not want to map data from an Input XML document to SAP Request fields, then deselect the Use NEP for mapping option by clearing the checkbox. In this case, the Native Environment Pane will not have an SAP Request tab and you will need to use the published methods available in the Expression Editor (see Expression Editor section below). Even with the Use NEP for mapping option selected you may still use the published methods in the Expression Editor.
You must click in the Include Field Attributes checkbox if you want field attributes to be included. When both the Use NEP for mapping and the Include Field Attributes options are selected, the SAP Request document displayed within the NEP's SAP Request tab will include metadata about each field, structure and table as attributes.
By default the SAP Request Tree in the SAP Function dialog displays mandatory nodes pre-selected and disabled. However, you may select or deselect any non-mandatory node.
Within the SAP Request Tree a parent node will display as selected with a gray background if some, but not all, non-mandatory child nodes are selected. A parent node will be displayed as selected with a normal white background if all non-mandatory child nodes are selected.
You may display a description the any field by placing the mouse over the field name. The description will display within a tooltip as illustrated.
Click on the SAP Response Tab.
By default, the Use NEP mapping checkbox is selected. You should select the Use NEP mapping option if you want to map any data from SAP Response fields within the Native Environement Pane to an Output XML document. Selecting the Use NEP mapping option will enable all other controls on the SAP Response tab.
If you do not want map data from the SAP Response fields within the Native Environement Pane to an Output XML document, then deselect the Use NEP mapping option by clearing the checkbox. In this case, the Native Environment Pane will not have an SAP Response tab and you will need to use the published methods available in the Expression Editor (see Expression Editor section below). Even with the Use NEP mapping option selected you may still use the published methods in the Expression Editor.
You must click in the Include Field Attributes checkbox if you want field attributes to be included. When both the Use NEP mapping and the Include Field Attributes options are selected, the SAP Response document displayed within the NEP's SAP Response tab will include metadata about each field, structure and table as attributes.
By default, the SAP Response Tree in the SAP Function dialog displays mandatory nodes preselected and disabled. However, you may select or deselect any non-mandatory node.
Within the SAP Response Tree a parent node will display as selected with a gray background if some, but not all, non-mandatory child nodes are selected. A parent node will be displayed as selected with a normal white background if all non-mandatory child nodes are selected.
You may display a description the any field by placing the mouse over the field name.
Click the OK button on the SAP Function action dialog to validate the entries and save the action. If the Use Mapping Model option is selected for them, the SAP Request and SAP Response tabs will appear in the Native Environment Pane and the new SAP Function action will automatically be created in the Action Model Pane.
The action, as shown in the in the Action model, consists of 4 lines:
Before Execute Actions: allows you to map data into the SAP Request mapping model document or set data directly into an SAP function.
Execute SAP Function: sets SAP Request mapping model data into the functions, executes the function and gets SAP Response mapping model data from the funtion.
After Execute Actions: allows you to map data from the SAP Response mapping model document or get data directly from the SAP function.
You may edit an existing SAP Function Action by performing the following:
To Edit an SAP Function Action:
Highlight the root node of the action, click on RMB and select Edit or double-click on the root node of the action
The SAP Component differs from other components in that the SAP Function action structure within the Action Model is built for you automatically. This structure is created when you add an SAP Function to your Action Model. You can create an SAP Component per the instructions in "How to Create an SAP Component" in Chapter 3 of this Guide. In creating the SAP Component shown in this example, the SAP Request and SAP Response templates were selected for Input and Output respectively. Once created, the new SAP Component appears in the SAP Component Editor window.
Before Execute Actions allows you to map data into the SAP Request mapping model document or set data directly into an SAP function. This can be done in several ways as explained in the following sections.
To map a portion of an XML document into the SAP Request, start by doing a right-mouse-click inside the empty area of the Native Environment pane (with the SAP Request tab selected). This brings up a contextual menu.
Select the Map . . . command. This will bring up the Map dialog. As illustrated below, the the Map dialog's Source and Target fields are intialized.
In the Map dialog, Input is shown as the default Source Part and SAPRequest is shown as the default Target. (You can choose different Source and Target Parts using the pulldown menus.) If you know the XPath fragment that you want to use as the source, type it in the box provided; otherwise, click on the blue Expression Editor icon on the right. Clicking the Expression Editor icon brings up the Expression Editor dialog for the Source.
With the aid of the pick lists in the top portion of this dialog, you can build an XPath fragment and/or an ECMAScript expression simply by pointing and clicking. In this case, we've expanded the tree view of the Input Part (in the upper left) to show the complete Input tree structure. Doubleclicking an item in the tree causes that item (i.e., the XPath fragment for that portion of the tree) to appear automatically in the lower portion of the dialog. Once you click OK, the XPath information appears in the appropriate place in the Map dialog.
To cause information to be mapped from Input to an XPath location of MATNR_LOW in the message body, type in the Target portion of the Map dialog:
Once you click OK, the map dialog disappears and you're able to see the result of your mapping in the SAP Component Editor main window:
This procedure can be repeated as many times as necessary to populate the message body with data. Alternatively, you can use Function actions (in conjunction with ECMAScript DOM methods) to create XML nodes in the message body programmatically.
You can use the drag-and-drop technique to map data from any portion of any Input Part straight into the SAP Request Document (subject to the limitations outlined below), or in the opposite direction. Simply click on an input node, in any visible Part pane, and drag over to the desired spot in the SAP Request Document, then release the mouse button. The appropriate Map action is added to the Action Model automatically.
You can drop nodes onto any branch or field node in the SAP Request tab. However, you cannot drop nodes onto attributes. If the source value does not validate against the target field node's type, the "forbidden drag operation" symbol shown at left, is displayed as the mouse pointer and the message, "Invalid drop target", is displayed in the status area. If the source value is too long for the target field nodes length, the "forbidden drag operation" symbol is displayed and the message, "Invalid drag length for this drop target" is displayed in the status area.
When an SAP Function Action executes the SAP Request DOM, if it exists, it is cleared and the SAP Response DOM, if it exists, is reloaded. Then the Before Execute Actions list is executed. The Execute SAP Function action then executes by setting the SAP Request mapping model document mappings into the function, executing the function, and then setting the SAP Response mapping model document with the function results.
When the root of an SAP Function action is the current (or highlighted) action in the action model, the Execute SAP Function button on the main toolbar is enabled. It is disabled at all other times. By clicking the on SAP Execute Function button, it connects to the the SAP System, executes the actions within the SAP Function action and then disconnects from the SAP system.
If execution is successful a message dialog appears:
After Execute Actions allows you to map data from the SAP Response mapping model document or get data directly from the SAP function.
To map a portion of an SAP Response to an XML document, start by doing a right-mouse-click inside the empty area of the Native Environment pane (with the SAP Response tab selected). This brings up a contextual menu.
Select the Map... command. This will bring up the Map dialog.
In the Map dialog, SAP Response is shown as the default Source and Output is shown as the default Target Part. (You can choose different Source and Target Parts using the pulldown menus.) If you know the XPath fragment that you want to use as the source, type it in the field provided; otherwise, click on the blue Expression Editor icon on the right. Clicking the Expression Editor icon brings up the Expression Editor dialog for the Source.
With the aid of the pick lists in the top portion of this dialog, you can build an XPath fragment and/or an ECMAScript expression simply by pointing and clicking. In this case, we've expanded the tree view of the SAP Response Document (in the upper left) to show the complete tree structure. Doubleclicking and item in the tree causes that item (i.e. the XPath fragment for that portion of the tree) to appear automatically in the lower portion of the dialog. When you click OK, the XPath information appears in the appropriate place in the Map dialog.
This procedure can be repeated as many times as necessary to populate the Output Part with data. Alternatively, you can use Function actions (in conjunction with ECMAScript DOM methods) to create XML nodes in the Output Part programmatically.
You can use the drag-and-drop technique to map data from any portion of the SAP Response Document straight into the Output Part. Simply click on any node in the SAP Response Document and, while holding the mouse button, drag the node over to the desired spot in the Output Part, the release the mouse button. The appropriate Map action is added to the Action Model.
The Component with Connection Action is unique because it allows an SAP component to call another component allowing that component to share the same connection. The action allows you to break up a large component into a main SAP component and subcomponents so it is easier to maintain the Action Model. The ability to have the main component share the connection with the subcomponent greatly reduces the amount of connection overhead which enhances runtime performance. This is extremely useful when you want to specify a session connection.
To use the Component with Connection Action
Create and record the basic structure of the main component to the point where you are ready to call a subcomponent. For this example, the subcomponent will be entitled "BAPI_MATERIAL_GET_ DETAIL."
From the Main menu, or by clicking the RMB, select New Action>Component/w connection. The following dialog appears.
From the Component Type pull down list, select the name of the component type. From the Component Name pull down list, select the name of the Component.
Select the passed ID if you need to change it from the pull down list. Select the returned ID if you need to change it from the pull down list. Click OK.
Animate the Main component and step into the Component with Connection action. The subcomponent will now open. Notice how the screen changed to the component entitled "BAPI MATERIAL GET DETAIL."
Build the subcomponent action model as you did the component.
NOTE: You will notice in this example a Repeat for Element action built to process multiple rows.
Now animate the subcomponent and step into it. The results will now appear for the subcomponent in the Output DOM and the SAP Response tab.
An SAP Action Model can be built by using the Expression Builder and setting data directly into an SAP function. Often, it is useful to be able to reference these values in ECMAScript expressions. The Expression Builder pick list (in the top portion of the Expression Editor window) contains methods specific to SAP: (See dialog below.)
Object getImportField(String asName) - gets a Simple Import field value by name.
setImportField(String asName, String asType) - sets a Simple Import field value by name and type. Used as a Target expression in Map actions.
Object getExportField(String asName) - gets a Simple Export field value by name.
Object getImportStructField(String asStructName, String asName) - gets an Import Structure field value by structure name and field name.
Node getImportStructAsXML(String asStructName) - gets an Import Structure by name as an XML Node.
setImportStructField(String asStructName, String asName, String asType) - sets an Import Structure field value by structure name, field name, and field type. Used as a Target expression in Map actions.
setImportStructWithXML(String asStructName) - sets an Import Structure by name with an XML Node.
Object getExportStructField(String asStructName, String asName) - gets an Export Structure field value by structure name and field name.
Node getExportStructAsXML(String asStructName) - gets an Export Structure by name as an XML Node.
Object getTableField(String asTableName, String asName) - gets a Table field value by table name and field name.
Node getTableAsXML(String asTableName) - gets a Table by name as an XML Node.
int getTableRowCount(String asTableName) - gets the number of rows in a named Table as an integer.
appendTableRow(String asTableName) - appends a row to the end of named Table.
nextTableRow(String asTableName) - moves the cursor to the next row in the named Table.
setTableRow(String asTableName, int aiRow) - moves the cursor to specified row in the named Table.
setTableField(String asTableName, String asName, String asType) - sets a Table field value by table name, field name, and field type. Used as a Target expression in Map actions.
setTableWithXML(String asTableName) - sets a Table by name with an XML Node
Node getFunctionAsXML() - returns a Node representing the SAP function. Can be used before or after execution.
dumpFunctionToLog() - calls getFunctionAsXML(), adds a DATE attribute to the function name element, and prints with format to the log via the Framework Factory log() method.
String getLastError() - returns the most recent execution error.
String getFunctionName() - returns the function name.
Object getRFCObject() - returns the RFC object. For JCo this is a JCO.Function Object.
setRequestSetAsString(boolean abFlag) - sets whether input to a function prior to execution should be set as a String or converted to an Object appropriate for the field type and then set. By default this flag is true in the ECMA wrapper. For example, if true and the field type is DATE then input via the model document or published setter methods is expected to be in the form "YYYYMMDD". If false and the field type is DATE and the input is via the model document the String will be used as input to a java Date() object. If false and the field type is DATE and the input is via a published setter the user can directly pass in a java Date() Object or the user can pass in a String which will be used as input to a java Date() object.
Field Type Conversions when flag is false
BYTES - byte[] array (currently) no way to pass an array in
DATE - java Date (conversion tries YYYYMMDD pattern and
java Date() default string patterns)
XSTRING - byte[] array (currently) no way to pass an array in
setResponseGetAsString(boolean abFlag) - sets whether output from a function after execution should be retrieved as a String or as an Object appropriate for the field type. By default this flag is true in the ECMA wrapper. For example, if true and the field type is DATE then the field will be retrieved using the JCO.Field.getString() method for the model document and for published getters. If false and the field type is DATE and the field is being retrieved via the model document then the field will be retrieved using the JCO.Field.getObject() method and then converted to a String using the Objects toString() method. If false and the field type is DATE and the field is being retrieved via a published getter method then the field will be retrieved using the JCO.Field.getObject() method.
Field Type Conversions when flag is false
BYTES - byte[] array (if getting for response model document getString() is used)
XSTRING - byte[] array (if getting for response model document getString() is used)
Getting and setting SAP tables requires different logic because Tables may have multiple rows.
Rows in the SAP Response document are identified by the <item> element. To process multiple rows all a user needs to do is create a Repeat for Element action in the After Execute Actions list of the SAP Function action. Figure 8 shows an example.
By using SAP.getTableRowCount(), SAP.getTableField(), and SAP.nextTableRow() together with a Repeat While action a user can walk the items in a Table.
A SAP function may allow a user to enter multiple records via a table. To insert multiple rows via the SAP Request model document the user may create a Repeat for Element action in the Before Execute Actions list.
By using SAP.appendTableRow() and SAP.setTableField() together with a Repeat for Element action a user can insert multiple rows into a table.
In addition to the Add SAP Function action, you have all the standard Basic and Advanced Composer actions at your disposal as well. The complete listing of Basic Composer Actions can be found in Chapter 7 of the Composer User's Guide. Chapter 8 contains a listing of the more Advanced Actions available to you.
Error handling has been enhanced. If a connection error occurs at any time during design time Composer releases the connection to allow you to fix the problem and recover without exiting the component.
The SAP Function dialog will now display one of three error messages in the Functions list:
No function(s) found - RFC_FUNCTION_SEARCH failed to find RFCs matching the criteria. Can occur when pressing Search.
Error searching for functions - Communications error or other system error. Can occur when pressing Search.
Error getting metadata for function - Communications error or other system error. Can occur when selecting a function.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
