33 Editing Transformations Using Mapping Editor

This chapter discusses the process for editing transformations using the Mapping Editor.

This chapter includes the following sections:

33.1 Overview of Mapping Editor

The Mapping Editor is a browser-based application that enables you to customize prebuilt integration mappings. Changes are saved as layered customizations, which protects them from being overridden when applying patches or upgrades. The application also enables you to merge the customizations and deploy the impacted composite services to the runtime environment.

33.2 Administering the Mapping Editor

This section discusses the following Mapping Editor administration tasks:

33.2.1 Enabling the Mapping Editor

To enable the Mapping Editor, the AIAMappingCustomizer Enterprise Role must be assigned to the appropriate user(s).

The Oracle WebLogic Administrator must enable the role to the users.

The AIAMappingCustomizer Enterprise Role becomes available in the Oracle WebLogic console after the AIAHome application is deployed.

To assign the AIAMappingCustomizer Enterprise Role to a user:

  1. Open Oracle WebLogic Server Administration Console.

  2. Navigate to Security Realms, myrealm, Users and Groups and select the user.

  3. In the Settings for <User> screen, select Groups tab.

  4. Move AIAMappingCustomizer from Available to Chosen.

  5. Click the Save button.

    The Mapping Editor panel becomes available in the Oracle AIA Foundation Pack console for that user.

33.2.2 Deploying the AgileAPI.jar File as a Shared Library

Deploy the AgileAPI.jar as a shared library to enable users to retrieve user-defined names for Agile flexfields and display them for editing on the Mapping Editor page as described in Show Flexfield Names in Table 33-2.

The Mapping Editor uses the AgileAPI.jar file to retrieve the flexfield names for transformations whose source or target system is Agile.

Out-of-the-box, a stub version of the AgileAPI.jar file is deployed on the SOA server under the AgileAPI 1.0, 0.0 shared library. However, at this point, if you try to edit an Agile XSLT file in Mapping Editor, the Warning on Flexfield Names error displays, as shown in Figure 33-1.

Figure 33-1 Warning on Flexfield Names Error

Warning on flexfields

Select the Don't display this warning again option if you don't want this error to display again during the current session for the system(s) listed in the Warning on Flexfield Names dialog.

To enable flexfield name functionality, you must deploy the AgileAPI.jar file as a shared library to the WebLogic server. The AgileAPI.jar file uses the wlsauth.jar and crypto.jar files. These three JAR files must be available at runtime. In addition, the wlsauth.jar and crypto.jar files must be a part of the classpath when you start the SOA server.

You can access the AgileAPI.jar, wlsauth.jar, and crypto.jar files from the following locations on the Agile server:

  • <AGILE_HOME>/integration/sdk/lib/AgileAPI.jar

  • <AGILE_HOME>/<AGILE_DOMAIN>/lib/wlsauth.jar

  • <AGILE_HOME>/<AGILE_DOMAIN>/lib/crypto.jar

The location of <AGILE_HOME> depends on your installation.

The Mapping Editor supports only AgileAPI.jar file versions that are binary-compatible with Agile 9.3.1.2, 9.3.2, and 9.3.3 versions.

For more information about using Agile APIs, see the SDK Developer Guide - Using Agile APIs available in the Agile PLM 9 Documentation library.

To deploy the AgileAPI.jar file as a shared library:

  1. Deploy the AgileAPI.jar file as a shared library in the WebLogic server.

    The deployment sequence can be 370. The deployment sequence must be prior to 505.

    For information about how to deploy a shared library, see "Deploying Shared Java EE Libraries and Dependent Applications" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.

  2. Redeploy the AIAHomeApp.ear file.

  3. To make the wlsauth.jar and crypto.jar a part of the classpath used by the SOA server at runtime, access the setDomainEnv.sh file located in your Fusion Middleware domain: <FMW_HOME>/user_projects/domains/soainfa/bin.

    Search for the declaration of the PRE_CLASSPATH variable. Append the absolute paths to the wslauth.jar and crypto.jar files to the PRE_CLASSPATH.

    For your reference, this is the default PRE_CLASSPATH configuration: PRE_CLASSPATH="${SOA_ORACLE_HOME}/soa/modules/user-patch.jar${CLASSPATHSEP}${SOA_ORACLE_HOME}/soa/modules/soa-startup.jar${CLASSPATHSEP}${PRE_CLASSPATH}"

  4. Save the setDomainEnv.sh file.

  5. Restart the SOA server.

