Path cardinalities: Select occurrences

Paths to nodes are used in expressions to address data that resides in input Business Documents. Review the following if you need to develop a DML Block that fills the amount node in the following document:

invoice               1..1
  line                1..n
      item_id         1..1, class s
      quantity        1..1, class i
      unit_price      1..1, class r
      amount          1..1, class r
   customer           1..1
      name            1..1, class s
      address         1..1
        lines         1..n, class s
        zip_code      1..1, class s
        city_name     1..1, class s
      discount_code   1..1, class i
      id              0..1, class s

The amount node is computed from unit price and quantity using a simple multiplication. The expression that fills the node \invoice\line\amount is:

\invoice\line\unit_price * \invoice\line\quantity

The problem is that node line is multiple, so both paths in the above expression address more than one occurrence, more than one data element. Performing such a multiplication on more than one value is beyond the capacities of the integration engine. This expression is rejected with a path cardinality error.

Paths, similar to nodes, have their own cardinality that restricts their use in expressions. Each individual node that is included in the path impacts the cardinality of the whole path. The integration engine computes the path cardinality by examining each node. If an optional node is encountered, the path is considered as optional; if a multiple node is encountered, the path is considered as multiple. Using the previous example, you can exhibit paths with different cardinalities:

  • \invoice\line\quantity
  • is multiple-mandatory (1..n) because both invoice and quantity are mandatory whereas line is multiple.
  • \invoice\customer\name
  • is mandatory (1..1) because all its components are mandatory (1..1).
  • \invoice\customer\id
  • is optional (0..1) because although invoice and customer are 1..1, id is optional.

In most situations, expressions cannot contain paths with multiple or optional cardinalities (either 0..1, 0..n or 1..n). Chapter Handle multiple occurrences describes what can be done with such paths.

If you want to use the quantity of the first invoice line, the bracket specifier has been included in DML for such a situation. You can select one occurrence of a multiple or optional node using that specifier. For example, the following addresses the quantity node of the first occurrence of line:

\invoice\line[1]\quantity

The specifier has turned the original 1..n path \invoice\line\quantity into a 1..1 one because you have selected only one occurrence of line among the potential ones.

The bracket specifier can be used on any node, even on those that are 1..1. Between the brackets is a class I value that specifies the occurrence index, starting at one. That value can be any legal expression. The index can be computed combining literals, variable values or values from nodes of any input document. For example:

\invoice\line[1]\quantity
* \invoice\line[1]\price
* in2:\discount[\invoice\customer\discount_code]\rate

The line amount is computed from quantity and unit price, as expected. A special discount rate is also used that comes from another Business Document on input in2. This later document contains a discount rates list through multiple node discount. The correct occurrence of discount (the correct item in the list) is selected using the discount code as the occurrence index.

The only requirement about the index value concerns its compatibility with class I. At the time you check the expression in Axway Mapping Services, no specific control is done about the value being in a specified range. This is because the number of occurrences is known only at the time data is being processed.

If, by accident or deliberately, the index value is more than the number of occurrences, or less than one, the path would address something that does not exist. As a result, the value would be absent. If your invoice contains only one line where item quantity is 345:

Value Description
\invoice\line[1]\quantity

refers to an occurrence that exists, value is 345

\invoice\line[2]\quantity does not refer to something that exists, value is absent

Related Links