SentryOne DOC xPress Server

DOC xPress Server

DOC xPress Server brings the metadata capabilities of the DOC xPress desktop application to a web application that you host. DOC xPress Server makes it easier to share your documentation, lineage, and data dictionary information to everyone within your organization that requires it. By supporting a web-based user interface, you can provide access to all of your business and technical users, without requiring them to have a desktop installation.

Feature Highlights

  • View DOC xPress-generated documentation online, in your web browser.
  • Share documentation with others in your organization.
  • View lineage and impact analysis information online, so that you can easily assess the impact of changes in your database.
  • View and edit data dictionary information in-line with the generated documentation.
  • Use the Visual Studio add-in to look up information from inside of your development environment.
  • Take snapshots of your metadata from the DOC xPress client application, then compare snapshots online, so that you can determine what has changed over time.
  • Save and view multiple versions of the documentation, both for different audiences and different time periods.
  • Search documentation and lineage for specific objects to see their details.
  • The web-based solution runs on IIS, and can leverage IIS features for scalability and fail-over.

Release Notes

Download a PDF copy of the release notes here.

Setup Instructions

Installation

Workbench Server is the main application that DOC xPress Server is hosted within. 

Note:  Features only become available if you have purchased a license for the product you are trying to use.

1. After ensuring you meet the Hardware and Software Requirements, open the installer.

2. Uncheck the box Send feature usage statistics to Pragmatic Works if you don't want to send feature usage statistics. Read the License terms and conditions and then select I agree to the License terms and conditions. Select Next to continue the installation. DOC xPress Server Installer License terms and conditions

Note:  The Use previous installation settings option helps you upgrade from older versions by attempting to gather as much of the previous installation's settings as possible. For example, the application pool identities may need reconfiguring.

3. Review the itemized list of components that Workbench Server will install, and the total space required on the Select Components page. Select Next to continue the installation.DOC xPress Server Installer Component selection

4. Configure the website where Workbench Server will be accessed. The following configuration options are available:DOC xPress Server Workbench Server Website Configuration

Configuration OptionDescription
Workbench Server URLThe URL that you enter in a browser to access Workbench Server.

Note:  If you want to associate Workbench Server with a different port number than the industry standard port 80 (or 443 for https), include the port number using the following syntax: http[s]://<ServerName>[:<Port>]/
Run application pool asThe user account that the website uses for accessing the database, server files, and resources.

Note:  The account should already have access to the database(s) and server(s) that you want to access and document. The account should have database access that includes the ability to create, update, and delete tables, stored procedures, and other database objects.

The following accounts are selectable:
  • Application Pool Identity - An IIS controlled user account designed to have minimal permissions to only the server where Workbench Server is hosted.
  • Network Service - A built-in Windows user account that has limited network permissions. Generally, the Network Service account only has access to resources on the same computer hosting Workbench Server.
  • User specified below (Recommended) -  A local or domain user account created by the user or a system administrator that must have permissions to local and remote databases and local and remote resource files or folders. Using a specific local or domain user account makes it easier for system administrators to maintain and grant permissions to local and remote databases.

Select Next to continue the installation.

Important:  The user account that Workbench Server Website's Application Pool is authorized to use, dictates the option that's used for BI xPress Server Website and DOC xPress Server Website's Application Pools. If the websites are authorized to run as a specific user, unique users can still be selected for each Application Pool.

If Workbench Server needs access to services, databases, or assets on any other computer than the machine where Workbench Server is installed, then a specific domain user must be used by the Application Pool Identities and the DOC xPress Data Handler Service.

5. Setup the connection information for the database that's used to store the user and administration information. Select Next to continue the installation. DOC xPress Server Installer User and Adminsitration Database

Note:  If you want the User and Administration Database located on a different system than the Workbench Server website and the setting Windows Authentication, then the Workbench Server Application Pool configured in Step 4 must be run using a domain user account.

6. If you selected User specified below for the Workbench Server Application Pool, then you can enter a different User name and password. If you did not select User specified below, select Next to continue the installation.DOC xPress Server Installer BI xPress Server Website Configuration

7. Setup the connection information for the database that's used by BI xPress Server within the Monitoring Console. Select Next to continue the installation. DOC xPress Server Installer BI xPress Database

Note:  The BI xPress Application Pool configured in Step 6, and the Workbench Server Application Pool configured in Step 4 must be running a domain user account if you want the BI xPress Database located on a different system than the Workbench Server website.

8. If User specified below was selected for the Workbench Server Application Pool, then you can enter a different User name and password. If User specified below was not selected, select Next to continue the installation.DOC xPress Server Installer DOC xPress Website Configuration

9. Review the settings for how the DOC xPress Server meta data is distributed. Select Next to continue the installation.DOC xPress Server Installer DOC xPress Settings

Note:  The DOC xPress Application Pool configured in Step 8 must be run using a domain user account if you want the DOC xPress Database located on a different system than the Workbench Server website.

10. Single Database: If you want to store all of the meta data in a single DOC xPress Server database, select Use a single database for DOC xPress Server storage.  Enter the connection information for the database used to store the DOC xPress Server meta data information. Select Next to Continue the installation. 

DOC xPress Server Installer Use a Single Database
DOC xPress Server Installer Single DOC xPress Database

Multiple Databases: If you want to store your meta data in up to four separate databases, select Use up to four separate databases for DOC xPress Server. Enter the connection information for the databases that used to store the DOC xPress Server meta data information. Select Next to continue the installation.

ConfigurationDescription
Command Query StoreThe DOC xPress metabase that DOC xPress Desktop Application users connect to in order to manage and create snapshots and data dictionary categories.
Dictionary Query StoreAn optimized database used to store Data Dictionary content for use within DOC xPress Server.
Generator Query StoreAn optimized database used to store metadate regarding DOC xPress Server generated documentation.
Browser Query StoreAn optimized database used to store the structure of objects for use within DOC xPress Server.
DOC xPress Server Installer Use up to four databases
DOC xPress Server Installer Multiple DOC xPress Databases

Note:  For management or scalability reasons, all database information can point to the same database, shared databases between any number of DOC xPress Server database(s), or even separate databases for each database required by DOC xPress.

11. Configure the DOC xPress Data Handler Service and the service login settings. Select Next to continue the installation.DOC xPress Server DOC xPress Data Handler Service

Important:  The DOC xPress Data Handler Service runs in the background and performs all the DOC xPress document generation and processing. This service runs after installation and when the computer starts up by default. 

If the DOC xPress Data Handler Service is set to run as a specific user, that user must be contained within the Log on as a service local security policy.

If documentation is not being generated, ensure the service is running and that the user account running the service has access to create, update, and delete tables, stored procedures, and other database objects within the DOC xPress Server database(s) that were created in Step 10.

12.   Configure the server paths to the server directories. The following configuration options are available:

Directory ConfigurationDescription
 DOC xPress Templates DirectoryThis directory that contains server templates that are used to lend form and reason to the output in DOC xPress Server.
DOC xPress Output DirectoryThis is the directory that contains all of the documentation that is generated by DOC xPress Server.
CHM Compiler Application PathThis is the path to the CHM Compiler that is installed on the server.

 Select Next to continue the installation.

