Exercise 2.5 – Map Business Object Card

In previous exercises, you built the Source Map for the Business Objects Card. So you have told the Source Map how to extract the source data you need in order to assign values to the Target Interface Fields on the Business Object.

In this exercise, you are going to do just that. Some of the fields are fairly simple as you can use the value of some Source Field as-is. For other fields you will be creating the Export Rules and even a Bag Method you need in order to calculate the value to assign. You will create the Valuesets and Events that you need along the way.

This exercise presumes that you already have created Rules, Valuesets and Events as part of the section 1 Studio, Target Map.

Roll up your sleeves and get ready, there's work ahead!

Map the easy Fields

First, map all the Fields that take a simple Source Value

• Open the Card Business Object
• Select the Export tab and - once there - notice you are on the Target Interface tab 
  • Export Only fields are a special case outside the scope of these exercises. These fields are only created if your migration does not include the import step executing the Target Engine. This is the case if your project is only exporting the Business Objects using the Source Engine in order to deliver the export result to somebody else
• Let's map some of the Target Interface Fields 
  • BankId
    • Select value Source in the drop-down
    • Tab right or click in the Content cell to open the Source value selection dialog
      • Select Business Object Card
      • Select Source Object Src.DebitCard
      • Select Field BankId
      • Click the Ok button

  • A hint: The mapping process can go a bit smoother by using the drag and drop capabilities of Studio and drag a value from one field to another. At the end of this exercise, you'll find an attached video showing how to do this

  • Similarly, map these Fields using Source values

    • CardPanNumber: Src.DebitCard/CardNumber
    • AccountNumber: Src.DebitCard/Account
    • CardHolderNumber: Src.DebitCard/Customer
    • CardHolderCompanyNumber: Src.DebitCard/Company
    • CardActiveDate: Src.DebitCard/ActiveDate

  • Finally 

    • PinCode: Value Null

Now the Target Interface Fields on Card should look like this:

Save your changes. Notice the first time you save the Business Object, its icon in the Project Explorer tree view is no longer faded.

Map Target Interface Field CardType

In this training project Card types in the source system are different from Card types in the target system, so they must be translated. In order to assign a value to the Target Interface Field CardTypes you need an Export Rule. In turn, this rule will need a Valueset for the translation. Finally, you are also going to create an Event to fire if the translation fails. 

Let's create these prerequisites and then map the field.

Create Valueset TranslateCardTypes

You will create a Valueset to translate the code values for Card Types in the Source System to code values for card types in the Target System. Give this Valueset the type Translation. A Translation Valueset will automatically appear in the Portal Operations and the data can be entered by someone outside the migration team - could be a business user associated with the project.

• Create a new Valueset and name it TranslateCardTypes
• Provide description: Translate Card types from source values to target values
• For Valueset Type check the radio button Translation
• Create the columns of the Valueset
• Mark the BankId and SourceCardType as keys
• Now go to the Data tab
  • Select the BankId as PartitionColumn. Remember this Valueset will end up in the Portal Operations. The Portal Operations must ensure that the users from one bank cannot enter add/edit/delete valueset row for the other bank. By selecting the BankId as PartitionColumn, you tell the Portal Operations  how to partition the rows
  • Require a non-blank value for TargetCardType and Description
    
• Save 

Create Export Rule TranslateCardType

Now create a new lookup Export Rule using the Valuset you just created:

• Create a new Export Rule and name it TranslateCardType
• Provide description: Translate Card type from source value to target value
• For Type, check radio button Lookup
• Select Valueset TranslateCardTypes
• Select Returns: TargetCardType
• Leave Default as Null
• Check the Lookup columns BankId and SourceCardType
• Save

Create Event to fire if the Export Rule raises the Not found Flag

• Create a new event and assure the Event Code is 14
• Disposition: Full Discard
• Impact: Critical
• Receiver: Migration
• English text: No translation found for CardType ({0})
• Parameter: CardType Num(1)
• Save     

Map the Target Interface Field

Now you have all you need and can proceed to map the Target Interface Field CardType. Go back to - or re-open - the Card Business Object and select the Export tab, sub-tab Target Interface.

• On the CardType field, select value Calculated
• Tab right or click the Content cell to open the Rule selection dialog
  • First drop down: Leave on Rule
  • Second drop-down: Select the Export Rule TranslateCardType you have just created 
  • Parameter values
    • BankId: Source value Src.DebitCard/BankId
    • SourceCardType: Src.DebitCard/CardType
  • Flag Handling
    • Found: Leave Action on Ignore
    • Not found: 
      • Action: User Event
      • Tab right or click the Event cell to open the Event assignment dialog
        • Select Event E0014
        • Parameters
          • CardType; Source value Src.DebitCard/CardType
      • Leave Severity and Receiver at default values from Event
      • Click the Ok button to close the Event assignment dialog
  • The Rule selection dialog should now look like this
  • Click the Ok button to close the Rule selection dialog and Save

