Jdruker/GCXI Instructions
Contents
Writer's Job Aid (aka How to use this document)
The model to provide reference information to support creation of reports is really three pieces:
- A library, which has all the content that is used to generate the customer-facing pages
- Some templates, which extract and format the data from the library
- A customer-facing doc that just calls the templates
Library
Pretty much all the content for the customer-facing document comes from the Library, where it is jammed into the wacky template parameters. See: https://docs.genesys.com/Documentation/GCXI/9.0DRAFT/Library/Welcome
Because GCXI /MSTR organizes the Project objects into folders and subfolders, so does this document.
About Folders
Each folder page represents a folder, and subfolders, that would be found within one of the project root folders:
This is the main Genesys CX Insights project -- "open this folder to browse objects, such as prompts, attributes, and metrics, organized in a convenient hierarchy. When you are creating or modifying reports, select metrics and attributes from a given subfolder, to ensure compatibility."
This is a separate project for Genesys CX Insights for iWD reporting -- "open this folder to browse objects, such as prompts, attributes, and metrics, organized in a convenient hierarchy. When you are creating or modifying reports, select metrics and attributes from a given subfolder, to ensure compatibility."
How the library handles this
Each Library book page populates a page with the same topic name in the customer-facing doc. There are two versions of the Library book, both unreleased: 9.0DRAFT and 9.0PGSource. Content in 9.0DRAFT populates pages in the draft (unreleased) version of the customer-facing doc, and 9.0PGSource populates the published (released) version.
- You create the Library book content in the 9.0DRAFT version and you "publish" it in the usual way by using the update tool to push content from 9.0DRAFT to 9.0PGSource.
- When you first create and publish a customer-facing page, you do so in the usual way, but for future updates you don't touch these pages again unless you need to modify content that falls outside the templates (see Customer-facing documents).
The final output on the customer-facing page is constructed by queries, which draw on parametric (a.k.a. templatized) markup on the Library pages.
Your Library book pages can include, as straight wiki markup, any notes, comments, or headings that will help you organize and manage the content. However, the content itself -- in other words, all the reference information you want to include on the customer-facing pages -- must be entered in a very structured way as values for template parameters inside template calls. The query templates that generate the customer-facing pages will ignore any markup outside the template parameters.
There are currently no forms associated with the pages, to streamline data entry for the templatized content. This enhancement can be considered for the future, particularly if dev contributors are brought into the picture.
For your convenience, each Library book page shows the template markup you must use for individual entries on that page. To add or edit table/metric/attribute information on the Library book pages, it's easier to use the Edit Source tab (not the visual editor you get from the Edit tab). To add a new folder/metric/attribute, copy the blank template markup at the top of the applicable page, paste it anywhere on the page, populate the respective parameters with the applicable information, then save the page in the usual way.
The order in which parameters appear inside a template call is not significant, but it's good practice to always use a consistent set of parameters.
You don't have to populate all the parameters inside a particular template call, but be aware that some queries rely on certain parameters, and leaving them empty might affect query results -- for example, a metric might be incorrectly included in or missing from a particular list. Some parameters are not yet being used in any queries, but they've been set up to accommodate expected future requirements and template enhancements. Therefore, even if a particular parameter isn't directly included in information displayed on the customer-facing page, don't assume that you can ignore it. In general, try to populate all the parameters whose default setting, as described below for the respective templates, does not match reality.
Page names
Page-naming conventions in the Library book and in the customer-facing pages that use the Library book content are very strict.
- Each top-level (root) folder has its own page, with topic name=<name of folder>.
- For each top-level folder, there are separate pages for Metrics and Attributes. The topic names must be:
- <name of folder>Metrics
- <name of folder>Attributes
- The customer-facing doc must have a set of equivalently named pages.
The following subsections provide detailed information about the markup to populate the respective types of Library pages:
Folder pages -- Library
Folder pages in the Library book contain the markup for the templates that capture folder and report information.
The folders markup
The markup for each top-level folder and its subfolders goes on the folder page for that root folder, each inside its own {{GCXI_Folder}} template call. The information is captured in the following parameters:
{{GCXI_Folder
|folderName = The folder name. If it is a subfolder, include the parent folder and a "greater than" symbol (>). For example, "Callback" or "Callback > Detail"
|longDesc = Full description, up to 2000 characters.
|shortDesc = Less than 300 characters. Links and special formatting will be lost from this field, in some contexts.
|cloud = Indicates whether the folder is supported for cloud. If no value, then default = yes. (Not currently used)
|premise= Indicates whether the folder is supported for premise. If no value, then default = yes. (Not currently used)
|project = Identifies objects that do not belong to the GCXI project. For objects in the GCXI project, leave this blank. For objects that are not part of the GCXI project, enter the project name(s) here in a comma-separated list. For example: "iWD". (Not currently used*)
|notproject = Identifies objects that are in all projects except the one(s) specified. In a comma-separated list, enter the project name(s) of the project(s) to which the folder doesn't apply. (Not currently used and unlikely to ever be needed)
|introduced = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the folder was introduced on both cloud and premise at the same time.
|modified = A release number with no embellishment, for example: "9.0.010.04". Put information about what changed into the longDesc.
|discontinued = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the folder was discontinued on both cloud and premise at the same time.
|anchor = The anchor that will be used on the customer-facing page as a target for links. Use the exact string of the folder path and object name with no spaces. For example, if you had an object named Accepted Once in the Callback > Detail folder, this string should read: CallbackDetailAcceptedOnce
}}
* Note about the |project parameter: Strictly speaking, the template entries for the iWD project folders should should "|project = iWD". However, because the iWD project falls neatly into a single root-level folder in the GUI, it has been treated as simply another root-level folder, with the TOC hierarchy used to indicate that it's a separate project.
The reports markup
The markup for each report goes on the page for the folder in which the report is available, each inside its own {{GCXI_Report}} template call. The information is captured in the following parameters:
{{GCXI_Report
|reportName = (Required) The name of the report, as it appears in the User's Guide.
|shortDesc = Less than 300 characters. Links and special formatting will be lost from this field, in some contexts.
|longDesc = Full description, up to 1000 characters.
|cloud = (If applicable) Indicates whether the report is available for cloud. If no value, then default = yes.
|premise= (If applicable) Indicates whether the report is available for premise. If no value, then default = yes.
|project = Exact usage TBD. Same as for folders.
|notproject = Same as for folders.
|displaysInFolder = (Not currently used for report objects) Tony, I moved the planned description into the template as an FYI note for the template developer.
|compatibleWith = (Not currently used — usage TBD)
|introduced = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the report was introduced on both cloud and premise at the same time.
|modified = A release number with no embellishment, for example: "9.0.010.04". Put information about what changed into the longDesc.
|discontinued = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the report was discontinued on both cloud and premise at the same time.
|reportPage = (Required) Name of the page in the User's Guide where the report is described.
|anchor = (If applicable) The anchor that will be used on the customer-facing page as a target for links, if the report heading is not the H1 on the target page. Match whatever anchor is on the target page.
}}
Metrics pages -- Library
The markup for each metric goes on the <name of folder>Metrics page for the folder in which the metric is defined in the GUI, each inside its own {{GCXI_Metric}} template call. In the code, some metrics are shortcuts to metrics actually defined in another folder. The |displaysInFolder parameter in the template handles this use case.
The information is captured in the following parameters:
{{GCXI_Metric
|metric= The metric name. For percent metrics, spell out "percent" (for example, "Percent Abandoned Inviting"). Tony, are there any other special characters that are likely to be used?
|displayName= The metric name as you want it to display (for example, "% Abandoned Inviting"). If not specified, the metric name is used as the display name.
|shortDesc= Less than 300 characters. Links and special formatting will be lost from this field, in some contexts.
|longDesc= Full description, up to 2000 characters.
|type= The metric type. One of: Disposition|Interval|Detail
|mediaType= A comma-separated list of the supported media type(s). For example: "voice, data" or "all".
|dataType= The general classification of how the data is represented. One of: Number|Character|Date
|folder= The folder or subfolder in which the metric is stored (defined in the code). If it is a subfolder, include the parent folder and a "greater than" symbol (>). For example: "Callback" or "Callback > Detail".
|displaysInFolder= For cases where a given metric appears in another folder as a shortcut, a comma-separated list of the other folder(s) in which the metric appears. If it is a subfolder, include the parent folder and a "greater than" symbol (>).
|internalMetricID= An ID that further identifies the measure. This ID is for reference only, to capture information GCXI uses internally. (Not currently used in any queries)
|dbTable= A comma-separated list of the table(s)/view(s) and column(s) from which data is retrieved in your data mart. Populate either this parameter or |calculation.
|calculation= The calculation that generates the value for this metric. Populate either this parameter or |dbTable.
|usedIn= A comma-separated list of all the reports that use this metric.
|project = For objects in the GCXI or iWD* project, leave this blank. For objects that are not part of the GCXI project, enter the project name(s) here in a comma-separated list.
|notproject = In a comma-separated list, enter the project name(s) of the project(s) to which the folder doesn't apply. (Not currently used and unlikely to ever be needed)
|introduced = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the metric was introduced on both cloud and premise at the same time.
|modified = A release number with no embellishment, for example: "9.0.010.04". Put information about what changed into the longDesc.
|discontinued = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the metric was discontinued on both cloud and premise at the same time.
|anchor= The anchor that will be used on the customer-facing page as a target for links. Use the exact string of the folder path and object name with no spaces. For example, if you had a metric named Percent Abandoned Inviting (with displayName=% Abandoned Inviting) in the Agent > Activity folder, this string should read: AgentActivityPercentAbandonedInviting
}}
Attributes pages -- Library
Attributes pages in the Library book contain the markup for the templates that capture attribute and form information.
The attributes markup
The markup for each attribute goes on the <name of folder>Attributes page for the folder in which the attribute is defined in the GUI, each inside its own {{GCXI_Attribute}} template call. In the code, some attributes are shortcuts to attributes actually defined in another folder. The |displaysInFolder parameter in the template handles this use case.
The information is captured in the following parameters:
{{GCXI_Attribute
|attr= The attribute name
|shortDesc= Less than 300 characters. Links and special formatting will be lost from this field, in some contexts.
|longDesc= Full description, up to 2000 characters.
|folder= The folder or subfolder in which the attribute is stored (defined in the code). If it is a subfolder, include the parent folder and a "greater than" symbol (>). For example: "Callback" or "Callback > Detail".
|displaysInFolder= For cases where a given attribute appears in another folder as a shortcut, a comma-separated list of the other folder(s) in which the attribute appears. If it is a subfolder, include the parent folder and a "greater than" symbol (>).
|dataType= The general classification of how the data is represented. One of: Number|Character|Date
|form= A comma-separated list of the "detail" sub-attributes (aka forms).
|lov= The list of values that populate the corresponding prompt. (Not currently used and unlikely to ever be needed)
|internalMetricID= An ID that further identifies the measure. This ID is for reference only, to capture information GCXI uses internally. (Not currently used in any queries)
|dbTable= A comma-separated list of the source Info Mart table(s), view(s), alias(es), or synonym(s) and column(s) from which data is retrieved for this attribute. Tony, the source list is slightly more extensive than for GCXI_Metric. OK to make them identical?
|usedIn= A comma-separated list of all the reports that use this attribute.
|project = For objects in the GCXI or iWD* project, leave this blank. For objects that are not part of the GCXI project, enter the project name(s) here in a comma-separated list.
|notproject = In a comma-separated list, enter the project name(s) of the project(s) to which the folder doesn't apply. (Not currently used and unlikely to ever be needed)
|introduced= A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the attribute was introduced on both cloud and premise at the same time.
|modified = A release number with no embellishment, for example: "9.0.010.04". Put information about what changed into the longDesc.
|discontinued = A release number with no embellishment, unless you need to show separate support on cloud and premise. For example: "9.0.010.04" or "9.0.010.04 (cloud), 9.0.011.15 (on-premises)". A release number with no parenthetical comment (i.e., the first example) means the attribute was discontinued on both cloud and premise at the same time.
|anchor= The anchor that will be used on the customer-facing page as a target for links. Use the exact string of the folder path and object name with no spaces. For example, if you had an attribute named End Timestamp in the Agent > Detail > Session folder, this string should read: AgentDetailSessionEndTimestamp
}}
The forms markup
The markup for each form goes on the page for the attribute(s) for which the form is used, each inside its own {{GCXI_Form}} template call. The information is captured in the following parameters:
{{GCXI_Form
|form= The form name
|formDisplayName= The form name as you want it to display. If not specified, the form name is used as the display name.
|shortDesc= Less than 300 characters. Links and special formatting will be lost from this field, in some contexts.
|longDesc= Full description (expected to be the same as shortDesc -- unlike in other templates, the size of this field has not been increased to more than 300 characters).
|dataType= |dataType= The general classification of how the data is represented. One of: Number|Character|Date
|dbTable= A comma-separated list of the source Info Mart table(s), view(s), alias(es), or synonym(s) and column(s) from which data is retrieved for this attribute. Match to attr.
|introduced= A release number with no embellishment, unless you need to show separate support on cloud and premise. See above for examples.
|modified = A release number with no embellishment, for example: "9.0.010.04". Put information about what changed into the longDesc.
|discontinued = A release number with no embellishment, unless you need to show separate support on cloud and premise. See above for examples.
|anchor= The anchor that will be used on the customer-facing page as a target for links. If not specified, the form name is used as the anchor, with underscores replacing wordspaces.
}}
Templates
The above-referenced templates are the only templates you can use to store folder/report/metric/attribute/form information in Cargo. Talk to Jose, or someone else who can edit them. Or if that's you, see <Links from Jose> For a list of the supported values in each template, see these pages:
- Folders — https://docs.genesys.com/Template:GCXI_Folder
- Metrics — https://docs.genesys.com/Template:GCXI_Metric
- Attributes — https://docs.genesys.com/Template:GCXI_Attribute
|compatibleWith considered for metrics and attributes. See history
Customer-facing docs
Creating GCXI Reports
This document contains a similar ToC to the Library, and draws most of its content from the library. https://docs.genesys.com/Documentation/GCXI/9.0DRAFT/PG/Welcome
The exception: procedures
There are a few procedures that are useful (shared with the UG?)
The rule: pages that draw from the library
All of the Folder, metric, attribute, and report pages (if present) are generated by templates, based on the Library. To edit them, look for a same-named page in the library (https://docs.genesys.com/Documentation/GCXI/9.0DRAFT/Library/Welcome) or for a page of the right type. So, if you see a metric definition on any page in this book, look for the corresponding metrics page (nested below a folder page) in the library doc.
The markup on the customer-facing page is the following template call:
{|
{{GCXI_Folder_Display}}
|}