SentryOne DOC xPress

Release Notes

A PDF copy of release notes for SentryOne DOC xPress may be downloaded here.

SentryOne DOC xPress Overview

Single Machine Hardware Requirements

In the single machine deployment model, the same machine has the SentryOne Workbench and the DOC xPress database installed. The SentryOne Workbench is the program that contains SentryOne DOC xPress and its associated assemblies, while the DOC xPress database is hosted within a SQL Server Instance.

The following memory and processor requirements apply to all editions of DOC xPress:

Component Minimum RequirementRecommended Requirement
Memory4 GBAt least 8 GB and should be increased as the DOC xPress database size increases to ensure optimal performance.
Processor Speed1.4 GHz2.0 GHz or faster
Processor TypeNot ApplicableAny x64 Processor

Multiple Machine Hardware Requirements

In the multiple machine deployment model, the SentryOne Workbench and the DOC xPress database are installed on separate machines. The SentryOne Workbench is the program that contains SentryOne DOC xPress and its associated assemblies, while the DOC xPress database is hosted within a SQL Server Instance. 

Important:  It's important to differentiate between the client machine and the server machine:

  • Client machine is the machine where the SentryOne Workbench is installed.
  • Server machine is the machine containing a SQL Server instance where the DOC xPress database is deployed.

The following memory and processor requirements apply to all editions of DOC xPress:

Client Hardware Requirements

Component Minimum RequirementRecommended Requirement
Memory4 GB6 GB
Processor Speed1.4 GHz2.0 GHz or faster
Processor TypeNot ApplicableAny x64 Processor

Server Hardware Requirements

Component Minimum RequirementRecommended Requirement
Memory4 GBAt least 6 GB and should be increased as the DOC xPress database size increases to ensure optimal performance.
Processor Speed1.4 GHz2.0 GHz or faster
Processor TypeNot ApplicableAny x64 Processor

Software Requirements

Before installing the SentryOne Workbench, make sure you meet the following system requirements:

  • SQL Server Integration Services 2005, 2008, 2008 R2, 2012, 2014, 2016, 2017 BIDS 2005, 2008, 2008 R2 (Business Intelligence Development Studio) or SSDT 2010, 2012, 2014, 2016, 2017 (SQL Server Data Tools)
  • Microsoft ® .NET 3.5 with Service Pack 1
  • Microsoft ® .NET 4.0
  • Microsoft ® .NET 4.5 (2017 Providers only)
  • Microsoft ® SQL Server ® 2012 Transact-SQL ScriptDom x8

The following operating systems are supported by the SentryOne Workbench:

 64-bit (x64) Operating Systems32-bit (x86) Operating Systems
Windows Server 2003 (at least Service Pack 2) *Windows XP (at least Service Pack 3) *
Windows Vista (at least Service Pack 2)Windows Server 2003 (at least Service Pack 3) *
Windows Server 2008 R2Windows Vista (at least Service Pack 2)
Windows Server 2012Windows Server 2008 R2
Windows Server 2016Windows Server 2012
Windows 7Windows 7
Windows 8Windows 8
Windows 10Windows 10

Important:  Windows XP and Server 2003 have been deprecated from full support. Any issues encountered on either Windows XP or Server 2003 must be reproducible on newer versions of Windows to be eligible for support.

The following prerequisites are required to enable some features within DOC xPress:

  • SQL 2008 or higher is required to create a DOC xPress metabase.

Note:  If you're connected to a valid DOC xPress metabase, SQL 2005 and up may be documented, though there are some limitations to SSRS 2005 and 2008 documentation.

The following prerequisites are required to enable some features within BI xPress and DOC xPress:

64-bit Operating Systems32-bit Operating Systems
Microsoft ® System CLR Types for Microsoft ® SQL Server ® 2012 (or later) x64Microsoft ® System CLR Types for Microsoft ® SQL Server ® 2012 (or later) x86
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x64Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x64Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Transact-SQL ScriptDom x64Microsoft ® SQL Server ® 2012 (or later) Transact-SQL ScriptDom x86
Microsoft ® System CLR Types for Microsoft ® SQL Server ® 2012 (or later) x86
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Transact-SQL ScriptDom x86

Providers

ProviderOperating Systems
Hive
64 bit Operating Systems32 bit Operating Systems
64-bit HortonWorks Hive ODBC Driver32-bit HortonWorks Hive ODBC Driver
32-bit HortonWorks Hive ODBC Driver
SQL
64-bit Operating Systems32-bit Operating Systems
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x64Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
SSAS
64-bit Operating Systems32-bit Operating Systems
Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x64Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Analysis Management Objects x86
  • Microsoft ® .NET 4.5 is required by SSAS 2017 Only.
  • SSAS Azure Analysis Services:
    • Microsoft Azure Analysis Services Client Libraries
SSIS
  • Microsoft ® .NET 4.5 (Required by SSIS 2017 Only)
  • Each version of SQL Server Integration Services (2008 R2 or above) that you want to document.
  • SQL Server Data Tools or Business Intelligence Development Studio.
  • Any Third-Party Products (Connection Managers, Tasks, Components, etc) that are used within the SSIS Package(s)
SSRS
  • At least one version of SQL Server Reporting Services (2008 R2 or above) that you want to document.
  • SQL Server Data Tools or Business Intelligence Development Studio.
  • Support provided for the following report locations:
    • File System: SQL Server 2005 and above
    • Native Web Services: SQL Server 2008 R2 and above
    • SharePoint Web Service: SQL Server 2008 R2 and above
Informatica PowerCenterIf connecting to a SQL Repository:
64-bit Operating Systems32-bit Operating Systems
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x64Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
Microsoft ® SQL Server ® 2012 (or later) Shared Management Objects x86
If connecting to an Oracle Repository:
64-bit Operating Systems32-bit Operating Systems
64-bit Oracle Data Access Components (ODAC) 12c
  • 64-bit Oracle 12c Managed Data Access Client installed into the GAC
32-bit Oracle Data Access Components (ODAC) with Oracle Developer Tools for Visual Studio 12c
  • 32-bit Oracle 12c Managed Data Access Client installed into the GAC
32-bit Oracle Data Access Components (ODAC) with Oracle Developer Tools for Visual Studio 12c
  • 32-bit Oracle 12c Managed Data Access Client installed into the GAC

System Requirements for other SentryOne Workbench products:

The following prerequisites are required to enable some features within BI xPress:

BI xPress extension for Visual Studio 2015 requires:

  • An installation of one of the following editions of Visual Studio:
    • Visual Studio 2015 Community Edition        
    • Visual Studio 2015 Professional
    • Visual Studio 2015 Enterprise
  • The following extension installed within their Visual Studio 2015 environment:
    • SQL Server Data Tools for SQL Server 2016 (now includes BI Projects)

Plug-ins:

  • Auditing Framework, BI Compare, Package Builder Wizard, and/or SSIS Unit Test:
    • Any Third-Party Products (Connection Managers, Tasks, Components, et cetera) that are used within the SSIS Package(s)
  • Report Mover
    • Reporting Deployment is compatible with SQL 2008 R2 or later
  • Report Monitoring Console:
    • Reporting Performance Monitor is compatible with SQL Server 2008 or later

Required Permissions

Many of the features within the SentryOne Workbench only need db_owner for database updates when upgrading from an older version to a newer version. Outside of database updates, you only need db_datareader and db_datawriter permissions. 

The following is a comprehensive list of each feature and their required permissions:

DOC xPress Required Permissions

DOC xPress database:

Permissions needed for Regular UsagePermissions needed for Database Updates
  • db_datareader
  • db_owner
  • db_datawriter

Technology specific permissions:

TechnologyRequired Permissions
Hive
  • Read permissions for the HDFS files that you want to document
Azure Power BI 
  • Content.Create
    • Delegated
    • Create content
  • Dashboard.Read.All
    • Delegated
    •  View all dashboards
  • Dashboard.ReadWrite.All
    • Delegated
    • Read and write all dashboards
  • Dataset.ReadWrite.All
    • Delegated
    • Read and write all datasets
  • Group.Read
    • Delegated
    • View user's groups
  • Report.ReadWrite.All
    • Delegated
    • Read and write all reports
Informatica Powercenter
  • View definition permissions on the Informatica repository
  • Read permissions within the Informatica repository on any folder and object you want to document
SQL Server
  • Definition permissions for any object you want to document
SQL Server Analysis Services
  • Multidimensional:
    • Read definition permission on each database object you want to document
  • Tabular:
    • Administrator permission on each database object you want to document
SQL Server Integration Services
  • SSIS Catalog:
    • Read and Modify permission for each project within the SSISDB you want to analyze
SQL Server 2008 R2 (or higher) Reporting Services
  • Folder Security Settings:
    • Minimum Predefined User Roles required:
      • My Reports
      • Content Manager
    • Minimum Tasks required for a custom User Role:
      • View Reports
      • View Folders
      • View Data Sources
      • View Models
      • Consume Reports
  • Web Service Security Settings:
    • Minimum Predefined System Role required:
      • System User
    • Minimum Tasks required for a custom System Role:
      • Execute Report Definitions
Tableau Permissions
  •  You must be a part of the Server Administrator role

Installing DOC xPress

DOC xPress produces documentation for your SQL Server instances and enables the documentation for the following providers:

  • SQL Server
  • Analysis Services (SSAS) 
  • Integration Services (SSIS) 
  • Reporting Services (SSRS) 
  • Hive Server 
  • Informatica PowerCenter Repositories 

Additional Information: Your license for DOC xPress determines the number of documentation targets that you can snapshot and generate documentation for within your environment. For more information about licensing for DOC xPress, see the DOC xPress product page

DOC xPress documents information about your tables and databases. Using the snapshot tools provided you can take a picture of your database's information at a certain point in time to create metadata. After making sure that your system meets the System Requirements for DOC xPress, you can begin the installation process. Complete the following steps to install DOC xPress on your machine:

  1. Run the SentryOne Workbench Installation file to display the Installation wizard.
  2. Select I agree to the License terms and conditions, and then select Next to continue the installation. DOC xPress Installer Agree to License terms and Conditions

Note:  Send feature usage statistics to SentryOne is selected by default. Deselect the checkbox if you want to opt out of telemetry. 

Typical Setup

3. Select the Typical setup type to begin the installation.  

DOC xPress Installer Typical Setup
DOC xPress Installer Installation progress

Note:  The Typical setup type is recommended for most customers.

4. Select Finish to complete the installation. 

DOC xPress Installer Finish installation

Custom Setup

3. Select Custom setup to open shortcut selection. Select the checkboxes where you want to install the DOC xPress shortcut, and then select Next to Continue.

DOC xPress Installer Custom Setup
DOC xPress Installer Shortcut options

4. Select the components of the SentryOne Workbench that you want to install, and then select Install to begin the installation. 

DOC xPress Installer Install selected components
DOC xPress Installer Installation Progress

5. Select Finish to complete the installation. 

DOC xPress Installer Finish installation

Success: Your DOC xPress Installation is ready to use!

Note:  When running a trial version of DOC xPress, only the first three topics at each level are generated for documentation.

AlwaysOn Availability Group Installation Considerations

If you want to install the DOC xPress metabase to an AlwaysOn Availability Group as an availability database, consider the following: 

Note:  The following section isn’t intended to be a guide for configuring an AlwaysOn Availability Group. This guide is assuming that an AlwaysOn Availability Group has already been properly configured and you want to add the DOC xPress metabase to an existing availability group as an availability database.

Client Installation

The SentryOne Workbench doesn’t require any additional setup instructions before configuring Workbench's databases to work within an AlwaysOn Availability Group.

Once the SentryOne Workbench is installed,  you can create the DOC xPress metabase through the Workbench UI. When you create a DOC xPress metabase, configure its server settings to point to the availability group listener. After the database has been created, continue to Adding the Databases to the Availability Group below.

Note:  If you want to use an existing DOC xPress metabase, you can execute a full recovery back up of your database and restore it on your primary availability replica before continuing to add the database to an availability group.

Adding the Databases to the Availability Group

After creating your metabase, you can add it as an availability database to the availability group. The following process is the same way you would add any other database to an availability group:

  1.  Within the database properties, set the databases' recovery model to Full.
  2. Create a network share that each availability replica has permissions to access.
  3. Create a full back up of each database on the network share created in Step two.
  4. Expand AlwaysOn High Availability within Management Studio's object explorer. Right-click on the availability group that you want to add the database(s) to and then select Add Database...DOC xPress AlwaysOn Add Database
  5. Walk through the steps within the Add Database to Availability Group wizard, ensuring the database(s) selected meet all of the prerequisites. On the Select Data Synchronization page, select Full and specify the network share created in Step two as the location accessible by all replicas.DOC xPress Add Database to Availability Group

Once the DOC xPress metabase has been added to the availability group as an availability database, connect to the metabase through the availability group listener.

Activating the Workbench

Activate your DOC xPress License within the Product section of the Workbench Help tab. The Help tab manages licensing and version information, and provides you with quick access to the user documentation. 

Additional Information: Your license for DOC xPress determines the number of documentation targets that you can snapshot and generate documentation for within your environment. For more information about licensing for DOC xPress, see the DOC xPress product page

Activate any SentryOne Workbench Product by completing the following steps:

1. Open the SentryOne Workbench, then open the Help page. SentryOne  Workbench Help tab

2. Select the product you want to activate, then select Register to open the Licensing window. SentryOne Workbench Help Window select Register

3. Select an activation method, then select OK to continue.

SentryOne  Workbench Use an activation key
SentryOne  Workbench Activate manually without internet connection

Note:  Select Use an activation key if you already have an activation key, and access to the internet. Select Activate Manually without Internet Connection if you need assistance from SentryOne's technical support or do not have internet access.

Use an activation key

4. Paste or type the activation key within the appropriate textbox, then select Activate to complete the license activation. SentryOne Workbench Use an activation key

Success: A green check mark appears for a valid license after entering the activation key.

Activate without internet connection

4. Select Copy Details to Clipboard to copy the environment key. Send an email with the copied information to Support@sentryone.com to obtain a manual key from support. SentryOne  Workbench Activate manually without Internet connection

5. Paste the manual key within the appropriate box and then select Activate to complete the activation process.

SentryOne  Workbench Activate manually without Internet connection

Once you have successfully activated your license, the licensing window displays a list of all the currently activated products in the SentryOne Workbench. SentryOne  Workbench Licensing Activation Complete

Activation Warnings

You may encounter the following warnings during the activation of the SentryOne Workbench:

Already Activated License

Activation Failed There are no licenses left to activate this application.

SentryOne Workbench Licensing Activation Failed

This warning is due to license already being activated. Resolve this warning by completing the following steps:

1. Go to your SentryOne account management at https://www.SentryOne.com. Select My account to open the account manager.

SentryOne select My Account

2. Log in with your SentryOne account username and password. Go to the S1 TaskFactory/Workbench Licenses section and select the product key you want to register.

SentryOne Log into Web Portal
Log into the S1 Portal

SentryOne select the Product License
Select the Product License

3. Select View Activations to open the Activated Environments for the license. Select the Environment key for the Environment you want to deactivate.

SentryOne select View Activations
View Activations

SentryOne select Deactivate
Deactivate Environment

Note:  After looking at this information, if you find a license that you can deactivate, you can deactivate it through the help page of the Workbench. If that user is no longer with the organization, you can contact support.sentryone.com through email with the Environment Identifier and Environment Key to deactivate the license.

Locks On Icons

If your product is displaying a lock on the upper left hand corner of any of your feature's icons, you need to purchase an activation license for that product. Purchase a license for the desired product at the SentryOne product website.   SentryOne  Workbench Icons Locked

Note:  You may see this after your trial period has ended and you have yet to activate your product.

Deactivating a License

You can deactivate your product in the SentryOne Workbench Help tab. The Help tab manages licensing and version information, and provides you with quick access to the user documentation. 

The licenses for the SentryOne Workbench are per machine. If another machine needs to run Workbench, then the second machine needs a license. You can move a license from an old machine to a new machine. Moving a license requires you to deactivate the license on the old machine and then reactivate it on the new machine. Deactivate a license by completing the following steps:

  1. Open the SentryOne workbench, then open the Help page. SentryOne  Workbench Help tab
  2. Select the desired product, then copy the activation key to the clipboard. SentryOne Workbench Copy Activation Key
  3. Select Deactivate for the product(s) you want to deactivate to open the Deactivate License prompt.
  4. Select Yes to Deactivate the license. SentryOne Workbench Deactivate License

Workbench Features

After the SentryOne Workbench is installed, launching the SentryOne Workbench automatically directs you to the Workbench toolbar with the Feature Finder page selected. 

In the upper left corner of SentryOne Workbench is a toolbar buttonSentryOne Workbench Toolbar button that allows you to minimize and maximize the Workbench toolbar. SentryOne Workbench Feature Finder

 The Workbench toolbar contains six options that help you navigate to or configure the following features:

Toolbar OptionDescription
Feature FinderAllows you to navigate through the features in the SentryOne Workbench.
ActivitiesGives you a historical record of all actions taken across each product feature during the current session and allows you to search activities that occurred in previous sessions.
OpenA way to open supported files. Selecting Open automatically opens the best feature for the selected file.
Open RecentGives you a list of recently opened files. Selecting Open Recent automatically opens the best feature for the selected file.
PreferencesDetails feature specific options and allows you to customize the behavior of each feature as desired.
HelpAllows you to check for product updates, activate or deactivate licenses, and view product versions.

Tab Preview

While using the SentryOne Workbench, you can have several features open at same time. Display multiple features lined up side-by-side in tabs above your workspace. Hover over a tab to display a preview of that tab. 

SentryOne Workbench Tab preview

Additionally, the SentryOne Workbench includes a Feature Switcher. The Feature Switcher makes switching between features much easier with a dedicated switching window that includes a preview window for each feature.                 

To open the Feature Switcher, enter Ctrl + Tab, to display a pop up window, and then release tab but continue to hold Ctrl. Enter tab to cycle through the currently open features. Once you've selected the desired feature, release Ctrl to navigate to that specific feature.

SentryOne Workbench open Feature Switcher
SentryOne Workbench Feature Switcher

Feature Finder

The Feature Finder allows you to navigate through the features in the SentryOne Workbench.

Sort the features by technology type, product family, a specific role, keywords, or use a combination of filters and/or keywords. These filters allow you to fine tune the SentryOne Workbench to your needs and make your frequently used features more readily available.

OptionDescriptionImage
TechnologyNarrow down the feature list by eliminating all features that are not associated with the selected technology.SentryOne Workbench Filter Features by Technology
ProductNarrow down the feature list by eliminating all features that are not associated with the selected SentryOne Product.SentryOne Workbench Filter Features by Product
RoleNarrow down the feature list by eliminating all features that are not associated with your Role within your company.SentryOne Workbench Filter Features by Role
Keywords

Narrow down the feature list with the search toolbar by filtering out features that don't contain a specific keyword.

SentryOne Workbench Filter Feature by Keyword

Activities

The Activities page gives you a historical record of all actions taken across each product feature during the current session, and allows you to search activities that occurred in previous sessions.

The Activities page also contains useful information regarding the activity's feature, title, information, status, date started or ended, and the activity log.

SentryOne Workbench Activities

