Routing: Determine route

Event action – Abstract

Purpose: Attempts to determine a relevant route via the Routing table applicable to the data context based on the addressing of a business transaction object (reference object). If a 'suitable' Routing table entry is determined, its data can be transferred to the reference object's attributes.

images/download/attachments/73609732/image2021-7-6_15-15-30-version-1-modificationdate-1625577333247-api-v2.png

The event action Routing: Determine route determines a relevant route via the Routing table applicable for the data context (see Routing table) on the basis of the addressing of a specific business transaction object passed as a reference object. The decisive factor for the assignment of the route is a Routing table entry evaluated as 'suitable' in the applicable Routing table. In addition to the route name, this can also define values for route attributes that can optionally be transferred to the reference object.

Logic for route determination

Step 1: Identify applicable Routing table

The applicable Routing table is assigned according to the best-matching principle depending on the data context.

Step 2: Determine starting point ('From') and end point ('To') of the route

Selected company and address attributes of the reference object are examined depending on the From chain and To chain parameters according to the following scheme to qualify the starting point ('From') and end point ('To') of the route via the characteristics 'Country' and 'Postal code':

  1. The From chain and To chain parameters define the selection and the sequence in which the company and address attributes of the reference object are evaluated via a multiple selection for the Company type.

  2. Each Company type is checked as to whether the respective 'company and address attribute' refers to a company address (company.address) and/or an address (address) for which at least the 'Country' field is specified.

  3. If both a company address and an address exist for the same Company type, the address that additionally contains an entry for the 'Post code' (zipcode) is given priority. If this applies to both addresses, then 'Country' and 'Post code' of the address are used.

  4. Only if no address data is found for the examined Company type, or none of the addresses defines at least the Country, the search is continued with the next Company type in the chain.

Step 3: Search Routing table for matching Routing table entry

If the best matching principle is used to assign an applicable Routing table for the data context, its entries are matched with the Country and post code information previously determined for the starting point ('From') and end point ('To') for the reference object.

Each Routing table entry defines default values for 'From' and 'To', which are determined for the Country as a specific selection and for the 'Post code' as an interval (for a string comparison). Both entries are optional, whereby an entry without a 'Post code' is only evaluated as suitable if no postal code was determined for the corresponding starting or end point. Similarly, an entry that does not specify a Country or postal code for 'From' or 'To' is only considered a match if both characteristics are undefined for the corresponding starting or ending point.

NOTE◄ A Routing table entry that defines neither 'From' or 'To' criteria is not evaluated as a match even if the reference object does not provide address data for either the starting point or the end point.

Step 4: Apply applicable Routing table entry

Provided that a Routing table entry is identified within the applicable Routing table that matches the start and end point characteristics determined in step 2 for the reference object, its detail data is used as follows:

  1. The value of the 'Name' field (name), i.e. the route name, is assigned to the Target field configured in the Routing: Determine route event handling (see 'Configuration').

  2. If the routing table entry defines values for route attributes, these are applied to the reference object taking into account the configuration parameters Copy route attributes to target and Override target attributes.

NOTE◄ A Routing table can contain several entries that specify the same route name, but specify different values for route attributes. The 'From'/'To' criteria should always be selected without overlapping, so that the relevant Routing table entry always applies unambiguously and repeatably.

IMPORTANT

  • Assignments that affect the reference object are not automatically saved, but only affect its volatile data state. Unless the Routing: Determine route event handling is executed in the context of an event such as 'Create' or 'Change' for the reference object, Save changes later event handling can be executed if required to mark the assignments for saving at the end of the transaction.

  • If no Routing table is applicable or the applicable Routing table does not contain a suitable Routing table entry, the Target field is assigned 'No value' (null). The assignment is therefore not omitted, but the target value is deleted if necessary!

Configuration

