Relate Objects

Relating objects is one of the essential parts within UBIK^® and can be achieved by two means:

• Use Relations to build up an n:n relationship between two instances of an entity
• Use References to build up an 1:n relationship between two instances of an entity

Which method fits best depends on the use case and the data model.

Connect objects via Reference

If you want an object to refer to a single target object (1:n relation), a Reference is what you need. You can either ask an object about the one it refers to, or ask a target object about all objects referring to it via a reference. This is useful, if you want to connect objects but there is no necessity for both "sides" to be connected to multiple other objects.

In this case, an object's property contains a link to the target object (respectively, its UID). Let's call the target object B and the object referring to the target object A. A refers to B.

In order for an object referring to another object, the following requirements must be met:

• The MetaClass of object A must have a respectively configured link MetaProperty.
  • The property type should be Guid.
  • A Reference object defining the target MetaClass should be set on the MetaProperty.
• The property value for the link MetaProperty on object A must be set to object B.

You can achieve this with the following steps:

1. Create a new Reference (Create a new Reference).
2. Set the MetaClass of B on the TARGETTYPE property of the previously created reference, as explained in the HowTo above.
3. Make sure there is a MetaProperty on the MetaClass of object A you can use. If necessary, create a new MetaProperty instance and relate it to the MetaClass of A via the MetaClass to MetaProperty relation (Add a MetaProperty to a MetaClass).
4. Set the previously created reference on the new MetaProperty (Create a new MetaProperty).
   
5. Make sure all changes are saved.
6. Open the Bulk Editor for the MetaClass of A and set the property value for the new MetaProperty on A to B, in one of the following ways:
   1. dragging and dropping object B onto the cell
   2. selecting the object B from the dialog appearing after double-clicking the cell
      
7. Save object A. The connection is now established and can be used, e.g., in the ACM view or by programmatic customizing.

Connect objects via Relation

If you want to connect one source object to multiple other target objects, but it should also be possible for a target object to be connected to multiple source objects (n:m relation), you require a Relation.

Essentially, every individual relation connection is a UBIK^® object referring both to the source object and the target object (we say, left and right target). This allows us to have many such connections for the same left and right object, whereas a reference property would just enable many connections for the target object (right). For simplicity, let's call the left object A and the right object B. A is related to B.

In order for two objects to be related, the following requirements must be met:

• There must be a Relation defining the connection between the MetaClasses of A and B.
  • The Relation requires a RelationData MetaClass describing the individual relation connections, e.g., between A and B.
  • On the Relation and the RelationData MetaClass, the respective left and right target MetaClasses must be configured.
• There must be a RelationData instance, referring to A via the Left target and referring to B via the Right target reference property.

You can achieve this with the following steps:

1. Create a new Relation (Create a new Relation).
2. Set the MetaClass of A on the TARGETTYPELEFT property and set the MetaClass of B on the TARGETTYPERIGHT property of the relation, as explained in the HowTo linked above.
3. Set a RelationData template MetaClass on the RELATIONDATA property of the relation, as described in the HowTo linked above.
4. Relate A to B in one of the following ways:
   1. Open the actual RelationData MetaClass (not the template, see the HowTo linked above) in the Bulk Editor and create a new instance, setting the Left target property value to A and the Right target property value to B.
   2. Open A in the Relation Editor. In the tree view you see now, drag B onto the tree node for the previously created relation.
5. Save all changes. The connection is now established and can be used, e.g., in the ACM view or by programmatic customizing.

Connecting objects by customizing code

Reference

You can set a reference connection by custom code as follows, assuming you have:

• A meta class with a reference meta property
• An instance "objectA" of that meta class
• An instance "objectB" of the reference target meta class

       
            // Setting a reference using the property name
            string referencePropertyName = "LNK_MY_REFERENCE_PROPERTY";
            objectA.SetLinkedObject(referencePropertyName, objectB);

            // You can also remove the connection by setting it to null
            objectA.SetLinkedObject(referencePropertyName, null);

Similarly, you can also read a connected object:

            string referencePropertyName = "LNK_MY_REFERENCE_PROPERTY";
            BaseClass objectB = objectA.GetLinkedObject(referencePropertyName);

            // You can also get the objects referring to objectB, restricted by their metaclass.
            MetaClass someMetaClass = objectA.MetaClass;
            objectB.ReferencedByObjects(someMetaClass);

Relation

You can add a relational connection by custom code as follows, assuming you have:

• A relation
• An instance "objectA" of the relation's left target meta class
• An instance "objectB" of the relation's right target meta class

            Relationship relation = objectA.Environment.UBIKDataFactory().Relation(Guid.Parse("insert UID of relation here"));
            // You can, alternatively, get the relation by name instead of UID:
            objectA.TryGetRelationByName("insert name of relation", out relation);

            // Adding a relational connection
            ((RelationalObject)objectA).AddRelation(relation, objectB);
            // Removing a relational connection
            ((RelationalObject)objectA).RemoveRelation(relation, objectB);

You can also read relational information in multiple ways (assuming objectA is already declared as variable of type RelationalObject to avoid the casts):

            Relationship relation = objectA.Environment.UBIKDataFactory().Relation(Guid.Parse("insert UID of relation here"));
            // You can, alternatively, also get the relation by name instead of UID:
            objectA.TryGetRelationByName("insert name of relation", out relation);

            // Getting all objects related to objectA (children of objectA)
            UBIKClassList<RelationalObject> childrenOfA = objectA.RelatesTo(relation);

            // Getting all objects reverse-related to objectB (parents of objectB)
            UBIKClassList<RelationalObject> parentsOfB = objectB.RelatesFrom(relation);