ComponentDescriptionImage
FeatureThe upper left corner of each activity contains the Feature that generated the activity.SentryOne Workbench Activity Monitor Feature
TitleOn the same line as the Feature Name separated by a colon (:), the title of the activity describes the action that occurred within the activity.SentryOne Workbench Activity Monitor Title
InformationBelow the Feature and Activity Title is a general description of the current status of the activitySentryOne Workbench Activity Monitor Information
Date Started or EndedThe far right of the activity displays the date the activity started or ended depending on the current status of the activity.SentryOne Workbench Activity Monitor Date
Activity LogDouble-click on an activity, to view a more detailed activity log.SentryOne Workbench Activity Monitor

Activity Status Legend

The background color of each activity visually describes the current status for the activity.

Color Description
RedActivity completed with at least one error.
GreenActivity completed successfully without errors
YellowActivity completed with warnings
BlueActivity is running, manually stopped, or completed with information.

Activity Search

The Activity Window is a powerful search tool that allows you to search through all activities, regardless of their session. Select the Search tab to begin searching for activities with specific search parameters. Selecting Search from within the Search tab opens the Search Activity Log window.

SentryOne Workbench Activities Search tab
Activities Search Tab

SentryOne Workbench Search Activity Log
Search Activity Log

The Search Activity Log contains five parameters to narrow down the search results by:

ParameterDescription
Finished AfterFilters all activities based on activities that finished after the start of a specific date parameter.
Finished BeforeFilters all activities based on activities that finished before the end of a specific date parameter.
Ending StatusFilters all activities based on the specific ending status of the activity.
Title ContainsFilters all activities based on the whether the title contains a specific string.
Message ContainsFilters all activities based on the whether the message contains a specific string.

Preferences

The Preferences page details feature specific options, and allows you to customize the behavior of each feature as desired. Including a general workbench section, each workbench product has its own preferences that can be used to customize the product's features individually. SentryOne Workbench Preferences

Makes changes to the default key bindings for features and create custom keys by selecting Key bindings... at the bottom left of the Preferences window. SentryOne Workbench Key Bindings

Workbench Preferences

Within Workbench Preferences, customize the behavior and properties for the SentryOne Workbench.

Appearance

SentryOne Workbench Preferences Appearance

PreferenceDescription
Theme NameControls the theme used for Workbench colors.

Behavior

SentryOne Workbench Preferences Behavior

PreferenceDescription
Selected ProductsControls the products to filter by when starting Workbench.
Selected RolesControls the roles to filter by when starting Workbench.
Selected TechnologiesControls the technologies to filter by when starting Workbench.
Show Feature FinderControls whether to show or hide the Feature Finder tool in the features list.
Show Works NewsControls whether to show or hide the Works latest news and messages. The latest product features, discounts, and tips will be shown here.
Start-up Plug-inControls the plug-in that loads when Workbench first starts.
Error ReportingControls whether to send anonymous error reporting information to Works.
Usage ReportingControls whether to periodically send anonymous feature usage reporting to Works.

DOC xPress Preferences

Within the DOC xPress Preferences, customize the behavior and properties of Data Dictionary, DOC xPress, and Lineage Analysis:

Data Dictionary

SentryOne Workbench Preferences Data Dictionary

PreferenceDescription
EnabledControls whether or not auto save is enabled.
IntervalControls the number of minutes between auto saves.

DOC xPress 

General

SentryOne Workbench Preferences DOCxPress General

PreferenceDescription
Automatically Open Generated DocumentsControls whether to automatically open documents once they generate.
 Default Output FolderControls the default folder where generated documentation is placed.
HTML Help Workshop CompilerControls the file path to the HTML Help Workshop compiler executable used by CHM documentation generation.
Snapshot Combination TimeControls the number of minutes between snapshot updates where the two updates are considered to be a part of the same snapshot update.
Automatically Update Default OutputControls whether the default output folder for generated documentation should update whenever a new output folder is selected.

Metabase

SentryOne Workbench Preferences DOCxPress Metabase

PreferenceDescription
Command TimeoutControls the timeout applied to operations against the DOC xPress metabase.
Connection StringControls the connection string used to connect to the DOC xPress metabase.

Templating

SentryOne Workbench Preferences DOCxPress Templating

PreferenceDescription
Disable Data Dictionary OutputControls whether to suppress data dictionary elements from being generated in documents. Disabling Data Dictionary output does reduce memory usage.
Disable Lineage OutputControls whether to suppress Lineage Analysis images and tables from being generated in documents. Disabling Lineage Analysis output does reduce memory usage.
Source Folder

Controls the folder where templates are loaded to apply to objects when documenting.

Lineage Analysis

Appearance Options

SentryOne Workbench Preferences Lineage Analysis Appearance options

PreferenceDescription
Show Technology Type AdornmentsControls whether to show the name of the technology next to each node within the graph.
Input Link ColorControls the color of input links in the lineage display.
General Link ColorControls the color of general links in the lineage display.
Modification Link ColorControls the color of modification links in the lineage display.
External Dependency ColorControls the color of external dependency nodes in the lineage display.
Selected Item ColorControls the color of selected nodes in the lineage display.
SQL Server ColorControls the color of SQL Server nodes in the lineage display.
SSAS ColorControls the color of SSAS nodes in the lineage display.
SSIS ColorControls the color of SSIS nodes in the lineage display.
SSRS ColorControls the color of SSRS nodes in the lineage display.

Behavior Options

SentryOne Workbench Preferences Lineage Analysis Behavior options

PreferenceDescription
Double-click ModeControls whether to refocus the graph around a double-clicked node, or to extend from it.
Default Follow ModeControls the default link following mode applied to graphs.
Default Detail LevelControls the default detail level applied to graphs.
Default Layout TypeControls the default layout type used to lay out graph nodes.
Default Legend VisibilityControls whether or not the legend is visible by default.
Default Dependency LevelsControls the number of dependency levels shown by default.
Track Selection by DefaultControls whether selection tracking is active by default.
 Default to Trace ModeControls whether trace mode is active by default.
Default View ModeControls the default view mode for interacting with lineage information.
Trace Mode Route LimitControls the maximum number of routes that can be found with trace mode.
Cache Lineage Sets LocallyIf lineage sets are cached locally, then lineage will open faster the second time you view a particular solution snapshot.
Cache PathThis is where the lineage sets are stored so that lineage opens faster. Faster storage will result in faster operation of lineage.

Creating a DOC xPress Solution

Create a new DOC xPress Solution in the SentryOne Workbench by completing the following steps:

1. In the SentryOne Workbench, select DOC xPress.

SentryOne DOC xPress select DOC xPress

2. Open an existing, or create a new DOC xPress metabase. In this example, we create a new DOC xPress metabase by selecting New metabase. Select Browse to open the Connect to Database window, then enter the server name and security information for the connection. Select OK to create the connection string for the server. 

DOC xPress New metabase
New metabase

DOC xPress Browse for server connection
Browse for connection

DOC xPress Connect to Database window
Connect to Database

3. Enter a name for your DOC xPress Metabase, then select Create metabase.

DOC xPress Create metabase

Note:  If you would like to connect to an existing DOC xPress database, select Change Connection, enter your server name and credentials, select the database from the drop-down list, and then select OK.

Note:  If this is your first solution, the solution wizard runs first to walk you through creating a solution. Select Start to create a new solution.

DOC xPress Solution Wizard

4. Select Add to create a new Solution and open the Solution Wizard. Enter a meaningful name for the solution, then select OK.

DOC xPress Add Solution
DOC xPress Solution Wizard Add Solution

Success: You have now created a new DOC xPress Solution!

Note:  The next screen prompts you to name the item and select a source type.

DOC xPress Solution Wizard Add Solution Item form

Managing an Existing Solution

To make changes to an existing DOC xPress Solution, complete the following steps: 

1. Open DOC xPress in the SentryOne Workbench, then select the solution you want to manage.

SentryOne DOC xPress select DOC xPress

2. Select Open to display the associated solution items. Select the desired Solution item, then select Edit to begin making changes. 

DOC xPress Open Solution
Open Solution

DOC xPress Edit Solution item
Edit Solution item

Note:  After a snapshot has completed, you can expand and navigate the metadata for a solution item by using the Metadata Viewer. Select the item you wish to explore, and then select View on the right side of the Items Panel.

Adding Solution Items

Important:  While adding solution items to your DOC xPress Solution, you may run into an issue where the source type you want to use does not show up. If this happens, you may not meet the system requirements for that specific provider. Ensure you have all the system requirements for that specific provider installed properly.

Custom Metadata import

Solution Item IconSolution Item Description
DOC xPress Custom Metadata Import Provider

DOC xPress gathers data using providers. If there is no existing provider for a source, then you can use the Custom Metadata Import provider to import custom metadata files. This is useful when there is a need to incorporate data about unsupported platforms such as Access or DB2.

Component Functionality

FeatureDescription
Best PracticesBest Practices rules can be analyzed for the marked provider(s) once the user has created User Defined Best Practices.
BI CompareThis feature is compatible.
DocumentationDocumentation sets generated from the marked provider(s) do not contain a unique structure and instead use a common layout.
LineageThis feature is compatible.
Data DictionaryData Dictionary categories can be applied to the marked provider(s) once custom paths have been created.

Adding Custom Metadata import

Add a Custom Metadata import Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select Custom metadata import from the Source type drop-down list.   DOC xPress Add solution item Custom metadata import
  4. Enter the file paths for the three necessary files (object file, property file, and lineage file), then select OK to add the solution item. DOC xPress Add solution item Custom metadata import

Note: 

  • Object files contain the names of the objects within in the database.
  • Property files contain information about the objects within the database.
  • Lineage files contain information about how the objects within the database are related.

Success: The files have been applied to the solution. The information gathered from those files is included in the DOC xPress documentation and displays in the lineage analysis. DOC xPress Custom metadata import Solution item example

Excel Spreadsheet

Solution Item IconSolution Item Description
DOC xPress Excel Spreadsheet Provider

DOC xPress allows you to develop a Lineage overview of your Excel Workbooks (*.xlsx) that contains SQL Server and Analysis Services data sources.

Component Functionality

FeatureDescription
Best PracticesBest Practices rules can be analyzed for the marked provider(s) once the user has created User Defined Best Practices.
BI CompareThis feature is compatible.
DocumentationDocumentation sets generated from the marked provider(s) do not contain a unique structure and instead use a common layout.
LineageExcel Spreadsheet Lineage Analysis only supports dependency scanning Data Sources from SQL Server and Analysis Services Databases and does not support PowerPivot.
Data DictionaryData Dictionary categories can be applied to the marked provider(s) once custom paths have been created.

Adding Excel Spreadsheet

Add an Excel Spreadsheet Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select Excel Spreadsheet from the Source type drop-down list.   DOC xPress Add Solution Item Excel Spreadsheet
  4. Select File to document an Excel Workbook on the file system, or select Folder to recursively document all Excel Workbook items within the selected folder.
DOC xPress Add Solution Item Excel Spreadsheet File
Excel Spreadsheet select File

DOC xPress Add Solution Item Excel Spreadsheet Folder
Excel Spreadsheet select Folder

Note:  Selecting the ellipsis launces the file explorer, allowing you to navigate to the desired file or file folder. 

Important:  Excluding some types or items through a filter may affect Lineage Analysis.

5. Select OK to add the Excel Spreadsheet Solution item to your DOC xPress Solution.

DOC xPress Add Solution Item Excel Spreadsheet select Ok

Sample Lineage

DOC xPress allows you to develop a Lineage overview of your Excel Workbooks (*.xlsx) that contain SQL Server and Analysis Services data sources. DOC xPress Excel Spreadsheet Sample Lineage

Hive Server

Solution Item IconSolution Item Description
DOC xPress Hive Server Provider

DOC xPress allows you to document Hive Server components within your environment. 

Hive Server Provider Requirements

64-bit Operating Systems32-bit Operating Systems

Component Functionality

FeatureDescription
Best PracticesBest Practices rules can be analyzed for the marked provider(s) once the user has created User Defined Best Practices.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is incompatible.
Data DictionaryData Dictionary categories can be applied to the marked provider(s) once custom paths have been created.

Note:  Hive Server provider works against HDP 2.0 and above.

Adding Hive Server

Add a Hive Server Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select Hive Server from the Source type drop-down list.   DOC xPress Add solution item Hive Server
  4. Enter a valid connection string to your Hive Server. DOC xPress Add Solution Item Hive Server Connection String

Important:  Excluding some types or items through a filter may affect Lineage Analysis.

5. Select OK to add the Hive Server Solution item to your DOC xPress Solution. 

DOC xPress Add Solution Item Hive Server select Ok

Sample Output

DOC xPress Hive Server Sample Ouptut Example one
DOC xPress Hive Server Sample Ouput Example two
DOC xPress Hive Server Sample Output Example three

Power BI

Solution Item IconSolution Item Description

DOC xPress allows you to document the Power BI Files, Folder, or Azure components in your environment.

Power BI Provider Requirements







Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Adding Power BI

Add a Power BI Solution item by completing the following steps :

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, and then select Power BI from the Source type drop-down list. DOC xPress Add Solution Item Power BI
  4. Select the Power BI File, Folder, or get content from Power BI in Azure.
DOC xPress Add Solution Item Power BI File
DOC xPress Add Solution Item Power BI Folder
DOC xPress Add Solution Item Azure Power BI

 5. Select OK to add the Power BI Solution item to your DOC xPress Solution. DOC xPress Add Solution Item Power BI select Ok

Power BI Report Server

Solution Item IconSolution Item Description

DOC xPress allows you to document the Power BI Report Server components within your environment.

Power BI Report Server Provider Requirements







Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Adding Power BI Report Server

Add a Power BI Report Server Solution item by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution item
  3. Enter an item name, then select Power BI Report Server from the Source type drop-down list. DOC xPress Add Solution Item Power BI Report Server
  4. Enter the Power BI Report Server URI in the Server URI box, then select Validate to verify the connection. DOC xPress Add Solution Item Power BI Report Server enter credentials
  5.  Select OK to add the Power BI Solution item to your DOC xPress Solution. DOC xPress Add Solution Item Power BI Report Server select OK

SQL Server

Solution Item IconSolution Item Description
DOC xPress SQL Server Provider

DOC xPress allows you to document databases across all major versions of SQL Server: 2005, 2008, 2008 R2, 2012, 2014, 2016, 2017, and 2019.

SQL Provider Requirements

64-bit Operating Systems32-bit Operating Systems

Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Note:  SQL Server provider works against SQL Server 2005 and above when connecting to both SQL Server On-Premises and Azure Instances.

Note:  The SQL Server Provider can collect columns with the Sensitivity Classification in Azure, and SQL Server 2019.

Adding SQL Server

Add a SQL Server Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select SQL Server 2005 - 2019 from the Source type drop-down list.   DOC xPress Add Solution Item SQL Server
  4. Select SQL Server or SQL Azure, then enter a valid server name and connection credentials.
DOC xPress Add Solution Item SQL Server credentials
DOC xPress Add Solution Item SQL Azure credentials

5. Select OK to add the SQL Server Solution item to your DOC xPress Solution.

DOC xPress Add Solution Item SQL Server select Ok

Sample Output

DOC xPress allows you to document databases across all major versions of SQL Server: 2005, 2008, 2008 R2, 2012, 2014, 2016, 2017, and 2019.

DOC xPress SQL Server Sample Output Example one
DOC xPress SQL Server Sample Output Example two

Important:  Non-systemadmin users must be granted View Server State permissions to view log file objects within the documentation.

SSAS Server

Solution Item IconSolution Item Description
DOC xPress SSAS Server Provider

DOC xPress is able to document SSAS Cubes and Databases across all major versions of SQL Server: 2005, 2008, 2008 R2, 2012 Multi-Dimensional, 2016, 2017, and 2019. With the SSAS Cube and Database Documentation you can see the properties and attributes of each dimension in a cube.

SSAS Server Requirements

Note:  Microsoft ® .NET 4.5 is required by SSAS 2017 Only.

64-bit Operating Systems32-bit Operating SystemsSSAS Azure Analysis Services
  • Microsoft Azure Analysis Services Client Libraries


Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Note:  SSAS provider works against SSAS 2005 and above when connecting to a Multidimensional Instances and SSAS 2012 and above when connecting to a Tabular Instances. To connect to Azure Analysis Services, you need to download and install the latest Microsoft Analysis Services Client Libraries.

Adding SSAS Server

Add an SSAS Server Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select SSAS Server 2005- 2014, SSAS Server 2016, or SSAS Server 2017 - 2019 provider from the Source type drop-down list.   DOC xPress Add Solution Item SSAS Server 2017

Important: 

Use the SSAS Server provider when connecting to the following SSAS Modes:

  • MultiDimensional instances with server versions between 2005 and 2014
  • Tabular instances with server versions between 2012 and 2014

Use the SSAS Server 2016 provider when connecting to the following SSAS Modes:

  • MultiDimensional instances with server versions above 2016
  • Tabular instances with server versions above 2016
  • Azure Analysis Services

4. Select On Premises or Azure, then enter a valid server name and connection credentials for your connection.

DOC xPress Add Solution Item SSAS Server On Premises
On Premises

DOC xPress Add Solution item SSAS Server Azure
Azure

Note:  If you have selected SSAS Server 2016 and are attempting to connect to Azure Analysis Services, Azure Active Directory credentials are required. To connect to Azure Analysis Services, you need to download and install the latest Microsoft Azure Analysis Services Client Libraries.

5. Select OK to add the SSAS Server Solution item to your DOC xPress Solution. DOC xPress Add Solution Item SSAS Sever select Ok

Sample Output

When documenting KPI's, you can see the trend expression, goal expression, and status expression.

DOC xPress SSAS Server Sample Output Example one
DOC xPress SSAS Server Sample Output Example two

SSIS Package

Solution Item IconSolution Item Description
DOC xPress SSIS Package Provider

DOC xPress allows you to develop an overview of your Integration Services Packages. With the SSIS Package documentation you can display diagrams of both the control and data flow of an SSIS package.

SSIS Provider Requirements

  • Microsoft ® .NET 4.5 (Required by SSIS 2017 Only)
  • Each version of SQL Server Integration Services (2008 R2 or above) that the user wishes to document.
  • SQL Server Data Tools or Business Intelligence Development Studio.
  • Any Third-Party Products (Connection Managers, Tasks, Components, et cetera) that are used within the SSIS Package(s)

Important:  Workbench (32-bit) must be used when snapshotting SSIS Solution items from a machine that only contains SSDT for Visual Studio 2015.

Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Note:  SSIS provider works against SSIS 2005 and above when connecting to the File System, SQL Server, SSIS Package Store and SSIS 2012 and above when connecting to the SSIS Catalog.

Important:  Workbench (32-bit) must be used when using the SSIS Package provider on a machine that only contains SSDT for Visual Studio 2015 or 2017.

Adding SSIS Package

Add an SSIS Package Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select SSIS 2017 from the Source type drop-down list.   DOC xPress Add Solution Item SSIS Package
  4. Select the desired SSIS Package connection option (File, Folder, SQL Server, Package Store, and Catalog), then enter the connection properties.
DOC xPress Add Solution Item SSIS Package File
SSIS File
DOC xPress Add Solution Item SSIS Package Folder
SSIS Folder
DOC xPress Add Solution Item SSIS SQL Server
SSIS SQL Server
DOC xPress Add Solution Item SSIS Package Store
SSIS Package Store
DOC xPress Add Solution Item SSIS Catalog
SSIS Catalog

