Application documentation

This page explains how to configure the application documentation feature in Semarchy xDM.

Overview

You can expose documentation content within the application to help end-users better understand how the application works, the underlying data model, and rules that apply to the data.

This documentation is available through various means within the application:

  • An information icon on table headers and form fields in forms and collection views.

  • A Documentation item in the user menu, which opens the documentation page.

  • An Open Documentation action that opens the documentation page.

Document the model

The documentation exposes model objects like entities, attributes, or enrichers displayed to end-users with designated labels and documentation that you set in the model. Descriptions, which are meant for designers, are not visible to end-users.

For a robust documentation set, make sure to define clear Documentation values for each object of your model, preferably using Markdown rich text. Describing every object and its purpose automatically generates a comprehensive documentation set.

Configure the application documentation

In addition to configuring documentation properties for model objects, you can also set up a documentation page and a list of diagrams for users to explore the data model.

To configure the documentation page:

  1. In the Design perspective of the Application Builder, expand the Applications item.

  2. Expand your application’s item, and double-click Documentation Configuration
    The Documentation Configuration editor opens.

  3. In the Contents field, enter a text to introduce your application. You can use plain text or the Markdown syntax for rich text.
    This text appears as a single page in an editor.

  4. In the Documentation Diagrams table, click the Add model diagram Add Model Diagram button to reference one or more diagrams in the documentation.
    Links to these diagrams appear after the content on the documentation page.

  5. Press Control+S (or Command+S on macOS) to save the editor.

Once the content is set or a diagram is added to the documentation, the Documentation item appears in the user menu within the MDM application’s user interface.

Secure the application documentation

The documentation automatically hides elements like entities and attributes if the user lacks read access based on their model privilege grants. Therefore, if a user cannot view an entity’s data, they will not access this entity’s documentation.

Additionally, you can configure access to the data quality and enrichment components within the documentation through the model privileges grants.

When writing Markdown content within Semarchy xDM applications, you can use specific link patterns to open the model documentation using URL patterns.

These links prove particularly useful for navigating between documentation pages, such as linking to an important validation or match rule from an entity’s documentation.

The table below provides the supported patterns:

URL pattern Documentation

diagram://<diagramName>

Model diagram editor

doc://Lov:<lovName>

List of Values documentation sidesheet

doc://Reference:<referenceName>

Reference documentation sidesheet

doc://Entity:<entityName>

Entity documentation sidesheet

doc://Entity:<entityName>/Attribute:<attributeName>

Attribute documentation sidesheet

doc://Entity:<entityName>/MatchAndMerge:<entityName>

Match and merge documentation sidesheet

doc://Entity:<entityName>/MatchRule:<matchRuleName>

Match rule documentation sidesheet

doc://Entity:<entityName>/SurvivorshipRule:<survivorshipRuleName>

Survivorship rule documentation sidesheet

doc://Entity:<entityName>/Enricher:<enricherName>

Enricher documentation sidesheet

doc://Entity:<entityName>/Validation:<validationType>.<validationName>

Validation documentation sidesheet. <validationType> is one of the following: SemQL, Plugin or UniqueKey.

These patterns are case-sensitive.
Examples of documentation links in Markdown
  • Link to a diagram: <diagram://CustomerB2CDiagram>

  • Link to a reference: <doc://Reference:PersonProductsPerson>

  • Inline link to a [Person entity]: <doc://Entity:Person>

  • Link to an attribute: <doc://Entity:Product/Attribute:ProductName>

  • Link to a match rule: <doc://Entity:Person/MatchRule:ExactNameAddressDOB>

  • Inline [plugin validation] link: <doc://Entity:Person/Validation:Plugin.InvalidEmail>

  • Inline [SemQL validation] link: <doc://Entity:Person/Validation:SemQL.InvalidMiddleName>

You can also use direct URLs with similar patterns to access documentation opened on a specific side sheet. For example, to access an entity’s documentation with a direct link:

https://<hostname>:<port>/semarchy/mdm-app/<dataLocationName>/<applicationName>/documentation/Entity:<entityName>