Users can now view user-defined flexfield names for Agile transformations on the Search For Mapping Page, as well as edit Agile transformations on the Mapping Editor page.

33.3 Working with the Search For Mapping Page

To launch the Search For Mapping page, navigate to the Oracle AIA Foundation Pack console and click the Go button in AIA Mapping Editor section.

The Search For Mapping page is displayed as illustrated in Figure 33-2. This page has two sections. The top section enables you to enter search criteria. The bottom section lists transformation files (.xsl) that are available to customize. Transformation files contain the individual mappings that convert data from the source to target in the integration. The list shown is derived from the MapperConfiguration.xml file.

Figure 33-2 Search For Mapping Page

This image is described in surrounding text.

Use the filters provided in the Filter area to help you locate the transformation file you want to customize. Table 33-1 lists the filters and their descriptions.

Table 33-1 Filters Area on the Search For Mapping Page

Field Description

Match

Enables you to retrieve transformations based on All or Any of the search parameters.

Transformation Name

Name of the transformation file (.xsl) in the file system.

Service Solution Component

Name of the Service Solution Component in Project Lifecycle Workbench.

Source System

The originating application system.

Business Task

Name of the Business Task in Project Lifecycle Workbench.

Target System

The receiving application system.

PIP

Name of the Process Integration Pack (prebuilt integration provided by Oracle) in Project Lifecycle Workbench.

Customized

Filters transformations based on whether they have been customized or not.

Enter search parameters in any of the Filter fields and click Search.

Use the controls describes in Table 33-2 to act upon mapping search results.

Table 33-2 Controls on the Search For Mapping Page

Control Description

Edit

Click to edit the selected transformation to apply custom mappings.

Show Flexfield Names

Used in combination with the Edit button. When selected, the system dynamically queries the source or target application metadata to retrieve user-defined names for flexfields and display them as the business alias on the Mapping Editor page.

Note: E-Business Suite and Agile are the supported applications in this release.

If you get a Warning on Flexfield Names message when editing Agile mappings, see Section 33.2.2, "Deploying the AgileAPI.jar File as a Shared Library".

If you get a warning message when editing E-Business Suite mappings, then you should troubleshoot using the warning message content and SOA server logs.

Deploy

After you customize the mappings, click to merge the customization layer with the base file and deploy the impacted composite services to the runtime server.

Remove Customizations

Click to remove all customized mappings from the selected transformation.

33.4 Editing Transformations

To edit the transformations:

  1. Select a transformation.

  2. Optionally, if the source or target system is E-Business Suite or Agile, check the Show Flexfield Names option to view user-defined names for flexfields.

    Note:

    When you select this option, loading the mappings may take longer.

  3. Click the Edit button.

    The Mapping Editor page is displayed.

33.4.1 Mapping Editor Page

The Mapping Editor page, as shown in Figure 33-3, enables you to view existing mappings and extend them. The Mapping Editor is preloaded with existing mappings from the selected Transformation. It enables you to add, change, and delete individual mappings. The Mapping Editor page is divided into multiple frames.

Figure 33-3 Mapping Editor Page

This image is described in surrounding text.

33.4.1.1 Page Header

  • Displays the name of the transformation file (.xsl) being edited.

  • Save and Close: This button saves mapping changes to the customization layer, and returns to the Search for Mapping page.

  • Cancel: This button returns you to the Search for Mapping page without saving mapping changes.