Note:  The SSIS Provider contains several connection options:

  • File: Select File to document SSIS Item(s) located on the file system. Select the ellipses to open the file explorer and then navigate to the location of any *.dtsx, *.dtproj, *.sln, or *.ispac files.
  • Folder: Select Folder to recursively document all Excel Workbook Item(s) located within a specific folder on the file system. Select the ellipses to open the file explorer and then navigate to a folder that contains at least one SSIS item.
  • SQL Server: Select SQL Server to document SSIS Item(s) deployed to a SQL Server instance.
  • Package Store: Select Package Store to document SSIS Item(s) deployed to an SSIS Package Store.
  • Catalog: Select Catalog to document SSIS item(s) deployed to an SSIS Package Catalog.

Important:  Due to DOC xPress' need to extract metadata from SSIS Packages, Integrated Security is required to connect to an SSIS Catalog.

5. Select OK to add the SSIS Package Solution item to your DOC xPress Solution. DOC xPress Add Solution Item SSIS select Ok

Sample Output

View detailed information for package event handlers. Document properties for every component across all Data Flows.

DOC xPress SSIS Package Sample Output Example one
DOC xPress SSIS Package Sample Output Example two
DOC xPress SSIS Package Sample Output Example three

SSRS Report

Solution Item IconSolution Item Description
DOC xPress SSRS Report Provider

DOC xPress documents SSRS Reports found on the File System across the following versions of SQL Server: 2008, 2008 R2, 2012, and 2017. Additionally, DOC xPress documents SSRS 2008 R2 and 2012 Reports in both Native and SharePoint Integrated Mode. With SSRS Report documentation you can view the properties, parameters, and data sources of a report.

SSRS System Requirements

  • At least one version of SQL Server Reporting Services (2008 R2 or above) that the user wishes to document.
  • SQL Server Data Tools or Business Intelligence Development Studio.
  • Support provided for the following report locations
    • File System: SQL Server 2005 and above
    • Native Web Services: SQL Server 2008 R2 and above
    • SharePoint Web Service: SQL Server 2008 R2 and above

Component Functionality

FeatureDescription
Best PracticesThis feature is compatible.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageThis feature is compatible.
Data DictionaryThis feature is compatible.

Note:  SSRS provider works against SSRS 2005 and above when connecting to the File System and SSRS 2008 R2 and above when connecting to the Native or SharePoint Web Service.

Important:  KPIs and Mobile Reports are currently not supported when connecting to an SSRS 2016 or above Report Server.

Adding SSRS Report

Important:  You must have SQL 2008 R2 Reporting Services or higher to document. You also need the following permissions: 

  • Browser in the report tree 
  • System user on the web server itself

Add an SSRS Report Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select SSRS 2008 R2 - 2017 from the Source type drop-down list. DOC xPress Add Solution Item SSRS 2008 R2 - 2017
  4. Select the desired SSRS Report connection option (File, Folder, Native Web Service, or SharePoint Web Service), then enter the connection properties.
DOC xPress Add Solution Item SSRS File
SSRS File
DOC xPress Add Solution Item SSRS Folder
SSRS Folder
DOC xPress Add Solution Item SSRS Native Web Service
SSRS Native Web Service
DOC xPress Add Solution Item SSRS SharePoint Web Service
SSRS SharePoint Web Service

Note:   The SSRS Provider contains several connection options:

  • File: Select File to document SSRS Item(s) located on the file system. Select the ellipses to open the file explorer and then navigate to the location of any *.rdl, *.rds, *.rsd, or *.rptproj files.
  • Folder: Like File, select Folder to document SSRS Item(s) located on the file system. Unlike file, the Folder option will recursively document all SSRS items located within the folder. Select the ellipses to open the file explorer and then navigate to a folder that contains at least one SSRS item.
  • Native Web Service: Select Native Web Service to document an SSRS Native Web Service. Use the Folder text box to only document specific folders within an Native Web Service.
  • SharePoint Web Service:  Select SharePoint Web Service to document an SSRS SharePoint Web Service. Use the Folder text box to only document specific folders within an Native Web Service.

Note:  Excluding certain types may affect Lineage Analysis.

6. Select OK to add the SSRS Report Solution item to your DOC xPress Solution. DOC xPress Add Solution Item SSRS select Ok

Sample Output

Use the documentation to gain a better understanding of what tables your reports are using by viewing the data set of the report.

DOC xPress SSRS Report Sample Output Example one
DOC xPress SSRS Report Sample Output Example two

Tableau Server

Solution Item IconSolution Item Description
DOC xPress Tableau Server Provider

DOC xPress allows you to document databases across all major versions of SQL Server: 2005, 2008, 2008 R2, and 2012.

Tableau System Requirements

Tableau provider works against Tableau Servers with REST API enabled with the following API Versions: 2.3, 2.2, 2.1 and 2.0.

Component Functionality

FeatureDescription
Best PracticesBest Practices rules can be analyzed for the marked provider(s) once the user has created User Defined Best Practices.
BI CompareThis feature is compatible.
DocumentationThis feature is compatible.
LineageTableau Lineage Analysis only supports dependency scanning Data Sources from SQL Server Databases.
Data DictionaryData Dictionary categories can be applied to the marked provider(s) once custom paths have been created.

Adding Tableau Server

Add a Tableau Server Solution item to your DOC xPress Solution by completing the following steps:

  1. Create a new, or open an existing DOC xPress Solution. DOC xPress Open DOCxPress Solution
  2. Select Add to open the Add Solution window. DOC xPress Add Solution Item
  3. Enter an item name, then select Tableau Server from the Source type drop-down list.   DOC xPress Add Solution Item Tableau Server
  4. Enter your valid server name and connection credentials. DOC xPress Add solution item Tableau Server Configuration

Important:  The credentials used to connect to the Tableau Server must be assigned the Server Administrator role.

5. Select OK to add the Tableau Server Solution item to your DOC xPress Solution. DOC xPress Add Solution Item Tableau Server select Ok

Sample Output

DOC xPress Tableau Server Sample Output Example

Filtering Solution Items

DOC xPress allows you to control the amount of data you want to record within your solution items. Manage the data within new or existing solution items by using the Edit Filter button. Complete the following steps to filter your solution item:

1. Open an existing DOC xPress Solution (or create a new one). DOC xPress Open Solution

2. Select Add to create a new solution item, or select Edit to open an existing solution item.

DOC xPress Add Solution Item
Add Solution Item

DOC xPress Edit Solution Item
Edit Solution Item

3. Select Edit Filter to open the Configure filtering window for the selected solution item. DOC xPress Edit Solution Item select Edit Filter

4. Select the object type(s) you want to exclude from solution item snapshot, then select Next to continue. DOC xPress Configure Filtering window Choose included types

Note:  A checkmark DOC xPress Included Object indicatorindicates that the Object type is included in the snapshot. An X mark DOC xPress Excluded object indicatorindicates that the object type is excluded from the snapshot. All Object types are included for the solution item by default.

Note:  The next section presents you with a tree diagram that represents the solution item snapshot.  You can select to exclude individual objects in this section.

5. Select DOC xPress Tree expander buttonto expand the solution item tree, and then select the object(s) you want to exclude from the snapshot. DOC xPress Configure Filtering window Choose included and excluded items

Note:  Selecting an object at the top of a hierarchy automatically excludes the objects below the selected object.

DOC xPress Configure Filtering window select to exclude items in hierarchy
DOC xPress Configure Filtering window items excluded in hierarcy

6. Select OK to save your solution item filter. DOC xPress Configure Filtering window select Ok to save filter

DOC xPress Snapshots

Note:  All solutions and their snapshots created during your evaluation period are stored within the DOC xPress metabase and will still be available after you enter your license.

A snapshot in DOC xPress is a detailed picture of your environment's state at the time the snapshot was taken. Snapshot your environment with the steps below, and capture what your environment looks like before making changes. Snapshots can be used to generate documentation, run comparisons against previous snapshots using Snapshot Compare, explore an object's dependencies using Lineage Analysis, and add extra information within their documentation using Data Dictionary.

Creating a Snapshot

Create a snapshot for your DOC xPress solution by completing the following steps:

1. Open an existing DOC xPress solution (or create a new one).   DOC xPress Open Solution

2. If there are solution items in the solution, select Take Snapshot.DOC xPress DOCxPress Solution Take Snapshot

Note:  You can select an individual solution item and then select the Snapshot button to the right of the Items pane to take a snapshot of that individual item. Dependencies of all solution items update during the snapshot. DOC xPress DOCxPress Solution Snapshot selected Solution item

Note:  DOC xPress displays an Activity Monitor once a snapshot is created. Hide the Activity Monitor and continue working by selecting To Background . To re-open the Activity Monitor, or check on the snapshot progress, select Activities from the Workbench ribbon bar. DOC xPress Activity Monitor

3. Once the snapshot completes, DOC xPress displays the result of the snapshot process. Copy this documentation to the clipboard by selecting Copy Details.

DOC xPress Activity Monitor Copy Details

Note:  After a snapshot has completed, you can expand and navigate through the metadata for a solution item by using the Metadata Viewer. Select the item you want to explore, and then select View on the Items Panel.

Snapshot Command Line

To create a snapshot using the command line, complete the following steps:

1. Add all of the desired solution items to the solution list, then select Create snapshot request file. DOC xPress Solution Create snapshot request file

Note:  The snapshot request file is a simple XML file that contains the solution item references. 

2. Open the windows command prompt, specify the request file, then run the DOCxpress.exe executable. DOC xPress enter DOCxPress.exe Command Prompt

Note:  Your entire command should appear as:

C:\Program Files (x86)\Pragmatic Works\Pragmatic Workbench>DOCxPress.exe "C:\directoryname\snapshotrequest.xml"

Once the execution has completed your snapshot is updated! DOC xPress Command Prompt Complete

Generating Documentation

After adding solution items, and creating a snapshot, you are ready to generate documentation for your DOC xPress solution. 

Important:  Documentation can be customized by modifying the DOC xPress Templates. These are advanced operations, and may result in unexpected documentation outputs. 

It's recommended to always save a copy of the default templates before proceeding with modifying the templates in case the changes negatively impact your documentation.

Documentation Layout

The items that DOC xPress includes in your documentation are based on the documentation layout. By default, all the solution items are added to the layout automatically. Add, group, order, or delete solution items on the Layout panel.

Adding Items to the Layout 

Select the item that you want to include within the layout, and then drag and drop the item within the Layout panel. DOC xPress Solution Layout panel drag and drop

Important:  DOC xPress uses template structure maps to manage the overall structure of the documentation. When you include an item within the Layout that doesn't have a corresponding structure map for an item's object type, DOC xPress displays a yellow warning (DOC xPress Yellow Warning Icon) to notify you that a default structure map will be used instead of one of the supported structure maps. 

When you use a default structure map, the generated documentation represents the structure of the extracted metadata, which may result in a large number of pages being generated that show the full metadata content.

Grouping Items in the Layout

Group items by technology, owners, servers, or other user-defined categories. Select + Add on the right of the Layout panel to create a Layout node. After creating the layout node, add items to the layout by placing the desired item(s) within the layout node.

DOC xPress Solution Add Layout node
DOC xPress Add text layout node window

DOC xPress Solution Drag item into Layout node

Ordering Items in the Layout

Adjust the order of the layout by selecting a desired item, and then selecting the up and down arrows located on the right side of the layout, or by dragging and dropping the item within the desired location. 

DOC xPress Move items in Layout
DOC xPress items moved in Layout

Deleting Items from the Layout

Remove items from the layout by selecting Delete on the right side of the layout.

DOC xPress Solution Delete item from Layout

Important:  Deleting an item from the layout does not remove the item and its snapshots from the solution, it only excludes the item from the documentation.

Generating Documentation

After completing your layout, generate documentation for your DOC xPress solution by completing the following steps:

  1. Select Generate documentation to open the Generate documentation form. DOC xPress Solution Generate documentation
  2. Select a documentation Generation point, then select an Output type from the drop-down list. DOC xPress Generate documentation window
  3. Provide a meaningful name for your documentation, then select an Output format(s). Select OK to begin generating the document. DOC xPress Generate documentation window select Ok

Note:  The documentation is created in the DOC xPress folder by default.

If you have the Automatically Open Generated Documents preference active while generating multiple document formats, the Documentation complete window displays upon the completion of the document(s). DOC xPress Documentation complete window

Generated documentation also supports images. SQL Server documentation automatically generates impact analysis. DOC xPress Generated documentation example

Important:  Lineage analysis and data dictionary output can be suppressed from inclusion in the document through the DOC xPress Templating preferences.

Generating Documentation Command Line

After a snapshot has been created for your DOC xPress solution you can begin generating documentation. Generate documentation through the command line by completing the following steps:

1. Create a documentation request file for your DOC xPress solution. Set your layout in the Layout pane, then select Create documentation request file to open the Generate documentation window. DOC xPress Solution Create documentation request file

2. Select an Output type from the drop-down list, enter a Document title, and then enter the desired Output folder for your documentation.

DOC xPress Generate documentation select Output type for the request file
DOC xPress Generate documentation window Document title for request file

Note:  The documentation is created in the DOC xPress folder by default.

3. Select the desired Output format(s), select OK, and then select a directory for the documentation request file. Select Save to continue.

DOC xPress Generate documentation window select Ok
DOC xPress Save documentation request file

4. Open the command prompt, run the DOCxPress.exe executable and specify the documentation request file.  Your entire command should look like the following :  

C:\Program Files (x86)\Pragmatic Works\Pragmatic Workbench>DOCXPRESS.exe"C:\directoryname\documentationrequest.xml"

DOC xPress Command Prompt DOCxPress.exe executable

Success: Once the execution has completed, your documentation is output into your specified directory.

Viewing CHM Files

Microsoft released a security path that makes it difficult to view CHM files that are stored on a network drive or generated from a different machine than what is currently viewing them.  The help file may appear, but instead of being able to view the documentation, an error message appears : this page cannot be displayed

To view the CHM files, complete the following steps:

  1. Download the CHM file to your local machine.
  2. Open up Windows Explorer, then navigate to the folder location where the CHM file is located.
  3. Right-click on the CHM file and select Properties. DOC xPress Full Environment CHM Properties
  4. Select the CHM General Tab, then select Unblock to allow access to the CHM Documentation. DOC xPress Full Environment CHM Properties General
  5. Select Apply, then select OK to save your changes.

Success: You should now be able to view the CHM on your local machine without any issues.

SnapShot Comparison

Snapshot Comparison enables you to determine the differences in your SQL Server environments over time. Using DOC xPress to compare solution items at different intervals saves developers and DBAs time in tracking down the source of consistency or performance problems.

Note:  Snapshot Comparison works hand-in-hand with the DOC xPress feature and requires more than one snapshot within your metabase to be useful. Snapshots can be of the same or differing solution items.

Snapshot Comparison Feature Highlights

Use Snapshot comparison to:

  • View changes that have occurred in your SQL environment over time
  • Find differences between two separate environments

Comparing your Snapshots

Compare multiple snapshots by completing the following steps: 

  1. Open Snapshot Comparison from the SentryOne Workbench. DOC xPress open Snapshot Comparison
  2. Set the Left source of the comparison by selecting the Solution, Item, and Version from the respective drop-down list. Repeat this step for the Right source.
DOC xPress Snapshot Comparison Solution selection
DOC xPress Snapshot Comparison Item selection
DOC xPress Snapshot Comparison Version selection

Note:  Comparing objects that are different technology types isn't advised.

Note:  The left and right starting point are set to the root of the source by default. Adjust the Left source or Right source starting points to create a more specific comparison. DOC xPress Snapshot Comparison Select starting point window

3. Select OK to create the snapshot comparison. DOC xPress Snapshot Comparison select Ok

Important:  To save space in your DOC xPress metabase, a new version of your metabase snapshot is created only when an object or property change is detected.

Additional Uses of Snapshot Comparison

  • Choose to view objects that are equal, not equal, exist on the left side only, and exist on the right side only.
  • Filter in or out specific objects from the comparison.
  • Switch an individual side of the comparison from the window.

For example, in the left side of the comparison there is a RowCount that doesn't exist on the right side of the comparison. This example makes all parent levels unequal, allowing you to locate the difference between the comparisons. DOC xPress Snapshot Comparison Example

Snapshot Comparison Page Options

The following configuration options are available in your Snapshot Comparison:

Comparison 

Button DescriptionImage
DOC xPress Snapshot Comparison Filters buttonOpens the Filters manager window.DOC xPress Snapshot Comparison Filters window
DOC xPress Snapshot Comparison Switch left buttonOpens the choose source window for the left side comparison.DOC xPress Snapshot Comparison Choose source window
DOC xPress Snapshot Comparison Switch right buttonOpens the choose source window for the right side comparison.DOC xPress Snapshot Comparison Choose source window
DOC xPress Snapshot Comparison Generate document buttonOpens the Generate documentation window for the snapshot comparison items. DOC xPress Snapshot Comparison Generate documentation window

View 

ButtonDescriptionImage
DOC xPress Snapshot Comparison Equal view buttonShows items in the comparison tree that are equal.DOC xPress Snapshot Comparison Equal view
DOC xPress Snapshot Comparison Not Equal view buttonShows items in the comparison tree that are not equal.DOC xPress Snapshot Comparison Not Equal view
DOC xPress Snapshot Comparison Left Only view buttonShows items in the comparison tree from the left side of the comparison only.DOC xPress Snapshot Comparison Left Only view
DOC xPress Snapshot Comparison Right Only view buttonShow items in the comparison tree from the right side of the comparison only. DOC xPress Snapshot Comparison Right Only view

Starting points

ButtonDescriptionImage
DOC xPress Snapshot Comparison Change left start point buttonOpens the Select starting point window for the left side comparison.DOC xPress Snapshot Comparison Select starting point window
DOC xPress Snapshot Comparison Change right start point buttonOpens the Select starting point window for the right side comparison. DOC xPress Snapshot Comparison Select starting point window

Snapshot Management

Snapshot management in DOC xPress allows you to track and maintain snapshots in the DOC xPress database.

Feature Highlights

  • Import and export entire solutions or individual solution items.
  • Manage repository size by purging snapshots that are no longer needed.

Solution Management

The solution management page allows you to manage all of the solutions within your DOC xPress metabase. From this screen you can export solutions, import solutions, purge a solution's history, or view a solution's history.

Solution Item Management

To manage a solution item within your DOC xPress solution, complete the following steps:

  1. Open the Solutions page of the Snapshot Management add-in, select a solution you want to manage, and then select Open to display the Snapshot Management page. 
DOC xPress open Snapshot Management
DOC xPress Snapshot Management Open solution

2. Expand the hierarchy to view child objects, export solution items, import solution items, purge a solution item's history, or view a solution item's metadata. DOC xPress Snapshot Management expand hierarchy

Viewing History

View the history of your solution by selecting History. The history panel displays a list of the extracted snapshots for your solution.

DOC xPress Snapshot Managment Solution select History
DOC xPress Snapshot Management History for Solution item

Rescanning Dependencies

Select rescan to trigger a dependency scan. 