DOC xPress Server Installer DOC xPress Settings

Important:  DOC xPress Server only supports local folder locations for the DOC xPress Output Directory. Without the HTML Help Compiler application (hhc.exe), generating CHM documentation will fail.

13. Enter the connection information for the database that's used to store the LegiTest Server test suite history and assemblies. Select Install to begin the installation. 

DOC xPress Server Installer LegiTest Server Database

Note:  Selecting Install downloads and installs the necessary software prerequisites. After installing the software prerequisites, Workbench Server begins installing the necessary software. After installation has completed, it may take several minutes while the server self configures before the website becomes operational. 

Allowing IIS Access

After the Workbench Server installation has completed, the administrator must allow users and groups within IIS to access the homepage of Workbench Server. Allow access by completing the following steps:

Note:  Control over users is handled within Workbench Server's administrative area. 

  1. Open IIS, right-click on the Workbench Server site, then select Edit Permissions.DOC xPress Server Internet Information Services Edit Permissions
  2. Navigate to the security tab, then select Edit to open the Permissions for Workbench Server Host windowDOC xPress Server Workbench Server Host Properties
  3. Select Add to open the Select Users or groups window.DOC xPress Server Permissions for Workbench Server Host
  4. Add any individual users and groups that need access to Workbench Server's homepage. Select OK for all of the remaining dialogs to save your changes.DOC xPress Server Select Users or Groups

Hardware Requirements

Determine your hardware requirements based on your environment's deployment model. DOC xPress Server needs access to several databases to function. This creates the following two deployment scenarios:

Single Machine

In the single machine deployment model, the same machine has both Workbench Server and the databases installed. Workbench Server is the web application that contains DOC xPress Server and its associated assemblies while the databases are hosted within a SQL Server Instance.

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

ComponentMinimum RequirementsRecommended Requirements
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 Applicable
  • AMD Opteron
  • AMD Athlon 64
  • Intel Xeon with Intel EM64T support
  • Intel Pentium IV with EM64T support

Important:  Hardware requirements can vary based on workloads and other processes.

Multiple Machines

In the multiple machine deployment model, Workbench Server and the databases are installed on separate machines. Workbench Server is the web application that contains DOC xPress Server and its associated assemblies while the databases are hosted within a SQL Server Instance. It is important to differentiate between the Server machine and the Database machine:

  • Server machine - the machine where Workbench Server is installed. 
  • Database machine - 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 Server:

Server Hardware Requirements:

ComponentMinimum RequirementsRecommended Requirements
Memory4 GB6 GB
Processor Speed1.4 GHz2.0 GHz or faster
Processor TypeNot Applicable
  • AMD Opteron
  • AMD Athlon 64
  • Intel Xeon with Intel EM64T support
  • Intel Pentium IV with EM64T support

Database Hardware Requirements:

ComponentMinimum RequirementsRecommended Requirements
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 Applicable
  • AMD Opteron
  • AMD Athlon 64
  • Intel Xeon with Intel EM64T support
  • Intel Pentium IV with EM64T support

Important:  Hardware requirements can vary based on workloads and other processes.

Software Requirements

Before installing DOC xPress Server, make sure you meet the following system requirements:

  • Internet Information Services (IIS) 7 or later with:
    • Dynamic Compression installed
    • Windows Authentication installed and enabled
  • .NET 4.5.1 or later installed
  • PowerShell 3.0 or higher installed
  • Access to SQL Server 2008 or later instance

Note:  DOC xPress Server needs access to a SQL Server 2008 or later instance to install the following databases:

  • Workbench Server User and Administration database
  • Up to four separate databases for the DOC xPress database (in either Single or Multiple Database mode)

The following operating systems are supported by DOC xPress Server:

64-Bit (x64) Operating Systems:32-Bit (x86) Operating Systems:
  • Windows Server 2008
  • Windows Server 2008
  • Windows Server 2012
  • Windows 7
  • Windows Server 2016
  • Windows 8
  • Windows 7
  • Windows 10
  • Windows 8

  • Windows 10

The following optional prerequisites are required to access some resources using DOC xPress Server:

  • Security
    • Windows User account(s) that can be used to access databases, servers, and documentable objects within the user's organization
    • SQL Server User account(s) to use for accessing DOC xPress Server databases
  • Documentation
    • CHM
      • HTML Help Workshop and Documentation

The following browsers are supported by DOC xPress Server:

  • Mozilla Firefox 29 or later
  • Internet Explorer 8 or later
  • Google Chrome 35 or later

Note:  JavaScript must be enabled within the Web Browser for proper viewing of DOC xPress Server.

The following optional prerequisites are required to access some resources using DOC xPress Visual Studio Extension: 

  • Visual Studio 2012 (Professional, Premium, or Ultimate Edition)
  • Visual Studio 2013 (Professional, Premium, or Ultimate Edition)
  • Visual Studio 2015 (Professional, Premium, or Ultimate Edition)

The following optional prerequisites are required to access some resources using DOC xPress Remote Agent:

64-bit Operating Systems:32-bit Operating Systems:




Providers:

SQL:

64-bit Operating Systems:32-bit Operating Systems:

SSAS:

64-bit Operating Systems:32-bit Operating Systems:SSAS Azure Analysis Services:
  • Microsoft Azure Analysis Services Client Libraries


SSIS:

  • Each version of SQL Server Integration Services (2005 or above) that the user wants to snapshot.
  • SQL Server Data Tools or Business Intelligence Development Studio.

SSRS:

  • Each version of SQL Server Reporting Services (2005 or above) that the user wants to snapshot.
  • 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

Unsupported: Hive, Informatica, and Oracle are no longer supported by DOC xPress Server.

Software Requirements for other Workbench Server products:

The following optional prerequisites are required to access some resources using BI xPress Server:

  • Security
    • Windows User account(s) that can be used to access databases, servers, and documentable objects within the user's organization
    • SQL Server User account(s) to use for accessing BI xPress Server databases
  • Auditing Framework
    • Each version of SQL Server Integration Services that the user wants to apply the auditing framework to.
    • Any Third-Party Products (Connection Managers, Tasks, Components, et cetera) that are used within the SSIS Package(s)

The following optional prerequisites are required to access some resources using LegiTest Server:

  • Scheduling Test Assemblies
    • MSTest Suites: Microsoft Visual Studio 2013 or Agents for Microsoft Visual Studio 2013
    • NUnit Test Suites: NUnit Test Console
    • Any software requirements (SSIS, SSAS, etc.) used by LegiTest needed to execute a deployed test suite

Required Permissions

Important:  Many of the Application Service accounts need db_owner. These accounts issue updates to the database that may alter the schema of the database.

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

Application Pool Identities:

Workbench Server Application Pool:

  • User and Administration database:
    • db_owner
  • LegiTest Server database:
    • db_owner
  • LegiTest Command Line Execution and Task Scheduler:
    • Local Security Policy:
      • Log on as batch job
    • Any permissions (databases, report servers, file system, et cetera) required to successfully run a LegiTest Test Suite deployed to the server

