Use Business Document Paths

When an Axway Server applies the processing instructions specified using Mapping Services, certain instructions must be applied to data found in specific nodes or node sets in the structure of an input Business Document. To identify these points, you define Business Document Paths.

You can define Business Document Paths in the:

  • Validation Rule of a Business Document to specify the values used to validate the content of the Business Document.
  • Decision path of a DML Block to specify when to generate output Business Documents.
  • Map of a DML Block to specify how to generate an output Business Document.

Methods for defining a Business Document Path

To define a Business Document Path, you can use several basic methods. This topic presents a series of cases that demonstrate when and how to use each method:

  • Case 1: Most of the time, the only identification you need to supply is the name of the node itself.
  • Case 2: When two or more nodes have the same name.
  • Case 3: When a node is outside the current context.

Before you begin: Current context

To identify nodes in a Business Document Path, the Map Engine server starts at a location in the Business Document that is referred to as the current context. By default, the current context is the root node (that is, the first node) of the Business Document.

In the Map of a DML Block, the instructions for each(BusinessDocument_Path) and for each do(BusinessDocument_Path), move the current context away from the root to a node that is specified via BusinessDocument_Path. This new context is valid for all of the child nodes that are descendent of the node that carries the for each or for each do instruction.

The instruction for each moves the content away from the root.

Case 1: Most common situation...

Most often, you define the path to a node in the tree structure of a Business Document using the name of the node. When the software encounters this type of path, it starts at the current context (by default, the root) of the Business Document and searches down through the tree until it encounters that node name.

To specify the name of:

  • Attribute nodes, enter the commercial at symbol (@) followed by the name of the node (for example, @node_name).
  • For all other nodes, enter the name of the node.

In Map expressions

In a Map expression, the cardinality of both the input and output nodes affects how you define a Business Document Path.

  • When the output node has single cardinality (0-1, 1-1) and the cardinality of the input node is multiple, use one of the following in the Path:
  • When the output node has multiple cardinality (0-n, 1-n), use one of the following DML instructions in your Path:

The following example illustrates how to use the name of a node to define a Business Document Path:

Business Document tree structure What happens at execution

Business Document icon Purchase_Order

Parent element icon Customer 1-n

Leaf element icon Name 1-1

Leaf element icon Address 1-1

Leaf element icon Telephone_Number 1-n

When the Map Engine server encounters the Business Document Path, it identifies every occurrence of Address in the Business Document.

The cardinality of:

  • Customeris multiple (1-n)
  • Address is single (1-1)

For each occurrence of Customer in the Business Document, the Mapping Services Server identifies one occurrence of Address.

Case 2: When two or more nodes have the same name

When two nodes have the same name in a Business Document, the name of the node cannot by itself uniquely identify each instance of the name in the tree structure. In this case, the way you define the Path to the node depends on whether the current context is the root of the Business Document or another location that is defined using the for each (or for each do) instruction.

When the root is the current context

When the root is the current context of a Business Document, identify each instance of nodes that have the same name in the tree structure via the relevant parent node. The following example illustrates how to refer to each occurrence of a node in a tree structure when the root is the current context:

Business Document tree structure Business Document Path

Business Document icon Purchase_Order

Parent element icon Customer 1-1

Leaf element icon Name 1-1

Leaf element icon Address 1-1

Leaf element icon Telephone_Number 1-1

Parent element icon Seller 1-1

Leaf element icon Name 1-1

Leaf element icon Id_Number 1-1

To identify the name of the customer (the first instance of Name), type Customer\Name.

Alternatively, you can type \Purchase_Order\Customer\Name.

To identify the name of the seller (the second instance of Name), type Seller\Name.

Alternatively, you can type \Purchase_Order\Seller\Name.

When a for each instruction (or for each do instruction) defines the current context

In the Map of a DML Block, the for each and for each do instructions define the current context for the Paths that follow and refer to them. The following example illustrates how to refer to each occurrence of a node in cases where for each defines the current context in a Map:

Output Business Document tree structure Business Document Paths Input Business Document tree structure

Business Document icon Invoices

Leaf element icon Seller ID (1-1)

Parent element icon Buyer (1-n)

Leaf element icon Name (1-1)

