Application Documentation

Overview

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

This documentation is available at multiple places in the application. For example:

  • In forms and collection views, from an information icon that appears on table headers and form fields.

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

  • From Open Documentation application actions that open the documentation page.

Document the Model

The documentation exposes objects of your model, such as the entities, attributes, enrichers, etc. For end-users, these objects are exposed with the Labels and Documentation that you set in the model. The Description does not appear for end-users, as it is intended to document the model for the designers.

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

Configure the Application Documentation

You can also configure, in addition to the model objects' documentation properties, a documentation page and a list of diagrams for users to browse the data model.

To configure the documentation page:

  1. Double-click the Documentation Configuration node under the application. The Application opens on the Documentation Configuration editor.

  2. 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 will appear as a single page in an editor.

  3. In the Documentation Diagrams table, click the ModelDiagram Add Model Diagram button to reference one of more diagrams in the documentation.
    Links to these diagrams appear after the content in the documentation page.

  4. Press CTRL+S to save the editor.

Once the content is set or a diagram is added to the documentation, the Documentation menu item appears in the user menu.

Secure the Application Documentation

The documentation automatically hides elements (entities, attributes) for which the user has no read access in his model privileges grants. Therefore, if a user cannot view the data of an entity, he cannot view this entity’s documentation.
Besides, you can configure access to the data quality and enrichment components of the documentation in the model privileges grants.

Application Documentation Links

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

These links are particularly useful to create navigation between documentation pages. For example, to link 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.
Example 1. Examples of documentation Links in Markdown
* Link to a diagram: <diagram://CustomerB2CDiagram>
* Link to a regerence: <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](doc://Entity:Person/Validation:Plugin.InvalidEmail) link.
* Inline [SemQL Validation](doc://Entity:Person/Validation:SemQL.InvalidMiddleName) link.

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

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