References in Content

References in Content

The advanced link management feature in Bloomreach Experience Manager (BrXM) is designed to enhance the visibility and management of references to documents, images and assets across components, pages and projects. This feature aims to support editors and authors in their daily tasks by providing better tracking. The next version of the feature will also provide more capabilities for workflow management for references.

Terminology

Content Items: Content items in BrXM include documents, images, assets, components, menu items, and pages, which can refer to each other in various ways, such as a document being used in a component or an image being included in a document field.

Reference in BrXM: In Bloomreach Experience Manager (BrXM), a reference is an internal link between content items, such as documents, images, or assets, and other components or pages within the platform. Please note that the feature only includes the direct first level references to or from a content item.  

What does this feature do?

The advanced link management feature allows users to:

• Track Usage: Easily see where specific documents, images, or assets are used across the platform. (Available since v16.2)

• Impact Analysis: Identify the impact of changes made to a document or asset on related pages or components.(Available since v16.2)

• Concurrent Publication Workflows: Streamline the publication process for directly referenced content, reducing manual effort and potential errors. (Available since v16.3)

Benefits

The benefits of the advanced link management feature include:

• Improved Visibility: Gain clear insights into how content items are connected, making tracking and management much simpler.

• Streamlined Workflows: Simplify the concurrent publication of referenced documents, minimizing manual steps and reducing mistakes.

• Increased Efficiency: Enhance the overall efficiency and accuracy of your content management processes, benefiting both editors and authors.

How to use it

1. Accessing the feature:

   • Navigate to the document, image or asset, or component you want to manage within BrXM.

   • Click on the "Show References" button in the “Document” menu  to open the new “References” interface.

2. Viewing references:

   • The "Referenced" dialog will appear with three tabs:

     • Referred in: Content items that refer to the opened document.

     • Refers to: Content items that the opened document refers to.

     • Site References: Components, menu items, pages, and channel settings that refer to the opened document.

   • Use the dropdown filters to narrow down the list by document type, document status or reference status. Please note that images and assets will always be in “published” status.

3. Understanding the references: 

3.1. Details of Content Items in "Referred in" Tab:

• Name: The user-given name of the content item.

• Type: The type of the content item, which can include content types for documents, images, assets.

• Status: The publication status of the referenced content item and the status of references to or from the opened document.

  • Published: Indicates that the document mentioned in the references is published and has a direct reference to the opened document.

  • Offline: Indicates that the document mentioned in the references is offline and has a direct reference to the opened document.

  • Changed: Indicates that the document is published but has unpublished changes 

• There are additional icons that explain the status of the reference itself so that users can easily understand the impact of a workflow action on the reference. 

• Reference added: The icon indicates that the reference to the opened document is from the “preview”(unpublished) version of the document in the references. So reference is not available in the live version of the document in the references.

• Reference removed: The icon indicates that the reference to the opened document is removed in the “preview”(unpublished) version of the document in the references. So reference is available in the live version of the document in the references and when the “preview” version is published the reference will be removed .

• Additional information for references in “Referred in Tab”:
  To see additional information related to each content item in the Referred in Tab, click on the dropdown button next to the content item.

  • Channel: This indicates the channel in BrXM that the content item belongs to.

    • If the document is not directly referenced in any channel, a warning message will display: “Document is not part of any component, menu item or channel setting.”

    • If the document is directly referenced in a channel in multiple locations, a warning message will display: “Document found in x other locations - Go to the document to see its site references.” By clicking on the link in the message, you can open the document in references and see its site references from the References menu.

  • Project: This shows the project that the document in references is part of. Currently, the feature only works for the “Core” project, meaning it does not take into account the version of the document that is included in a project. This limitation will be eliminated in the next release.

  • Location: If the content item is used in a channel, this will show the location of the content item in the channel.

  • Translations: This shows the available translations of the document.

  • Path: This is the direct CMS URL path of the document.

3.2. Details of Content Items in "Refers to" Tab:

• Name: The user-given name of the content item.

• Type: The type of the content item, which can include content types for documents, images, assets.

• Status: The publication status of the referenced content item and the status of references to or from the opened document.

3.3. Details of Content Items in “Site references” Tab:

• Name: The user-given name of the content item.

• Type: The type of the content item, which can include specific component types,pages or menu items for site references.

• Additional information for references in “Site references”:
  To see additional information related to each content item in the Site references Tab, click on the dropdown button next to the content item.

  • Channel: This indicates the channel in BrXM that the content item belongs to. 

  • Project: This shows the project that the content item in references is part of. Use the "Project" filter on top of the tab to look into site references of the document in different projects.

  • Location: This indicates the location of the content item in the channel.

  • Variant: This indicates the available variants of the component. Please note that this doesn’t indicate which specific variant of the component has the reference to the opened document specifically.

4. Managing the reference publication workflows:

Use bulk action options to publish, take offline, request publication or for all referenced documents together, reducing the need for manual updates.

• To publish or unpublish a document and its references, select either "Publish" or "Take Offline" from the Publication menu. A dialog box will appear, listing references based on the workflow action:

• For publication, the "Refers to" tab opens, filtering references in "preview" version by default. This helps users identify which referenced documents should also be published.

• For "take offline" action, the "Referred in" tab opens and filters references in "live" version by default. This helps users identify which referenced documents should also be unpublished.

• Select the documents to publish or unpublish alongside the opened document in the dialog box, then click "Publish/Take Offline with Selected Documents".

• The button displays the number of selected documents. By default, the count starts at 1, as it includes the opened document.

• Key Points to Remember:

• Workflows only apply to direct document links. Nested links cannot be included in the workflow.

• Documents within a project can only be published with the project itself.

Limitations

• Projects Feature Limitation: The feature only covers site references in projects. This means that users can easily see site references to a specific document from different projects, however for document, asset and image references the feature is only available for the core project. 

• Component References via Query: Components that reference a document through a query are not included in the references. This limitation means that if a component uses a query to reference a document, it will not be tracked or displayed by the advanced link management feature.This limitation will be eliminated in the upcoming release.

• Bulk Workflows for Folders: The bulk workflow actions to publish or take offline all documents in a folder is not in the scope of this feature.

These limitations should be taken into account when using the advanced link management feature to ensure a smooth and accurate experience.