Leaf element icon Address (1-1)

Parent element icon Receiver (1-n)

Leaf element icon Name (1-1)

 

 

 

 

Seller

for each Purchased_By

Name

Address

for each Send_To

Name

Business Document icon Purchase_Orders

Leaf element icon Seller_ID (1-1)

Parent element icon Purchased_By (1-n)

Leaf element icon Name (1-1)

Leaf element icon Address (1-1)

Leaf element icon Telephone_Number (0-n)

Parent element icon Send_To (1-n)

Leaf element icon Name (1-1)

Leaf element icon Address (1-1)

Leaf element icon Telephone_Number (0-n)

Because each Business Document Path Name follows the for each (which modifies the current context), each Name identifies a unique location in the input Business Document. In the:

  • First case, for each sets the current context to Purchased_By
  • Second case, for each sets the current context to Send_To

Case 3: When a node is outside the current context

In the Map of a DML Block, the for each and for each do instructions define the current context for the Paths that follow and refer to them. However, sometimes you need to define a Path below a for each or for each do instruction that does not reuse (refer to) the current context. To identify a node outside the current context, you can define:

  • An Absolute Path
  • A Relative Path

Absolute Path

An Absolute Path instructs the software to start at the root of the Business Document and identify the first node that matches the name you specified in the Path.

To define an Absolute Path, start at the root of the tree structure and list the name of each parent node that nests the node you want to identify. For example, end the Path with the name of the node you want for to identify.

Relative Path

Using the Business Document Path syntax, a Relative Path instructs the software to start at the current context of the tree structure and identify a target node in terms of a source node. From the current context, the software moves up or down in the tree structure.

Although you use Relative Paths to leave the current context in a Map, you can use them anywhere you define Business Document Paths. In the absence of a for each or a for each do instruction, the root of a Business Document is always the current context. Use the syntax of Relative Paths as shortcuts for defining Business Document Paths that refer to the root of a Business Document. See Business Document Path Syntax for more information.

Examples

The following example illustrates and explains possible Absolute and Relative Paths that can be used in a Map to identify nodes in an input Business Document. In a Map, Business Document Paths are defined for and stored with the nodes of the output Business Document. To simplify the following example, the output Business Document tree structure is not displayed.

Input Business Document tree structure Business Document Paths What they do

Business Document icon Purchase_Order

Parent element iconCustomer_Seller (1-n)

Parent element icon Customer (1-n)

Leaf element icon Name (1-1)

Leaf element icon Address (1-1)

Leaf element icon Telephone_Number (0-n)

Parent element icon Seller (1-n)

Leaf element icon Leaf element icon Name (1-1)

Leaf element icon Id_Number (1-1)

for each Seller

Defines the current context as Seller in the input Business Document.

Name

Uses the current context that is defined via for each Seller to evaluate the expression. This is a Relative Path.

The software:

  • Identifies Name that is nested in Seller
  • Does not identify Name that is nested in Customer

\ Purchase_Order\ Customer_Seller\ Customer \ Name

Instructs the software to leave the current context that is defined via for each Seller. This is an Absolute Path.

The software follows an Absolute Path and:

  • Identifies Name that is nested in Customer
  • Does not identify Name that is nested in Seller

..\Customer \Name

Uses the current context that is defined via for each Seller to locate another node. Via Business Document Path syntax, this node is identified in terms of how it is related to the current context. This is a Relative Path.

Via two periods (..\), the Path identifies the parent of the current context, which is Customer_Seller.

Via Customer\Name, the Path identifies Name in Customer.

Keep in mind that the current context can only be the root of a Business Document or a node that is defined via the for each or for each do instruction. You cannot define a Relative Path that uses another Relative Path as a starting point. In the preceding example, this means that you cannot define a Relative Path that uses ..\Customer\Telephone_Number as a starting point.

Business Document Path syntax

When you define Business Document Paths, referring to the names and locations of nodes can require a lot of effort and time. For this reason, the DML includes a set of characters that you can use as shortcuts to define Paths. These shortcuts can help you quickly identify:

  • A node set without naming every node in the set
  • A node in terms of how the node is related to the current context
  • A node without using the location of the node
  • A node without using the name of the node
  • A node based on the position of the node in a node set