DOC xPress Snapshot Management Solution select Rescan
DOC xPress Activity Monitor Updating dependencies

Note:  The dependency scan does not take a new snapshot; it rebuilds the lineage used within Lineage Analysis for the latest snapshot. If you're connected to a DOC xPress Server instance, it also notifies the server to refresh the solution's metadata. It could take several minutes for the changes to appear within DOC xPress Server.

Metadata Viewer

Use the Metadata Viewer to navigate the metadata for a specific solution item. To navigate to the metadata viewer, select the solution item you want to view, and then select View to open the metadata viewer.

DOC xPress Snapshot Management Solution select View
DOC xPress Metadata Viewer for Solution item

Exporting Solutions and Solution Items

Create an obfuscated file that can be used as a back up for your DOC xPress solutions. Transport the obfuscated file to other environments, or import it into other DOC xPress solutions or databases. Export a solution Item from a selected solution by completing the following steps:

  1. Open the solution that you want to export. Select the solution items you want to export, then select Export to continue.
DOC xPress Snapshot Management Open solution
DOC xPress Snapshot Management Solution select Export

2. Select the amount of History that you want to include in the export (Full, Latest only, Last month, Last six months, Last year, Snapshots after). DOC xPress Snapshot Management select History

3. Select Export to open the Export Solution window, then enter a file name and location to save the file. Select Save to begin the export.

DOC xPress Snapshot Management select Export
DOC xPress Snapshot Management select Save

Note:  Selecting Save opens the Activity Monitor, which details the export progress.

DOC xPress Activity Monitor Export Snapshot

Importing Solutions and Solution Items

Take the obfuscated snapshot files created from an exported snapshot and include them in new or existing solution(s) or new DOC xPress database(s). Import a solution item by completing the following steps:

1. Open the Snapshot Management pane, then select Import to open the Import Solution window. DOC xPress Snapshot Management select Import

2. Select the objects you want to import from the available .dxm file selections, then select Open to display the Import from solution form in snapshot management. DOC xPress Snapshot Management Import solution

3. Select the solution items you want to import, then select where you would like to import the solution items (New Solution or Existing Solution). Select Import to begin the importation process. DOC xPress Snapshot Management Import Existing Solution

Note:  Rename any solution items that have the same name as an existing solution item. Errors are denoted by a red X.

Note:  Selecting Import opens the Activity Monitor, which details the import progress. DOC xPress Activity Monitor Import Solution

4. After the import is complete, select Yes to run a dependency scan on the newly created solution items. DOC xPress Import Complete window

Important:  Once you add solution items to your solution, you should conduct a new dependency scan to rebuild the lineage history of the solution. This can be done at a later time, but your lineage may be out of date until it's conducted.

Purging Solutions and Solution Items

Free up space on your DOC xPress metabase by using the Purge feature. The purge feature allows you to clear out old snapshots from solutions or solution items based on five different methods. Purge a solution item by completing the following steps:

  1. Open the Snapshot Management page, then Open the solution you want to purge. DOC xPress Snapshot Management Open solution
  2. Select the solution items you want to purge, then select Purge to open the Purge Solution form. DOC xPress Snapshot Management select Purge
  3. Select the time period you want to purge from the selections (All except latest, All older than one month, All older than six months, All older than one year, Snapshots before), then select Purge. DOC xPress Snapshot Management Purge solution
  4. Select Yes to confirm your selection. DOC xPress Purge data window

Note:  Selecting Purge displays the Activity Monitor which details the progress of the data purge. DOC xPress Activity Monitor Purge Solution

Data Dictionary Overview

Data Dictionary allows you to annotate the objects within a DOC xPress snapshot, including additional information and comments. Within your documentation, you may want to capture additional information like SLAs, persons responsible for the data, timeliness of the data, and other attributes. This additional information can be captured using the DOC xPress data dictionary. Add annotations to existing objects in the DOC xPress repository to capture any additional information you desire.

Note:  Data Dictionary works hand-in-hand with the DOC xPress feature and requires an existing solution with at least one snapshot generated.

Feature Highlights

  • Add business definitions to any item in the documentation
  • Provide annotations useful to business users

Data Dictionary Toolbar Buttons

The following toolbar buttons are available within the DOC xPress data dictionary :

ButtonDescriptionImage
DOC xPress Data Dictionary Edit categories buttonOpens the Edit data dictionary categories window for the selected Metabase.DOC xPress Edit data dictionary categories window
DOC xPress Data Dictionary Analyze button Analyzes the data dictionary categories on the selected metabase for missing entries.DOC xPress Data Dictionary solution analysis
DOC xPress Data Dictionary Switch to edit mode buttonEnter full-editing mode to edit all entries across all objects.
DOC xPress Data Dictionary Edit global entries buttonOpens the Edit data dictionary global entries window.DOC xPress Edit data dictionary global entries window

Creating and Managing Annotations 

Note:  Opening the Data Dictionary from the SentryOne Workbench for the first time prompts you to create a metabase or connect to an existing one.

To add annotations to the DOC xPress data dictionary, complete the following steps:

1. Open the Data Dictionary from the SentryOne Workbench, select the solution you want to open, and then select Open to display the Data Dictionary Welcome prompt. DOC xPress Data Dictionary Open Solution

2. Select Get started to open the Edit data dictionary categories window. DOC xPress Data Dictionary Get started

Note:  After creating a new data dictionary for your DOC xPress solution, the first thing you need to do is create categories. A category is a field that contains information about different objects in the solution such as business owner, emergency contact, etc.

3. Select Add to create a new category. DOC xPress Edit data dictionary categories window

4. Enter a category name, select a scope for your category, and then select the technology type and data type for the category. DOC xPress New Data Dictionary Category

Note:  The category scope can be to the metabase, a whole solution, or an item in a solution.

5. Select an Applicable Item(s) from the drop-down list, then select Add to add that item to your data dictionary category. Repeat this step as desired for your data dictionary category.  

DOC xPress Edit data dictionary categories select Applicable item
Select Applicable item

DOC xPress Edit data dictionary categories Add Applicable item
Add Applicable item

Note:  You can create custom applicable items with the SentryOne Workbench Path Language that select specific metadata object types. These custom items can be applied to the current data dictionary category.

6. Select OK to complete the edits to your data dictionary and return to the Solution Selection window. DOC xPress Edit data dictionary categories select Ok

Adding Items to the Data Dictionary Category

After adding categories to your data dictionary, you can add individual objects to the categories by completing the following:

1. Select the solution from the previous steps, then select Open. Next, select the solution item that applies to your data dictionary category, then select Open.

DOC xPress Data Dictionary Open solution
DOC xPress Data Dictionary Solution Open solution item

2. Expand the object tree until you see text boxes (this is where you add information about the individual objects). Enter information for the individual objects you want to update, then select Save to update the entries. DOC xPress Data Dictionary Updated entries

Note:  When you generate new documentation, the data dictionary entries display on each corresponding object containing populated data dictionary categories. DOC xPress Generated Document with Data Dictionary entries

Analyzing the Data Dictionary

Use the Analyze feature in the data dictionary tool to scan your metabase or solution for objects that you've assigned mandatory categories, but don't have assigned values.

1. Open your data dictionary solution. Select a solution item from the Data Dictionary Solution window, then select Analyze.

DOC xPress Data Dictionary Open solution
DOC xPress Data Dictionary Solution Analyze solution itemDOC xPress Data Dictionary Solution Analyze solution item

Note:  Selecting Analyze opens the Activity Monitor, which details progress of the analysis and any errors or warnings discovered during the process. DOC xPress Activity Monitor Data Dictionary Solution

Once the analysis completes, a results window displays. In the example shown, you can see that the QA-SRV-1 solution has a total of 33 objects with categories, and 20 of those objects are missing values for their required categories. The items in bold are solution items that have missing entries.

2. Resolve these missing entries by selecting on one of the solution items, then selecting open to display the Grid View. DOC xPress Data Dictionary analysis Open solution item

3. Edit the desired categories, then select Save to update the entries. DOC xPress Data Dictionary analysis Save entries

Lineage Analysis

Lineage Analysis allows you to answer two vital questions: 

  • Where did this data come from?
  • Where is this data used?

Tracing the lineage and impact of data within a system is generally a time-drain for all types of SQL developers and DBA's, whether they are focused on BI or not. Lineage Analysis eases this strain by enabling you to explore the dependencies in your environment.  

Important:  Lineage Analysis works hand-in-hand with the DOC xPress feature and requires an already set up solution with at least one snapshot generated and its dependency scanned.

Overview

DOC xPress Lineage Analysis Example

Feature Highlights

  • Diagrammatic and interactive form saves you many hours
  • Speeds up development by allowing you to view dependencies clearly
  • Enables you to pinpoint the source of data in objects
  • Allows business analysts to make clear judgments about the correctness of data
  • Enables you to identify areas where errors may be introduced

Opening Lineage Analysis

1. Select Lineage Analysis from the navigation bar to open the Lineage Analysis Solution selection. DOC xPress Open Lineage Analysis

Note:  All available solutions containing lineage analysis display within the selected DOC xPress repository. Solutions can be sorted by: Date Created, Name, Last Updated, Last Snapshot, and Last Refreshed. They then can be placed in Ascending or Descending order.

2. Select a solution, then select Open to open the solution's lineage. DOC xPress Lineage Analysis Open Solution

Note:  The Lineage Analysis Visual view displays by default. If you want to view a textual version of lineage analysis, select the text view (DOC xPress Lineage Analysis Text View button) button on the lineage analysis toolbar. DOC xPress Lineage Analysis Select View

Important:  For lineage analysis to work properly, it requires the desired solution to contain a dependency set. If there is no dependency set for the currently selected solution, a red warning displays prompting you to immediately take a snapshot. A snapshot must be taken before Lineage Analysis allows you to view the dependencies for a solution.

DOC xPress Lineage Analysis Welcome prompt

Navigating Lineage Analysis

Lineage Analysis Toolbar

Regardless of the current view, the lineage analysis toolbar allows you to navigate and adjust the behavior of lineage analysis. 

Toolbar buttons on the Lineage Analysis Tab

Toolbar ButtonDescriptionLineage Analysis Mode
DOC xPress Lineage Analysis Change Connection buttonChange connection allows you to connect to a different DOC xPress metabase.Available in all modes.
DOC xPress Lineage Analysis Back to Solution selection buttonThe back to solution selection button allows you to go back to the list of available solutions for use within lineage analysis.Available in all modes.
DOC xPress Lineage Analysis manage aliases buttonThe manage aliases button allows you to clarify the location of implicit items for this solution.

Important:  After aliases have changed, DOC xPress requires a snapshot of the solution in to refresh the dependency links within lineage analysis.
Available in all modes.
DOC xPress Lineage Analysis detail level buttonThe detail level button allows you to adjust the granularity of the objects that are included within the current session of lineage analysis. The following options are available:
  • High Detail: Allows you to see down to the column, measure, and attribute level of lineage.
  • Medium Detail: Allows you to see down to the table, component, SSRS item, KPI, and measure group level of lineage.
  • Low Detail: Allows you yo only see the database, package, and report level of lineage.
Available in all modes.
DOC xPress Lineage Analysis diagram layout buttonThe diagram layout button allows you to control the way objects are organized within the lineage diagram. The following options are available: 
  • Force-Directed: Organizes the diagram in a nondeterministic manner surrounding the focused object.
  • Circle: Organizes the diagram into concentric rings with the focused object being in the center.
  • Grid: Organizes the diagram in a grid where inbound dependencies are in one column and outbound dependencies appear in another column.
Diagram layout is only available in Visual View.
DOC xPress Lineage Analysis Save image buttonThe save image button allows you to save an image of the current diagram.Save image is only available in Visual View.
DOC xPress Lineage Analysis reload solution buttonThe reload solution button allows you to refresh the lineage data from the DOC xPress metabase.Reload solution is only available in Visual view and Textual view.
DOC xPress Lineage Analysis show legend buttonThe show legend button allows you to toggle the refresh the legend.Show legend is only available in Visual View.
DOC xPress Lineage Analysis dependency direction buttonThe dependency direction button allows you to select the direction types of the dependencies you want to include within the current session of Lineage Analysis. An object's dependencies are typically created when an object is included within another object's definition. The following options are available: 
  • Bi-Directional: Both inbound (lineage) and outbound (impact) dependencies are included within the current session.
  • Inbound Only: Only relationships that an object depends on are included within the current session.
  • Outbound Only: Only relationships that are impacted by objects are included within the current session.
Dependency direction is only available in Visual View and Textual View.
DOC xPress Lineage Analysis View modeThe view mode button allows you to alternate between the three different view modes used within Lineage Analysis. The following options are available: 
  • Visual View: Allows you to view the currently focused object using the visual view.
  • Text View: Allows you to view the currently focused object using the text view.
  • Trace Results: Only enabled when a trace has been executed, the trace results button switches the user to trace mode.
View mode is only available in Visual View and Textual View.
DOC xPress Lineage Analysis show trace bar buttonThe show trace bar button allows you to toggle the trace mode bar.Available in all modes.
DOC xPress Lineage Analysis Track selection buttonThe track selection button allows you to disable the feature that causes the diagram to re-draw every time a new selection is made within the Solution Explorer.Available in all modes.

The dependency level button allows you to increase or decrease the number of levels of separation from the currently focused object to be displayed within the Lineage Diagram. 

Important:  The more dependency levels included within the Lineage Diagram may cause it to become increasingly more difficult to read the diagram.

Dependency level is only available in Visual View.

Toolbar buttons on the Refinements Tab

Toolbar ButtonDescriptionLineage Analysis Mode
DOC xPress Lineage Analysis Key filter button

The Key filter button allows you to toggle the visibility of relationship links that involve the use of foreign keys.

Key filter is only available in the Visual View and Textual View.
DOC xPress Lineage Analysis Object filter buttonThe Object filter button allows you to toggle the visibility of relationship links that involve object dependencies.Object filter is only available in the Visual View and Textual View.
DOC xPress Lineage Analysis Data Lineage filter buttonThe Data Lineage filter button allows you to toggle the visibility of relationship links that involve the impact or dependency of another object's data.Data Lineage filter is only available in the Visual View and Textual View.
DOC xPress Lineage Analysis Collapse by technology buttons

The five collapse by technology buttons allow you to toggle between collapsing all objects of a specific technology that you want hide into a single, more manageable, node.

Available in all modes.

Solution Explorer

The Solution Explorer contains a hierarchically organized tree of all objects within the current detail level that contain lineage. Select an object with track selection enabled to re-draw the focus of the lineage diagram to the newly selected object within the Solution Explorer.

DOC xPress Lineage Analysis Solution Explorer

Expand and collapse selected objects and display the object's children by using the arrow to the left. 

Note:  If an object does not have an arrow, the object does not have any child objects that contain lineage, or the current detail level prevents it from expanding further. 

Search the current solution for the exact object you want to view lineage for with the Search text box.

Context Menu Options

DOC xPress Lineage Analysis Context Menu

Right click on objects within the Solution Explorer to open the context menu.

Context Menu OptionDescription
Focus on thisRefreshes lineage analysis and changes the focus to the currently selected object.

Note:  Applicable if track selection is disabled and the currently selected object contains lineage.
View metadataOpens the Metadata Viewer for the currently selected item.
Set as trace sourceEnables the trace bar and sets the currently selected object as the source if the selected object contains lineage.

Note:  This context menu option is used within trace mode.
Set as trace targetEnables the trace bar and sets the currently selected object as the target if the selected object contains lineage.

Note:  This context menu option is used within trace mode.

Lineage Analysis Visual View

DOC xPress Lineage Analysis Visual View

In the Visual View, the view diagram panel takes up a majority of the window within lineage analysis. The visual view applies all of the settings selected within the lineage analysis toolbar to the currently focused object within the solution explorer to create a visual representation of the object's lineage.

Note:  The Visual View is the default view for lineage analysis.

The icons and colors within the diagram help you identify the object and technology types associated with each node. The following legend displays when you select the Legend icon:   DOC xPress Lineage Analysis Visual View Legend

Note:  The colors can be configured using the Preferences section within the SentryOne Workbench.

Using the Visual View

Including the two buttons in the lower left of the diagram, there are other ways of navigating the diagram in a meaningful way:

OptionDescriptionExample
Move NodeLeft-clicking on a node and then dragging the mouse allows you to move a single node around the diagram without affecting the other nodes.DOC xPress Lineage Analysis Move node
PanLeft clicking on the view diagram allows you to pan the lineage diagram and adjust the visual if it does not all fit within the screen.DOC xPress Lineage Analysis Pan view
Zoom in and outUse the mouse wheel to zoom in and out to see more details within the diagram.DOC xPress Lineage Analysis Zoom
Reset ZoomSelect the reset zoom buttonDOC xPress Lineage Analysis Reset Zoom button to reset the zoom of the diagram to its default value.DOC xPress Lineage Analysis Reset Zoom
OptionDescriptionImage
Zoom PreviewSelect the zoom preview buttonDOC xPress Lineage Analysis Zoom preview buttonto open the zoom preview window.

Note:  The zoom preview window contains a small preview window of the entire lineage diagram, with the ability to zoom in, zoom out, and change views.
DOC xPress Lineage Analysis Zoom Preview windowDOC xPress Lineage Analysis Zoom Preview
Lineage Route InspectorDouble-click on a link between two objects to open the lineage route inspector. The lineage route inspector allows you to view all dependencies that link one object to another object.
DOC xPress Lineage Analysis Route inspector tooltipDOC xPress Lineage Analysis Route inspector window

Visual View Context Menu

DOC xPress Lineage Analysis Visual View Context menu

Right-click on an object node to  open the Visual View context menu.

Context Menu OptionDescription
Focus on this Select Focus on this to re-draw the diagram with the currently selected object as the main focus.
View metadataOpens the Metadata Viewer focused on the selected item.
Show collapsed item namesProvides you with a detail list of all the collapsed objects.
Extend this itemDisplays more dependency levels for the currently selected object.
Hide this itemTemporarily hides the currently selected node. Note:  Once the diagram is redrawn the item is included again.
Hide this item for this sessionIgnores the currently selected node, excluding it from being included within the diagram.

Note:  Selecting the reload solution button includes the select node within the lineage again.
Set as trace sourceEnable the trace bar and sets the currently selected object as the source if the object contains lineage.

Note:  This context menu option is used within trace mode.
Set as trace targetEnables the trace bar and sets the currently selected object as the target if the object contains lineage.

Note:  This context menu option is used within trace mode.

Lineage Analysis Text View

DOC xPress Lineage Analysis Text View

After selecting an object from the solution explorer, the lineage analysis explorer loads a hierarchically organized tree of the object, its dependencies, and the following three columns:  Object, Type, and Endpoint.

ColumnDescription
ObjectThis column contains the name of the object.
TypeThis column contains the technology and object type.
EndpointThis column contains the complete path to the object.

If the dependency direction is set to BI-Directional, then expanding an object reveals two nodes: Outbound and Inbound Dependencies. 

NodeDescription
Outbound DependenciesAll relationships that are impacted by the parent object are included underneath the outbound dependencies node.
Inbound onlyAll relationships that the parent object depends on are included underneath the inbound dependencies node.