NOTE◄ Using the Routing: Determine route event action is only useful with a 'Business transaction object' as the reference object, since only this object has the company and address attributes evaluated to determine the route.

  • The Target field parameter provides for the configuration of a value resolver that defines the target of a value assignment for the route name, i.e. the value of the 'Name' field from the Routing table entry determined as suitable. Typically, the text value of a typed attribute of the reference object is referenced at this point. However, other value resolvers (e.g. Variable or List item) can also be used as the Target field, as long as they provide the appropriate target objects for value assignments as a return value.

  • The From chain and To chain parameters each define a multiple selection based on the dynamic enumeration Company type. For the selection, unlike in many other cases, the sequence is relevant, because it determines priority for the evaluation of the relevant company and address attributes. Details on the interpretation are described in 'Step 2' in the section 'Logic for route determination' (above).

  • The option Copy route attributes to target (deselected by default) must be set so that value assignments for route attributes from the Routing table entry are executed in the reference object. Only if the Override target attributes (deselected by default) option is also set, will existing values for the relevant attributes in the reference object be overwritten with the data from the Routing table entry. Otherwise, only values in previously 'empty' attributes will be transferred.

images/download/attachments/73609732/image2021-7-6_15-15-30-version-1-modificationdate-1625577333247-api-v2.png

NOTE◄ As can be seen in the screenshot, a value resolver for static text appears by default for the Target field parameter. This is systematically justified, since a text is expected as the route name. Since the value resolver is supposed to define the target for an assignment, a static assignment or the direct input of text instead of a reference to a suitable target serves no purpose. However, it does not cause an error either. If a static text is entered, the route name is simply not assigned.

Example

When saving ('Create'/'Modify', see Common action event) Shipments, an attempt should be made to determine the applicable 'route' using Routing tables:

  • For the starting point ('From'), the addressing for the Company type 'Loading party' (DPA) or – alternatively – the address for the 'Principal' (AAL) is evaluated.

  • The end point ('To') is to define the addressing for the Company type 'Consignee' (CNE).

If a route can be identified, certain event actions (e.g. Show alert (Popup), Export, etc.) are executed. In addition, the values of route attributes are taken over into the shipment, as long as no corresponding data is yet available.

NOTE◄ The name of the route, on the other hand, should not be noted within the shipment, since the final assignment of the route is done later by an operational system.

Within an event handler that responds to the 'Create' or 'Modify' of relevant Shipments, the event actions are configured as shown on the right.

Event action Routing: Determine route:

  • The value resolver for the Target field points to a string Variable 'ROUTE' to which the route name is assigned in successful cases.

  • The From chain defines that the company and address attributes for the company types 'Loading party' and 'Principal' should be evaluated in this order.

  • The To chain specifies the 'Consignee' company type as the only relevant type for the end point of the route.

  • The option Copy route attributes to target, is set so that mappings for route attributes are transferred to the reference object if a 'matching' Routing table entry is found. The Override target attributes option has not been selected to protect existing attribute values in the refernce object.


The following If then else event action checks whether a route could be determined and defines the subsequent procedure:

  • Per Entity property rule it is checked if the Variable 'ROUTE' is empty.

  • The 'Then' branch of the case distinction provides a 'Warning' here via Show alert (Popup), after which event handling is continued if necessary.
    NOTE◄ An Abort would also be conceivable here, by which the transaction could be 'rolled back' altogether with a notification. Then a shipment could only be effectively saved if its addressing enables the determination of a route.

  • The 'Else' branch defines the processes after a successful 'routing'. In addition to the success message (via Show alert (Popup)), the shipment is flagged here via Export event action for transfer to a Lobster_data profile when the transaction is completed. For example, the forwarding of data to an executing system can be made dependent on the addressing of the shipment being evaluated as "legitimate" or sufficiently qualified in comparison with the applicable Routing table. As long as information is missing or an invalid 'From'/'To' combination is present, a warning appears instead.

images/download/attachments/73609732/image2021-7-6_15-20-57-version-1-modificationdate-1625577660502-api-v2.png