Show TOC

Rules for Service MappingLocate this document in the navigation structure

You can create mapping between attributes and operations of application services, business objects, and external services.

Operation Mappings

If operation S is mapped to operation T, then:

  • T does not have an implementation.
  • At runtime, a call to T is transformed to a call to S. The input message mapping is applied before the call to S, and the output message mapping is applied after the call to S.

The following scenarios are supported:

  • Mapping an external operation to a CRUD/findBy operation of a BO node with remote persistency.
  • Mapping an external operation to an application service operation.
Operation Mapping Rules

Structure of CRUD operations for Mapping

When mapping CRUD operations, refer to the table below:

Operation Input Message Attributes Output Message Attributes Description

create

Custom key, mandatory, default, and optional create attributes

Custom key attributes

Requires only the absolute minimum of parameters for the object to be created. If you need to set values to additional attributes, either mark them as optional create attributes, or call the UPDATE operation immediately after the create one.

If the value of the custom key is generated by the external system, you should map it in the output mapping.

read

Custom key attributes

All attributes

Requires the custom key attributes so that the external system can identify the object.

update

All attributes

None

Requires the custom key attributes to identify the object. All other attributes are required because any of them may need to be changed.

No output is needed because if the operation is not successful, it throws an exception.

delete

Key

None

Requires the custom key attributes to identify the object.

No output is needed because if the operation is not successful, it throws an exception.

Constant Mapping Values

On the Datasource tab page there is a list of all mappings for the selected operation in the table below the mapping trees. You can set constants which are assigned to the target attribute if the result of the attribute mapping is a null value.

To do this, enter the constant in the target attribute Fixed Value field. The Is Null checkbox indicates that there is no value in the Fixed Value field. If Is Null is unchecked and the Fixed Value field is empty, an empty string is used as the value.

Attribute Mappings

It is important to be able to determine unambiguously the cardinality of every target attribute during a concrete message mapping execution. Most of the restrictions below work towards this goal. The examples use these message structures:

There are several types of attribute mappings:

  • Collection mappings (denoted by -c->).
  • Ordinary (simple_attribute-to-simple_attribute and complex_attribute-to-complex_attribute) mappings (denoted by -o->).
  • Constant (constant-to-simple_attribute) mappings - a constant-to-attribute mapping is applied when there is no attribute-to-attribute mapping for the target attribute. That is, if there are both an attribute-to-attribute and a constant-to-attribute mapping for a given target attribute, then the attribute-to-attribute one has a higher priority.

Common Conditions

  • Each type of mapping has exactly one target attribute. The constant mappings do not have a source attribute; the collection and ordinary mappings have exactly one source attribute.
  • The source attributes must belong to the source message of the enclosing message mapping. The target attribute must belong to the target message of the enclosing message mapping.
  • A given target attribute may have at most one mapping from every type.

Conditions for Collection Mappings

  • Both the source and the target attributes must be collections (that is, minOccurs > 1).
  • Source collection's minOccurs >= target collection's minOccurs;

    Source collection's maxOccurs <= target collection's maxOccurs - switched on by default, but you can switch it off using the property IgnoreMinMaxOccursConstraints.

  • A given source collection attribute may be mapped to more than one target collection attributes, but none of latter should enclose any of the others.

    Right: A -c-> O and A -c-> Q

    Wrong: A -c-> O and A -c-> O/p

  • There is no restriction about the complexity of both the source and the target collection attributes.
  • All the enclosing collection attributes of the source collection attribute must be mapped.

    Right: A -c-> O and A/B -c-> O/p

    Wrong: A/B -c-> O/p (without A -c-> O)

  • The closest enclosing collection attribute of the source collection attribute must be mapped to an enclosing collection attribute of the target collection attribute.

    Right: A -c-> O and A/B -c-> O/p

    Wrong: A -c-> Q and A/B -c-> O/p

Conditions for Ordinary Mappings

  • Both source and target attributes must be simple, or they may be structures in case they have the same structure or the source structure is a parent of the target one.
  • Source attribute's minOccurs > 1 or source attribute's minOccurs >= target attribute's minOccurs. Source attribute's maxOccurs <= target attribute's maxOccurs.  This is switched on by default, but you can change it using the property IgnoreMinMaxOccursConstraints.
  • A given source attribute may be mapped to more than one target attributes.
  • All the enclosing collection attributes of the source attribute (including itself if it is a collection) must be mapped with collection mappings.

    Right1: A -c-> Q and A/c -o-> Q/r

    Wrong1: A/c -o-> Q/r (without A -c-> Q)

    Right2: A -c-> O and A/d -c-> O/p and A/d -o-> O/p

    Wrong2: A -c-> O and A/d -o-> O/p (without A/d -c-> O/p)

  • The closest enclosing collection attribute of the source attribute (or the source attribute itself if it is a collection) must be mapped to an enclosing collection attribute of the target attribute (or the target attribute itself if it is a collection).

    Right1: A -c-> Q and A/c -o-> Q/r

    Wrong1: A -c-> Q and A/c -o-> O/p

    Right2.1: A -c-> O/p and A/c -o-> O/p

    Right2.2: A -c-> O and A/c -o-> O/p

    Wrong2: A/c -o-> O/p (without A -c-> ...)

    Right3.1: A -c-> O and A/d -c-> O/S and A/d -o-> O/S/t

    Right3.2: A -c-> O and A/d -c-> O/S/t and A/d -o-> O/S/t

    Wrong3: A -c-> O and A/d -o-> O/S/t (without A/d -c-> ...)

Attribute Mapping Rules
  • You can only perform the following types of mapping:
    • Input mapping - input parameters are mapped to input parameters.
    • Output mapping - output parameters are mapped to output parameters.
  • You cannot map input to output, or output to input parameters.
  • You can map one attribute to several attributes.
  • You cannot map several attributes to one attribute.
  • You can map simple attributes to simple attributes.
  • You can map complex attributes to complex attributes. The following conditions must be met: the mapped attributes must be from the same structure, or the source is the parent of the target.
  • You cannot map simple attributes to complex attributes and vice versa.
  • You cannot map references between business objects (associations). All the associations are stored locally. The references are not displayed as attributes in the operation messages at all.
  • You can create collection mappings between structures, if they are collections.
Supported Mapping Types

CAF supports all mappings between attributes with the same simple type as well as the following cases (Java representations of XSD types as defined by JAXB):

  • String to primitive types and java.math.BigDecimal or java.math.BigInteger and vice versa
  • String to enumeration and vice versa
  • Enumeration to enumeration by value (different enumeration types with identical values)
  • Primitive to java.math.BigDecimal or java.math.BigInteger
  • One and the same Java array types
  • Different primitive and primitive wrapper types such as int to long and vice versa.

In all other cases, the generated mapping classes may have compilation errors or may not function properly.

More Information