33.4.1.2 Target Frame

The first frame you see on the top left is the Target frame. It has target schema name and displays target schema elements. The Mapping Editor is designed to enable you to build the output document. The page is arranged this way so that you select target elements on the left and drag and drop elements to build the mapping from the right.

  • Target elements are displayed in tree structure. Elements whose children are only attributes are not initially expanded. Expand them to view attribute elements. The tree is initially expanded up to the sixth child. If the sixth child has children underneath it, those children are no longer expanded. The MaxDepth value can be configured in the MapperConfiguration.xml file.

  • Search for Element enables you to search for an element in the tree. Type the name of the element to search and press Enter or click the icon to initiate the search. The next element that contains the entered text is retrieved. Keep pressing Enter or click the icon multiple times to find the next matching elements.

  • All Items, Mapped and Not Mapped options enable you to filter elements.

    • All Items: Displays all the elements of the Target schema.

    • Mapped: Filters the tree to display only those Target elements that are mapped. When a child element is mapped, its parent is displayed to keep the Target schema structure intact.

    • Not Mapped: Filters the tree to display only those Target elements that are not currently mapped. When a child element is unmapped, its parent is displayed to keep the Target schema structure intact even if the parent is mapped.

  • Right click on any element to Show as Top, Collapse All, or Expand All.

  • This frame is divided into two columns. They are Node Name and Mapping Summary.

    • Mapping Summary column is the summary of what has been mapped to the target element. It displays Source elements, Variables, Text and Functions. When a Function is used in mapping, it normally contains a few parameters which involve a combination of Source elements, Variables, Texts, Operators and so on. Since the Mapping Summary column has a limited length which cannot accommodate all the different combinations used in a function, an abbreviated format is displayed to convey that a function was used and the parameters passed to it.

    • Target Elements with customized mappings are marked with a blue dot indicator.

    • When you select the target element, the complete expression is displayed in Mapping section of Mapping Builder frame.

33.4.1.3 Source Frame

This frame on the right displays three sections inside an accordion control: Source Schema, Mapping Components and Variables. All the three sections in the frame have search fields.

  • Source Schema

    • Source elements are displayed in tree structure. Elements whose children are only attributes are not initially expanded. You can expand to view attribute elements under them. The tree is initially expanded up to the sixth child. If the sixth child has children underneath it, those children are no longer expanded. The MaxDepth value can be configured in the MapperConfiguration.xml file.

    • Source elements have check marks to indicate that those elements have already been mapped to target.

    • Search for Element enables you to search for an element in the tree. After typing the name of the element to search, press Enter or click on the icon to initiate the search. The next element which contains the entered text is retrieved. Keep pressing Enter or click the icon multiple times to find the next matching elements.

    • You can drag and drop Source elements to an unmapped Target element or into the Mapping builder. Alternatively, you can click the Add To Mapping button to insert the selected source element into the Mapping builder.

      Note:

      When Source elements are inserted into a mapping, the appropriate relative or absolute path is automatically calculated for you based on the current execution context.

  • Mapping Components: Mapping Components consist of XSL Elements, Functions and Operators.

  • XSL Elements are a subset of the most frequently used elements in the XSL language. All Mapping Statements must start with an XSL Element. The following elements are supported:

    • Attribute: Use this when an attribute is needed to complete the mapping. For example while setting the nil attribute to true.

    • Choose: Use this to specify a condition with multiple cases. The When element is automatically inserted along with Choose.

    • For-each: Use this to map a repeating source element to a repeating target element. For-each statements change the execution context, which may result in automatic adjustment of the relative paths of Source and Variables inside child statements.

    • If: Use this to specify a condition with a single case.

    • Otherwise: Use this statement to specify the final condition under a Choose statement.

    • Text: Use this to specify literal values.

    • Value-of: Use this primary statement to perform the actual mapping assignment.

    • When: Use this to specify a condition under a Choose statement. If Choose is not already a parent statement, than it is automatically inserted along with When.

  • Functions consist of standard XPATH functions such as Date functions, advanced functions, string functions, and so on. There are also frequently used AIA functions such as DVM, XREF and so on.

  • Operators consist of Addition, And, Division, Greater Than, Less Than and so on.

  • The Mapping Component section also supports Search and Add To Mapping.

  • Variables: Displays variables that can be used for a selected Target element. Variables are context sensitive.

    • When a Target element is first selected, any applicable variable is displayed only if the Target element has not been mapped. It can be dragged and dropped to the Target element as a value-of select statement.

    • Variables are also displayed when a row has been selected in the Mapping panel. As long as the variable is applicable for the selected Mapping row, it is displayed.

    • Certain Variables can have a tree structure. You can expand these Variables to see its children and continue expanding until it reaches a leaf node.

      Note:

      When variables elements are inserted into a mapping, the appropriate relative or absolute path is automatically calculated for you based on the current execution context.

    • The Variables section also supports Search and Add To Mapping.

