Jdruker/PDMInstructions

PDM instructions

All the Historical Reporting physical data model (PDM) reference manuals for GIM, RAA, and ICON use the same PDM model and templates.

The model

The PDMs use the Library book model to single-source multiple parallel customer-facing documents:

• The Library book exists in a version that is never released. There are two versions of the Library book, one that is the source content for the draft customer-facing manual, and one that is the source for the published customer-facing manual:
  • In Ponydocs, the draft version of the Library book is called DRAFT and the "published" version is called PDMSource.
  • In MintyDocs, the actual version is called Library; the draft Library book is in the Draft namespace, and the published version is in the published namespace.
• The customer-facing PDMs are regular documents:
  • In Ponydocs, the draft version of the customer-facing PDMs is called DRAFT and the published version is called Current.
  • In MintyDocs, the version of the customer-facing PDMs is Current; the draft manuals are in the Draft namespace, and the published manuals are in the published namespace.
• All editing is done in the Library book. The Library book is "published" in the usual way, meaning that you update the draft version of the Library book and when ready push the updated content to the "published" version of the Library book.
• The pages in the customer-facing PDMs are populated by template and query from their single source, the Library book. The actual markup on the customer-facing PDMs is a single template call, {{PDMPageQuery}}. After you have created a customer-facing page and published it for the first time, you never touch it again -- all subsequent updates are automatically passed through based on updates to the Library pages.

The following diagram illustrates the model from the point of view of the markup.

The following diagram illustrates the model from the point of view of the source content.

Pagename conventions

The model relies on very strict pagename conventions, with the topic names in the customer-facing manuals exactly mirroring the equivalent pages in the Library book.

• All Table pages start with Table- (for example, the GIM ANCHOR_FLAGS table is described on Table-ANCHOR_FLAGS).
• All View pages start with View- (for example, the GIM CAMPAIGN view is described on View-CAMPAIGN).
• All Schema pages start with Schema- (for example, the ICON Core schema is described on Schema-Core).
• All Subject Area pages start with SubjArea- (for example, the GIM INTERACTION subject area is described on SubjArea-INTERACTION).
• There are no strict pagename conventions for unstructured pages, except for the requirement that topic names in the Library book and in customer-facing manuals match exactly.

Templates used

The markup on the structured Library book pages is entered in a "templatized" way, with the data stored in Cargo tables in the Mediawiki database. The templates used to display content on the customer-facing pages are query and formatting templates.

Important

Some of the Library book templates use display templates and queries to display content, even in Cargo templates. The display templates and sub-queries are not exhaustively listed here. If you need to see all the templates that are involved in providing a particular display, follow the trail from one template to another.

Library book templates

The Library books use the following key Cargo templates:

• PDMTable — Stores data about the database tables. This is the main template appearing on Table-* pages.
• PDMColumn — Stores data about the table columns. The column data is entered and displays on the Table pages.
• PDMView — Stores about about the database views that are documented. This is the main template appearing on View-* pages.
• PDMViewColumn — Stores data about the view columns. The column data is entered and displays on the View pages.
• PDMIndexItem — Stores data about a table's index(es). The index data is entered on the Table pages and, in the GIM and RAA PDMs, displays on the Table pages; in the ICON PDM, the templates are set so that the data actually displays on the applicable Schema pages.
• PDMRef — Stores data about the references from a table or view. The references data is entered on the Table or View pages and displays on these pages in the Library book (for ease of checking), but in the customer-facing PDMs the references display only on a summary page.
• PDMs_SubjectArea — Stores data about the subject areas to which tables and views belong. The subject area data is entered on Subject Area pages, and the subject area is referenced in a PDMTable or PDMView parameter. (This template was only ever used in the GIM on-premises PDM. It is no longer maintained for GIM and is not used in the GIM Multicloud PDM.)

Important

The PDMTable, PDMColumn, and PDMView templates include parameters to identify when the respective object was introduced, modified, or discontinued. It is very important that you populate these parameters, because they provide important information for customers and important summary queries depend on this data.

In addition to the structured Library content, the Library books contain unstructured content, which is regular wiki markup contained between <onlyinclude> tags. Some of this content is conditionalized for cloud vs. premise and/or for various flavors of Multicloud (Azure vs. AWS vs. private edition) by using the SwitchForCloud template.

Query and display templates

The following are some of the more important query templates used to construct and display customer-facing pages.

• PDMPageQuery — This is the main template on customer-facing pages and, in fact, is expected to be the only content markup on these pages. The template switches based on the URL pattern to use topic-specific sub-templates, which contain a number of queries and sub-queries. In the customer-facing manuals, content which comes from structured Library book pages — in other words, the Table-*, View-*, etc. pages that use the Library book templates noted above — are constructed entirely by query; content which comes from unstructured pages is transcluded. Some of the transcluded pages themselves use query templates.
• PDMRefQuery — Constructs the summary list of references.
• PDMListQuery — Requires you to specify an object (such as Table, View, or Index) and accepts a number of other parameters to enable further filtering and control the display of the list. See the description in the template itself (PDMListQuery). This template is used to generate various lists of tables, etc., as well as the summary list of indexes.
• PDMSchemaChangeSummary — Constructs the summary of schema changes in the GIM PDM.