Create a link type

To create a new link type, you can either:

• Select New link type from the link type card in the home page header; or,

  

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

  

Configure a new link type

After creating a new link type, the link type must be configured and saved. The following configuration steps are required before saving a new link type:

1. ID: Choose a unique identifier of the link type, primarily used to reference links of this type when configuring an application.
   • An ID can contain lowercase letters, numbers, and dashes.
   • The first character of an ID must be a lowercase letter.
   • Once an ID is saved, the ID cannot be changed.
2. Object type: Choose an object type you want to link to your starting object type.
3. Cardinality: Choose the cardinality of each side of the link type. Object types can be related through four different types of cardinality: one-to-one, one-to-many, many-to-one, and many-to-many. 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. Note that the one-to-one cardinality serves as an indicator of the intended relationship, but the one-to-one mapping 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.
     • Note that when you select a many-to-many cardinality you will be prompted to upload a datasource that includes all combinations of links between the primary key of the first object type (Aircraft in this example) and the second object type (Flight in this example).
   • A many-to-many cardinality, which requires a backing datasource, is required in order to enable users to edit or write back to the link type. Learn more about allowing users to edit data.
4. Key: Choose which properties or columns to use to create the links.
   • In a one-to-one or in a one-to-many cardinality link type, the foreign key property of one object type must refer to the primary key property of the other object type.
     • For example, the aircraft ID property is the primary key on the Aircraft object type. The assigned aircraft ID property on the Flight object type is the foreign key. Links will be created between Aircraft and Flight object types when the Aircraft’s aircraft ID matches a Flight’s assigned aircraft ID.
   • In a many-to-many cardinality link type, select which columns in the link type’s backing datasource map to the primary keys of each of the linked object types.
     • If the base type of the primary key property of the object type is not the same as the type of the column to which the primary key is being mapped in the link type’s backing datasource, an error will prevent you from saving.
5. Display name: Fill in the display names for each side of the link type. A side of the link type represents the link to that object type. The display name for the Aircraft object type describes the link from Flight to Aircraft. In this example, you could choose the display name Assigned Aircraft since one Flight has one Assigned Aircraft.
6. Plural display name: For sides of a link type with the cardinality many, you will also be prompted to fill in a plural display name, so that user applications can display the correct name when displaying the linked objects. In our example, the plural display name for the Flight object type will describe the link from Aircraft to Flight. We might choose the plural display name to be Scheduled Flights as one Aircraft has many Scheduled Flights.
7. API name: Fill in the API name field that 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:
     • Begin with a lowercase character and consist of only alphanumeric characters.
     • Be written in camelCase.
     • Be unique across all link types associated with the same object type.
   • Learn more about API names.

With these fields filled in, you will now be able to save your link type. 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.