Note:  Generally, expanding an object reveals all respected relationships for the dependency direction that is currently set. For example, if the dependency direction is set to inbound only, then expanding an object reveals all relationships that an object depends on. If the dependency direction is set to outbound only, then expanding an object reveals all relationships that are impacted by the object.

Lineage Analysis Trace Mode

Trace mode allows you to set a source and target object, and then run a trace that builds a step by step path from the starting object to the target object. Begin trace mode using the following three techniques:

TechniqueImage

Within the Solution Explorer, right-click on an object to open a context menu. Select set as trace source or set as trace target to enable the trace bar and set the respected item as either the source or target item.

DOC xPress Lineage Analysis Set as trace target
Within Visual View, right-click on a node to open a context menu. Select set as trace source or set as trace target to enable the trace bar and set the respected item as either the source or target item.DOC xPress Lineage Analysis Visual View Set as trace target
Enable Trace mode, select objects within the solution explorer or text view, and then drag-and-drop them into the source or target text box.DOC xPress Lineage Analysis Trace Mode

Once both the source and target have been set, select the trace switch buttonDOC xPress Lineage Analysis Trace switch button to switch the source object with the target object.

Once you're satisfied with the source object and target object, select the start trace buttonDOC xPress Lineage Analysis Start Trace buttonto allow DOC xPress to begin calculating all possible paths between the source and target objects.

Trace Operation

Traces only follow similar types of links. For example, a route from object A to object B would not be reported if it contains Column and Object links. The links that can be combined to form a trace route are:

•   Column and Data Flow links

•   Foreign Key and Foreign Key Column links

•   Object links

Note:  When multiple types of links follow the same path, the links may be reported as Link Set or Aggregate.

Note:  The trace operation respects the Refinements set in lineage. For example, if you only want to trace data lineage, deselect the Object and Key refinements before starting the trace. This can significantly improve the performance of a trace because it reduces the size of the search graph.

Trace also operates from target to source, tracing backwards. A key table within a database may be read by many entities, but only updated by a few. By tracing in reverse, we cut down on the number of paths we must follow because only the links that update the table need to be traced to find the route.

Important:  The process of calculating all possible paths between a source and target object may take several minutes depending on the complexity of the solution. Select Cancel to terminate the process.

Results

Once trace calculations are completed, the first trace path is displayed. Move between each of the trace paths by selecting the left or right arrows on the trace results page numbers. DOC xPress Lineage Analysis Trace results

The number of routes returned is limited by the Trace Mode Route Limit preference and the shorter routes display before the longer ones.

Each path result contains a series of objects connected by a route dependency. The first object in the trace result is located at the top of the trace result view and is always the source object. The last object in the trace result is located at the bottom and is always the target object.

Each route dependency contains a link set. Select the link set displays a list of the route information that created the dependency.

DOC xPress Lineage Analysis Trace mode

Metadata Viewer

The DOC xPress Metadata Viewer allows you to dive into each solution item and navigate the metadata of an object directly. 

DOC xPress Metadata Viewer

Feature Highlights

  • Explore your solution items' metadata without needing to generate documentation.
  • Build paths through the search panel to help customize your documentation.

Opening the Metadata Viewer

Open the Metadata Viewer through one of the following methods:

DOC xPress Solution Management

Open the Metadata Viewer from the DOCxPress Solution Management by completing the following:

  1. Open the DOCxPress Solution Management page, then open a solution. 
DOC xPress Open DOC xPress
DOC xPress DOC xPress Open Solution

2. Navigate through items that have already had a snapshot taken, then select a snapshot. Select View to open the Metadata Viewer focused on the selected item. 

DOC xPress DOC xPress select View
DOC xPress DOC xPress Metadata Viewer

Snapshot Management 

Open the Metadata Viewer from the Snapshot Management page by completing the following:

  1. Open the Snapshot Management page, then open a solution. 
DOC xPress Open Snapshot Management
DOC xPress Snapshot Management Open solution

2. Navigate through items that have already had a snapshot taken, then select a solution. Select View to open the metadata viewer focused on the selected item.

DOC xPress Snapshot Management select View
DOC xPress Metadata Viewer Snapshot Management

Lineage Analysis

Note:  Not all objects or nodes within Lineage Analysis Graph and Tree have metadata associated with them. This can occur because of grouping nodes through the Collapse by technology feature or implicit objects that are included within the lineage graph are not a part of the snapshot.

Open the Metadata Viewer from within lineage analysis by completing the following: 

  1. Open Lineage Analysis, then open a Solution
DOC xPress Open Lineage Analysis
DOC xPress Lineage Analysis Open Solution

2. Expand the Lineage Tree, then select an item within the solution. Right-click on the selected item and then select View metadata from the context menu to open the Metadata Viewer focused on the object selected from the lineage tree.

DOC xPress Lineage Analysis View metadata through Solution Explorer
DOC xPress Metadata Viewer Lineage Analysis

Open the Metadata Viewer from within the lineage analysis diagram by completing the following:

  1. Open Lineage Analysis, then open a Solution
DOC xPress Open Lineage Analysis
DOC xPress Lineage Analysis Open solution

2. Scroll through the lineage diagram, then select a solution item. Right-click on the selected item, then select View metadata from the context menu to open the Metadata Viewer focused on the object selected from within the lineage graph.

DOC xPress Lineage Analysis View metadata context menu
DOC xPress Metadata Viewer Lineage Analysis

Navigating the Metadata Viewer

When you first open the Metadata Viewer, it's divided into two sections: Metadata Tree and Object Properties. In addition to these two panels, the Search Panel can also be displayed.

DOC xPress Metadata Viewer

Metadata Tree

The Metadata Tree Panel is located on the left of the Metadata Viewer and is used to manually explore an object's metadata by expanding or collapsing nodes within the metadata tree. Each node within the metadata tree contains two items: 

  • The Object Name
  • The Object Type

DOC xPress Metadata Viewer Metadata tree

ItemDescription
Object NameThe object name represents the name given to the object as it's displayed in your environment. It's commonly the most familiar name that you might use for an object and is used by DOC xPress to name match an object to Templates from a specific Structure Map when generating documentation.
Object TypeThe object type represents the object's class and is used by DOC xPress to type match an object to Templates from a specific Structure Map when generating documentation.

Object Properties Panel

The Object Properties Panel is located on the right of the Metadata Viewer and displays details for the currently selected object within the metadata tree or search panel. Display object details and enable a property value textbox that allows you to copy values from the currently selected property.

DOC xPress Metadata Viewer Object properties

ButtonDescription
DOC xPress Metadata Viewer Show object details button

Displays specific metadata properties for the currently selected object. 

Note:  Although most of these properties can be found by default within the metadata tree (object name and object type), the object path is important when building paths through the search panel or for structure maps.

DOC xPress Metadata Viewer Show property value button

Displays a selectable textbox at the bottom of the Object Properties Panel that allows you to select and copy the property's value out of the Metadata tree. 

Note:  The Property Value textbox is valuable for extracting DDL scripts and other properties that may contain long strings.

Search Panel

DOC xPress Metadata Viewer Show search panel buttonDOC xPress Metadata Viewer Search panel

The Search Panel allows you to use the Workbench Path Language to dynamically search a metadata tree for the currently scoped object that fits specific criteria. Open the search panel by selecting show search panel from the metadata viewer ribbon located at the top of the plug-in.

Note:  The Search Panel is a valuable tool for creating custom Structure Maps.

Note:  When using the Search Panel, the Metadata Tree Panel can toggle between viewing a filtered tree that only displays the Search results that match the path, or the full metadata tree.

ButtonDescription
DOC xPress Metadata Viewer Show tree buttonWhen on the Search Results panel, the Show Tree button is enabled and allows you to switch between displaying the search results for the currently filtered and the unfiltered metadata tree.
DOC xPress Metadata Viewer Show search results buttonWhen on the Metadata Tree panel and a valid search has been initiated, the Show Search Results button is enabled and allows you to switch between displaying the unfiltered and filtered metadata tree.

Important:  The Search panel displays search results based on the scope of the currently selected item. If the scope changes, typically by selecting a node from within the metadata tree or the search results, then it is very likely that the path selector used to search will no longer display results.

Managing Aliases

When working within a complex environment, SQL Server Aliases can make it difficult to document the lineage between one object and another. DOC xPress may detect object dependencies to external object items not currently within the solution. These items appear as Implicit Items within Lineage Analysis.

Implicit items can be a part of the solution, but Server Aliases make the links undetectable. The following images show an example of an Analysis Services database that references the AdventureWorksDW2014 located on FL-WS-QA-TR01 through the server alias localhost:

DOC xPress Lineage Analysis example before Managing Aliases
Before Adding Aliases

DOC xPress Lineage Analysis example after Managing Aliases
After Adding Aliases

The DOC xPress Manage Aliases feature allows you to organize aliases into a manageable list that simplifies external links. 

Setting Up Solution Aliases

To manage the aliases of a DOC xPress solution, complete the following steps:

  1. Open the desired DOC xPress solution. DOC xPress Open Solution
  2. Select Manage aliases to open the Manage Solution Aliases window. DOC xPress Solution Manage Aliases
  3. Select Add to open the Add Solution Alias window. DOC xPress Manage solution aliases window select Add
  4. Select a Source solution item and a Target Technology type from their respective drop-down lists. Enter the Original Target name of the target, then enter the Replacement Target name. Select OK to save your alias. Repeat this step for all of the desired aliases.
DOC xPress Add solution alias window select Source solution item
DOC xPress Add solution alias window select Target technology type
DOC xPress Add solution alias window enter target names

Note:  Add multiple aliases at the same time by selecting More. Selecting More displays an additional box to enter an Original Target name and Replacement Target name.

DOC xPress Add solution alias window select More
DOC xPress Add solution alias window section added

5. Select OK to exit the Manage Solution Aliases window and display the Aliases changed pop-up window. DOC xPress Manage solution aliases window select Ok

6. After adding the desired solution aliases, select Yes in the Aliases changed pop-up window to run a dependency scan and fully extract all dependency links. DOC xPress Aliases changed pop-up

Note:  Once the dependency scan completes, the dependency links display as a complete lineage for the object.

Manage Solution Aliases Window Options

DOC xPress Manage solution aliases window

ButtonDescription
OKSaves all changes to solution aliases and closes out of the window.
CancelCancels out of all changes made to solution aliases and closes out of the window.
AddAllows the user to begin configuring a new solution alias to add to the solution.
EditEdits an already existing solution alias.
DeleteDeletes an already existing solution alias.

Add Solution Alias Window

DOC xPress Add solution alias window

ButtonDescription
Source solution itemDesignates the solution item(s) where the alias will be applied. Setting the Source solution item to Global applies this alias to all solution items.
Target technology typeDesignates the technology type where this alias will be applied. Setting the Target technology type to None applies this alias to all technologies.
SourceDesignates the string that you want to search for within the target technology.
ReplacementDesignates the string that you want to replace the Source with.
 Match Case

Designates whether DOC xPress matches the Source part exactly or whether it ignores case sensitivity.

Less ^Removes an additional Original target, and Replacement target text box from the window.
More Adds an additional Original target, and Replacement target text box to the window.

Customizing Documentation Overview

Important:  Modifying the DOC xPress templates is not officially supported by SentryOne. While we provide documentation within this guide, any modifications to the DOC xPress templates are made at your own risk.

We encourage you to back up the DOC xPress templates folder before beginning any modification work. At this time, the only assistance our support team may be able to offer is with restoring the template files to their original state.

The DOC xPress templates are fully customizable and control the information included in the documentation. Use the templates to form and add reason to the output. 

If you're just beginning to learn how to customize your templates, this section provides an introduction to using templates in DOC xPress. It's recommended to read through this overview before continuing. After completing the overview, the document control, structure map, and templates sections provide you with a more detailed description of the functions present within the DOC xPress template documentation generation.

Note:  The templates are stored within a folder in the installation directories for the SentryOne Workbench and Workbench Server by default. The two default install locations are:

  • DOC xPress -  C:\Program Files (x86)\Pragmatic Works\Pragmatic Workbench\DOC xPress Templates
  • DOC xPress Server - C:\Program Files (x86)\Pragmatic Works\Workbench Server\DOC xPress Web Services\DefaultTemplates

Template Files and Folders

Within the template folder,  there are four files types and two folders:

Files

Template FileDescription
.template filesControls the general layout of an object and the properties that display within that object's page.
.lookupManages the lookup key-value pairs that are searched when called from the Lookup( ) Function.
defaultTemplate.documentControlThis file is responsible for setting what displays within templates and Structure Maps using output type flags that are set in the Generate Documentation dialog box.
StructureMap.*.xmlControls the overall structure of the root object within a Solution Layout. If a valid Structure Map cannot be found then the StructureMap.Default.xml is used, which is a data dump.

Folders

Template Folder Description
ImagesThis folder contains all of the images that are used along side the Image( ) Function.
TemplateImageThis folder contains small (16x16) and large (32x32) icons for many of the major templates. To add additional TemplateImages, the images must be saved within the TemplateImage folder in the following syntax:
  • <template key><size>
    • template key – The key of the template file that you wish to include, as described in the templates Page( ) function.
    • size – Whether this template image is the small (16x16) or large (32x32) version of the icon

Important:  If you plan to use custom templates, take a backup of the existing templates and point the templates folder to a new location with DOC xPress. You can't edit the templates, lookups, document control, structure maps, images, or template images in the default folder and must first copy them into a new template location. 

Additionally, you may be required to change the template and structure map files from read-only before being able to edit them.

Customizing Documentation Walkthrough

Many users of DOC xPress have expressed an interest in customizing the templates used within DOC xPress to generate documentation. The following is a walk-through for creating a simple custom template that summarizes SQL Server column data at the table level. 

Note:  All files modified within this documentation can be downloaded for review here.

Within the standard templates included in DOC xPress, drilling down to a table displays summary information about the table. Drilling down further allows you to see individual column information. The goal in this walkthrough is to create a new report that shows all columns as seen in the example below. The table column named Description will contain a DOC xPress Data Dictionary category.

DOC xPress Generated Documentation all columns example

Note:  Throughout this introduction, code snippets will be used as examples. 

Step One: Modifying the Document Control

The defaultTemplate.documentControl file controls which components are included within the generated documentation. The defaultTemplate.documentControl file is an XML file containing two major sections: OutputTypes and Flag.

OutputTypes Node

The first section of the defaultTemplate.documentControl XML begins in the OutputTypes node and displays within the Generate Documentation dialog window. 

The name attribute provides a friendly name for each of the output types, while the key attribute is used as a unique identifier that associates the output type with the flags found in the second section of the XML.

<OutputTypes>
<OutputType name="Compact Table" key="compactTable" />
<OutputType name="SQL Developer" key="developer" />
<OutputType name="Business Analyst" key="businessAnalyst" />
</OutputTypes>

DOC xPress Generate documentation window Compact Table

Flag Nodes

The remaining section of the defaultTemplate.documentControl file defines the various objects that can be documented. These flags are hierarchical in nature and contain several important attributes. A small snippet of the SQL.Server flag portion of the defaultTemplate.documentControl file and an image of how the file displays within the Generate Documentation dialog window are shown below. 

<Flag name="SQL.Server" description="SQL Server" developer="True" businessAnalyst="True" >
<Flag name="SQL.Configurations" description="Server Configurations" developer="True" businessAnalyst="True" />
<Flag name="SQL.Database" description="Database Details" developer="True" businessAnalyst="True" >
<Flag name="SQL.Tables" description="Table Details" developer="True" businessAnalyst="True" >
<Flag name="SQL.SchemaDiagrams" description="Schema Diagrams" developer="True" businessAnalyst="False" />
<Flag name="SQL.LineageImpact" description="Lineage and Impact" developer="True" businessAnalyst="False" >
<Flag name="SQL.ImpactLists" description="Impact Details" developer="True" businessAnalyst="False" />
<Flag name="SQL.LineageLists description="Lineage Details" developer="True" businessAnalyst="False" />
</Flag>
<Flag name="SQL.TableColumns" description="Column Details" showWarning="True" developer="True" businessAnalyst="False" />
<Flag name="SQL.TableForeignKeys" description="Foreign Key Details" showWarning="True" developer="True" businessAnalyst="False" />
<Flag name="SQL.TableIndexes" description="Index Details" showWarning="True" developer="True" businessAnalyst="False" />
<Flag name="SQL.TableTriggers" description="Trigger Details" developer="True" businessAnalyst="False" />
</Flag>
Snipped for brevity...
</Flag>
</Flag>

Important:  The XML above may have wrapped due to restrictions in printed form, but each node should all be on a single line in the XML file.

DOC xPress Generate documentation SQL Developer

AttributeDescription
Name The name attribute is used as a unique identifier that helps each Structure Map and Template associate the flags with the currently active output type.
DescriptionThe description attribute provides a friendly name for each of the flags.
showWarningThe showWarning attribute is an optional attribute that details whether or not a performance warning should be displayed within the Generate Documentation dialog window.

Each of the output type attributes provide the flag with the default behavior for that particular output type. For example, the SQL.SchemaDiagrams flag is set to True for the developer output type, but is set to False for the businessAnalyst output type by default.

Each flag corresponds to one of the lines in the dialog and is hierarchical in nature. 

Note:   In the above XML snippet, two of the attributes on each flag correspond directly to the key attribute of the output type in the OutputTypes section of the XML. Every flag must contain an attribute for each output type, indicating whether it should be included in the documentation (True) or excluded (False).

In this example, the Compact Table output type is essentially a subset of the SQL Server node. Set the compactTable attribute to False within each Flag except for on the SQL Server node. These modifications can be seen in the following XML sample:

<Flag name="SQL.Server" description="SQL Server" developer="True" businessAnalyst="True" compactTable="False" >

Next, add two new child flags (named SQL.CompactTable and SQL.Full) to the SQL.Server flag that are mutually exclusive with the developer and businessAnalyst attributes. These flags will be used within the next step to control which elements are included in the structure maps. After completely adding the new compactTable attribute to all flags and the two new nodes, the above example should appear as it does in the following example. The bold sections are the new additions to the document control:

<Flag name="SQL.Server" description="SQL Server" developer="True" businessAnalyst="True" compactTable="True" >
<Flag name="SQL.CompactTable" description="Compact Table SQL Server" developer="False" businessAnalyst="False" compactTable="True" />
<Flag name="SQL.Full" description="Compact Table SQL Server" developer="True" businessAnalyst="True" compactTable="False" />
<Flag name="SQL.Configurations" description="Server Configurations" developer="True" businessAnalyst="True" compactTable="False" />
<Flag name="SQL.Database" description="Database Details" developer="True" businessAnalyst="True" compactTable="False" >
<Flag name="SQL.Tables" description="Table Details" developer="True" businessAnalyst="True" compactTable="False" >
<Flag name="SQL.SchemaDiagrams" description="Schema Diagrams" developer="True" businessAnalyst="False" compactTable="False" />
<Flag name="SQL.LineageImpact" description="Lineage and Impact" developer="True" businessAnalyst="False" compactTable="False" >
<Flag name="SQL.ImpactLists" description="Impact Details" developer="True" businessAnalyst="False" compactTable="False" />
<Flag name="SQL.LineageLists description="Lineage Details" developer="True" businessAnalyst="False" compactTable="False" />
</Flag>
<Flag name="SQL.TableColumns" description="Column Details" showWarning="True" developer="True" businessAnalyst="False" compactTable="False" />
<Flag name="SQL.TableForeignKeys" description="Foreign Key Details" showWarning="True" developer="True" businessAnalyst="False" compactTable="False" />
<Flag name="SQL.TableIndexes" description="Index Details" showWarning="True" developer="True" businessAnalyst="False" compactTable="False" />
<Flag name="SQL.TableTriggers" description="Trigger Details" developer="True" businessAnalyst="False" compactTable="False" />
</Flag>
Snipped for brevity...
</Flag>
</Flag>