BI xPress Application Pool:

  • BI xPress database:
    • db_owner
  • SSIS Monitoring Console:
    • For importing package layouts from SSIS Catalogs:
      • db_datareader
  • SSRS Monitoring Console:
    • SSRS ReportServer database(s):
      • db_datareader

DOC xPress Server Application Pool:

  • DOC xPress database(s):
    • db_owner

DOC xPress Data Handler Service:

  • DOC xPress database(s):
    • db_owner
  • Local Security Policy:
    • Log on as a service

DOC xPress Remote Agent Required Permissions

  • Local Security Policy:
    • Log on as a service
  • Technology-specific permissions:
    • 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
    • SQL Server Analysis Services 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 the user wants 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
      • User must be a part of the Server Administrator role

Unsupported: Hive, Informatica, and Oracle are no longer supported by DOC xPress Server.

Managing Your Server

Manage your Workbench Server and DOC xPress Server with System Settings. Open System Settings by selecting the gear icon at the top right of the navigation bar. 

Workbench Server System Settings

The system settings are divided into different pages:

Roles

Within Workbench Server's administration page, the Roles page allows you to create, edit, or delete roles that dictate the actions users can take and the securables they can view within Workbench Server. Workbench Server Roles tab

Viewing Role Members

View the users within a selected role by selecting the role category you want to manage.

Workbench Server Role members

Note:  Selecting a role such as Administrators displays a list of all users that are assigned to that role, their display name, date joined, and last login time.  Within the selected role page, you can edit the role assignment for any selected users.

Adding Users to Roles

Add users to a specific role by completing the following steps: 

  1. Open the desired role category.
  2. Select  Add users to (role) to extend the pane and display the user search bar.
  3. Enter a username, then select the search button or scroll through the user list, and select a user.  Workbench Server Add User to a role
  4. Select the checkbox next to the desired user, then select Add users to add the user to the selected role.

Removing Users from Roles

Remove users from a specific role by selecting the checkbox next to each user that you want to remove, then selecting Remove users from (role).Workbench Server Remove user from role

Creating a New Role

Create a new role by completing the following steps:

  1. Open the Roles page, then select Create new role to add a new row within the Roles table.  
  2. Enter a name for the role, then select whether to make this the default role to assign new users. 
  3. Select Update to add the role to the list of roles. 
Workbench Server create new role
Add Role name and select Update

Workbench Server Roles tab new role added
New Role added

Editing or Deleting a Role

Edit a role by completing the following steps:

  1. Select edit for the role you want to edit to open the naming box.
  2. Make the desired changes to the name, then select whether you want to specify the role as the default role. 
  3. Select update to save your changes. 

Delete a role by completing the following steps: 

  1. Select delete for the role you want to delete to open the warning prompt. 
  2. Select delete to confirm the deletion.Workbench Server Delete a role

Note:  Select Cancel to stop the deletion of the role.

Users

The User page displays a list of all current users that have accessed Workbench Server. Administrators can use the User page to manually add domain users to Workbench Server or delete users from Workbench Server.Workbench Server Users tab

Note:  Workbench Server automatically adds users once they open the server URL by default.

To delete a user, select delete next to the desired user. Select OK to confirm the deletion Workbench Server Delete user prompt

Note:  Select cancel to stop the deletion of the user.

Administrators can manually add users to the server using the Add Domain Users button.Workbench Server Add Domain users

From here, administrators can filter and select any domain user they want to include.

Actions

The actions page provides a list of predefined actions for each of Workbench Server's Features that detail what each role can perform. The main actions page lists the actions, the feature it pertains to, and a description of that action. Workbench Server Actions tab

Select an Action Name to open that action's page. On the Action page you can add or remove roles assigned to the action. Workbench Server Action page

Note:  By adding a role to an action, you are granting the role permission to perform the action. Removing a role from an action prevents the role from performing the action.

Adding Roles to Actions

Add roles to a specific action by completing the following steps: 

  1. Select the desired action, then select Add roles to to extend the pane. 
  2. Use the Search bar to search for roles to add to the action. If you do not type anything into the search bar, you can search a list of all roles that have been created on Workbench Server. 
  3. Select the check box next to the desired role, then select Add roles...  next to the search bar.Workbench Server Add role to action

Success: A message displays confirming the role was added and the role appears in the list of roles associated with that action.Workbench Server role added to Action

Deleting Roles from Actions

Select the checkbox for the desired role and then select Remove roles from to remove a role from an action. Workbench Server Remove roles from action

Note:  Selecting Remove roles from displays a confirmation message and the role will no longer be in the list.

Securables

Within Workbench Server's administration page, the securables page gives more granular control over what each role can see within each DOC xPress solution. The Securables page displays as a tree list with all solutions and their solution items present within your server's DOC xPress Metabase. You can choose to change access to each individual solution item, or the entire solution itself.

Important:  Explicit allowed and deny permissions placed within solution items are only applied to DOC xPress Data Dictionary and Snapshot Comparison Features.

Workbench Server Securables tabBy default all roles are allowed on each solution and its solution items. Select All roles allowed to the right of the desired solution or solution item to display all the roles that currently have been granted or explicitly denied access to that particular solution or solution item.Workbench Server Securables Add role

Adding Roles to Solutions or Solution Items

To add specific roles, select add to open the add roles window, where you can select the roles you want to add to the specified solution or solution item.Workbench Server Securables Add roles to Full Environment

Once a role is added it appears in the allowed roles box. The added role now has an allowed/denied switch to easily grant or deny permissions for that role on the particular solution or solution item.

Removing Roles from Solutions or Solution Items

Remove a specific role from a solution or solution item by completing the following steps:

  1. Expand the drop-down menu located on the right of the specific solution or solution item.
  2. From within the list of allowed roles, select the check box next to the role you want to remove and then select remove.Workbench Server Securables Remove role

Workbench Features

Workbench Server Features tab