33.4.1.4 Mapping Builder Frame

This frame provides a mapping building utility that enables users to create and edit complex mappings. This frame is on the bottom left. This frame has the following sections.

Mapping Builder Header

  • Target Element: Displays the full path to the selected target element (above in the target frame).

  • Save: Saves the changes made in the Mapping Builder to an internal document in memory. Changes must be saved in one target element before selecting another target element.

  • Cancel: Discards the changes made in the Mapping Builder. The target mapping reverts back to its previous state.

    Clear Mapping: Erases all the mappings made on the Target element.

Context:

Displays relevant contextual information to help the user understand under which conditions and code paths the currently selected target element shall be mapped. Context is not editable. The execution context may include apply templates, match templates, call templates, for-each, choose/when/otherwise and if statements that must be satisfied for the mapping to be executed. This pane is initially collapsed. Click the Restore Pane icon for it to display its content.

Mapping

Displays the complete collection of statements used in the mapping of a Target element. The mapping includes the mapping assignment itself as well as conditional statements which affect the target. Users can insert, edit or delete statements using the following toolbar options:

  • Insert: Provides options to Insert Parent, Insert Sibling Before, Insert Sibling After and Insert Child statements in the Mapping pane. These options are also available in a context menu when a user right clicks on a statement in the pane.

  • Edit: Enables the user to expand the selected statement to display subcomponents that make up the statement. Once expanded, these subcomponents can then be edited. This button and the Edit option in the context menu are only enabled for statements that can be edited. For example value-of select, if, when and so on. Editable statements in the pane are preceded with the pencil icon.

  • Done Editing: This option is enabled after the Edit button is clicked and the selected statement is expanded. After you complete making changes to any of the subcomponents, click this button to complete the change and collapse the statement. Clicking the Save button automatically clicks the Done Editing button.

  • Input Literal: This option is enabled when an expanded subcomponent contains an expression that can be modified to a literal.

  • Delete: This option is enabled when a selected statement or expression is eligible for deletion.

33.4.2 Building Mappings (Examples)

This section, using simple examples, shows you how to use the Mapping Editor page.

33.4.2.1 Building Simple Mappings

You can do simple mapping when no complex conditions are required. For example, you need to map a product ID in source system to a product ID in target system and no conditions are involved, do the simple mapping.

Figure 33-4 Mapping Expression Builder Screen

This image is described in surrounding text.

To do a simple mapping of elements:

  1. Select the element in target frame that need to be mapped.

  2. Select the element you want to map in the source frame.

  3. Drag the source element into the target element row that needs to be mapped.

    Mapping summary column of that row gets refreshed with the source element and the row is highlighted with a blue dot indicating that the element is customized.

    Mapping Builder frame is refreshed with the complete mapping statement for the simple mapping just created. The value-of statement, which is the XSL equivalent of a simple assignment, is automatically added for you.

    You can also map a Variable into the target this way. However, Mapping Components can only be mapped using the Mapping builder.