Important:  The XML above may have wrapped due to restrictions in printed form, but each node should all be on a single line in the XML file.

Remember the two flag names (SQL.CompactTable and SQL.Full) because they will be needed later. The SQL.Full flag will be associated with the original output types included with DOC xPress. The SQL.CompactTable flag will be associated with the new format currently being created.

Take note of the values of the output type attributes. Within SQL.CompactTable flag, the developer and businessAnalyst attributes are set to False, while the compactTable attribute is set to True. Within SQL.Full flag, the output type attribute values are switched. 

Step Two: Modifying the Structure Maps

DOC xPress Generated Documentation Structure Maps

The Structure Map files control the layout of the table of contents for the documents and control which objects are associated with which templates. There are multiple structure map files that make up a single documentation. When document generation begins, DOC xPress starts with the root level of the object within the document layout. In this case, that root level is SQL Server. DOC xPress then uses the root object type as a guide to match it to a structure map.

Note:  Structure Map files all follow the naming pattern StructureMap.*.xml .

To determine which structure map to initially use, DOC xPress examines each structure map file it finds within the templates folder. DOC xPress looks for the StructureMap node declaration, which is typically the second line within the structure map. The StructureMap node for the StructureMap.Sql.Server.xml file displays as the following:

<StructureMap typeMatch="Microsoft\.SqlServer\.Management\.Smo\.Server">

The typeMatch attribute is a regular expression used to match the correct structure map to the root object's type. Every object cataloged by DOC xPress has a specific object type, but not every object has a structure map that matches that object type. DOC xPress examines the root object's type and then matches that object type to the Structure Map using its typeMatch attribute. If DOC xPress finds multiple matches, it only uses the first structure map it finds, which may or may not be the desired result.

For you to properly determine the object type of the object that you want to add custom documentation, DOC xPress has a built in tool called the Metadata Viewer.

Select the View button DOC xPress Metadata Viewer View button to open the Metadata Viewer.Once the Metadata Viewer has loaded, the root object of the metadata tree represents the selected object in DOC xPress. Underneath the object's name is the object's type. DOC xPress Metadata Viewer Metadata tree

Note:  In this case, localhost's object type is Microsoft.SqlServer.Managment.Smo.Server. This matches directly to the typeMatch attribute for the StructureMap.Sql.Server.xml file.

To accommodate for the Compact Table output type created in Step One, the StructureMap.Sql.Server.xml file needs to be modified so that only databases and tables are present without adversely affecting the original SQL Developer and Business Analyst output types. To accomplish this, we insert the SQL.Full and SQL.CompactTable flags that were added into the StructureMap.Sql.Server.xml file to control which objects display in the Structure Map (and "Table of Contents").

Within the StructureMap.Sql.Server.xml file are two Objects that are child nodes to the Structure node. One object controls the table of contents for non-Azure Servers, while the second controls the table of contents for Azure Servers. Both Object nodes need to be tagged so they only work with the SQL Developer and Business Analyst output types. To do so, the flag attribute SQL.Full, which was created in Step One, needs to be added to both nodes. The modifications described above can be seen in the following XML sample :

<Object selector="." templateKey="SqlServer" flag="SQL.Full" condition="./[/Information[@Edition != &quot;SQL Azure&quot;] || !(/Information)]" >

Important:  The XML above may have wrapped due to restrictions in printed form, but should all be on a single line in the XML file. Case is very important when adding flags. In our modifications, the original flag in the control template file was SQL.Full and would not match to the flag Sql.FULL.

Next, within the StructureMap.Sql.Server.xml file, scroll down to find the second Object declaration and modify it similarly to the first one:

<Object selector="." templateKey="SqlServer" flag="SQL.Full" condition="./[/Information[@Edition == &quot;SQL Azure&quot;]]" >

Finally, we need to add a third Object declaration handle to control the Compact Table output type that was created in Step One. This new Object will be simple, containing only the databases and none of the other objects, such as jobs, linked servers, et cetera. The Object node will be similar to the other two Objects, its selector will still be (period) and its templateKey will also be SqlServer. This object will not contain a condition attribute and will have its flag set to SQL.CompactTable. These modifications can be seen in the following XML sample :

<Object selector="." templateKey="SqlServer" flag="SQL.CompactTable" >
<ChildObjectsSubStructure selector="./Databases" condition="./Databases/" />
</Object>

The ChildObjectsSubStructure tells DOC xPress to search for another Structure Map to fill in the structure for this section, specifically the one for the Databases object. The structure map that controls databases (StructureMap.Sql.DatabaseCollection.xml) drills down into tables using a third structure map (StructureMap.Sql.Database.xml). Since these structure maps reach down into the tables, there is no need to modify them. Even though a database contains many objects, the document control that was modified in Step One excludes all objects when documenting and using the Compact Table output type. DOC xPress does not attempt to generate documentation for these other, non-table objects. Since DOC xPress never generates the documentation for these items, it won't add an entry in the Table of Contents.

Note:  A good analogy for why this occurs would be the 13th floor of many buildings. Many buildings skip over the 13th floor when assigning floor numbers. Since there is no 13th floor, there is no need to put a 13th floor button in the elevator. Even though the elevator technicians may have wired the elevator for floor 13, because there is no button for the 13th floor the elevator technician merely pushes the wires back and they are safely ignored.

In the standard documents generated by DOC xPress, selecting tables allows you to drill down further into individual column details. For the new Compact Table output type, this behavior needs to be altered so that the Table object becomes the lowest level. The structure map for tables needs to be altered to accommodate this change of behavior.

Find and open the StructureMap.Sql.Table.xml file. Within it, the columns, triggers, and index branches need to be modified so that they only display if you select SQL Developer or Business Analyst, and not the new Compact Table output type. These three sub-branches need to have the flag attribute set to SQL.Full to accomplish this. The modifications described above can be seen in the following XML sample :

<Structure><Object selector="." templateKey="SqlTable" flag="SQL.Tables" >
<Object selector="Columns" templateKey="SqlColumnsCollection" flag="SQL.Full" condition="Columns/" >
<ChildObjects selector="$Object(Path:'./',OrderBy: Int(@PropertyValue('ID')))" flag="SQL.TableColumns" />
</Object>
<Object selector="ForeignKeys" templateKey="SqlForeignKeyCollection" flag="SQL.Full" condition="ForeignKeys/" >
<ChildObjects selector="./" flag="SQL.TableForeignKeys" />
</Object>
<Object selector="Indexes" templateKey="SqlIndexCollection" flag="SQL.Full" condition="Indexes/" >
<ChildObjects selector="$Object(Path:'./[@IndexType->&quot;Clustered&quot;]')" templateKey="SqlRelationalIndex" flag="SQL.TableIndexes" />
<ChildObjects selector="$Object(Path:'./[@IndexType->&quot;SpatialIndex&quot;]')" templateKey="SqlSpatialIndex" flag="SQL.TableIndexes" />
<ChildObjects selector="$Object(Path:'./[@IndexType->&quot;XmlIndex$&quot;]')" templateKey="SqlXmlIndex" flag="SQL.TableIndexes" />
</Object>
<Object selector="Triggers" templateKey="SqlTableTriggerCollection" flag="SQL.Full" condition="Triggers/" ><ChildObjects selector="./" flag="SQL.TableTriggers" />
</Object>
</Object>
</Structure>

With the modification above, Columns, ForeignKeys, Indexes, and Triggers only display when the SQL.Full flag is set in the original document control file to True. With the structure maps now set, the final step is to modify the templates.

For more information about Structure Maps in DOC xPress, see Structure Maps.

Step Three: Modifying the Template

Unlike the other files, the *.template files are not XML. The *.template files are a special template language used by DOC xPress to control the layout of each individual page within documentation. 

Note:  This introduction does not cover the entire language. Only the functions necessary to achieve the original goal of this introduction are discussed. For more information about the template language, see Templates.

For purposes of this exercise, the only modifications that are necessary can be found within the SqlTable.template file. This file controls the visual layout of each SQL Server Table.

Like the structure maps edited in Step Two, SqlTable.template will be used by all output types to generate documentation, not just the new Compact Table output type. We need to ensure that any modifications made to SqlTable.template will not affect the SQL Developer or Business Analyst output types that are included within DOC xPress.

Note:  The template language does support simple programming constructs such as the if-else statement. Using an if-else statement, the document control can switch between two different sets of code depending on the output type used.

Open up the SqlTable.template, and add an If statement just below the DeclareSelector function that uses the FlagIsSet function to check to see if the SQL.CompactTable flag has been set to True. If the SQL.CompactTable flag has been set to True, the code within the If statement will run. The modifications described above, and the new code can be seen in the following template sample :

01: If(FlagIsSet('SQL.CompactTable'))
02: {
03: If(Any(RunSelector('Columns')))
04: {
05: Table(RunSelector('Columns'),
06: {'Column Name', 'Description', 'Data Type', 'Length', 'Can Be Empty' },
07: {
08:  Link($CurrentObject, @ObjectName),
09:  ParameterRequest('DataDictionaryEntry(Description)') ,
10:  @PropertyValue('SqlDataType').From($Object(Path:'DataType')),
11:  @PropertyValue('MaximumLength').From($Object(Path:'DataType')) == '-1' ?
12:  ('Maximum') : (@PropertyValue('MaximumLength').From($Object(Path:'DataType'))),
13:  Image(@PropertyValue('Nullable') == 'True'? ('True.png') : ('False.png'))
14:  });
15:  }
16:  Else
17:  {
18:  Span('No columns are present for this table.');
19:  }
20:  }
21:  Else
22:  {
23:  // Original Template
24:  }

Note:  Line numbers have been added for purposes of this discussion and are not a part of the final code.

Line 1 has an If statement that checks to see if the SQL.CompactTable flag has been set. In line 3, another If statement checks to see if any columns exist. If no columns exist, the Else clause on line 16 triggers and only outputs a string notifying you that the current table does not have any columns. If this was not done, then no columns would be returned by the Table function on line 5 and a large blank area would be present, leaving you to wonder what happened.

Line 5 initiates a Table function, line 6 describes how many columns will be within the table as well as their names: Column Name, Description, Data Type, Length, and Can Be Empty, and lines 8 through 13 create a comma separated list for the values used within each column. Line 9, contains a ParameterRequest function that retrieves a special value from the DOC xPress repository for the current column. The type of parameter is a DataDictionaryEntry that requires the name of the entry the template creator wishes to retrieve. In the case of line 9, the template creator wishes to retrieve the Description Data Dictionary Entry for each column. You may add new columns to the Data Dictionary and may explicitly add them to their documentation by replacing Description with the name of the new Data Dictionary Entry you want to include. The other lines make fairly standard calls to retrieve items from the DOC xPress snapshot.

Line 21 contains an Else statement the encapsulates the original template with two curly brackets (line 22 and 24). This Else statement runs when SQL.CompactTable is False.

For more information about the Templates in DOC xPress, see the Templates article. 

Step Four: Generating Documentation

After editing the document control, structure map, and templates to handle both the new output types and the original, generating documentation is the last step! Generating a document with the new output types is now as easy as using any of the built in types. After opening a solution in DOC xPress and selecting Generate Documentation, ensure that the Output Type is set to the new Compact Table. After selecting the desired output format, select OK to begin generating the documentation.

DOC xPress Generated Documentation custom template example

Note:  See how the Structure Maps kicked in, and the Tables no longer drill down into the columns. In addition, the new template pages only show a compact view of the columns and hide the more robust details present within the standard templates.

Document Control

The document control file defaultTemplate.documentControl is in the template folder for DOC xPress. This file is responsible for setting what displays within templates and Structure Maps using output type flags that are set in the Generate Documentation dialog box. 

DOC xPress DOC xPress Templates Folder
DOC xPress Templates Folder

DOC xPress defaultTemplate.document.Control File
defaultTemplate.document.Control File

Set your own custom output styles by completing the following steps:

  1. Open the Generate Documentation window, and then select the Output Type arrow to open the Specify included output items window. DOC xPress Generate documentation window
  2. Select or deselect the desired output items for your custom selection. Select the Save my selection as: checkbox, then name your selection. Select OK to save your custom Output. DOC xPress Specify included output items window

Note:  This method does not update the Document Control file. Edit a copied version of the Document Control file to add your own Output Types and select the flags you want. If you add your own <OutputType> tag you then add the name to each <Flag> tag and set it to either True or False to choose whether it outputs that type. Each Flag inherits the Boolean from its parent, so setting the parent to False automatically disables all of its children Flags.

Output Style Added Through Document Control:

DOC xPress default Template.documentControl

The added output type showing in Generate documentation window:

DOC xPress Generate Documentation added output example
DOC xPress Generate documentation Specify included output items added output example

Structure Maps Overview

Structure Maps are XML files that help organize the layout (table of contents) of your documentation during documentation generation and determine which templates are used for each object within the structure map. 

Note:  You need a basic knowledge of XML file structure to edit structure map files.

Due to the vast number of object types that can be found within a carbon tree, there aren't structure maps that correspond to every object type. For a detailed list of all object types that currently have structure maps included within DOC xPress, see the Supported Structure Maps section below

Note:  When generating documentation, if your documentation appears to represent the metadata available rather than custom tailored documentation, then DOC xPress was unable to find a matching structure map and used the default structure map instead.

Note:  The DOC xPress Metadata Viewer can help you create custom structure maps because it provides you with an exact structure of a carbon tree, including its object types and properties.

When generating documentation for the root object found within the layout, DOC xPress looks for all files within the templates folder that follows the naming pattern StructureMap.*.xml. After gathering all structure map files, DOC xPress uses the StructureMap's typeMatch to find all matching structure maps. If DOC xPress finds more than one structure map that matches, it uses the first match, otherwise, it uses the default structure map (StructureMap.Default.xml). After a structure map is found, DOC xPress uses the structure map to generate the layout (table of contents) of your documentation and apply the correct templates for each object within the structure map.

The following example is a simplified structure map for a SQL Server Instance that includes links for further details of the expected behavior for each node and attribute:

<?xml version="1.0" encoding="utf-8" ?>
<StructureMap typeMatch="Microsoft\.SqlServer\.Management\.Smo\.Server">
<Structure>
<Object selector="." templateKey="SqlServer" condition="./[/Information[@Edition != &quot;SQL Azure&quot;] || !(/Information)]" >
<Object selector="." templateKey="SqlConfigurations" flag="SQL.Configurations" condition="./Configuration/" />
<ChildObjectsSubStructure selector="./Databases" condition="./Databases/" />
<Object selector="$Object(Path:'.[./Logins/ || ./Credentials/]')" templateKey="SqlSecurity" flag="SQL.Security" >
<Object selector="Logins" templateKey="SqlLoginsCollection" condition="Logins/" >
<ChildObjects selector="./[@IsDisabled == &quot;False&quot;]" templateKey="SqlLogin" flag="SQL.SecurityDetail" />
<ChildObjects selector="./[@IsDisabled == &quot;True&quot;]" templateKey="SqlLoginDisabled" flag="SQL.SecurityDetail" />
</Object>
<Object selector="Credentials" condition="Credentials/" >
<ChildObjects selector="./" flag="SQL.SecurityDetail" />
</Object>
</Object>
</Object>
</Structure>
<Rules>
<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials" />
<Rule templateKey="SqlCredential" typeMatch="Smo\.Credential$" />
<Rule templateKey="GlobalDefault" />
</Rules>
</StructureMap>

Yellow Warnings in Solutions

DOC xPress uses template structure maps to manage the overall structure of the documentation. When you include an item within the layout that does not have a corresponding structure map for that items' object type, DOC xPress displays a yellow warning icon DOC xPress Yellow Warning iconto notify you that the default structure map will be used instead.

DOC xPress DOC xPress Solution Yellow warning example

If DOC xPress can't find a corresponding structure map, it uses a default structure map that generates documentation that represents the metadata available rather than custom tailored documentation. The following is an example of default documentation:

DOC xPress Generated default documentation

Note:  If you don't want to use the default structure map, you can add custom structure maps and templates to the template location to customize the documentation to your needs.

Supported Structure Maps

The following is a list of the object types and their associated structure maps. These structure maps are included within the installation for DOC xPress.

Generic

  • Default
  • Folder

Hive

  • Database
  • Server
  • Table

Informatica

  • Repository Server
  • Widget
  • Workflow Folder Collection
  • Workflow Folder
  • Workflow Mapping
  • Workflow Task
  • Workflow Worklet
  • Workflow Mapping

SQL Server

  • Agent Job Collection
  • Agent Job
  • Availability Group Collection
  • Availability Group
  • Service Broker
  • Database Collection
  • Database
  • Server
  • Stored Procedure Collection
  • Stored Procedure
  • Table Collection
  • Table
  • View Collection
  • View

SSAS

  • Action Collection
  • Cube Collection
  • Cube
  • Database Collection
  • Database
  • Dimension Collection
  • Mining Model Column
  • Mining Structure
  • Perspective Collection
  • Role Collection
  • Server
  • Tabular Column Collection
  • Tabular Column
  • Tabular Connection Collection
  • Tabular Connection
  • Tabular Database
  • Tabular Hierarchy Collection
  • Tabular Hierarchy
  • Tabular Measure Collection
  • Tabular Measure
  • Tabular Partition Collection
  • Tabular Partition
  • Tabular Perspective Collection
  • Tabular Perspective
  • Tabular Perspective Table Collection
  • Tabular Perspective Table
  • Tabular Role Collection
  • Tabular Role
  • Tabular Table Collection
  • Tabular Table

SSIS

  • Containers
    • For Each Loop
    • For Loop
    • Sequence
  • Destinations
    • ADO.NET
    • Data Reader
    • Flat File
    • ODBC
    • OLE DB
  • Event Handler'
  • Package
  • Package Collection
  • Package Store
  • Sources
    • ADO.NET
    • Data Reader
    • Flat File
    • OLE DB
  • SQL Server
  • SSIS Catalog
  • SSIS Folder
  • SSIS Project
  • SSIS Solution
  • Tasks
    • Analysis Services Execute DLL
    • Analysis Services Processing
    • Backup Database
    • Bulk Insert
    • CDC Control
    • Check Database Integrity
    • Data Mining Query
    • Data Profiling
    • Execute Package
    • Execute Process
    • Execute SQL Server Agent Job
    • Execute SQL
    • Execute T-SQL Statement
    • Expression
    • File System
    • FTP
    • History Cleanup
    • Maintenance Cleanup
    • Message Queue
    • Notify Operator
    • Rebuild Index
    • Reorganize Index
    • Send Mail
    • Shrink Database
    • Transfer Database
    • Transfer Error Messages
    • Transfer Jobs
    • Transfer Logins
    • Transfer Master Stored Procedures
    • Transfer SQL Server Objects
    • Update Statistics
    • Web Service
    • WMI Data Reader
    • WMI Event Watcher
    • XM
  • Transforms
    • Aggregate
    • Audit
    • Cache
    • CDC Splitter
    • Character Map
    • Conditional Split
    • Copy Column
    • Data Conversion
    • Derived Column
    • Lookup
    • Merge
    • Merge Join
    • Multicast
    • Ole Db Command
    • Percentage Sampling
    • Pivot
    • Row Count
    • Row Sampling
    • Script
    • Slowly Changing Dimension
    • Sort
    • Term Extraction
    • Union All

