Configure mappings

Overview

In Axway Decision Insight (DI), use mappings to configure how to absorb instances and values.

To access the Mappings screen, click the Data Integration  icon. On the left menu, click Mappings

This page details all the areas of the Mappings screen.

User interface

Parameters (1)

All available parameters that a user can use in a mapping configuration. A parameter is composed of:

  • A name
  • A type
  • An optional field for expressions, only used for routes. Describes how to retrieve values from incoming exchanges:
    • If defined, this expression is used to retrieve the values.
    • If not defined, a standalone node or a technical cluster expects that the incoming body exchange is a map, and uses the values with the parameter name as a key.

For simpler use of mappings in routes, it's recommended to use a map as the body exchange and store all values in it.

Create a parameter

To create a parameter, click the Add parameter hyperlink:

Note: When you create a new parameter, do not leave the Name field empty. Space characters at the beginning or at the end of the name are ignored.

Edit a parameter

User can edit

  • parameter name
  • parameter type
  • Optionally, the expression used to retrieve value from incoming message

Add Instance Operation button (2)

Each data absorption defined in Mappings produces a single transaction. Click the Add Instance Operation button to group operations on several entities into a single transaction. If one of the operation fails, the rest of the absorption is reverted.

Note:  You can also group several absorption calls into a single transaction. For more information, see How to group absorptions.

Default times configuration (3)

You can define the default times used for resolution and operations.

Time Description Used by Default value if empty
Resolution Time at which the instance should be resolved
  • Resolution of an instance by key
  • Resolution of a relation target instance by key
Current time (now)
Operations begin Time at which the operations begin
  • Begin time of any attribute or relation change
  • Begin time of any attribute or relation removal
  • Time at which a key is bound
  • Time at which a key is unbound
Current time (now)
Operations end Time at which the operations end
  • End time of any attribute or relation change
  • End time of any attribute or relation removal
Deletion time of the instance

Special values

Value Description Valid for
Resolution Operation begin Operation end
FROM_APPLICATION_START From the start instant of the application (tick) (tick) (minus)
FROM_INSTANCE_CREATION From the creation of the resolved instance (minus) (tick) (minus)
UNTIL_END Until the end of time (minus) (minus) (tick)
UNTIL_CHANGED Until the next stored value change (or end of the instance) (minus) (minus) (tick)
UNTIL_INSTANCE_DELETION Until the instance deletion (or end of time if instance is not deleted) (minus) (minus) (tick)
NOW Current instant (tick) (tick) (tick)
TODAY Current day at midnight (server time) (tick) (tick) (tick)
YESTERDAY Yesterday at midnight (server time) (tick) (tick) (tick)
FROM_START (warning) From 1970-01-01 (tick) (tick) (minus)





To use a special value, use a constant with the following value: FROM_INSTANCE_CREATION

FROM_START constant is still present for compatibilty purpose, application developpers must use FROM_APPLICATION_START instead.


Parsing

There is a Utility function for parsing dates,

example:

 <!-- Parse the given date -->
<u:date-parse pattern="yyyy-MM-dd HH:mm:ss">
    <!-- Expression to use in order to retrieve the date -->
    <simple>${body[date]}</simple>
</u:date-parse>

It is recommended to parse the date in the route, store the result in the body map, and use the parsed date in the mapping.

Resolution type (4)

There are two ways to resolve an instance of a particular entity.

Type Description
Key Using one of its keys. Each attribute and relation of the key must be defined otherwise, you will get an error message.
Instance Identifier Using its unique identifier which can be retrieved using Events (instance ID or instance UUID)

Key resolution options (5)

These options are only available when you select the resolution by Key option The options are not available if you select the instance id option.

Resolution option Description Comment
Ignore if instance of Entity not found at resolution time If there is no instance with the given key at the given resolution time, the instance operation or the relation change will be skipped. If a skipped operation contains resolutions in auto-create, the resolutions are created.
Error if instance of Entity not found at resolution time

If there is no instance with the given key at the given resolution time, you will get an error message.

Use this option to update fields on instances that should exist.
Create an instance of Entity if not found at resolution time or after