Note:

To remove the mapping that you have just made, select the element in the target frame and click the Clear Mappings button.

33.4.2.2 Building Complex Mappings

To do more complex mapping that requires conditions, functions, and so on, use Mapping builder.

To create mapping using Mapping Builder:

  1. Select the element in the Target frame.

    • If the selected element is unmapped, an empty row in the Mapping section is added with the text Drag and Drop or Type here.

    • If the selected element is mapped, the complete set of mapping statements for that target is displayed in the Mapping section. You can create an empty row and add a new statement or edit an existing statement before continuing. For more information, see To add a new mapping statement row below.

  2. Select and drag the source element and drop it into the empty row in the Mapping section.

    • The value-of statement, which is the XSL equivalent of a simple assignment, is added for you.

    • Alternatively you can select a source element and click the Add to Mapping Expression button.

  3. Click the Done Editing button once you are done with changes.

  4. Click Save.

To add a new mapping statement row:

  1. Click the Insert button and choose either a parent, sibling before, sibling after, or child row.

    An empty row is inserted in the desired position with the text Drag and Drop or Type here.

  2. From the Mapping Components section, drag and drop an XSL Element onto the new row. For example, select if.

  3. This statement is expanded to display the following required subcomponents.

    • A child row for Test which is a required attribute of the if XSL Element.

    • A new empty child row under Test has been defaulted for you with the text Drag and Drop or Type here… for Test.

  4. Complete the new XSL Element by inserting a valid Source, Function, Operator, or Variable onto the new empty child row. If a Function/Operator is inserted, it is once again expanded to display its required subcomponents. Complete them too.

  5. Click the Done Editing button once you are done with changes.

  6. Click Save.

To edit a mapping statement row:

  1. Select the row you want to edit in the Mapping section.

  2. Click Edit and make necessary changes.

    This statement is expanded to display its subcomponents. Edit existing subcomponents by inserting Source, Function, Operator, or Variables onto the existing subcomponent row.

  3. Click Done Editing button once you are done with changes.

  4. Click Save.

To save all mapping changes:

Once you are done with all the edits, click Save and Close button. This takes you back to Transformations search page. This page helps you deploy the customized transformations.

To discard all mapping changes, click the Cancel button.

Refer to Section 33.5, "Editing Rules for Mapping Editor" section before you proceed with editing expressions.

33.5 Editing Rules for Mapping Editor

This section discusses rules for editing transformations. This section also discusses in detail editing rules for “for-each”.

33.5.1 Definitions

  • Empty Row: A row without a Target Tag, Source element, Mapping Component, Variable or Literal in it. Empty row says “-- Available for D&D or Type ...”

  • Target tag: XML sentence defining the tag for a Target Element.

  • Attribute-Value Template Mapping: The expressions shown in the Expression Builder window for an Attribute-Value Template.

  • Regular Mapping: A mapping that is not for Attribute-Value Template.

  • Mapping Component: A component listed under Mapping Components accordion panel.

  • Sentence: An XML Element or an XML complete sentence.

  • Ancestor Sentence: Parent, grand parent or grand-grand parent or so on sentence excluding shared sentences.

  • Sub-component: Part of a sentence or part of a subcomponent.

  • Shared Sentence: An XSLT sentence which has two or more sibling target elements under its scope.

  • OOTB: Out Of The Box.

33.5.2 Read-only Sentences

The following sentences are read-only:

  • xsl:copy

  • xsl:copy-of

  • xsl:element

  • xsl:attribute

  • xsl:for-each

  • Target tag with attribute-value template

  • An OOTB sentence with a function or operation not listed on the Mapping Components panel

33.5.3 Drag and Drop or Typing

Table 33-3 lists various Drag and Drop (D & D) or typing activities that you can do while editing transformations.

Table 33-3 Drag and Drop or Typing