The features page displays all of the  installed Workbench Server products. Administrators can do the following:

  • Allocate users
  • See the version (whether it's a trial) 
  • Disable or enable beta features

Select a feature to view all of the users that are currently licensed for that particular feature. 

Note:  Workbench Server hands out licenses to users who log in until all user licenses have been consumed by default.

Note:  Features that are in beta are disabled by default. Enable beta features for general use within Workbench Server by selecting Enable next to the desired feature.

Adding Users to a Feature

Administrators can add users to a specific feature by completing the following steps:

  1. Select Add users to next to the desired feature to extend the pane and display the search bar.  
  2. Search for a user with the search bar, or leave the search bar blank to search a list of all users with access to Workbench Server. 
  3. Select the check box next to the desired user name, then select Add users next to the search bar to add the user.Workbench Server adding users to a feature

Important:  When new features are installed to your Workbench Server server, users  are automatically added to the new Feature from the Default Role. If no role is currently set as the Default Role, users from the Administration Role are added automatically instead.

Removing Users from a Feature

Remove users from a specific feature by selecting the check box next to each user that you want to remove and then selecting Remove users from.Workbench Server Removing users from a feature

Feature Settings

The feature settings page allows you to manage the automatic generation and retention count for each solution. Expand and collapse specific features to view settings related to that feature. Workbench Server Feature Settings tab

Auto Document Generation

Auto Document Generation allows you to specify which solutions trigger document generation when DOC xPress Server receives additional snapshots. If enabled, DOC xPress Server kicks off documentation when it receives a snapshot for that solution.

Document Retention Count

Indicates how many versions of documentation to store for the specific solution. When a new documentation request comes in and the retention count limit has been reached, DOC xPress removes the oldest version of the documentation. 

Note:  0 represents no storage limit.

License

The license page displays all licenses associated with Workbench Server. View the license name, issue date, expiration date, maintenance expiration date, number of users, and if it's a trial. Users can also add a license, view details of a license, or update a license from this page.Workbench Server License tab

Important:  Users who have been assigned a role that is a part of the Administration action have access to the Web Administration portion of Workbench Server, where License information is found.

Automatically Activating a License

If you already have an activation key and the server where Workbench Server is installed on has Internet access, then you should be able to automatically activate Workbench Server. Complete the following steps to automatically update your license:

  1. Open the License page, then select Add a new License to begin the process of automatically activating your installation of Workbench Server.Workbench Server Add new license button
  2. Enter your Activation key in the text box and then select activate online to automatically activate your license of Workbench Server Feature.Workbench Server License tab activate online

Manually Activating a License

If you require the assistance of the SentryOne's Support Staff to receive your license, or the machine where you installed Workbench Server does not have Internet access, you may need to manually activate your license of Workbench Server Feature. Complete the following steps to manually activate your license:

  1. Open the License page, then select Add a new License to begin the process of automatically activating your installation of Workbench Server.Workbench Server Add new license button
  2. Select activate manually. Copy the Environment Identifier, Environment Key, along with your Activation Key, and e-mail the information to SentryOne Support.
  3. Once a SentryOne Support Representative has provided you with your license block, paste the license block into the license block text box and then select apply license to manually activate your license for the currently selected Workbench Server feature.Workbench Server License tab activate manually

License Detail

Selecting a license's details button provides you with more information about the license currently activated on the server. Update (automatically), manually update, or deactivate your license on the license details page.Workbench Server License detail page

Deactivating a License

If you plan to migrate Workbench Server from one machine to another and have already activated your license on the old machine, you need to deactivate your license on the old machine. Deactivate your license by completing the following steps:

  1. Open the License page, then select details next to the corresponding feature that you want to deactivate.
  2. Select deactivate at the bottom of the page to begin the deactivation process.Workbench Server deactivate license button
  3. Within the confirmation text box, type YES and then select the remove license to confirm deactivation and remove the license from the machine.Workbench Server remove license prompt

Features

DOC xPress Server works alongside DOC xPress. The solutions, solution items, snapshots, and data dictionary categories that are used in DOC xPress Server are created and maintained by DOC xPress. When a solution is added to the DOC xPress metabase that's used by DOC xPress Server, it's then pushed to DOC xPress Server automatically and becomes available for all users with proper permissions. Solutions and Snapshot updates are also pushed automatically to the server.

Once on the server, any user who has permission to access the solution items, can generate documentation and snapshot comparisons. End users don't need DOC xPress installed on their machine to have access to these features.

Note:  You can manage your DOC xPress Solutions, create Snapshots, and create Data Dictionary categories through DOC xPress Professional Edition.

DOC xPress Server Workflow diagram

Through the DOC xPress Desktop Application, clients create a metabase. This metabase is used by the server as a part of the DOC xPress Server Storage and stores all of the raw metadata for a solution (snapshots, lineage, and data dictionary categories).

Once a snapshot has been taken and stored within the metabase, DOC xPress Server then uses the Data Handler Service to optimize the raw metadata for viewing within DOC xPress Server. 

DOC xPress Server can configure remote agents services that run in the background and periodically scans and generates snapshots that are stored within the DOC xPress metabase.

When you first load the DOC xPress Server, you will see the following screen:DOC xPress Server Welcome page

From here you can use the top bar to navigate through the DOC xPress Server. Selecting the DOC xPress server link at the top left to open the Let's Get Started page. 

At the top right you will also see three icons:

ButtonDescription
DOC xPress Server Search iconThe search icon opens a search page. On pages that can be searched, a search box appears next to the icon.
DOC xPress Server Profile iconGives access to your user account. Selecting this icon displays your user name, selecting the user name opens the Manage Account page.
DOC xPress Server Settings iconDisplays links to System Settings, Solution Security, and Remote Agents. The system settings are for all products on Workbench Server and are only be viewable by users that have been assigned a role that is a part of the Administration action.

Data Dictionary

DOC xPress Server's Data Dictionary lets you annotate the objects within a DOC xPress snapshot, including additional information and comments within your web browser. Users often want to capture additional information as part of their documentation. Information like SLAs, persons responsible for the data, timeliness of the data, and other attributes can be captured using DOC xPress Server's Data Dictionary. By adding annotations to existing objects in the DOC xPress repository, you can capture any additional information they desire.

To access the Data Dictionary page, select Data Dictionary on the top navigation bar. All available solutions display on the Data Dictionary page. The solutions on the page can be sorted by: Date Created, Name, Last Updated, Last Snapshot, and Last Refreshed. They can also be displayed in Ascending or Descending order.

Note:  To manage your Data Dictionary categories for editing within DOC xPress Server, use DOC xPress Professional Edition's Data Dictionary plug-in.

DOC xPress Server Data Dictionary Available Solutions

To access a Data Dictionary for a given solution, select the solution you want to view to open the solutions page. The top of the page displays details of the solution, and the bottom pane displays the solution items. DOC xPress Server Solution Details

Select an item to view a description. If an item has a Data Dictionary entry or a pending change you will see an icon next to it. You can edit or add a description to the item. Once the description is entered you can either save the entry now, or you can add multiple descriptions and select the save all icon.DOC xPress Server Solution Details Add Data Dictionary Entry

Icons

IconDescription
DOC xPress Server Data Dictionary IconDenotes the item has Data Dictionary entries.
DOC xPress Server Pending changes iconDenotes the item has a pending change.
DOC xPress Server Item not Saved iconDenotes the item was not saved successfully.
DOC xPress Server Save all changes buttonSaves all pending changes.
DOC xPress Server Cancel all changes buttonCancels all pending changes.
DOC xPress Server Delete pending changes iconDeletes pending change for this item only.

Documentation

The documentation page displays available Solutions and Documents. The top window displays all available solutions on the server. The available solutions can be sorted by Date Created, Name, Last Refreshed, Last Snapshot, and Last Update. The solutions can then be sorted in Ascending or Descending order.

Warning:  

Documentation can be customized by editing the DefaultTemplates, however these are advanced operations and may result in unexpected documentation outputs for all users moving forward. 

It's recommended to always save a copy of the default templates before proceeding in case the changes negatively impact your documentation. Changes to the DefaultTemplates can only be applied to newly generated documentation. Previously generated documentation that used the old templates will not be updated to reflect the newly edited templates.

The bottom window lists the recent documents created. These documents can be sorted by Document Title, Date Created, and Solution Name. On each document available you can see a preview of the items that are available. The document lists the Solution it belongs to, the date and time it was created, and the available formats. DOC xPress Server Documentation Available Solutions

Generating Documentation

Generate documentation in DOC xPress Server by completing the following steps:

1. Open the Documentation page and select the solution that you want to generate documentation to open the documentation form.DOC xPress Server Generate New Document page

Note:  The documentation form lets you generate documentation for a selected solution, and see documentation that has already been generated for the solution.

2. Enter the Document Title, and select from CHM, HTML Frameset, RTF, or Word documentation. Once you set the options you want, select Generate Document to begin generation.DOC xPress Server Generate New Documentation Page Pending Documents

Note:  Documentation progress displays in the Pending Documents pane where you can monitor its status and progress. The status area updates continuously, showing which current step it is on, and the progress bar updates accordingly. Once the document is finished it displays in the Generated Documents pane.DOC xPress Server Generate New Documentation page Generated Documents

Viewing Documentation

All the documentation created within DOC xPress server is available for viewing immediately from the server. Access the documentation for a solution from two areas: the Documentation page or the page for the specific solution. Once you find the documentation you want to view, select it to open the Document Details page.DOC xPress Server Document Details page

The Document Details page displays the Document Title, Solution Name, and the date it was created. When you generate documentation, it becomes available in the selected format for both Developers and Business Analysts. Each available format displays under each role type. Selecting on either RTF or Word will initiate a download of the file to your system. Once downloaded, you can open the file on your system for viewing. Select HTML Frameset to open the documentation in the current window.

Deleting documentation from DOC xPress Server using the Delete button only removes the documentation from the DOC xPress repository and not from the DOC xPress Server file system. To fully delete a DOC xPress document from both the repository and the file system, complete the following steps:

1. Open the Document Details page for the documentation you want to delete.

Note:  The URL for the documentation should use the following pattern:

  • http://{ServerName}/DOCxPress/Documentation/Detail/{GUID1}/{GUID2}

2. Select Delete at the top of the Document Details page for the documentation you want to delete.

3. Open the DOC xPress Server Output folder located on the DOC xPress Server. By default, the DOC xPress Server Output folder can be found on the DOC xPress Server's file system in the following location:

  • C:\DOC xPress Server Output\

4. Within the DOC xPress Server Output folder, find and delete the folder that's name matches {GUID1} within the URL.

An example of the HTML Frameset documentation:DOC xPress Server HTML Frameset documentation

In-Line Data Dictionary

All the documentation created within DOC xPress server includes the details for your Data Dictionary entries. The HTML Frameset documentation grants users the ability to update your Data Dictionary entries directly from within the documentation through a web browser.

Note:  To manage your Data Dictionary categories for editing within DOC xPress Server, use DOC xPress Professional Edition's Data Dictionary plug-in.

On the Document Details page, select an existing document that used HTML Frameset format, then select the HTML Frameset as the documentation you want to display. Select HTML Frameset to open the documentation in the current window.DOC xPress Server Document Details HTML Frameset

Any page within the HTML Frameset Documentation that contains at least one Data Dictionary category includes an in-line Data Dictionary form that allows you to update the entry without opening the Data Dictionary feature page.DOC xPress Server Data Dictionary Entries

Lineage Analysis

Lineage Analysis allows you to answer the following questions through your browser:

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

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

Feature Highlights

  • Diagrammatic and interactive form saves users many hours
  • Speeds up development by giving users the ability 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 easily identify areas where error may be introduced

To access this information, select Lineage Analysis on the top navigation bar. Lineage Analysis displays all available solutions within the DOC xPress repository that contain Lineage. These 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.DOC xPress Server Lineage Analysis Available Solutions

Select a solution to open the Lineage page for that solution. By default, you are directed to Lineage Analysis' Visual View. Select the Text View button located on the Lineage Analysis header to change to the Text View.

Visual View

Lineage Analysis' Diagram Mode lets you visually navigate the dependencies found within a specific solution. Diagram Mode is divided up into three panels: Diagram Toolbar, Solution Explorer, and Lineage Diagram.

Diagram Toolbar

The diagram toolbar allows you to navigate around and adjust the behavior of Lineage Analysis.

ButtonDescription
DOC xPress Server Lineage Analysis Back to Solution buttonBack to Solution Selection: Go back to the list of available solutions for use within Lineage Analysis.
DOC xPress Server Lineage Analysis Text View buttonText View: View the currently selected solution within Lineage Analysis' Text View.
DOC xPress Server Lineage Analysis Detail Level buttonDetail Level: Adjust the granularity of the objects that are included within the current session of Lineage Analysis. The following options are available:
  • High Detail: See down to the column, measure, and attribute level of lineage
  • Medium Detail: See down to the table, component, SSRS item, KPI, and measure group level of lineage
  • Low Detail: Only see the database, package, and report level of lineage
DOC xPress Server Lineage Analysis Relationship Filter buttonRelationship Filter: Adjust the types of dependencies to include within the current session of Lineage Analysis. The following options are available:
  • All: All relationship dependencies are included within the current session of Lineage Analysis
  • Data Lineage: Only relationship links that involves the impact or dependency of another object's data are visible
  • Key + Object: Only relationship links that involve the use of primary or foreign keys or object dependencies are visible
DOC xPress Server Lineage Analysis Dependency Directions buttonDependency Directions: Adjust the direction types of the dependencies to include within the current session of Lineage Analysis. 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
DOC xPress Server Lineage Analysis Diagram Layout buttonDiagram Layout: Control the way objects are organized within the lineage diagram. The following options are available:
  • Tree: Organizes the diagram in a hierarchical way surrounding the focused object
  • Force-Directed: Organizes the diagram in a nondeterministic manner surrounding the focused object
  • Layered: Organizes the diagram with an emphasis on the flow of the diagram while minimizing the crossing between each layer and node surrounding the focused object
DOC xPress Server Lineage Analysis Track Selection buttonTrack Selection: Disable the feature that causes the diagram to re-draw every time a new selection is made within the Solution Explorer.
DOC xPress Server Lineage Analysis Dependency Level buttonDependency Level: Increase or decrease the number of levels of separation from the currently focused object to be displayed within the Lineage Diagram.

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

Solution Explorer

The solution explorer contains a hierarchically organized tree of all objects found within the selected detail level that contain lineage. If track selection is enabled, selecting an object within the solution explorer re-draws the lineage diagram focused on the currently selected object.DOC xPress Server Solution Explorer

Expand and collapse an object, displaying the object's children, by using the arrow to the left. If an object does not have an arrow, or the arrow disappears after it's selected, then that object does not have any child objects that contain lineage or the current detail level prevents it from expanding further. 

Lineage Diagram

The lineage diagram takes up a majority of the window within Lineage Analysis' visual view. It applies all of the settings selected within the diagram toolbar to the currently focused object within the solution explorer to create a visual representation of the object's lineage.DOC xPress Server Lineage Diagram

The use of icons and color within the diagram help you quickly identify the object and technology types associated with each node. See the following table for an abbreviated list of the colors and icons used for the main technology types:

IconDescription
DOC xPress Server Lineage Diagram SQL Server ObjectSQL Server Object
DOC xPress Server Lineage Diagram SSIS ObjectSSIS Object
DOC xPress Server Lineage Diagram SSAS ObjectSSAS Object
DOC xPress Server Lineage Diagram SSRS ObjectSSRS Object
DOC xPress Server Lineage Diagram Other ObjectOther Object

Navigate the Lineage diagram by doing any of the following:

Navigation methodDescription
Move NodeSelect a node and then drag the mouse to move a single node around the diagram without affecting the other nodes.
Pan DiagramHolding down the Control key and selecting the lineage diagram to pan the lineage diagram to display more of the diagram if it does not all fit within the screen.
Navigation buttonDescription
DOC xPress Server Lineage Diagram Reset Zoom buttonReset Zoom: Select reset zoom to reset the zoom of the lineage diagram to its default value.
DOC xPress Server Lineage Diagram Zoom In buttonZoom In: Select zoom in to decrease the size of the objects within the lineage diagram.
DOC xPress Server Lineage Diagram Zoom Out buttonZoom Out: Select zoom out to increase the size of the objects within the lineage diagram.

The arrows connecting nodes together also allow you to identify the directional relationship between the two objects. If only one side contains an arrow, then the node with the arrow depends on other node. If both sides contain an arrow, then both nodes depend on each other.

If documentation has already been generated, some objects within the lineage diagram may be associated with a documentation page. Right-clicking on a node launches a context menu containing a list of the latest documentation outputs containing the selected object. Select a documentation output to launch a separate window that opens the object within the selected documentation output.DOC xPress Server Lineage Diagram Jump to Documentation

Text View

Use the Lineage Analysis Diagram Mode to visually navigate the dependencies found within a specific solution. Diagram Mode is divided up into four panels: Solution Details, Lineage Options, Solution Explorer, and Lineage Analysis Explorer.

Solution Details

The solution details panel provides you with information about your solution.DOC xPress Server Solution Details

Lineage Options

Navigate around and adjust the behavior of Lineage Analysis with the following options:

Navigation buttonDescription
DOC xPress Server Lineage Analysis Visual View buttonVisual View: View the currently selected solution within Lineage Analysis' Visual View.
DOC xPress Server Lineage Analysis Jump to Documentation buttonJump to documentation: If documentation has already been generated, some objects within the solution and lineage analysis explorer may be associated with a documentation page. Select an object in the solution or lineage analysis explorer, and select on the desired jump to documentation drop down to display a list of the latest documentation outputs that contain the selected object. Select a documentation output to launch a separate window that navigates you to the object within the selected documentation output.
DOC xPress Server Lineage Analysis Detail Level buttonDetail Level: Adjust the granularity of the objects that will be included within the current session of Lineage Analysis. The following options are available:
  • High Detail: See down to the column, measure, and attribute level of lineage
  • Medium Detail: See down to the table, component, SSRS item, KPI, and measure group level of lineage
  • Low Detail: See the database, package, and report level of lineage
DOC xPress Server Lineage Analysis Relationship Filter buttonRelationship Filter: Adjust the types of dependencies to include within the current session of Lineage Analysis. The following options are available:
  • All: All relationship dependencies are included within the current session of Lineage Analysis
  • Data Lineage: Only relationship links that involves the impact or dependency of another object's data are visible
  • Key + Object: Only relationship links that involve the use of primary or foreign keys or object dependencies are visible

Solution Explorer

The solution explorer contains a hierarchically organized tree of all objects containing lineage.DOC xPress Server Solution Explorer

Use the arrow to the left to expand and collapse an object and display the object's children. If an object does not have an arrow, or the arrow disappears after it's selected, then that object does not have any child objects that contain lineage or the current detail level prevents it from expanding further.

Lineage Analysis Explorer

The lineage analysis explorer contains a hierarchically organized tree of the object selected within the solution explorer, the object's dependencies, and the following columns:

ColumnDescription
ObjectThe name of the object.
TypeThe technology and object type.
EndpointThe complete path to the object.

DOC xPress Server Lineage Analysis Explorer

Expand an object to reveal two nodes:

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.

Remote Agent

The DOC xPress Remote Agent is a service that runs in the background and periodically scans and generates snapshots that update selected solutions or solution items. Install and configure remote agents and be confident that the solutions you view within DOC xPress Server are up-to-date.

Required Permissions

The following is a list of providers and the requirements to use them within DOC xPress Server:

SQL Server Permissions

  • db_owner for the DOC xPress database
  • 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 the user wants to snapshot

SQL Server 2008 R2 (or higher) Reporting Services Permissions

  • Native Report Server
    • 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

  • User must be a part of the Server Administrator role

Unsupported: Hive, Informatica, and Oracle are no longer supported by DOC xPress Server.

Setup Instructions

Install the DOC xPress Remote agent to begin iterative scanning of solution items. It's recommended that the machine running the remote agent has network access and permisssion to access all of the solution items that you want to scan. 

Note:  The user set up to run the remote agent also needs permission to access the solution items.

Install the DOC xPress remote agent by completing the following steps:

1. Launch the DOC xPress Remote Agent installer.

Note:  The DOC xPress Remote Agent installer can be found at the following location on the machine that DOC xPress Server was installed on by default:

  • C:\Program Files (x86)\Pragmatic Works\Workbench Server\DOC xPress Data Services\DOC xPress Remote Agent.exe

2. Read the License terms and conditions and select I agree to the License terms and conditions. Select Next to continue the installation.DOC xPress Server Remote Agent Installer License terms

3. Enter the username and password configuration for the service. Select Next to continue the installation. DOC xPress Server Remote Agent Installer Remote Agent Service

Note:  The user specified to run the DOC xPress Remote Agent must have the appropriate permissions to access all the solution items that you want the remote agent to manage.

The user specified to run the DOC xPress Remote Agent Service must be contained within the Log on as a service local security policy.

4. Enter the Workbench Server Host URL for the remote agent. Select Install to begin the installation. DOC xPress Server Remote Agent Installer Server Location

Note:  The DOC xPress Remote Agent may need to download and install necessary software prerequisites. After installing the software prerequisites, the DOC xPress Remote Agent installs the necessary software.

Once installation has completed, DOC xPress Remote Agent launches the Remote Agent Licensing window.

5. If you already have an activation key and have access to the Internet, select I have an activation key. If you require the assistance of the Support Staff to receive your license, select I want to activate manually.DOC xPress Server Remote Agent Installer Licensing

Note:  The DOC xPress Remote Agent License installer can be launched again once the trial has expired. By default, the DOC xPress License installer can be found at the following location:

  • C:\Program Files (x86)\Pragmatic Works\DOC xPress Remote Agent\DOC xPress Remote Agent\LicenseInstaller.exe

Success: You are now ready to begin configuring the remote agent to scan solution items.DOC xPress Server Remote Agent Installer Finish

Configuration

Once a Remote Agent has been installed, it's ready to be configured through DOC xPress Server. Configure your remote agent by completing the following steps:

1. Open the DOC xPress Server home page, select the Settings icon, and then select Remote Agent from the drop down list to open the Remote Agent Configuration window.

2. Select a remote agent from the drop-down list.

Note:  A newly installed remote agent has the following name by default:

  • %MachineName% - Untitled Agent
  • %MachineName% is the name of the machine where the remote agent was installed.

3. Complete the Remote agent configuration by selecting options for the Remote agent configurations, scan item, and schedule.

Remote Agent Configurations

Once a remote agent has been selected, the agent details populate with scan configurations. Configure the following options:

ConfigurationDescription
Agent NameThe name of the remote agent. This property can be edited to something more meaningful than Untitled Agent.
Machine NameThe machine that the remote agent is installed on.
Registered DateThe date that the Remote agent was installed and registered to the DOC xPress Server.
Last ScanThe date that this remote agent was last scanned.
Next ScanThe date that this remote agent is next scheduled to run.

Scan Items

Scan items are a detailed list of solutions saved within DOC xPress Server. Remote Agents can scan entire solutions by checking the solution's checkbox, or individual solution items can be added by expanding the solution and checking individual items.

Schedule

Set up a schedule for the remote agent to routinely scan and update the configured items for changes. Configure the following options:

ConfigurationDescription
Schedule Start DateThe date you want the scan schedule to begin.
Scan EveryThe interval for the remote agent to scan. This interval can be in minutes, hours, days, and weeks.
Scanning EnabledSpecifies whether the current remote agent is enabled for scheduled scans.
Scan NowImmediately begin the process of scanning the currently configured items.

Search

Select the search icon to open the Search Criteria page. Search Documentation or Lineage from this page. Select the solution you want to search and then type in the term to search for.DOC xPress Server Search Criteria

Once you choose your options for searching, select search to display the status bar.DOC xPress Server Search Criteria Pending Results

After the search has completed, view your results in the Results pane.DOC xPress Server Search Criteria Results

Select the blue term under the Page column to open the HTML Frameset document where the term was found. The icons on the right side open different destinations:

ButtonDescription
DOC xPress Server Open Solution Details buttonOpens the Solutions Details page.
DOC xPress Server Open HTML Frameset documentation buttonOpens the HTML Frameset documentation for the environment.
DOC xPress Server Open term HTML Frameset buttonOpens the page the term is located on in the HTML Frameset documentation.

Snapshot Comparison

Use DOC xPress Server's Snapshot Comparison to determine the differences in your SQL Server environments over time through your web browser. Comparing solution items at different points in time saves significant time for developers and DBAs who are attempting to track down the source of either consistency or performance problems. Configure Snapshot Comparison by completing the following steps:

1. Select the Snapshot Comparison link to open the Snapshot Comparison page. DOC xPress Server Snapshot Comparison Setup

Note:  The Snapshot Comparison setup page opens by default.

2. Set up the left and right side of the comparison by selecting the left and right solutions. 

Note:  The drop-down list contains all solutions available on the server.

3. Select a left and right solution item. You can select from the following options: SSIS Solution, SSAS Tabular, SSAS MultiDimensional, SQL Server, or SSRS Web Service.

4. Select the version you want to compare, then configure your options. Select Compare to display the status pane.DOC xPress Server Snapshot Comparison Pending Results

Note:  The drop-down list contains all available versions to compare. The root of each snapshot displays in the Root panes. Right above the Compare and Reset buttons there is a checkbox for Include Equal Objects which is not selected by default. Keeping it deselected reduces the amount of data that's pulled for comparison.

5. View the Comparison Results. The top right of the Comparison Results pane displays a blue filter bar. If you did not include equal objects, then the Equal filter will not be usable.DOC xPress Server Snapshot Comparison Results

Results Legend

IconDescription
DOC xPress Server Left Side Only items iconLeft side only items.
DOC xPress Server Right side only items iconRight side only items.
DOC xPress Server Equal Items iconEqual items.
DOC xPress Server Not Equal items iconNot equal items.

Visual Studio Extension

The Visual Studio Extension for DOC xPress server displays as DOC xPress Metadata Query inside of Visual Studio. This extension allows for quick searching of your DOC xPress solution items, and then provides a link to view the information on the DOC xPress server page in your browser. Complete the following to install and use the Visual Studio extension:

1. Log into DOC xPress Server. Select Read More to open the DOC xPress Server about page, then select Get the Visual Studio Extension to start the download.

DOC xPress Server select Read More
DOC xPress Server Get the Visual Studio Extension

2. Extract the file and launch the VSIX installer to begin the installation. Once the installation completes, open Visual Studio and select Pragmatic Works >  DOC xPress > DOC xPress Metadata Query to open the welcome screen.DOC xPress Server DOC xPress Metadata Query

3. Enter the Host URL for your DOC xPress server. Enter your URL, then select Connect to open the search window.DOC xPress Server DOC xPress Metadata Query Settings

4. Across the top of this window you will see a search bar, a filter button, and the settings button. Select the settings icon to change the URL to the Host. Search for any item by entering the items in the search bar to display the results list.DOC xPress Server DOC xPress Metadata Query Search

5. The filter button allows additional control over your search. Select the filter button to display a drop-down of additional filters that can be applied to your searches. You may also type your own filter criteria into the filter bar.DOC xPress Metadata Query Filter results

6. When you find the item you want to view in the results, select the item, then select View to open the item on the DOC xPress server in your browser.

DOC xPress Metadata Query select Result
DOC xPress Metadata Query View

You will see all available information for that item, such as lineage and data dictionaries.DOC xPress Server Lineage Objects for selection

Using DOC xPress Server

Custom User Accessible URL

By default, Workbench Server's setup instructions require the machine name or the fully-qualified machine name to be used as the user accessible URL that will be used to access Workbench Server through the web browser. 

Note:  Additional configuration is required after installation if you want to use a custom user accessible URL.

Warning:  

The following configuration steps are designed for basic custom user accessible URLs within an intranet and should only be attempted by domain and web administrators. SentryOne is not responsible for any issues that may occur due to modifications to your organization's DNS.

Configure a custom user accessible URL by completing the following steps:

1. Follow the Setup Instructions for Workbench Server. Ensure the user accessible URL and host name are set to the default value as set within the installer. Everything else within the setup instruction can be customized for your environment.Workbench Server Website Configuration

2. Once Workbench Server has been installed, launch Internet Information Services (IIS) Manager on the host server. 

3. Open the Connections panel, expand the Sites node, then select the Workbench Server site.Workbench Server Internet Information Services select Sites

Note:  Depending on the settings the user configured during installation, the site's name may be different then what is shown below.

4. In the Actions panel, select the Bindings... action to open the Site Bindings dialog box. Select Add... to open the Add Site Binding dialog box. Type the host header that you want to use to connect within the Workbench Server, then select OK to continue.Workbench Server Add Site Binding

5. Once all the site bindings have been configured, select Restart within the Manage Website portion of the Actions panel to restart the Workbench Server site.

6. Connect to the intranet DNS Server once Internet Information Services (IIS) Manager has been configured. 

7. Launch Server Manager on the DNS Server. Use the left pane console tree to expand the DNS Server name in the Server Manager snap-in. Double-click on Forward Lookup Zones.Workbench Server New Alias (CNAME)

8. Select the DNS zone with the host server that Workbench Server is installed on from the displayed zones list. Right-click the DNS zone and select New Alias (CNAME)... to open the New Resource Record dialog box.

9. Use the alias name configured previously and use the fully qualified machine name that Workbench Server was installed on as the target host, then select OK.Workbench Server New Resource Record

Success: Workbench Server should now be configured to use a custom user accessible URL.Workbench Server Custom URL

Flushing the DNS Resolver Cache

In some rare cases, you may be unable to connect. In this instance, you need to flush your DNS Resolver Cache. To flush the DNS Resolver Cache, complete the following steps:

  1. Launch Command Prompt .
  2. Enter ipconfig /flushdns within the Command Prompt window and press Enter.Workbench Server Flush DNS Resolver Cache commmand prompt            

Customizing Documentation

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 introduction before continuing. After completing the introduction, the document control, structure map, and templates articles 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 as follows :

  • 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 want 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.

Introduction

Many users of DOC xPress have expressed an interest in customizing the templates used within DOC xPress to generate documentation. The following is a walkthrough 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 contains 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 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 must 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 the Structure Maps section.

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 the Templates section.

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 wants to retrieve. In the case of line 9, the template creator wants 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.

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

Important:  Note 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, and 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

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 Server, 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>

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
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.

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.

Attributes

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 gelector 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.
ObjectWhen 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.

For more information on the Workbench Path Language syntax used within a structure map selector, see the Path Language section.

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.

Templates

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.

For more information on the SentryOne Workbench Path Language Syntax within Object Selectors, see the Path Language section.

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 want 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
operatorEither && 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');

Multi-domain Considerations

Warning:  

SentryOne does not provide support, nor do we suggest these scenarios.

Almost all of the modifications require altering operating system, Internet Information Services, and domain settings. Proceed with caution and always make a backup before modifying anything.

The methods described below are for advanced IT administrators who are comfortable with and have been allowed to alter any required settings and/or security protocols. These helpful hints are only for illustrative purposes and each environment will have its own unique requirements and hurdles.

Workbench Server is a robust software suite that can span multiple assets within an organization, even those that lie on different Microsoft Windows Domains.  Below are some helpful hints and recommendations for implementing a multi-domain installation.

Workbench Server / SQL Database in Different Domains

Hosting Workbench Server on a computer that's in a different Microsoft Windows domain than the databases needed to store information can be accomplished by using Windows Authentication or SQL Authentication.  Accessing machines across domains carries additional security risks that need to be taken into consideration before implementing this scenario.

Complete the following steps to use Windows Authentication to access cross-domain databases:

1. Ensure that there's a domain trust between the two domains.  

Additional Information: See this  Microsoft MSDN for more information about the scenario listed above.

2. Open and secure any necessary ports for communication between Workbench Server and any SQL Server instance.  Port 1433 is the most common port assigned to SQL Server. 3. While installing Workbench Server:

  • The domain user used in the next two steps must belong to the domain that has trust.  The relationship defined within the Domain Controllers Domain Trusts area will dictate which domain the user must be defined within.
  • Ensure that the user installing Workbench Server has access to the other domain's database servers so that the installation SQL scripts can execute and create databases, tables, etc.
  • Specify a user for the various application pools which has access to the other domain's database servers.  This domain user will be used to run the website and will need to create, update, and delete database objects in the same manner as a single-domain installation.

Note:  If the domain user installing Workbench doesn't have the appropriate rights on the other domain, installation may fail.

Complete the following steps to use SQL Authentication to access cross-domain databases:

  1. Open and secure any necessary ports for communication between Workbench Server and any SQL Server instance.  Port 1433 is the most common port assigned to SQL Server.
  2. While installing Workbench Server, specify the SQL Server instance and database as usual although a static IP address will most likely be used instead of a friendly name.
  3. Be sure to include the user name and password as usual.

User / Workbench Server in Different Domains

Hosting Workbench Server on a computer that's in a different domain than the users that will be accessing it presents some challenges in making sure that both domains have a trust relationship. 

Additional Information: See this Microsoft MSDN article for information about Domain Trust and how to implement it. 

Once a trust has been established between domains, the domain users that should be allowed access must be granted permission to access Workbench Server.  This can be done in the Internet Information Services Manager.

Data Dictionary Entries Not Appearing

DOC xPress Server only shows categories and entries stored within the Dictionary Query Store. This process occurs immediately after DOC xPress has finished scanning a solution for dependencies. 

The easiest way to push changes made to a category or entry is to use DOC xPress' Snapshot Management tool. Trigger a dependency scan by selecting the rescan button. This dependency scan does not take a new snapshot. Instead, it rebuilds the lineage and notifies the server to refresh the solution's metadata. It could take several minutes for the changes to appear within DOC xPress Server.

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 exceptionally 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”)]