If there is no instance with the given key at the given resolution time or after, an instance is created.

Use this option if you want to update fields on instances, but don't know if they have already been created or not.
Create an instance of Entity if not found at resolution time

If there is no instance with the given key at the given resolution time, the instance is created.

This option is much faster than the previous one, but it may lead to inconsistent data in the database if an instance is already defined with this key later on.

Make sure that all operations on a single instance are time ordered. If you cannot guaranty that, use the previous option.

Resolution time override (6)

If not checked, the resolution time of the instance will be the default one. Check this option to force the user to define a resolution time that will override the default one.

Parameters and constants usage (7)

On first combo box, you can select:

Parameters

Use the drop-down to select parameters specified in parameters part. Parameters are filtered by type:

Constants

You can specify a literal string representing a constant value.

Some examples:

  • for a string: myStringValue
  • for an instant: UNTIL_END
  • for a decimal: 10.5

Empty values are allowed.

Add an operation chooser (8)

Once an instance is resolved you can perform several operations on it.

Operation Description
Change value(s) of attribute Defines the value of a particular attribute or relation of your instance.
Remove value(s) of attribute Removes the value of a particular attribute or relation of your instance.
Bind key

Changes the values of the key attributes or defines another key of the instance.

Unbind key Removes the values of the key. If there is no longer any key with values, the instance is deleted.
Set space Defines the space of an instance. It is only available for entities of type configuration.
Remove space Removes the space of an instance. It is only available for entities of type configuration.

Operation types on attributes (9)

Different operation types are available when changing or removing the values of attributes or relations.

For mono-valued members

Operation Type Description
Change value(s) of attribute Update

The attribute or relation is modified if the new value is different from the previous one, sometimes on the validity interval.

Additionally, if the storage already contains the new value on a validity interval overlapping the beginning or the end of the new validity interval, the new validity interval is extended.

Add The attribute or relation is updated with a new valid time, no matter the previous value.
Initialize

The provided value is added to the set between operation begin and operation end, only when the instance is created or extended.

If the instance is then updated or re-absorbed, this operation will have no effect. When the instance already exists and is not extended, this operation is skipped.

When extending an instance, if the storage already contains the new value on a validity interval overlapping the beginning or the end of the new validity interval, the new validity interval is extended.

Performance optimization

You typically use this setting if the mapping is too slow and called multiple times to update a large number of members.

Remove value(s) of attribute Remove The attribute or relation is removed if the saved value is equal to the current one.
Clear The attribute or relation is remove,d no matter its saved value.

To better understand how these operations works, read Mapping operations examples.

For a multi-valued members

Operation Type Description
Change value(s) of attribute Update

The provided value is added to the set between operation begin and operation end, only it is not already part of the set of existing values.

However, when intervals of new and previous values intersect and the values are the same, then these values are updated
on the merged interval.

Add The provided value is added to the set between operation begin and operation end, no matter what the existing values are.
Initialize

The provided value is added to the set between operation begin and operation end, only when the instance is created or extended.

If the instance is then updated or re-absorbed, this operation will have no effect. When the instance already exists and is not extended, this operation is skipped.

When extending an instance, if the intervals of new and updated values intersect and the values are the same, then these values are updated on the merged interval.

Performance optimization

You typically use this setting if the mapping is too slow and called multiple times to update a large number of members.

Remove value(s) of attribute Remove The provided value is removed from the set between operation begin and operation end.
Clear Remove all existing values from the set. After this operation, the set is empty between operation begin and operation end.

To better understand how these operations works, read Mapping operations examples.

Null policies (10)

Configure the desired behavior when the new value is not defined.

Policy Description
Error The user receives an error message. This option must be used if the value must always be defined.
Clear It clears the saved value. This option must be used if no value means there is no longer any value for this field
Ignore It ignores this operation. This option must be used if no value means there is no change to the value

Operation times override (11)

The same way that resolution time can differ from the default one, this section enables you to define custom values for operation begin time and operation end time.

Please note that when updating a rhythmic attribute, only the default begin time is available and must be aligned with the rhythm.

Related Links