SSRS

  • Chart
  • Report
  • Report Project
  • Shared Datasets
  • Shared Data Sources
  • SSRS Directory
  • SSRS File System
  • SSRS Folder
  • SSRS Web Service
  • Rectangle
  • Sub Reports
  • Tablix
  • Textbox

Tableau

  • Server
  • Site
  • Project Collection
  • Project
  • Data Source Collection
  • Data Source
  • Workbook Collection
  • Workbook

Task Factory

  • Destinations
    • Dynamics CRM
    • Fact Table
    • Oracle Upsert
    • SalesForce
    • SharePoint
    • Terminator
    • XML
    • Upsert
    • XML Output
    • Marketo
  • Sources
    • Dynamics CRM
    • Email
    • Facebook
    • Hadoop WebHDFS
    • LinkedIn
    • Placeholder
    • SalesForce
    • SharePoint
    • Twitter
    • Marketo
    • Rest
  • Tasks
    • Advanced Email and SMS
    • Advanced Execute Package
    • Advanced Execute Process
    • Compression
    • Delete or Move Email Source Messages
    • Download File
    • Excel Power Refresh
    • Expression
    • File Properties
    • PGP
    • Secure FTP
    • SecureConfig
    • SharePoint Documents
    • Timer
  • Transforms
    • Address Parse
    • Advanced Aggregator
    • Advanced Conditional Split
    • Advanced Derived Column
    • Advanced Lookup
    • Advanced Lookup Cache
    • Case
    • Data Cleansing
    • Data Flow Nugget
    • Data Validation
    • Delete Batch
    • Dimension Merge Slowly Changing Dimension
    • Error Output Description
    • Filter Rows
    • Hash
    • Null Handler
    • Pack Data
    • Placeholder
    • RegEx Replace
    • Replace Unwanted Characters
    • Surrogate Key
    • Timezone Conversion
    • Trim Plus
    • Unpack Data
    • Update Batch
    • XML Generator

Structure Map Node

The StructureMap node encapsulates the entire structure map, and contains the typeMatch attribute, which matches all of a solution's root object types to their respective structure map.

Syntax

This structure map matches to all object types that fit the regular expression string Microsoft\.SqlServer\.Management\.Smo\.Server and creates an empty structure with no nodes, and implicitly maps all templates to the template GlobalDefault. The following is an example of the structure map code:

<StructureMap typeMatch="Microsoft\.SqlServer\.Management\.Smo\.Server">
<Structure>
</Structure>
<Rules>
<Rule templateKey="GlobalDefault" />
</Rules>
</StructureMap>

Required Attributes

AttributeDescription
typeMatchUsed by DOC xPress during document generation to match the structure map to a regular expression based on each of the root object types present within the solution layout.

Important:  The typeMatch attribute is required for all structure maps with the exception of the default structure map. There must be one and only one structure map that does not specify a typeMatch. In a default installation of the DOC xPress templates, that structure map is named StructureMap.Default.xml.

Required Child Nodes

Child NodeDescription
StructureDetails the layout (table of contents) for the current Structure Map.
RulesDetails implicit matches between object and/or name matches for templates within the current structure map. A structure map must have at least one rule, which typically points to a default template that's used if there are no explicit templateKeys and no other rule matches.

Note:  Rules are evaluated in the order that they are specified. For example, if you have multiple rules that may match the same object, the first match is always used.

Structure Node

The Structure node encapsulates the entire layout for the StructureMap and separate the structure maps rules from the layout.

Syntax

<Structure>
</Structure>

Optional Child Nodes

Child Node Description
ChildObjects Creates child pages within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another structure map that matches the object type for each object that matches the selector.
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each object that matches the selector. This child node is most often used during the creation of a structure map to help display the entire structure of a set of objects.

Child Objects Node

The ChildObjects are used within the structure to create child pages within the documentation for each object that matches the selector.

Syntax 

This node returns all children of the parent node to be included within the Documentation:

<ChildObjects selector="./" >
</ChildObjects>

Required Attributes

AttributeDescription
selectorUses Path Grammar or an $Object selector to select one or more objects that the current node applies to. The selector is always scoped to the parent node.

Optional Attributes

AttributeDescription
conditionUses Path Grammar or an $Object Selector to dynamically show/hide nodes based on whether or not the Path Grammar or $Object Selector returns at least one object. The condition is always scoped to the parent node.
flagUsed in conjunction with the defaultTemplate.documentControl file to associate the current node's flag value with the name value as detailed within the defaultTemplate.documentControl file. During documentation, if the associated flag is set to False, then DOC xPress skips the current node and does not include it within the documentation.
templateKeyExplicitly overrides any rule and matches all objects that match the selector with the specified templateKey.

Optional Child Nodes

Child NodeDescription
ChildObjects Creates child page(s) within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another structure map that matches the object type for each object that matches the selector.  
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each child object that matches the selector. This child node is most often used during the creation of a structure map to help display the entire structure of a set of objects.

ChildObjectsSubStructure Node

The ChildObjectsSubStructure node is explicitly searches for another structure map that matches the object type for each object that matches the selector. ChildObjectsSubStructure nodes are used to create a more flexible structure map that allows for more object types within the solution's layout to return a formatted document. A ChildObjectsSubStructure node should contain no child nodes.

Syntax

This ChildObjectsSubStructure node returns all children of the parent node and attempts to match each child's object type to another structure map for use within the documentation:

<ChildObjectsSubStructure selector="./" />

Required Attributes

AttributeDescription
selectorUses path grammar or an $Object selector to select one or more objects that the current node applies to. The selector is always scoped to the parent node.

Optional Attributes

AttributeDescription
conditionUses path grammar or an $Object selector to dynamically show/hide nodes based on whether or not the path grammar or $Object selector returns at least one object. The condition is always scoped to the parent node.
flagUsed in conjunction with the defaultTemplate.documentControl file to associate the current node's flag value with the name value as detailed within the defaultTemplate.documentControl file. During documentation, if the associated flag was set to "False", then DOC xPress will skip the current node and will not include it within the documentation.

Object Node

An Object is used within the structure to create a single child page within the documentation for the first object that matches the selector. 

Syntax

This Object node returns the child of the parent node with the name columns to be included within the documentation:

<Object selector="Columns" >
</Object>

Required Attributes

AttributeDescription
selectorUses path grammar or an $Object selector to select the first objects that the current node applies to. The selector is always scoped to the parent node.

Optional Attributes

AttributeDescription
conditionUses path grammar or an $Object selector to dynamically show or hide the node based on whether the path grammar or $Object selector returns at least one object. The condition is always scoped to the parent node.
flagUsed in conjunction with the defaultTemplate.documentControl file to associate the current node's flag value with the name value as detailed within the defaultTemplate.documentControl file. During documentation, if the associated flag is set to False, then DOC xPress skips the current node and does not include it within the documentation.
templateKeyExplicitly overrides any rule and matches the object that match the selector with the specified templateKey.

Optional Child Nodes

Child NodeDescription
ChildObjectsCreates child page(s) within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another structure map that matches the object type for each object that matches the selector.
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each object that matches the selector. This child node is most often used during the creation of a structure map to help display the entire structure of a set of objects.

RecursiveChildObjects

The RecursiveChildObjects node maps out the entire metadata for each object that matches the selector. RecursiveChildObjects nodes are most often used during the troubleshooting process when creating custom structure maps to help visually display the entire structure of an object as well as all of its properties in an unformatted manner. A RecursiveChildObjects node should contain no child nodes.

Important:  When using a RecursiveChildObjects node, the generated documentation represents the structure of the extracted metadata, which may result in a large number of pages being generated that show the full metadata content.

Syntax

This RecursiveChildObjects node returns all children of the parent node and recursively maps out the entire metadata for each object within the Documentation:

<RecursiveChildObjects selector="./" />

Required Attributes

AttributeDescription
selectorUses path grammar or an $Object selector to select one or more objects that the current node applies to. The selector is always scoped to the parent node.

Optional Attributes

AttributeDescription
conditionUses path grammar or an $Object selector to dynamically show/hide nodes based on whether or not the path grammar or $Object selector returns at least one object. The condition is always scoped to the parent node.
flagUsed in conjunction with the defaultTemplate.documentControl file to associate the current node's flag value with the name value as detailed within the defaultTemplate.documentControl file. During documentation, if the associated flag is set to False, then DOC xPress skips the current node and does not include it within the documentation.

Rules Node

The Rules node encapsulates the entire list of rules that are used to implicitly associate objects of a specific name and/or type with a specific templateKey. If an explicit templateKey is present within the structure for an object that normally would match the rule, the explicit templateKey is used regardless of whether or not a rule matches the object type.

Important:  Rules are evaluated in the order that they are specified. For example, if you have multiple rules that may match the same object, the first match is always used.

Syntax

<Rules>
<Rule templateKey="GlobalDefault" />
</Rules>

Required Child Nodes

Child NodeDescription 
RuleImplicitly matches an object type or name with a template. At least one (default) rule must be present within each structure map to ensure that all objects present within the structure map are formatted regardless of whether an explicit or implicit templateKey match is found.

Rule Node

Specifies a single rule for implicitly associating objects of a specific name and/or type with a specific templateKey. If an explicit templateKey is present within the structure for an object that normally would match the rule, the explicit templateKey is used regardless of whether a rule matches the object type.

Syntax 

This rule implicitly maps all objects to the template mapped to the key GlobalDefault:

<Rule templateKey="GlobalDefault" />

This rule implicitly maps all objects with an object type that matches the regular expression string Smo\.Credential$ to the template mapped to the key SqlCredential:

<Rule templateKey="SqlCredential" typeMatch="Smo\.Credential$" />

This rule implicitly maps all objects with an object name that matches the regular expression string Credentials$ to the template mapped to the key SqlCredentialsCollection:

<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials$" />

This rule implicitly maps all objects with an object name that matches the regular expression string Credentials$ and an object type that matches the regular expression string Smo\.CredentialsCollection$ to the template mapped to the key SqlCredentialsCollection:

<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials$" typeMatch="Smo\.CredentialsCollection$" />

Required Attributes

AttributeDescription
templateKeySpecifies the templateKey that the following implicit rule references. If no nameMatch or typeMatch attributes are included within the rule, this rule is the default rule and only applies if there are no other matches found.

Optional Attributes

AttributesDescription
nameMatchA regular expression string that is used by the structure map to match all objects that do not contain explicit matches based on the object's name to a templateKey. If both nameMatch and typeMatch are included, then both nameMatch and typeMatch must match for the rule to be applied.
typeMatchA  regular expression string that is used by the structure map to match all objects that do not contain explicit matches based on the object's type to a templateKey. If both nameMatch and typeMatch are included, then both nameMatch and typeMatch must match for the rule to be applied.

Condition

The condition attribute uses Path Grammar or an $Object selector to dynamically show/hide the associated node based on whether the path grammar or $Object selector returns at least one object. The condition is always scoped to the parent node.

Syntax

This ChildObjectsSubStructure node only returns the Databases node if the Database nodes contains at least one child node:

<ChildObjectsSubStructure selector="./Databases" condition="./Databases/" />

This Object node only returns the parent node if the Property named Edition found on the Information node is not equal to SQL Azure or the Information node is not present within metadata:

<Object selector="." condition="./[/Information[@Edition != &quot;SQL Azure&quot;] || !(/Information)]" >
</Object>

This Object node only returns the UserDefinedTypes node if the object with path UserDefinedTypes/ exists:

<Object selector="UserDefinedTypes" condition="$Object(Path:'UserDefinedTypes/')" >
</Object>

Associated Optional Nodes

Optional NodeDescription
ChildObjectsCreates child pages within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another Structure Map that matches the object type for each object that matches the selector.
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each object that matches the selector. This child node is most often used during the creation of a Structure Map to help display the entire structure of a set of objects.

Flag

The flag attribute is used in conjunction with the defaultTemplate.documentControl file to associate the current node's flag value with the name value as detailed within the defaultTemplate.documentControl file. During documentation, if the associated flag is set to False, then DOC xPress skips the current node and does not include it within the documentation.

Syntax

This ChildObjects node returns all children of the parent node only if the flag SQL.SecurityDetail is set to True at the time of document generation:

<ChildObjects selector="./" flag="SQL.SecurityDetail" />

This Object node only returns the parent node if the flag SQL.Database is set to True at the time of document generation:

<Object selector="." flag="SQL.Database" >
</Object>

Associated Optional Nodes

Optional NodeDescription
ChildObjectsCreates child pages within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another Structure Map that matches the object type for each object that matches the selector.
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each object that matches the selector. This child node is most often used during the creation of a Structure Map to help display the entire structure of a set of objects.

nameMatch

The nameMatch attribute implicitly matches all objects within the Structure Map to a regular expression based on the object's name. If both nameMatch and typeMatch are included within the Rule, then both nameMatch and typeMatch must match for the rule to be applied.

Syntax

This rule implicitly maps all objects with an object name that matches the regular expression string Credentials$ to the template mapped to the key SqlCredentialsCollection:

<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials$" />

This rule implicitly maps all objects with an object name that matches the regular expression string Credentials$ and an object type that matches the regular expression string Smo\.CredentialsCollection$ to the template mapped to the key SqlCredentialsCollection:

<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials" typeMatch="Smo\.CredentialsCollection$" />

Associated Optional Nodes

Optional NodeDescription
RuleSpecifies a single rule for implicitly associating objects of a specific name and/or type with a specific templateKey.

templateKey

The templateKey attribute has different functionality depending on where it is used . If the templateKey is found within a Rule node, the templateKey implicitly matches objects found within the current Structure Map. If the templateKey is found within a ChildObjects or Object node, then the templateKey explicitly overrides any Rule that would otherwise match that object.

Syntax

This rule implicitly maps all objects with an object type that matches the regular expression string Smo\.Credential$ to the template mapped to the key SqlCredential:

<Rule templateKey="SqlCredential" typeMatch="Smo\.Credential$" />

This ChildObjects node returns all children of the parent node and explicitly applies the template mapped to the key SqlLogin:

<ChildObjects selector="./" templateKey="SqlLogin" >
</ChildObjects>

Associated Required Nodes

Required NodeDescription
RuleImplicitly matches an object type or name with a template. At least one (default) Rule must be present within each Structure Map to ensure that all objects present within the Structure Map are formatted regardless of whether an explicit or implicit templateKey match is found. The templateKey attribute is a required attribute for a valid Rule.

Associated Optional Nodes

Optional NodesDescription
ChildObjectsWhen the templateKey attribute is present under a ChildObjects node, then the templateKey explicitly overrides any Rule that would otherwise match that object. The templateKey attribute is an optional attribute for a ChildObjects.
Object When the templateKey attribute is present under an Object node, then the templateKey explicitly overrides any Rule that would otherwise match that object. The templateKey attribute is an optional attribute for an Object.

typeMatch

The typeMatch attribute has different functionality depending on where it is used. When used within the StructureMap node, the typeMatch is used by DOC xPress during document generation to match the Structure Map to a regular expression based on each of the root object types present within the solution layout. When present within Rule node, the typeMatch attribute implicitly matches all objects within the Structure Map to a regular expression based on the object's type. If both nameMatch and typeMatch are included within the Rule, then both nameMatch and typeMatch must match for the rule to apply.

Syntax

This structure map matches to all object types that fit the Regular Expression string Microsoft\.SqlServer\.Management\.Smo\.Server and creates an empty structure with no nodes as well as implicitly maps all templates to the template GlobalDefault:

<StructureMap typeMatch="Microsoft\.SqlServer\.Management\.Smo\.Server">
<Structure>
</Structure>
<Rules>
<Rule templateKey="GlobalDefault" />
</Rules>
</StructureMap>

This rule implicitly maps all objects with an object name that matches the regular expression string Credentials$ and an object type that matches the regular expression string Smo\.CredentialsCollection$ to the template mapped to the key SqlCredentialsCollection:

<Rule templateKey="SqlCredentialsCollection" nameMatch="Credentials$" typeMatch="Smo\.CredentialsCollection$" />

Associated Required Nodes

Required NodeDescription
StructureMapEncapsulates the entire Structure Map and contains the typeMatch attribute, which matches all of a solution's root objects types to theire respected structure map.

Associated Optional Nodes

Optional NodeDescription
RuleSpecifies a single rule for implicitly associating objects of a specific name and/or type with a specific templateKey.

selector

The selector attribute uses the Workbench Path Language or a Selector to select one or more objects for use by the current node. The selector is always scoped to the parent node.

Syntax

This ChildObjectsSubStructure node returns all children of the Databases node and attempts to match each child's object type to another structure map for use within the Documentation:

<ChildObjectsSubStructure selector="./Databases/" />

This ChildObjects node returns all children of the parent node in which the Property named FunctionType matches the regular expression string ^Scalar for use within the Documentation:

<ChildObjects selector="$Object(Path:'./[@FunctionType->&quot;^Scalar&quot;]')" />

Associated Required Nodes

Required NodeDescription
ChildObjectsCreates child pages within the documentation for each object that matches the selector.
ChildObjectsSubStructureExplicitly searches for another Structure Map that matches the object type for each object that matches the selector.
ObjectCreates a single child page within the documentation for each the first object that matches the selector.
RecursiveChildObjectsRecursively creates the entire metadata tree for each object that matches the selector. This child node is most often used during the creation of a Structure Map to help display the entire structure of a set of objects.

Object Selectors

Object selectors are used in a variety of circumstances to select one or more objects from which to operate. Object selectors create the path grammar to locate related objects within the carbon tree for listing, linking, and building tables. Object selectors also form the basis for the selection of nodes within the Structure Maps.

Syntax 

SelectorDescriptionCompatibility
$CurrentObjectReturns the currently scoped object. This is useful when generating links to objects within a table.Can be used within structure maps or templates.
$Object(Path:’path/to/related/object’)Returns the list of objects returned by the specified path using the Workbench Path Language.Can be used within structure maps or templates.
$ObjectReference(<referenceKey>)When a carbon object contains a reference to another object, this can be resolved using the $ObjectReference selector.Can be used within structure maps or templates.
RunSelector(<selectorKey>)Run a previously stored selector with 'DeclareSelector’.Can only be used within templates.

Examples

To return the children of child node 'Databases', use :

$Object(Path:’Databases/’)

To return the children of the child node 'Databases', ordered by the 'Name' property on each Database, use:

$Object(Path:’Databases/’,OrderBy:@PropertyValue(‘Name’))

To return the object stored in the object reference 'RelatedPackage', use:

$ObjectReference(‘RelatedPackage’)

To store and run a selector for all tables, use :

DeclareSelector(‘Tables’, $Object(Path:’Tables/’));
For(RunSelector(‘Tables’))
{

}