D&D D&D D&D D&D D&D D&D Type
Mapping Type Parent Destination Source Element XSLT Element XSLT Attribute Function Operator Variable Literal

N/A

N/A

Unmapped Target Element In Target Tree

Yes

No

No

No

No

Yes

No

N/A

N/A

Mapped Target Element In Target Tree

No

No

No

No

No

No

No

Regular

Target tag

Empty Row

Yes

Yes

No

No

No

Yes

Yes

Regular

XSLT Element

Empty Row

No

Yes

Yes

No

No

No

(1) Yes

Regular

XSLT Attribute

Empty Row

Yes

No

No

Yes

Yes

Yes

Yes

Regular

Function

Empty Row

Yes

No

No

Yes

Yes

Yes

Yes

Regular

Operator

Empty Row

Yes

No

No

Yes

Yes

Yes

Yes

Regular

Literal

Empty Row

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

Attribute-Value Template

Any

Empty Row

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

Any

Any

Target Tag

No

No

No

No

No

No

No

Regular

Any

Source Element

Yes

No

No

Yes

Yes

Yes

Yes

Attribute-Value-Template

Attribute

Source Element

Yes

No

No

No

No

Yes

Yes

Regular

Any

Variable

Yes

No

No

Yes

Yes

Yes

Yes

Attribute-Value-Template

Attribute

Variable

Yes

No

No

No

No

Yes

Yes

Regular

Any

XSLT Element

No

No

No

No

No

No

No

Regular

Any

XSLT Attribute

No

No

No

No

No

No

No

Regular

Any

Function

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Regular

Any

Operator

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Regular

Target

Literal

No

No

No

No

No

No

Yes

Regular

Text XSL Element

Literal

No

No

No

No

No

No

Yes

Regular

Select attribute of value-of XSL Element

Literal

Yes

No

No

Yes

Yes

Yes

Yes

Attribute-Value-Template

Any

Function

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

Attribute-Value-Template

Any

Operator

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

Attribute-Value-Template

Any

Literal

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

(2)Not possible

Any

Any

Any Read Only

No

No

No

No

No

No

No

(1) Yes: Valid for <xsl:text>. Other xslt sentences will error at runtime

(2) Not Possible: User cannot create an empty row for that parent

Note:

When you add more than one child element with different attributes, the Mapping Editor saves both the child elements. When you add two child elements with the same attribute, the Mapping Editor saves only one attribute. This is the expected behavior.

33.5.4 Inserting a Row

The Table 33-4 discusses situations when a new row can be inserted.

Table 33-4 Rules while Inserting a Row

Insert as Insert as Insert as Insert as
Mapping Type Parent of a Selected Row Selected Row Parent Child Sibling Before Sibling After

Regular

None

Any

Yes

Yes

No

No

Regular

Any

Target tag

Yes

Yes

Yes

Yes

Regular

Any

XSLT Element

Yes

Yes

Yes

Yes

Regular

XSLT Element

XSLT Attribute

No

(1) Yes

Yes

Yes

Regular

Any

Function

No

Yes

No

No

Regular

Any

Operator

No

Yes

No

No

Regular

Sub-component

Literal as subcomponent

No

No

No

No

Regular

XML Sentence

Literal as value of a XML Sentence

Yes

No

No

No

Regular

Any

Source Element

No

No

No

No

Regular

Any

Variable

No

No

No

No

Attribute-Value Template

Any

Any

No

No

No

No

(1) Yes: Valid for <xsl:text>. Other xslt sentences will error at runtime

33.5.5 Deleting

This section discusses rules while deleting transformations.

33.5.5.1 Deleting all Mapping rules (Remove All)

  • When the target element is a leaf element, target tag and all child sentences are deleted including variable declarations.

  • When the target element is a parent element, mapping editor does not allow the parent to be deleted until all child target mappings are deleted. You must delete child first and then parent.

  • When the Expressions UI shows sentences which are ancestors of the target element tag, the ancestor sentences are not shared with other target and that is the reason they are shown. These ancestor sentences are along with ancestor variables are deleted too.

