Instructions

Architecture

Version and Page Name Conventions

Graphics File Name Conventions

In general, the expected pattern for graphics files in the PDMs is:
<prodshort>-<category>-<descriptive file name>-<RDBMS>.png
where:

• <prodshort> is a required element, and must match the official product short name (GIM, ICON, RAA, etc).
• <category> is an optional element, intended to facilitate subsequent page-construction queries, grouping or searching. This element is required for diagrams of the database objects in PDMs, for which the category must be one of the following: SA (for GIM and RAA Subject Area pages), Schema (for ICON schema pages), View.
• <descriptive file name> is a required element, must contain no spaces or punctuation, and preferably use CamelCase.
• <RDBMS> is a required element if the diagrams are RDBMS-specific, otherwise optional. If specified, this suffix must be one of the following: Ora, MSSQL, Postgre, DB2.

See the annotated templates for Subject Area pages and Schema pages for rules for specifying diagrams on those pages.

Populating the Library Book Pages

Table Pages

Each database table has its own page, with a topic name starting with Table-. The structure and presentation of the content is strictly controlled by templates. All content that is to appear on the final pages must be entered within specific template parameters. All information related to a particular table — descriptions and metadata (e.g., when introduced) about the table and its columns, indexes, and references to other tables — goes on that table's page, in parameters inside the following templates:

• {{PDMTable}}
• {{PDMColumn}}
• {{PDMIndex}}
• {{PDMIndexItem}}
• {{PDMRef}}

See Template Parameters and Syntax for PDM Pages for both a blank sample and an annotated table page "template".

View Pages

Each view has its own page, with a topic name starting with "View-". Content is populated similarly to tables, except that the template that controls View pages is named {{PDMView}}.

Subject Area Pages

Each subject area has its own page, with a topic name starting with "SubjArea-". Again, all content is entered into template parameters. The template that controls Subject Area pages is named {{PDMs_SubjectArea}}.

See template parameters and syntax for Subject Area pages for both a blank sample and an annotated Subject Areas page "template", including important information about how you specify graphics file names for diagrams on the page.

General Discussion Pages

