Exercise 1.10 - Create Mapping Rules

In this exercise you will be creating a couple of Mapping Rules, a Lookup Rule and a Manual Rule. You will create them in this exercise and use them in the following exercise to calculate the value of some Target Fields on the Card Target Objects.

Have a look at this video for an introduction to Rules:

Rules

Create a Lookup Mapping Rule GetCardType

A Lookup Rule looks up a row in a Valuset. You just have to select the Valueset, point out the columns to look up and the column to return, and you are done. Further on in the process, the engine will generate all the code necessary to implement the rule.

• Locate and right-click the folder node Rules -> Mapping in the Project Explorer and select New in the context menu
• Name the new rule GetCardType and provide the description: Validate Card type and get Card type Id
• Select the Definition tab
  • Select Type radio button Lookup
  • In the Valueset dropdown, select the Valueset CardTypes
  • Select the Returns type Column
    • In the Column dropdown, select the column CardTypeId
  • In the Not found dropdown, select Literal and type the literal value 0 (zero)
    • The rule will now return the literal 0 if no row is found
  • Select the columns BankId and CardType as lookup columns by checking Lookup for both in the column list
  • Save (ctrl-s)   

That's all, you need to do to create a Lookup Rule (if you want to read more about Lookup Rules, your can find information here).

As you will see later on, when you use the rule to calculate the value for a Target Field, the Studio automatically creates 2 Flags for the rule, to signal whether a row was found or not.

Create the manual Mapping Rule GetCardStatus

While Lookup rules are nice and easy when all that is needed is to lookup a row in a Valueset, you can create rules in Studio of any complexity, from simple to insanely complex - even calling out to functionality in your environment. These are manual rules, let's create one of these.

The rule you are creating still looks up a row in a Valueset, this time the Valueset CardStatus. It looks for an internal id used in the Target system to represent the status of a Card. However, instead of just returning the value it found, it must react (if no row is found) by raising one of two different Flags, depending on whether the Card is active or expired.

In Studio you will define and use the rule. As part of the definition, you must provide a specification of what you want the rule to do. At a later stage, the rule must be implemented. In this training setup of course it will be you implementing the rule a bit further on, in c# in Visual Studio. But in a real world setup, it may very well be somebody else. So bear in mind that the rule will never be better than your specification.

Anyways, let's get to work:

• Locate and right-click the folder node Rules -> Mapping in the Project Explorer and select New in the context menu
• Name the new rule GetCardStatus and provide the description: Validate Card status and get CardStatusId
• Select the Definition tab
  • Select Type radio button Manual (default)
  • Define the return type of the rule: Set Returns to Num, Length to 5, and Scale to 0. Un-check Null, as this rule must always return a value (cannot return null).
  • In Parameters, provide
    • CardStatus format char 10
    • CardActiveDate format Date
    • CardInactiveDate format Date
  • In Flags, provide 2:
    • 1: Unknown CardStatus on Card in use
    • 2: Unknown CardStatus on inactive card

• Select the Code tab and the sub-tab Specification
• Type the specification (pseudo code) explaining what you want the rule to do. For instance:

Look up CardStatusId in the Valueset CardStatus (key: parameter CardStatus) and return the CardStatusId from the row. If no row is found, then raise flag 1 if the Card is in use and flag 2 if not and finally return 0 (zero).

A Card is in use if parameter CardActiveDate is less than or equal the Constant FirstBankDay AND parameter CardInactiveDate is either not supplied or greater than or equal to the Constant FirstBankDay.

A couple of points to notice:

• At this point, when you are defining the Manual Rule, you have to be exact when defining the interface of the rule (the parameters, flags etc.). You can then write down your intentions for the rule in the specification and you are free to go and use the rule in your mapping without worrying about the actual implementation of the rule 
• You have access to the Valueset CardStatus and the Constant FirstBankDay from the manual rule

You will get the chance to implement this rule in Visual Studio in a later exercise.

Flag Parameters

You have probably noticed that you can also specify Flag Parameters on the manual rule. We are not asking you to work with Flag Parameters in the exercises, but you do deserve a little explanation. 

If you define a Flag Parameter, you enable the rule to pass out information when it raises a Flag. For instance, if a rule injects some Target Object into the migration stream because it figured out it was missing, it would be convenient if the rule could raise a Flag and inform what it created.

Later when you use this rule, you may attach an Event to the Flag. And then you can use the Flag parameter to merge into the Event text. In this way, the rule can signal that it injected something in the migration stream and indeed - via the Event with the Flag parameter - get this published in the Tracker web application, properly with the Event Severity Information. 

What happened here?

You have created 2 Mapping Rules that you will be using later. One was a Lookup Rule and the other a Manual rule. These two were defined differently, but when you will use them later on they will look the same:

• Have a Name
• Return a value of a given data type
• Take some input parameters
• Raise some Flags

For the Lookup Rule everything is now done. For the Manual Rule, you provided a Specification and the rule must be implemented in c# in Visual Studio at a later stage.