33.5.5.2 Deleting an individual saved sentence

  • Individual saved sentences excludes sentences for “Attribute-Value Template sentences”.

  • Deleting whole mappings have precedence over deleting individual sentences.

  • A sentence that is created but not saved can be deleted. No rules apply for these.

  • If a sentence to be deleted defines the source execution context (for example, for each), it will be temporally flagged read only, so cannot be deleted.

33.5.5.3 Deleting Sentences in Target Element Tag

  • If the target tag sentence is a Parent Target tag, and the Child Target(s) have mapping(s) then it cannot be deleted.

  • If the target tag sentence has children sentences it cannot be deleted.

  • If the target tag has ancestor sentences, it cannot be deleted.

    Target tag should be the only sentences without any child, parent or ancestor to be deleted.

33.5.5.4 Deleting Attribute-Value Templates

Example of a Attribute-Value template: deleting action="CREATE" of <changeEBO:CreateEngineeringChangeOrderList actionCode="CREATE"> sentence.

Attribute-Value template can be deleted as a whole mapping. Individual rows cannot be deleted.

33.5.5.5 Deleting Sub-Components

  • Deleting an Attribute, Parameter, Operand: Only optional sub-components can be deleted. Required subcomponents cannot be deleted.

  • Deleting a Function, Operator, Literal, Source Xpath, Variable Xpath: They can be deleted.

33.5.6 Editing Rules for For-Each

This section discusses editing rules for for-each.

