Apart from the obvious hierarchic relationship between a Business Object and its children, Business Objects can have relationships to other Business Objects outside own hierarchy. For instance, the Business Object Card has relationships to both the Business Object Account and the Business Object Customer:

  • The Card is related to the debit Account backing the Card
  • The Card is related to the Customer that uses the Card
  • If the Card owner is a person, the user and owner is the same Customer. But if the the Card owner is a company, the Card also has a relation to another Customer: The company owning the Card


Here's a little video talking about relationships to get you in the mood:


Relationships


In this exercise you are going to create the relationships on the Card Business Object to Account and Customer. And you are going to use these relationships on Card to retrieve Field values from the Account and Customer Business Objects. Once again: You are 'standing' on Card and you are 'pointing to' Customer and Account.


Maybe you noticed, when you were creating the Interface Fields for the Business Objects Card and CardStatus, that some of the Interface Fields were given the usage Key. Likewise some of the Interface Fields defined on Account and Customer are marked as Key. It is in fact these Key fields that enables you to create the relationships. 


In this exercise, you are going to create the 3 relationships above to link from Card on the one side to Account and Customer on the other. Afterwards you are going to use these relationships on Card to retrieve values from Target Fields already calculated on Account and Customer. 


In the exercise you will encounter the notions of Flags and Events for the first time. Don't worry, these will be explained in greater depth in a later exercise.


Create a relationship from Business Object Card to Business Object Account


Establishing a relationship from Card to Account is all about telling the Target Map which values from Card will be used to look up the Key Interface Fields of Account: BankId and AccountNumber (you can open the Account Business Object and see that these 2 Interface Fields on Account are in fact marked as Key).

  • Open the Card Business Object in the Document canvas
  • In the Card Business Object, select the tab Relationships and click the Add button. This will open a dialog for you to define the new Relationship:
  • Click the browse button (...) to select the target Business Object you want to relate to. Note the dialog show all the Business Objects in a hierarchy. Relationships are not limited to root Business Objects, it is entirely possible to relate to children. Also, note that the child Business Objects Credit and Loan under Account in the screenshot are faded. This is because no Interface Fields on these have been marked as Key fields. As a consequence it is not possible to target these with a relationship
  • For this exercise you must locate and select the Account Business Object and click Ok
  • Name your new relationship is Account. In Description type: Relation between Card and Account
  • The Key Map lists the Key Interface Fields on defined on Account, and you must now assign a value for each Key Field, much like you have already done when you assigned values to Target Fields in the previous exercises.
    • For Key Field Account.BankId, select value Interface and then Business Object Card, Interface Field BankId.
    • For Key Field Account.AccountNumber, select value Interface, Business Object Card, Interface Field AccountNumber.
    • Now you have instructed the Target Map to use the interface Fields BankId and AccountNumber on Card to lookup the debit Account for the Card

  • The Flag Handling lists that the relationship can cause 2 Flags to be raised:
    • Not found: No Account can be found with the specified key.
    • Found: An Account with the specified key is found.
  • In most cases, it is only relevant to act on the Not found Flag. In this case you are going to specify, that the Event I0023 must be fired if the Flag Not found is raised.
    • Select Not Found row
    • In Action drop down, select User Event
    • Tab right, or click in event, to open the Event Usage dialog
    • Select I0023 (AccountNumber is missing…) in Event list
    • Notice that the Event text includes a placeholder ({0}) and a Parameter. At runtime, migFx will substitute the placeholder with the value of the Parameter. You must assign the value to be used for this Parameter
      • Select Interface in the value drop down
      • Tab right or click on Content and select the AccountNumber Interface Field from the Card Business Object
      • Click Ok and Save (ctrl-s)
  • Note that the Event supplies a default Severity and Receiver, but you can override these by selecting a different value
  • Severity defines the consequence if this Flag is raised:
    • Reject Root: The entire Card Business Object will be rejected and no Target data produced
    • Reject Child: Only relevant on a child Business Object. Will reject the current Child Business Object but let the rest of the Business Object through.
    • Error, Warning and Information have no consequence in the migration, but can be used to signal different levels of problems that may be expected in the Target System.
  • Receiver suggests who initially should assigned the responsibility to trace and fix the Event
    • Source: Users of the Source System, typically some need for data cleansing or likewise
    • Migration: The migration team handles the Event
    • Target: Users of the Target System, typically some missing code values or similar in the Target System

Create a CardHolder relationship from Business Object Card to Business Object Customer.


Use the Card Interface Fields BankId and CardHolderNumber to look up a Customer Business Object, much the same way as you just created the relation between Card and Account.

  • On the Business Object Card, add a relationship to Business Object Customer
  • Change the name to CardHolder and provide a description: Relation between CardHolder and Customer
  • Specify the Interface Fields on Card to use for the look up: BankId and CardHolderNumber
  • In Flag handling, select user event I0011 for the Flag Not found.

  • And as event parameter, use Card Interface Field CardHolderNumber

