Create a link type

We recommend creating and configuring a new link type with the guided helper outlined below. However, if you exit the helper before completing the object creation process, you can manually complete the process by specifying the link type, keys, and API names for the new link type.

Access the link type creation helper

Navigate to the Ontology Manager application. To access the link type creation helper, choose one of the following methods:

• Select New from the top right corner, then select Link type.

• In the left sidebar, select Link types under Resources. Then, select New link type in the top right corner of the Link types page.

• Navigate to an object type you want to link, then select Create new link type from within the link type graph on the object type’s Overview page.

  

Configure a new link type

Step 1: Choose the relationship type

1. In the first step of the Create a new link type dialogue, you will be prompted to select the relationship type for the link.

2. Choose the relationship type for defining links between your two objects:

   • Foreign key: Supports "one-to-one" and "many-to-one" cardinality link types. This option allows you to select properties that represent the foreign key and corresponding primary key for the desired objects. See step 2a below for details in defining link resources with a foreign key.
   • Dataset: For "many-to-many" cardinality link types. This option allows you to use a join table dataset to back the link. See step 2b below for details in defining link resources with a dataset.

In the examples below, assume that there are two object types that are related to each other through a cardinality: an Aircraft object type and a Flight object type.

• One-to-one cardinality: This indicates that one Aircraft should be linked to a single Flight. The one-to-one cardinality serves as an indicator of the intended relationship, but the one-to-one cardinality is not enforced.
• One-to-many cardinality: This indicates that one Aircraft can be linked to many Flights.
• Many-to-one cardinality: This indicates that many Aircraft can be linked to one Flight.
• Many-to-many cardinality: This indicates that one Aircraft can be linked to many Flights, and one Flight can be linked to many Aircraft.

3. Select Next to proceed to the next step.

Step 2a: Define link resources with the foreign key relationship type

In a one-to-one or many-to-one cardinality link type, you will define the foreign key property and primary key properties for the link. The foreign key property of one object type must refer to the primary key property of the other object type.

For example, the Tail Number property is the primary key on the Aircraft object type. The Flight Tail Number property on the Flight object type is the foreign key. Links will be created between Aircraft and Flight object types when the Tail Number of the Aircraft matches a Flight Tail Number of a Flight.

1. In the Link resources step, choose the object types for your link.
2. Select the foreign key object type from the dropdown menu on the left (Flight in our example).
3. Select the primary key object type from the dropdown menu on the right (Aircraft, in our example).
4. Choose the properties that will form the link:

• For the foreign key object type, select the property that will be used as the foreign key for the source object type (Flight Tail Number for the Flight object types).
• The primary key of the object type is auto-selected since there is only one primary key for each object type (Tail Number for the Aircraft object type).

5. Select Next to continue.

Step 2b: Define link resources with the dataset relationship type

In a many-to-many cardinality, select a datasource that includes all combinations of links between the primary key of the first object type (Aircraft in our example) and the second object type (Flight in our example).

A many-to-many cardinality, which requires a backing datasource, is required to enable users to edit or write back to the link type.

1. In the Link resources step, choose the object types for your link.
2. Select the first object type from the dropdown menu on the left (Flight).
3. Select the second object type from the dropdown menu on the right (Aircraft).
4. Choose the join table dataset. Select a dataset that contains columns matching the primary keys for both selected object types. A column can only be mapped to one primary key.
5. Select which columns in the link type’s backing datasource map to the primary keys of each of the linked object types.
6. Select Next to continue.

Step 3: Name the link type

1. In the Link type names step, provide the display and API names for your new link type.
2. Enter a display name for each side of the link type. A side of the link type represents the link to that object type. In our example, the display name for the Aircraft object type describes the link from Flight to Aircraft. You could choose the display name Assigned Aircraft since one Flight has one Assigned Aircraft.
3. The API name will be automatically generated based on the display name, but you can modify it if needed.
   • The API name field is used when referring to a link type programmatically in code. The API name on a side of a link type can be used to return objects of that type. For example, if the API name on the Aircraft side of the link type is assignedAircraft, then calling Flight.assignedAircraft.get() will return the Aircraft objects linked to those Flight objects.
   • Link type API names must adhere to the following:
     • Begin with a lowercase character and consist of only alphanumeric characters.
     • Be unique across all link types associated with the same object type.
     • Be between 1 and 100 characters long.
     • Be NFKC normalized.
     • Not be a reserved keyword.
   • Learn more about API names.
4. Select Submit to proceed.

After completing these steps, your new link type will be created and you can save it. To do this, follow the instructions on how to save changes to the Ontology.

Troubleshooting

Error: Phonograph2:DatasetAndBranchAlreadyRegistered

If you receive the error Phonograph2:DatasetAndBranchAlreadyRegistered, the datasource backing the link type you are trying to save is already backing a different link type in the Ontology and cannot be used again.