Note If the name of a node does not conform to the syntactic rule, is a reserved word or contains only digits, you must surround the node name with exclamation point characters (!). For example:

!my element!

!else!

Use Aliases in the Business Document Path

If the DML Block has two or more input Business Documents, you must indicate the Alias of the Business Document in the path. During processing, by default, the Map Engine selects the first Business Document in the list of the input Business Documents.

In the path for the element of the first input Business Document, it is not necessary to indicate the Alias. However, it is recommended to indicate the Alias for better readability of the expressions when there is more that one input Business Document.

To indicate an Alias use the syntactic:

alias:path

or

!alias!:path

The notation (!) is necessary when the Alias contains only digits or corresponds to a reserved-word.

For example:

in1:root\elem01 + in2:root\parent\elem01

Where inl is the alias.

Table of syntactic characters

The following table presents the syntactic characters that you can use to define Business Document Paths:

Use this... To refer to...

\

(backslash) the root

.

(period) the current context

\\*

(backslash backslash asterisk) all Descendants of the root

*

(asterisk) all Descendants of the current context

..

(period period) the parent of the current context

[index

The position of a node in a node set

For example, when the Map Engine server encounters the Business Document Path node_A [6], it returns the sixth instance of node_A. If this instance does not exist, it returns the value absent.

@nodeName

All attributes descending from the current context that have the same name.

@@

All nodes with values that descend from the current context.

this

Each instance of a node in the current context.

this\\*

All Descendants of the current context.

To filter the nodes that you specify via a Business Document Path, define a where clause.

Examples: Starting at the root

The following table illustrates how to use Business Document Path syntax to define Business Document Paths that start at the root of a Business Document:

This syntax... Identifies...

\\NodeName

All instances; of NodeName

\\NodeName [1]

The first instance of NodeName

\*

All Children of the root

\*[1]

The first child of the root

\\*

All Descendants of the root

\\*[1]

The first Descendant of the root

Examples: Start at the current context

The following table illustrates how to use Business Document Path syntax to define Business Document Paths that start at the current context of a Business Document. Unless you specifically modify the current context via the for each or for each do instruction, the current context is the root:

This syntax... Identifies...

NodeName

All instances of below the current context NodeName

.\\NodeName

this\\NodeName

NodeName [1]

The first instance of > below the current context NodeName

NodeName\*[1]

The first child of all occurrences of NodeName

.\\NodeName\*[1]

The first child of all occurrences of NodeName

this\\*

All Descendants of the current context

this\*

All Children of the current context

.\*

*[1]

The first Descendant of the current context

..

The parent of the current context

..\*

All Children of the parent of the current context

Example: Use this

The reserved word this refers to each instance of a node in the current context. The following example illustrates how to use this to refer to each instance of a node that is defined in a Map via a for each do instruction:

Output Business Document Definition Map Expressions Input Business Document Definition

Parent element icon CD_List (1-1)

Parent element icon CD_Out (1-1)

Leaf element icon Total (1-n)

 

 

for each Price do this + this*.07

Parent element icon CD_List (1-1)

Parent element icon CD_In (1-1)

Leaf element icon Price (1-n)

Because the Total node has multiple cardinality, (1-n), the for each do instruction is used in the Map to define the number of times that this node occurs in the output Business Document. The following illustrates the input and output Business Document for the preceding for each do instruction:

Output Business Document Input Business Document

Parent element icon CD List

Parent element icon CD Out

Leaf element icon Total=10.70

Leaf element icon Total=21.40

Parent element icon CD List

Parent element icon CD In

Leaf element icon Price=10

Leaf element icon Price=20

In this example:

  • for each Price moves the current context from the root of the Business Document to the Price node and identifies every instance of the Price node.
  • this + this * .07 instructs the Map Engine server to use the value that is stored in every instance of the Price node to calculate the total price of each CD purchased.

However, you could not enter: for each Price do Price> + Price*.07.

Here, for each Price moves the current context from the root of the Business Document to the Price node. However, Price + Price * .07 indicates that Price is a child of the current context, which is also Price. To refer to each instance of a node that is defined as the current context, use the reserved word this.

See for each-do for more information.

Related Links