Related entries

This document describes how to work with related entries, formerly known as associations, in relation to the content model.

How it works

Related entries are represented by the EPiServer.Commerce.Linking.Association class and administered using the EPiServer.Commerce.Linking.ILinksRepository service.

The Target property of the Association contains the ContentReference of the related entry. The class also has a EPiServer.Commerce.Linking.AssociationGroup (defined by its Name property) describing a grouping of several related entries, and a EPiServer.Commerce.Linking.AssociationType (defined by its Id property) describing the type of the relation.

These three properties, together with the Source ContentReference (the item that has the related item) together uniquely defines a related item, i.e. there can not be two Association objects with all these values equal.

Getting related entries for an entry

By calling the GetAssociations method of ILinksRepository with the ContentReference of an entry, you get all the related entries. The related entries are returned as Association instances:

public IEnumerable<Association> ListAssociations(ContentReference referenceToEntry)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();
    var associations = linksRepository.GetAssociations(referenceToEntry);
    return associations;
}

Adding a related entry to an entry

The UpdateAssociations method or UpdateAssociation extension method of ILinksRepository can be used to add new Association objects to describe a new relation to an entry. The new entry has to have a Target ContentReference, a Source ContentReference, a AssociationGroup and a AssociationType. The AssociationGroup class has a DefaultName property you can use as name of the group, and the AssociationType class has a DefaultId property you can use as id of the type.

public void AddAssociation(ContentReference referenceToEntry, ContentReference referenceToRelatedEntry)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    var newAssociation = new Association
    {
        Group = new AssociationGroup
        {
            Name = "CrossSell",
            Description = "",
            SortOrder = 100
        },
        SortOrder = 100,
        Source = referenceToEntry,
        Target = referenceToRelatedEntry,
        Type = new AssociationType
        {
            Id = AssociationType.DefaultTypeId,
            Description = ""
        }
    };

    linksRepository.UpdateAssociation(newAssociation);
}

Removing a related entry from an entry

By calling the RemoveAssociations method or RemoveAssocition extension method of ILinksRepository with a Association object object matching an existing related item, that related item will be removed. You can either construct a matching object, or use GetAssociations to get the existing Associations, filter out the object you want to remove, and pass it to RemoveAssociation.

public void RemoveAssociation(ContentReference referenceToEntry, ContentReference referenceToRelatedEntry)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    // Define an association matching the one to remove, or use
    // GetAssociations to find the one you want to remove and pass that to
    // RemoveAssociation
    var relationToRemove = new Association
    {
        // Group with name is required to match the correct association
        Group = new AssociationGroup
        {
            Name = "CrossSell"
        },
        // Source is required here to match the correct association
        Source = referenceToEntry,
        Target = referenceToRelatedEntry,
        // Type with id is required to match the correct association
        Type = new AssociationType
        {
            Id = AssociationType.DefaultTypeId
        }
    };

    // Removes matching Association, or no action if no match exists
    linksRepository.RemoveAssociation(relationToRemove);
}