Managing User Account Information

To access the Manage Account page, select the profile icon in the top right of the navigation bar, then select your user name to open your account page. The top lists your Role memberships and all roles assigned to you. On the bottom of the page you can update your profile. You may change your display name as well as your biography. After making any changes, select save to save your changes.DOC xPress Server Manage Account page

AlwaysOn Availability Group Considerations

Server Installation

Before beginning the installation process of Workbench Server, the users that will be set to run each of the application pools must have permission to connect to the availability group through the availability group listener.

Once the user(s) that will be running the application pools has been granted permission to connect to the availability group through the availability group listener, installation of Workbench Server can begin.

Installation of Workbench Server follows the default setup instructions with several noticeable differences:

  1. Ensure that the Workbench Server application pool is set to run as the user that was originally configured to have permission to connect to the availability group through the availability group listener.
  2. Ensure that the User and Administration database is configured so that its server setting is set to point to the availability group listener.
  3. Ensure that the BI xPress Server application pool is set to run as the user that was originally configured to have permission to connect to the availability group through the availability group listener.
  4. Ensure that the BI xPress database is configured so that its server setting is set to point to the availability group listener.
  5. Ensure that the DOC xPress Server application pool is set to run as the user that was originally configured to have permission to connect to the availability group through the availability group listener.
  6. Ensure that the DOC xPress database(s) are configured so that their server settings are set to point to the availability group listener.
  7. Ensure that the DOC xPress Data Handler Service is set to run as the user that was originally configured to have permission to connect to the availability group through the availability group listener.
  8. Ensure that the LegiTest database is configured so that its server setting is set to point to the availability group listener.

Once Workbench Server installation has been completed, creation of the BI xPress, DOC xPress, LegiTest, and Workbench Server databases occurs automatically on the primary availability replica and you can continue  adding the databases to the availability group as availability databases.

Adding the databases to the Availability Group

After creating your metabase, you can add it as an availability database to the availability group. 

Note:  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

Note:  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.

Trial Limitations

The DOC xPress Server trial offers users an extensive look into all of DOC xPress Server's features. Below is a list of limitations placed on the DOC xPress Server trial. Any feature not listed contains no limitations. 

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

Provider Capabilities

DOC xPress Server Provider Capabilities

Supported Structure Maps

You can get a list of supported structure maps in this PDF.

Trouble 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 and 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, and 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.