SDL Tridion Sites 9.1 – SDL Tridion Integration Framework – part 2

Just a quick recap, in my last blog I covered the architecture, available extension points and integration scenarios of the new SDL Tridion Integration Framework.

In this followup, we will now take an even closer look at the remaining topics, namely the connectors themselves, the entity data model, the SDK and finally the deployment process.

Connectors

Earlier (in the architecture part) I have vaguely described the connectors as pieces of the framework which implement a contract. To fully understand what that means, we first need to shed some additional light on what exactly these contracts are – because they play a crucial part in the architecture.

The contracts are basically collections of code interfaces which need to be implemented. These interfaces define capabilities (operations) over entities. The entities are the objects of interest of the external systems (e.g. user, video, product, etc.).

The list of key capabilities -- that the contract may dictate must be implemented -- is below:

• Get
• List
  • Returns a paginated list
• Mutation
  • Create
  • Delete
  • Update
• Query
  • Returns a paginated list

Not all capabilities are mandatory (or in some cases even possible) for a connector. However, we must register any capabilities that we intend to use. If a capability is not registered, calls to it will be blocked by the framework, in addition only the capabilities that are registered will be exposed on the GraphQL side.

There are two types of capabilities:

• Connector Wide, for example:
  • Download the binary reference
  • Get list of root items
• Entity Capability, for example:
  • Get
  • Delete

Entities can contain both (meta)data, as well as binary data, in the form of binary references. If the actual binary data is needed, it can be retrieved from the external system using the binary reference (i.e. the Connector would make a separate request for the Binary using the reference). The binaries are supported by the following data model:

• IBinaryReference
  • Namespace id
    • Supplied to the connector by the connector manager
  • Type
    • Example: Icon, thumbnail
  • Id
    • Identifier for retrieving binary from remote system
• IBinary
  • Stream
  • Content type
  • Length
• IDownloadBinary
  • Binary reference

The next core concept in the framework are schemas. Schemas are used to define the external metadata on the ECL side, and they also facilitate/enable additional filtering options on the GraphQL side. We will touch more on Entity Schema below.

Connectors also support a built in search/querying capability, meaning that entities can be queried for based on specified criteria.

And finally, there is the notion of associations, which allows for bidirectional awareness of an entity’s usage in both Tridion and the external system. Although this sounds complicated, it’s pretty straightforward and very useful to help with data integrity between disparate systems. For example, if someone tries to delete an entity from the external system, he/she could receive a notification that that item is in use by Tridion, or if someone tries to delete an external item through Tridion, that action can be intercepted and handled appropriately (e.g. propagated, validated, etc.) on the remote system.

Data Model

Within SDL Tridion Sites, the entities are defined by the following data model. This model also defines container items (e.g. used for organization and/or navigation within the CME) and the multimedia/binaries subtype mentioned earlier:

Each entity is defined by an Entity Identity, which consists of the following members:

• Id
  • Identifier on remote system
• Locale id
  • Publication
• Namespace id
  • Supplied to the connector by the connector manager
• Type
  • Name of the entity
• Structure Type
  • Root
  • Leaf
  • Container

Connectors SDK

The Integration Framework will come with its SDK, available on NuGet/Maven, which will help developers create and configure the connectors, register capabilities, handle pagination and build entity schemas more easily. There is also talk about supplying .NET templates/Maven archetypes for even faster development, personally I’m looking forward to those :).

The Entity Schema is defined by the following model:

• Name
• Description
• Field definitions
  • Description
  • Type
    • int, float, string, date, binary ref, nested schema
  • Is required, is read-only
  • Constraints
    • min, max, allowed values, regex

Examples of defining the schema model using attributes/annotations is below. An important thing to remember here – as noted above in our introduction of the schema concept – is that if a property is not decorated, then it won’t show up in the external metadata of the ECL item. Nor will it be available in the GraphQL data model.

Deployment

Deploying the new connectors makes use of another new (and very cool) feature of Tridion Sites 9.1 called the Add-on Service (note that the name may change). Since the Add-on Service will be the topic of my following blog, I won’t go into many details here apart from giving an example configuration needed for the service. The example configuration for implementing connectors is below:

This concludes part 2 of our series on the SDL Tridion Integration Framework, stay tuned for the next entry where we will focus on the new deployment model. And as always, if you have any questions or would like to share your thoughts, don’t hesitate to get in contact.

Disclaimer: All images are copied from SDL with their permission.