That's it. You have just asked your users to provide the translation from Source System card types to Target System card types, created the Export Rule and assigned the translated value to the target Interface Field Card Type - including an Event to fire if the translation does not succeed.

Didn't take long, did it?

Map Target Interface Field CardHolderName

The Source and Target Systems handles the name of the card holder differently. 

• In the Source System, the cardholder name is not stored separately but is built when needed from the card holders first and last names  
• Target System does store the cardholder name separately, so in the Source Map you need to concatenate the first and last names and maybe truncate the result if longer than the 26 characters reserved in the Target System

You're lucky, some friendly busy bee in your team has already created a Bag method that does exactly this. 

Have a look at the Bag called StringHandling:

This Bag has 3 methods in it, the one you need right now is the first one: CompressName. As you can see, each Method on the Bag is defined just like you define a Rule. It has a return type, Parameters, Flags and Flag Parameters just like a Rule.

This is the first time you use Flag Parameters. If the method CompressName raises a Flag, it will send these two Flag Parameters with the Flag. You can then use the values as Parameters to a User Event. The end result: If the method compresses the name, in your Event you can show what the name was before and after the compress.

So, now use this Bag method to map the Field:

• Open the Card Business Object and select the tab Export, sub-tab Target Interface
• For the field CardHolderName, select Value Calculation
• Tab right or click the Content cell to open the Rule selection dialog
• In the first drop-down, select Bag method
• In the second drop-down, select the Bag StringHandling
• In the third drop-down, select the method CompressName

Parameter values:

• FirstName: Source value CardHolder [Vw.Customer]/FirstName
• SurName: Source value CardHolder [Vw.Customer]/Name
• Length: Literal value 26
• Flag Handling
  • Flag Name Compressed:
    • Action: User Event E0012
    • Parameter 
      • InputName: FlagParameter value InputString
      • OutputName: FlagParameter value OutputString
    • Length: Literal value 26
    • Click the Ok button to close the Even assignment dialog
• Compress name not possible:
  • Action: User Event E0013
  • Parameter 
    • InputName: FlagParameter value InputString
    • OutputName: FlagParameter value OutputString
    • Length: Literal value 26
    • Click the Ok button to close the Even assignment dialog
• This is how the Rule selection dialog should look:

• Click the Ok button to close the Rule selection dialog and Save
  
  

Map Target Interface Field CardHolderCompanyName

The Target Interface Field CardHolderCompanyName has a maximum length of 26 characters, but it turns out that the corresponding Source Field on Src.DebitCard has a maximum length of 80 characters. So you need to handle if the length of the incoming Source Field exceeds the length of the receiving Target Interface Field. 

To do this you will create a new Bag method to truncate the Source Field if it is too long and raise a Flag if that was the case. 

Create Bag method StringHandling.TruncateString

The Source Map already contains the Bag StringHandling for non-specific string processing, so you will add a new method to this Bag:

• Open the Bag StringHandling on the Document canvas
• Checkout the Bag (if not already checked out)
• Select the Definition tag, sub-tab Methods
• Type a new method at the end of the list
  • Name: TruncateString
  • Type: Manual
  • Returns: Char(*)
  • Check the Nulls checkbox
• Parameters:
  • Name: InputString, Char(*)
  • Name: Length, Num(5)
• Flag: 1: String truncated
• Flag Parameter Name: OutputString, Char(*)

Now you need to write up a nice pseudo code specification of what you need the method to do so somebody (= yourself) can implement it later.

• Select the Code tab, sub-tab Specification 
  • Notice that the Specification already contains the description for the existing methods. Below the existing specifications, type the specifications (pseudo code) for the new method:

if String is longer than specified in String Length
Truncate string to the length allowed
Raise notification with truncated string as parameter
return truncated string
else
  return Parm.String

• Remove the check mark from the Implemented check box at the bottom
  • The Bag has been modified and now needs the new functionality to be implemented in c# in Visual Studio. Unchecking Implemented ensures that a Warning is will be raised during validation, making it easy to find the Rules and bags that need to be implemented in Visual Studio.
• Save, check in and close the Bag

Create a new Event for string truncated

Now create the new event to fire if the new Bag method truncates the CardHolderCompanyName. 

