Exercise 1.6 - Create and Use Relationships

Modified on Fri, 13 Oct 2023 at 06:22 PM

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. 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 marked as 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 shows 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 Account - or leave it as the proposed name FK_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 drop down list
- Notice that the Event text includes a placeholder ({0}) and a Parameter. At runtime, Hopp 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
  - Leave the values for Disposition and Impact as-is
  - Click Ok and Save (ctrl-s)
The default values from Impact, Disposition and Receiver,are defined when creating the Event. In the following exercise you will create some Events and there will be more explanations there
- Note you can override these default values here

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 to the Customer that holds the Card
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 the Card Business Object, add relationship to Business Object Customer
Change the name to CardHolderCompany and provide a description: Relation to the Company that holds the Card
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 on how to look up the debit Account, the Customer using the Card and in some cases, the Company owning the Card.

You have also been 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 established 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 the 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 tone 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 pick up 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 be a little patient with us here ...

What happened here?

You have told Hopp, 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 being 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 Hopp. From the straightforward 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