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:
-
Double-click the Documentation Configuration node under the application. The Application opens on the Documentation Configuration editor.
-
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. -
In the Documentation Diagrams table, click the
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. -
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 |
---|---|
|
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 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. https://<hostname>:<port>/semarchy/mdm-app/<dataLocationName>/<applicationName>/documentation/Entity:<entityName> |