Create CardHolderCompany relationship from Business Object Card to Business Object Customer


Use the Card Interface Fields BankId and CardHolderCompanyNumber to look up another Customer Business Object

  • On te Card Business Object, add relationship to Business Object Customer
  • Change the name to CardHolderCompany and provide a description: Relation between CardHolderCompany and Customer
  • Specify the Interface Fields on Card to use for the look up: BankId and CardHolderCompanyNumber
  • In this situation you can just ignore the 2 Flags. As described in the beginning of this exercise, not all Cards are owned by companies. In these cases the optional Interface Field on CardHolderCompanyNumber on Card is not supplied and the Not found Flag will be raised. This is a completely normal and valid situation, so it would not make any sense to fire an event
  • Save (ctrl-s)


Short break


Now you have given very precise instructions how to look up the debit Account, the Customer using the Card and in some cases the Company owning the Card. You have also instructed how to react if the targets of these relationships are Not found. In the next section of this exercise you will benefit further from these relationships by picking up values of Target Fields on Account and Customer to use for the values of Target Fields of the Target Object Tgt.Card.


Onwards, let's use the relationships to map some fields!


Map target field AccountId using a relationship to get a value from Business Object Account


If you look at the Target Fields of the Target Object Account -> Tgt.Account, you can see that a value is calculated for the Target Field AccountId. This is the internal key in the Target System for the Account. 


Now, here on Card, we need to establish the relation to the Account in the Target System. This relationship must be establed using the calculated value for the AccountId. This is where the full power of relationships come into play.

  • Open Target Object Card -> Tgt.Card
  • Select the Fields tab Target Object Tgt.Card
  • Locate Target Field AccountId
  • In the Value drop down, select Relationship
  • Tab right or click in the Content cell
  • In new dialog select
    • The Business Object that owns the relationship you want to use. In this case the relationship is defined on Card itself, but if you were working on a child Business Object you could also select an ancestor
    • Select the one of the 3 relationships on Card we have just defined above we called Account. By picking this relationship, you are now pointing to the Business Object you told relationship to relate to: Business Object Account
    • You have the option to either pickup the value of an Interface Field or a Target Field on Account. In this case we want a Target Field
    • Now choose the Target Object under Account, we will steal the value from
    • Finally choose the Target Field AccountId from Tgt.Account
    • Voila

  • On Target Object Tgt.Card, map the Target Field CardHolderId the same way:
  • Finally, to ram it home, on Target Object Tgt.Card, map the Target Field CardHolderCompanyId


A little side note here
Just above, the 2 different relationships on the Business Object Card (CardHolder and CardHolderCompany) are used to retrieve the calculated value from the Target Field IpId from the Customer Business Object. If you have a look at the mapping done for the Customer Business Object, you will note that the Target Field IpId exists on all the Target Objects under the Customer Business Object. However, the value of the IpId is calculated only once using a Mapping Rule on the Target Object Tgt.Involved_Part. The remaining Target Objects under the Customer Business Object all refer to this value for the IpId Target Field by using the Value Type Target.


Of course, when mapping Target Object Tgt.Card in this exercise, you can pick and choose any Target Object under Customer from which to retrieve the IpId value - the result for Tgt.Card would be the same. However, as a general rule in Studio, it is normally best practice to use any value where it is originally calculated, rather than using other values derived from this original.


Carrying on

The Target Object Tgt.Card should now look something like this. The remaining Target Fields with value None must be calculated, so you need to know a bit about Mapping Rules before we can get to them. And before you get to the Rules, there's some other stuff to go through, so you have to a little patient with us here ...




What happened here?


You have told migFx, that in order to migrate the Card Business Object, you need to pick up some of the values assigned to Target Fields under both Customer and Account.

 

Relationships are not limited to be only between root Business Objects, there is nothing stopping you from creating a relationship from a child Business Object in one hierarchy to a child Business Object in another hierarchy.


For instance, try to have a look at the second relationship on the child Business Object Account -> Statement, the one called PhysicalAddress. 

  • Here is a relationship defined on the Business Object Statement, a child under Account 
  • And this relationship is pointing to the Business Object PhysicalAddress, also a child - this time under Customer. 


Relationships are a very powerful feature of migFx. From the straight forward and logical way they are defined and used in Studio, to the way they are automatically resolved at runtime and finally how they are presented as links in the Tracker web application.


Oh, by the way, you also added another value type to your arsenal:


  • Interface
  • Literal
  • Target
  • Constant
  • Relationship, to pick up a value from another Business Object outside the current Business Object hierarchy. You can pick up either the value received for an Interface Field or the value assigned to a Target Field