33.5.6.1 Definitions

  • Execution Content: Execution context is a scope concept. When an execution context is defined, each child XSL sentence inherits the execution context. The execution context is mainly defined by the following XSLT sentences:

    • <xsl:template match='xxxx'>

    • <xsl:apply-template select='xxx'/>

    • <xsl:for-each select='xxx'/>

      “xxx” is the XPath expression defining the execution context.

  • Execution Context Definer: An XSL sentence that defines an execution context.

  • Execution context based on the Payload or a Variable: An execution context can be defined with a path (relative/absolute) to the payload (source) or to a Variable. The XPath expressions with relative paths access the information from the current execution context. In other words, when the execution context is based on a variable, the relative paths access the variable content and not the payload content.

  • Execution Context Dependent (ECD) sentence: An ECD sentence is a sentence with an XPath which has any relative paths.

    Attribute-Value Template is not XSLT. However, for this document they are considered as ECD sentence if the value assigned to the attribute uses a relative path.

  • Unknown Execution Context: It happens when a sentence which defines the Execution Context (for-each, apply-template and so on.) has an invalid XPath or a valid XPath but is using a complex XPath which the mapper cannot decipher. The Execution Context is flagged as Unknown for that sentence and its scope.

  • Not Editable Sentence: A sentence which is either not displayed on the Expression builder, like:

    • Variable declarations

    • Template invocations

    • Template declarations

    • A ReadOnly sentence

    • A sentence with wildcard XPath (//xxx)

33.5.7 Allowing Changing Execution Context

  • Out of the Box (OOTB) for-each: If the OOTB for-each scope involves Not Editable ECD sentences, the <xsl:for-each> sentence is set as ReadOnly.

    If the OOTB for-each has an Unknown Execution Context, the <xsl:for-each> sentence is set as ReadOnly.

  • OOTB Unknown Execution Context: When a context definer sentence defines an Unknown Execution Context, all ECD child sentences are set as Read Only.

  • Drag and Drop <xsl:for-each> or Editing an existing <xsl:for-each>: A <xsl:for-each> can be dragged and dropped or edited as long as:

    • There is no Not Editable ECD sentence under the scope of the new for each. If there is any Not Editable ECD sentence, an error pops-up.

      When inserting a <xsl:for-each> as an ancestor sentence of the tag sentence of a Parent Target, then the mapping sentences for the target's child mappings are within the scope of the new for-each. Those sentences are also evaluated as Not Editable ECD sentence.

    • There is no child sentence in edit mode. If a child sentence is in edit mode, an error pops-up.

  • Removing< xsl:for-each>: An xsl:for-each can be removed except when:

    • It is Read Only.

    • The <xsl-for-each> scope involves Not Editable ECD sentences.

33.5.8 Adjusting Relative Paths when Execution Context Changes

When a <xsl:for-each> is added, changed or deleted the execution context is changed.

When the Execution Context changes the ECD child sentences (sentences under the new <xsl:for-each> scope> are adjusted to keep accessing the same data as before the new context was introduced. Mapper will try to keep relative paths as much as possible.

When the new execution context changes from payload to a variable (or backwards) or from a variable to another variable, the ECD child sentences are adjusted to use absolute paths in order to keep them accessing the same data as before the execution context change.

When the new execution context changes from one location to another within the same payload or variable, the ECD child sentences are adjusted keeping relativity paths. This is done by using the XPath navigation commands (“../”, “.”, “/”)

Sentences with absolute paths are not adjusted on an execution context change.

For ECD sentences displayed on the Expression Builder, a user sees the relative paths adjusted immediately. The ECD child sentences for child target mappings are auto-adjusted when the Save button is clicked.

The Table 33-5 lists a few examples of relative path getting adjusted when execution context changes.

Table 33-5 Examples of Relative Path Getting Adjusted when Execution Context Changes

Execution Context changed from -> to (next row)

XPath to employee first name is adjusted from -> to (next row)

/company/employee/employee/name

first_name

/company/employees/employee

name/first_name

$department

/company/employee/employee/name/first_name

/company/employees/employee

/company/employee/employee/name/first_name

Execution Context changed from -> to (next row)

XPath to Company's phone number name is adjusted from -> to (next row)

/company/employee/employee/name

../../../phone_number

/company/employees/employee

../../phone_number

$department

/company/phone_number

/company

/company/phone_number

Execution Context changed from -> to (next row)

Absolute XPath to Company's city address. It is not adjusted.

/company/employee/employee/name

/company/address/city

/company/employees/employee

/company/address/city

$department

/company/address/city

Execution Context changed from -> to (next row)

XPath to Department Name from the variable $department. It is not adjusted because it is an absolute path.

/company/employee/employee/name

$department/name

/company/employees/employee

$department/name

$department

$department/name

33.6 Understanding Customization Layer

  • There is no need to put custom code in the _Custom.xsl which was recommended previously as the Mapping Editor leverages MDS Layered Customizations.

  • Using the Mapping Editor, you can now modify the existing transformation and changes are saved in the new mdssys folder.

  • The mdssys folder contains subfolders with mapperui. This subfolder contains an xml file whose name matches the xsl that was modified. For example, AgileCreateEngineeringChangeOrderListABM_to_CreateEngineeringChangeOrderListEBM.xsl.xml.

  • The xml file contains the mapping changes made to the original xsl file. These mapping changes are marked with unique xml:id=”mapperui_xxx. The mappings in this file are merged with the out-of-the-box and displayed accordingly in the Mapping Editor.

  • The mappings in the Customized Layer are not affected during pre-built integration upgrade or while applying patches.

33.7 Deploying Edited Transformations

The transformations that are customized have a mark in the customized column. To deploy the customized transformation, select the transformation and click the Deploy button.

The system does the following when you click the Deploy button:

  1. Merges the Customization Layer with the base XSL file to create a Merged file.

  2. Generates a custom Deployment Plan for the selected composite services.

  3. Runs the custom Deployment Plan using the Foundation Pack AID utility, which redeploys the selected composite(s) to the runtime server.

33.8 Removing Customizations

To undo the customization that you have done to the transformation, select the customized transformation and click the Remove Customizations button.