As far as possible, single-source general text pages that are outside the formal table/view, etc. structure. Remember to enclose the content to be transcluded inside <onlyinclude> tags, and use {{#switch}} or {{#if}} functions to control what content and link syntax is used for the various Library or RDBMS-specific manuals and versions. JD to do: Provide examples of useful switch functions.

Populating the Reference Manual Pages

Each table, view, schema, or subject area must have its own page, named identically to the equivalent page in the Library book. These pages are populated entirely by query via a single template call. In addition, other templates provide queries to generate summary lists — for example, lists of tables or indexes — which you can put on stand-alone pages or embed within description tags on table, schema, etc. pages.

Table/View/Schema/Subject Area Pages

Use the following template calls to populate the individual "database object" pages.

• Table pages (i.e., topic name is Table-TABLE_NAME): {{PDMTableDPL}}
• View pages (i.e., topic name is View-VIEW_NAME): {{PDMViewDPL}}
• Schema pages (i.e., topic name is Schema-SCHEMA_NAME): {{PDMSchemaDPL}}
• Subject Area pages (i.e., topic name is SubjArea-SUBJECT_AREA_NAME): {{PDMs_SubjectAreaDPL}}

General Discussion Pages

Use the following template call to populate general text content that you're single-sourcing from a page with the same name in the Library book:

• {{PDMTransclude}}

The template will automatically adjust the transclusion syntax for the Library book version you're transcluding from, using <two-digit rel>DRAFT to populate a <two-digit rel>DRAFT version of the manual and <two-digit rel>PDMSource to populate a <three-digit rel or two-digit-suffix> version of the manual.

Lists

Use the following template calls to generate alphabetical, bulleted lists of:

• Tables: {{PDMListDPL|object=Table}}
• Views: {{PDMListDPL|object=View}}
• Schemas: {{PDMListDPL|object=Schema}}
• Subject Areas: {{PDMListDPL|object=SubjArea}}

The {{PDMListDPL}} template also accepts the following additional parameters in the template call:

• group — The value you specify must exactly match the value of the |group parameter on Table-* pages. In principle, specifying this parameter in the template call will also filter lists of the other database objects, but at present this parameter is expected to be populated only for tables.
• withDesc — A value of yes means that the list item will print out with its short description.
• pattern — Restricts the list to pages whose URLs match the specified pattern. You must specify the URL pattern for the Library book page, excluding the namespace and using the percentage sign as a wildcard to indicate the start and end of the pattern. You can use variables in the pattern specification, but if you are calling the template from a published page (version 8.5.0, etc.), do not use {{PONYDOCSVERSION}}, since the source pages will reside in a different version in the Library book (8.5PDMSource). For examples of the use of variables (but with the additional proviso just noted), see Optional Template Parameters on the Generate Export Lists page.

  Note: In this case, you must specify the full pattern, because it did not seem worth overloading the template to automatically select the correct Library book version (8.5DRAFT or 8.5PDMSource), based on the version status of the page on which you're calling the template. This means that the syntax of the template call will have to be slightly different in draft and published versions of the final Reference Manual. To minimize maintenance, use the {{#switch}} function to put both syntax variants on all pages. See Genesys Info Mart Views for an example.

• notpattern — Restricts the list to pages whose URLs do not match the specified pattern. Follow the same rules as for |pattern.

Examples

• {{PDMListDPL|object=Table|group=SDR}} will generate a list of tables in the SDR group.
• {{PDMListDPL|object=Table|withDesc=yes}} will generate a list of tables including their short descriptions.
• {{PDMListDPL|object=Table|group=SDR|withDesc=yes}} will generate a list of tables in the SDR group, with short descriptions.
• {{PDMListDPL|object=View|notpattern=%GIM:Library:View-ADMIN%:8.5PDMSource{{!}}%GIM:Library:View-CTL%:8.5PDMSource|withDesc=yes}} will generate a list of non-administrative or control views (Library book topic names do not start with View-ADMIN or View-CTL), with short descriptions.

Question: Tanya/Vivian/Tony, will any of these lists get long enough that we should format them in columns? We could have an additional optional parameter to specify the number of columns.

Summary Tables

Use the following template calls to generate summary tables (possibly called "List" in the manual) of:

• Indexes: {{PDMIndexListDPL}}
• References: {{PDMRefListDPL}}

The templates to generate summary lists accept an optional |schema parameter, to restrict the results to the specified schema.

JD to check: List of tables by schema?

JD notes -- to do

PDMListTableBySchema

Underscores at end of page name -- add into and then remove from XML? Underscores in export list.

Collapse repeated fields. GIM: CONTACT_ATTEMPT_FACT.RECORD_FIELD_1-60 IRF_USER_DATA_CUST_1.CUSTOM_DATA_1-16 RECORD_FIELD_GROUP_1.RECORD_FIELD_1_STRING_1-10 RECORD_FIELD_GROUP_2.RECORD_FIELD_2_STRING_1-10 USER_DATA_CUST_DIM_1.DIM_ATTRIBUTE_1-5

The Library book version that’s the source for published docs will be “<two-digit rel>PDMSource” – e.g., 8.5PDMSource, 8.1PDMSource.

We want everything to be self-maintaining, so that when you push pages from one version to another, the DPL calls automatically adjust to use Library book pages from and produce links to the correct versions. FYI for how the template calls will work to populate content in the PDMs:

• For template calls from a page in a released PDM version, the templates will pick up the first two digits of that version and append “PDMSource”. So a template call on a GIM 8.5.0, 8.5.1, etc. page will use 8.5PDMSource and an ICON 8.1.4, 8.1.5, etc. page will look for 8.1PDMSource.
• For template calls from a page in an unreleased or preview PDM version, the templates are currently set to look for a library book in a matching version. So 8.5DRAFT goes to 8.5DRAFT, etc.
• In case this doesn’t cover all situations, I am also setting the templates to accept a |source parameter in the template call. So, e.g., if we have an 8.5-pr preview version with the template call specifying |source=8.5DRAFT, the DPL will use the 8.5DRAFT version of the Library book. This has the disadvantage that you might have to update the template call if you subsequently push the 8.5-pr page to another version.