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:
-
In the Design perspective of the Application Builder, expand the Applications item.
-
Expand your application’s item, and double-click Documentation Configuration
The Documentation Configuration editor opens. -
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. -
In the Documentation Diagrams table, click the
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. -
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.
Application documentation links
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 |
|---|---|
|
Model diagram editor |
|
List of Values documentation sidesheet |
|
Reference documentation sidesheet |
|
Entity documentation sidesheet |
|
Attribute documentation sidesheet |
|
Match and merge documentation sidesheet |
|
Match rule documentation sidesheet |
|
Survivorship rule documentation sidesheet |
|
Enricher documentation sidesheet |
|
Validation documentation sidesheet. |
| These patterns are case-sensitive. |
-
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> |