Page Level Objects

Page level objects are the main building blocks for the output of a given template file and form the major elements that are included within the documentation.

Code ( )

Specifies the content as code and provides indentation. If you're using the optional code type argument, then it also provides syntax highlighting based on the given code type.

Syntax

Code([<code type>, ]<content item>);

Arguments

ArgumentDescription
code typeAny code type from the following table:
Code Type TermLanguageHighlightingReformatting
SQLT-SQLYesNo
VBVisual Basic .NETYesNo
CSC#YesNo
XMLXMLYesNo
Formatted XMLXMLYesYes
Note:  If the code type is omitted, then the output is emitted in a monospace font, but no highlighting or reformatting is applied.
content itemThe content item to format.

Examples

Code(@PropertyValue('DdlScript'));
Code(SQL, @PropertyValue('DdlScript'));

EmbeddedImage ( )

Displays an image which is stored as a property from the currently scoped object in the carbon tree.

Syntax

EmbeddedImage(<property key>);

Arguments

ArgumentDescription
property keyThe name of the property which contains the image stream.

Examples

EmbeddedImage('SomePicture');

Header ( )

Writes the contents of the content item to the page in a large font.

Syntax

Header(<content item>);

Arguments

ArgumentDescription
content itemAny valid content item.

Example

Header('Object headers!');

Image ( )

Displays an image from the Images folder in the templates folder. The images folder found within the templates folder contains all usable images in templates. You can add more images into this folder as needed. 

Syntax

Image(<content item>);

Arguments

ArgumentDescription
content itemany content item that results in the name of a file (including the extension) from the images folder.

Examples

Image('MappingArrowRight.png');
Image(Lookup(‘TaskImages’, @PropertyValue(‘TaskTypeId’)));

The following is a list of all default images provided with the product in the images folder:

ImageDescription
DOC xPress Circle.0.pngCircle.0.png
DOC xPress Circle.25.pngCircle.25.png
DOC xPress Circle.50.pngCircle.50.png
DOC xPress Circle.75.pngCircle.75.png
DOC xPress Circle.100.pngCircle.100.png
DOC xPress CompletionAND.pngCompletionAND.png
DOC xPress CompletionOR.pngCompletionOR.png
DOC xPress FailureAND.pngFailureAND.png
DOC xPress FailureOR.pngFailureOR.png
DOC xPress False.pngFalse.png
DOC xPress ForeignKey.pngForeignKey.png
DOC xPress Inherit.pngInherit.png
DOC xPress MappingArrowLeft.pngMappingArrowLeft.png
DOC xPress MappingArrowLeftRight.pngMappingArrowLeftRight.png
DOC xPress MappingArrowRight.pngMappingArrowRight.png
DOC xPress PrimaryKey.pngPrimaryKey.png
DOC xPress SuccessAND.pngSuccessAND.png
DOC xPress SuccessOR.pngSuccessOR.png
DOC xPress True.pngTrue.png
DOC xPress Unchecked.pngUnchecked.png
DOC xPress Warning.pngWarning.png

Include ( )

Includes the specified Template file in the current template file.

Syntax

Include(<template key>);

Arguments

ArgumentDescription
template keyThe key of the template file, as described in the templates Page( ) function, that you want to include.

Examples

Include('GlobalDataDictionary');

Link ( )

Creates a link to the specified target item.

Syntax

Link(<link target>, <link text>[, <substitution>]);

Arguments

ArgumentDescription
link targetAny valid object selector that returns the object to link to. Note that when generating a table where you wish each row to be a link to the object related to the row, use $CurrentObject as the selector.
link textA content item that equates to the text to use for the link. Note that any attribute selectors within the content item operate on the item being linked to. If the item being linked to is not included in the current documentation, then the link will be emitted as plain text.
substitution

A content item that equates to the text to use if the link target is not found.

Examples

Link($CurrentObject, @PropertyValue('Name'), @PropertyValue('Description'));

List ( )

Lists loops through all of the objects selected by a selector and produces a content item for each item in the list.

Syntax

List(<object selector>, <content item>);

Arguments

ArgumentDescription
Object selector

The object selector which returns items to list.

Content itemThe content item to generate for each item in the list. Note:  Attribute selectors in the content item operate on each object.

Examples

List($Object(Path:'Roles/Administrators/Members/'), @PropertyValue('Name'));

Page ( )

Identifies the template file to the Structure Maps and Template Images.

Syntax

Page(<key>);

Arguments

ArgumentDescription
KeyThe key name given to the page. The key name is used when specifying template keys in structure maps, using the Include( ) statement, or for template images.

Examples

Page('SqlServer');

Span ( )

Writes the content item to the page is in regular text.

Syntax

Span(<content item>);

Arguments

ArgumentsDescription
Content itemThe content item to generate for each item in the list. Note:  Attribute selectors in the content item operate on each object.

Examples

Write out a simple message to the page:

Span(‘This is some plain text.’)

Write out a combination of content items to the page:

Span('Name: ' + @ObjectName);

Table ( )

Creates a formatted table based on the defined header row and body row(s).

Syntax

Table([<object selector>, ] <header row>, <body rows>)

Arguments

ArgumentDescription
Object selectorIf specified, the table generates with one set of <body rows> generated for each object returned by the object selector. The attribute selectors in the body rows operate over each returned object while generating the row.
Header rowA set of comma separated lists of content items that form the header, enclosed in curly braces { }.
Body rowOne or more sets of comma separated content items that form each body row, enclosed in curly braces { }. For a table generated with an object selector, any attribute selectors in the body row operate over each returned object. For a table generated without an object selector, the attribute selectors operate on the currently scoped object. Note:  After each row you can include .Where() – this allows you to specify a predicate that hides the row if it evaluates to false.

Examples

The following example generates a four column table with a row for each child for the object ‘WidgetFields’:

Table($Object(Path:'WidgetFields/'),
{ 'Name', 'Data Type', 'Precision', 'Scale' },
{
@ObjectName,
@PropertyValue('Datatype'),
@PropertyValue('Precision'),
@PropertyValue('Scale')
});

The following example generates a two column table operating on the currently scoped object that contains four rows:

Table(
{ 'Property', 'Value'},
{'Widget Type', @PropertyValue('WidgetType')}
{'Description', @PropertyValue('Description')}
{'Connection Name', @PropertyValue('ConnectionName')}.Where(@PropertyValue('ConnectionName') != '')
{'Connection Name', @PropertyValue('ConnectionValue')}.Where(@PropertyValue('ConnectionValue') != '')
);

Title ( )

Displays and defines the page's title.

Syntax

Title(<content item>);

Examples

Title('Functions');

UntypedPropertyTable

Creates a table containing all of the properties for the current scope and their values, but excluding the type name column for each property.

Syntax

UntypedPropertyTable;

Examples

UntypedPropertyTable;

Control Flow

Control Flow elements divide groups of page level objects into logical sections that may be included, excluded, or repeated based on predicates or object selectors.

For ( ) 

Loops through the object selector and includes the list of page level objects specified for each item.

Syntax

For(<object selector>) 
{
<list of page level objects> 
}

Arguments

ArgumentDescription
<object selector>Any valid object selector including stored object selectors.

Examples

For($Object(Path:'FieldGroupsAll/'))
{
Include('InfaWidgetFieldGroupAttributeCollection');
Include('InfaWidgetFieldGroupFieldCollection');
Include('InfaWidgetFieldGroupDefaults');
}

If ( )

An If expression allows a section of content to be included based on the result of a predicate, with an optional section of content to be included otherwise.

Syntax

If(Predicate) 
{ 
<list of page level objects>
 } 
[ Else { <list of page level objects> } ]

Arguments

ArgumentDescription
PredicateAny valid predicate.
list of page level objectsAny valid list of page level objects enclosed in {}.
ElseFollows an If() statement and the If() statement's list of page level objects. The Else statement defines an alternate set of commands to execute if the If() statement is not run. The Else argument along with it's list of page level objects is optional.

Examples

If(Any(RunSelector('widgets')))
{
Span('I will print if True');
}
Else
{Span('Otherwise I will print');
}

Predicates

Predicates return a Boolean value based on the object being processed and allow control flow elements, object selectors, and table row filters to take action(s) based on their results. 

Note:  Predicates can return the opposite of a value that was returned by placing an exclamation point ( ! ) in front of the predicate:

If (!FlagIsSet('SSIS.CfDiagram'))
{  
Span(‘The flag SSIS.CfDiagram is not set.’);
}

Any ( )

The Any( ) predicate determines whether a given object selector contains any objects.

Syntax

Any(<object selector>);

Arguments

ArgumentDescription
object selectorAny object selector.

Returns

True if the object selector contains at least one object, otherwise it returns false.

Examples

If(Any(RunSelector('PreCommands')))
{
Span(‘The stored selector called PreCommands contained at least one object.’);
}

FlagIsSet ( )

Returns true or false if the flag is checked from the Document Control file for structure maps.

Syntax

FlagIsSet(<content item>)

Arguments

ArgumentDescription
content itemAny valid content item, representing the name of the flag to check.

Returns

True or False.

Examples

If(FlagIsSet('SSIS.CfDiagram'))
{
Span(‘The SSIS.CfDiagram flag was set.’);
}

String Comparison

A string comparison expression effectively compares two content items.

Syntax

<content item> <comparison operator> <content item>

The comparison operators are as follows:

OperatorMeaning
==Equal – the predicate returns true if both content items are the same.
!=Not Equal – the predicate returns true if the content items are different.
->Regular expression – the right content item is treated as a regular expression pattern, and the predicate returns true if the left content item is a match for the pattern. The standard .NET Framework regular expression grammar is used.

Note:  All comparison operators are case-insensitive.

Compound Predicates

Condition comparing two Predicates.

Syntax

(Predicate <operator> Predicate)

Arguments

ArgumentDescription
operator Either && or ||. && means both predicates must be true for the compound predicate to be true, || means either of the predicates may return true for the compound predicate to be true.

Examples

If (Any(RunSelector('PreCommands')) || Any(RunSelector('PostCommands')))
{
Span(‘Either the selector PreCommands or the selector PostCommands contained at least one object.’);
}

Numeric Comparison Predicates

Returns True or False based on the comparison of two numerals.

Syntax

<numeric> <operator>  <numeric>

Arguments

ArgumentDescription
<numeric>Any valid numeric expression.
operatorAny valid comparison operator such as ==, !=, etc..

Returns

True or False.

Examples

Count($Object(Path:'./[@Location=="null"]')) >= 5

Count ( )

Returns the number of objects that a specified selector returns.

Syntax

Count(<object selector>);

Arguments

Argument Description
object selectorAny object selector.

Returns

The number of objects that the specified selector returns.

Examples

If (Count($Object(Path:'Details/')) == 1)
{
Span(‘The sub-object Details contained exactly one child.’);
}

Int ( )

Casts the specified @PropertyValue( ) to an integer, allowing it to be used in numeric comparisons or expressions.

Syntax

Int(@PropertyValue( ));

Arguments

ArgumentsDescription
@PropertyValue( )@PropertyValue(String), selects the Properties value.

Returns

ReturnDescription
intThe property's value is returned as an integer.

Examples

Int(@PropertyValue('Value'));

Operators

Numeric operators produce a numeric result by applying mathematical operators to two numbers. 

Syntax

<numeric> <operator> <numeric>

Arguments

ArgumentDescription
numericAny valid Count(), literal number, (NumericBinaryExpression) or a ternary expression containing numeric.
operatorA standard mathematical operator: +, -, *, /.

Examples

Count($Object(Path:'./[@Location=="null"]')) + 5

Content Items

Content Items retrieve specific values from the carbon tree or templates directory for use within the documentation. 

Note:  Content items may be formed of a series of more than one content item:

Span(‘This is the value of the property test: ‘ + @PropertyValue(‘test’) + ‘ and this is the lookup value using the lookup FunctionTypes: ‘ + Lookup(‘FunctionTypes’, @PropertyValue(‘test’));

Attribute selectors

Attribute selectors allow you to retrieve an object value or property from the currently scoped object, or a relative object. There are five attribute selectors available : @ObjectName, @ObjectPath, @ObjectType, @PropertyValue(<propertyKey>), @PropertyType(<propertyKey>).

Syntax

<AttributeSelector> [ ObjectSelector ]

Arguments

ArgumentDescription
ObjectSelectorThis is specified as .From(<objectSelector>) and allows you to retrieve the specified attribute from a related object.

Returns

SelectorReturns
@ObjectNameThe name of the object.
@ObjectPathThe path of the object within the carbon tree.
@ObjectTypeThe type of the object.
@PropertyValue(<propertyKey>)The value of the property specified by <propertyKey>.
@PropertyType(<propertyKey>)The type of the property specified by <propertyKey>.

Examples

Creates a span with the name of the current object:

Span(@ObjectName);

Creates a span with the value of the property ‘Description’ from the current object:

Span(@PropertyValue(‘Description’));

Creates a span with the value of the property ‘Description’ from a child object named ‘Details’:

Span(@PropertyValue(‘Description’).From($Object(Path:’Details’)));

Lookup ( )

Searches the specified lookup file for the given lookup key, and then attempts to match the given string to one for the mappings keys. If a match is found, it displays the mapping value, otherwise it displays the value of the given string.

Syntax

Lookup(String, <content item>);

Arguments

ArgumentsDescription
String

Matches to the mappings of the lookup file.

content itemAny valid content item.

Examples

Lookup('LocaleIDs', @PropertyValue('Language')); 

NULL Coalescer

A NULL coalescer returns the value of the second operand if the first operand equates to NULL or an empty string.

Syntax

<content item> ?? <content item>

Examples

The below example returns the value of the property ‘First’, or the value of the property ‘Second’ if 'First' is NULL or an empty string:

@PropertyValue(‘First’) ?? @PropertyValue(‘Second’)

Ternary

A ternary expression returns the first content item if the predicate evaluates to true, or the second content item if the predicate evaluates to false.

Syntax

Predicate ? (<content item>) : (<content item>)

Arguments

ArgumentDescription
PredicateAny predicate, used to determine which content item to include.

Examples

Lookup('LocaleIDs', @PropertyValue('Language');

Path Language

The Workbench Path Language is a special path language, similar to XPath, that's used throughout SentryOne Workbench to dynamically select specific objects. Though the syntax described below remains the same, the path language has different purposes depending on the feature that it is currently being used for. The path grammar outlined here is used within the following products and features:

BI xPress

  • User Defined Best Practices: Used to evaluate rules. When the Path Language returns a valid that matches the evaluated path, then the rule is in violation

DOC xPress

  • Custom Templates: Used throughout DOC xPress's document generation templates to control the Structure Maps and Templates
  • Metadata Viewer: Used to navigate the metadata for a DOC xPress Snapshot
  • Data Dictionary: Used to match custom category items to specific metadata object types within a DOC xPress Snapshot

DOC xPress Server

  • Custom Templates: Used throughout DOC xPress Server's document generation templates to control the Structure Maps and Templates

Introduction

Paths are composed of repeating groups of separators and path elements. Additionally, separators at the beginning or end of a path have special meaning. The general form is as follows:

Path 

[<initial separator>] [ (<element> <separator>) .. n] <element> [<trailing separator>]

Separator

/, //, ^

Element

 (., .., *, <object name>) [ conditional ]

Important:  When working with Path Grammar, the initial starting point, or scope, is especially important when building a valid path.

Examples

Using the following example tree, we can see how we can navigate to certain areas using the path's navigation elements:

DOC xPress Carbon tree example

If we are starting at A, then to get to the path would be:

B/C

If we are starting at A, then to get to the path would be:

E/F/G

However, you may want to get the set of all nodes present within the whole tree, in which case the path would be:

//X

Or, you may want to get all nodes that are a descendant of B, in which case the path would be:

B//X 

The importance of the initial and trailing separators can be demonstrated by considering the same tree, and starting at point D.

If we wanted to get to C, we could use one of the following paths:

../C
/B/C

The single slash at the start of the path means ‘start from the root’, which in the case of the above tree, is A. This is also the meaning when starting with the double slash. So, starting from point again, to get all nodes we can use the notation:

//X

Trailing separators allow us to look at get all children. To get all children of node from any point in the tree, we could use:

/B/

Alternatively, to get all descendants of B, we could use:

/B//

Elements

Path elements, in their simplest form, are object names. However, there are also special meaning path elements that allow us to navigate through the tree:

The . (period) explicitly states that a path starts from the current point. For example, you might want to navigate to then – so you could use B/C or ./B/C. The single dot notation is never required, but can help in giving context.

.

The .. (double period) navigates to the parent of a node.

..

The * (asterixis) accepts any node name as a match. For example, in our test tree (as shown in the introduction topic), we could get to the nodes that are descendants of by using the path /B/*/X.

*

Separators

Separators have special meanings and help navigate to an element in the Path's expression.

The / (slash) separates path elements to navigate to the series of immediate children.

/

The // (double slash) navigates to the series of immediate children and all descendants.

//

The ^ navigates to the series of all ancestor objects.

^

Conditionals

Conditionals add an extra element to path syntax. In their simplest form, they allow returning of nodes based on a given property value. However, they can also be used to check for the existence of related nodes.

A conditional is specified within square brackets after a path element. A simple example might be returning all nodes that are a child of that has the property named ‘Test’ equals ‘123’:

/B/*[@Test==”123”]

Simple Conditionals 

Simple conditionals take one of the following forms:

[<matchable> <operator> <value>]
[<matchable>.contains(<value>)]

Matchable is one of the following:

MatchableDescription
@TestThe value of the property with the key ‘Test’.
@Test.value()The value of the property with the key ‘Test’.
@Test.type()The type of the property with the key ‘Test’.
@Test.name()The name of the property with the key ‘Test’.
name()The name of the current object.
type()The type of the current object.

Operator is one of the following:

OperatorDescription
==Returns a match if the matchable is the same as value.
!=Returns a match if the matchable is not the same as value.
->Returns a match if the matchable is matched by the regular expression pattern specified by value.

Note:  The == and != operators are case sensitive. The -> and .contains() operators are case insensitive.

Related Path Conditionals

Related path conditionals take the following form:

[<path>]

Path is a path that can be found from the current object, and can contain the full array of path syntax allowed, including conditionals. For example, referring to the test tree in the introduction, a simple path conditional might be used to find all nodes that have a child node called X:

//*[./X]

Or, we might want to find all nodes that have a child node called X where that X node also has a property with a key ‘Test’ and a value ‘123’:

//*[./X[@Test==”123”]]

Negating Conditionals

We may want to negate a condition to retrieve the opposite. For any conditional in the following form:

[<conditional>]

Its negation would be the following:

[!(<conditional>)]

For example, referring to the test tree in the introduction, we might want to find all nodes that do not have a child node called X. The path for this would be:

//*[!(./X)]

Combining Conditionals

To combine conditionals we can create a new single conditional in the following form:

(<conditional>) <operator> (<conditional>)

The operator can be && to require that both conditionals match, or || to require that at least one of the conditionals match. We can then combine these conditionals again. For example, if we wanted to find any objects that had a property called Test that was equal to ‘1’ or ‘2’ and a property called OtherTest that was equal to ‘3’, we could use the following path:

//*[((@Test==”1”) || (@Test==”2”)) && (@OtherTest==”3”)]