• Create a new Event
  • Ensure that the Event Code is 15
  • Disposition: Retain
  • Impact: Advisory
  • Receiver: Migration
  • Text: Value truncated from ({0}) to ({1}), length ({2})
  • Parameters
    • From, Char(*)
    • To, Char(*)
    • Length, Num(5)
• Save the new Event and commit

Map Target Interface Field CardHolderCompanyName

Now you can map the Target Interface Field CardHolderCompanyName using the new Bag method and Event.

• Open Business Object Card, select Export tab, sub-tab Target Interface
• For field CardHolderCompanyName, select value Calculation
• Tab right or click in the Content cell to open the Rule selection dialog
• First drop down, select Bag method
• Second drop-down, select Bag StringHandling
• Third drop-down, select method TruncateString
• Parameters:
  • InputString: Source value, CardHolderCompany [Vw.Customer/Name
  • Length: Literal value 26
• Flag Handling
  • String truncated: User Event E0015
  • Parameters
    • From: Value = Source, View Vw.Customer (CardHolderCompany), Field Name
    • To: Value = FlagParameter = OutputString
    • Length: Value Literal, 26
      

• Save and check in

Map Target Interface Field CardInactiveDate

The Source and the Target Systems handle the CardInactiveDate differently. In the Target System, if the metadata field Tgt.Card.CardInactiveDate contains a value (is not null) the Card is inactive. In other words, in the Target System all inactive Cards must have a CardInactiveDate.

But the Source System controls the inactive state of the Card in another way. In the Source metadata Src.DebitCard you will find an ExpireDate, but also an Expired mark and a Blocked mark. The Source System does not always store an ExpireDate for an inactive Card.

Export Rule

Your team together with users from the banks being migrated have discussed and analyzed this intensively, and the result is the Export Rule GetCardInactiveDate. The rule has already been created and implemented by another teammate and looks like this:

And the specification looks like this:

If Parm.ExpireDate <= First bank day after migration
return ExpireDate
end

If Parm.Expired = 'X'
raise notification 1 (Card is expired, but ExpiredDate is not reached)
return the day before First bank day after migration
end

If Parm.Blocked = 'X'
raise notification 2 (Card is blocked, Default date is first bankday after migration)
return the day before First bank day after migration
end

return null

Events

You need to create a couple of new Events to use for the 2 flags of the new rule

• E0016: Card is expired, but expiredate ({0}) is not reached. CardInactiveDate set to default ({1})
  • Disposition: Retain
  • Impact: Advisory
  • Receiver: Source
  • Parameters
    • ExpireDate (Date)
    • DefaultDate (Date)
      
      
• E0017: Card is blocked. CardInactiveDate set to default ({0}).
  • Disposition: retain
  • Impact: Information
  • Receiver: Source
  • Parameters
    • DefaultDate (Date)

Map the field

Now map the Target Interface Field CardInactiveDate using this Rule.

• Open the Card Business Object and select the Export tab, sub/tab Target Interface
• Field CardInactiveDate
• Value: Calculation
• Method: Rule, GetCardInactiveDate
• Parameter values:
  • ExpireDate = SourceField, Src.DebitCard/ExpireDate
  • Expired = SourceField, Src.DebitCard/Expired
  • Blocked = SourceField, Src.DebitCard/ Blocked
• Flaghandling
  • Flag> Card is marked Expired, but ExpireDate is not reached, default date returned
    • Event E0016
    • Parameters
      • ExpireDate =  Value Source, Src.DebitCard/ExpireDate
      • DefaultDate = FlagParameter value, DefaultDate
  • Flag: Card is marked Blocked, default date returned
    • Event E0017
    • Parameters
      • DefaultDate = FlagParameter value, DefaultDate

You should end up with something like this:

Now Save and check in all our hard work!

The Target Interface Fields of the Card Business object should look something like this:

What happened here?

You have assigned values to all the Target Interface Fields on the Business Object Card. Now the Source Map knows which value to assign to each field. 

You should now have a good idea of how you are working in the Source Map.

• For each Target Interface Field you must figure out how to assign the value
• This leads to adding Source Objects to the Extraction Map of the Business Object - marking the metadata structures Active if needed
• For some Target Interface Fields you can assign the values of Source Fields directly, for others you need to calculate the value to assign with an Export Rule or a Bag method
• If you need to calculate, you can use Export Rules/Bag methods/Events already created or you can easily create them as needed

When building the Extraction Map for the Business Object Card, your Source Objects were linked to metadata structures (Src.DebitCard) and Views (Vw.Customer). In addition to these two, you can actually also use Valusets as Source Objects.