Please enable JS

Harmony User Guide

Installing Harmony

Prerequisites

A machine with the following is required to install Harmony:

  • Windows 10 - Home or Professional
  • 4GB RAM
  • 50Mb free disk space
  • ProjectWise Desktop Explorer 10.0.3.3XX or later (if using Harmony with Bentley ProjectWise)

Harmony was designed and tested on a 64-bit Operating System.

Installation

Double click the installer to start the install for Harmony.
The install is approximately 10Mb in size and will take a few minutes. If you have ProjectWise Explorer installed, a plug-in for it will automatically be installed. In order to integrate with ProjectWise, Harmony must be installed after ProjectWise.

Organization code

As part of the contract signed between you and Pencil 9 for the use of Harmony, you will have been sent an Organization code. Ensure this is entered correctly when you launch Harmony for the first time.

Harmony can be used in "Guest" mode. This mode is only utilized by external parties who are collaborating within BIM 360. Using Guest mode disables synchronization with an Organization's standards and the ability to create standard definitions.

Harmony Organization code screen

Creating installation packages

If your organization needs to generate an install package, ensure that Harmony is installed on a machine and the correct Organization code has been entered. Next navigate to C:\ProgramData\Pencil 9\Harmony and locate Organization.XML . Append this file as part of the install package to be placed in the same location. Harmony will read the Organization code and not require prompting by the application.

Quick Start

Let’s start by creating your first example package and automating its delivery!
The steps below guide you in creating your first package, creating an entry into the master standards catalogue and then using Harmony to automate its delivery.

  1. Create a new folder within your My Documents folder. Name the folder Harmony source files. Add some files to this folder.
  2. Create an empty folder called Harmony on your C Drive; C:\Harmony\
  3. Launch Harmony and navigate to the Admin screen by clicking the third icon on the left hand side menu. Input your account credentials, which would have been sent to you.
    Note: For users who are in trial mode, the following credentials can be used:
    User name: harmonyadmin
    Password: Harmony1234
  4. Click New Standard. This creates a new line in the master standards catalogue.
  5. Set the fields as follows:
Infrastructure Network
Source Folder in step 1. eg C:\Users\XXXXX\Documents\Harmony source files
Display Name Defaults to folder in step 1, can be changed if required.
Version Optional: 1.0
Status WIP
Vendor Optional: Any text is acceptable
Application Optional: Any text is acceptable
Target C:\Harmony\
Description Optional: My first Harmony package!
  1. Click Commit to master to ensure the content is saved to the database.
  2. Test the functionality by selecting the row you just created and clicking the Test standard button.

Congratulations, you have just automated the delivery of your first item!
The content from Step 1 should now have synchronized to the location in Step 2.

Now, imagine instead of Step 1 being a practice location on your machine, this can be a file server location on your network, a cloud storage solution, Autodesk® BIM 360® or Bentley ProjectWise. This is referred to as a “Master Location”. Step 2 represents a “Target Location”.
Harmony is great at automating the delivery of content from a Master Location to a Target Location. In addition to automating the delivery of the content, Harmony will always keep the target content up to date, and can also automate the configuration of your design applications (such as Autodesk user profiles and Bentley workspaces)

To remove this example package from your local machine, just go to the Download screen, select the Harmony source files line and click the Remove standard button.
To remove this example package from the master standards catalogue, go to the Admin screen, highlight the Harmony source files line and select the Remove standard button.

Now that you have created an example package, learn more about the functionality of Harmony in the proceeding sections.

Key Concepts

This section outlines the fundamental ways in which Harmony operates and then suggests some strategies that the admin could employ in order to maximize the benefit that Harmony can bring.
There are a few functions that are available for admins to use for the configuration of their applications.

  1. Synchronization of content from one location to another.
  2. Configuration of design applications.
  3. Plug-ins for Document Management Systems

Harmony will always synchronize content prior to setting any configurations.
In developing a strategy for your organization, it is worth knowing that Harmony can use either of the items 1 and 2 listed above or both together. Item 3 is used to automate the configuration from a Document Management System offering a “no-touch” experience for the end user.

Synchronization of content

Once a source and destination are set, Harmony will create a copy of the source content in the target location after the Set Standard or Test button has been clicked. If a source folder contains zip files, Harmony will also extract the contents of those zip files.
Once a synchronization is complete, any subsequent click of the Set standard button will start a check process to ensure that only the content from the source is at the target. Modifications to the target location are removed and replaced with that from the source ensuring that only the content from the source is at the target location.

  • See for more information.

Configuration of design applications

To configure a design application, an Instruction file is required and placed within the root folder of the source location. This file is read by Harmony and the configuration applied.
The Instruction file is generated by Harmony from the Design Apps tab of the Admin screen. This is where the configuration of the application is set.

  • See for more information.
  • See for more information.
  • See for more information.

Plug-ins for Document Management Systems

Plug-ins for Document Management Systems such as Bentley ProjectWise are also setup during the install, if the application was detected on the machine at that time.
The plug-ins do not require any input from an end-user or configuration from an administrator as they are fully automated. For Bentley ProjectWise, the only item required to automate a project is to have a valid Playlist file in a folder within a ProjectWise Work Area.
When a file from the Document Management System is then set to open, the Playlist automates the process of ensuring the most current up to date standards are synchronized and the design application configured properly.
This occurs before the file is opened and thus allows an application to be configured prior to launch.
The Playlist file is generated by Harmony from the Standards tab of the Admin screen.

  • See for more information.

Working across a Network

When working across a Network infrastructure (including but not limited to Shared Drives, Mapped drives, Network locations and cloud sync solutions such as One Drive), it is important to note that there is one extra step in the workflow to open a file.

  1. Harmony is launched and the user needs to select the standard to be set.
  2. The user opens the application and then opens the file to be worked on.

This first step, launching and setting the standard first, ensures that the latest content is cached and the design application is configured for use.

An application launcher is provided on the Available and Downloaded standards screens. This is an efficient way to launch the appropriate application. There are no extra command switches used by Harmony’s application launcher, it just launches the application allowing the most current configurations to be active. Applications can be launched outside of Harmony, however note any command switches (such as Autodesk user profile switches) in the shortcut will take precedence.

When setting a source or target for a networked location, ensure the full path is given where possible rather than mapped drives. This is to ensure that users who don’t have the same mapped drive are still able to access the content. Where all users have the same mapped drive, the drive letter can be used.

Working from BIM 360

When working from Autodesk BIM 360, it is important to note that there is one extra step in the workflow to open a file.

  1. Harmony is launched and the user needs to select the standard to be set.
  2. The user opens the application and then opens the file to be worked on.

This first step, launching and setting the standard first, ensures that the latest content is cached and the design application is configured for use.

An application launcher is provided on the Available and Downloaded standards screens. This is an efficient way to launch the appropriate application. There are no extra command switches used by Harmony’s application launcher, it just launches the application allowing the most current configurations to be active. Applications can be launched outside of Harmony, however note any command switches (such as Autodesk user profile switches) in the shortcut will take precedence.

Storing content in Amazon Web Services

Standards can be stored in an Amazon Web Services (AWS) S3 bucket and accessed by anyone through Harmony. The following sections outline the permissions and steps required to successfully setup AWS S3 buckets for storing Standards.

Roles and permissions

In order to create AWS Buckets, the user must have appropriate permissions. The following policy is recommended to be applied to the user for working with AWS Buckets:

  • AWS managed policy: AmazonS3FullAccess. This policy grants permissions that allow full access to Amazon S3.

The simplist method to achieve this is to access the Identity and Access Management Console, create a new User Group (e.g. S3_Admins), add the users and apply the AmazonS3FullAccess policy. See the link below for details on this workflow:

Creating a bucket

Follow the steps on the page below create a bucket. The bucket can be encrypted and have version control enabled, if desired.

Please note that Harmony is currently only able to access the following AWS Regions:

Location Region
Africa (Cape Town) AFSouth1
??? CNNorth1
???? CNNorthWest1
Europe (Frankfurt) EUCentral1
Europe (Milan) EUSouth1
Europe (Ireland) EUWest1
Europe (London) EUWest2
Europe (Paris) EUWest3
US East (N. Virginia) USEast1
US East (Ohio) USEast2
US West (N. California) USWest1
US West (Oregon) USWest2

Each bucket can have folders and sub-folders, however Harmony can access only the first level folder within a Bucket. For this reason, it is required to create a first level folder for each Standard and have no sub-folders. With this architecture a single AWS S3 bucket can house all Standards, each within their own folder.

Making a bucket public

Whilst creating a bucket, within the "Block public access (bucket settings)" section, ensure there is no tick against "Block all public access" and "Block public and crosss-account access to buckets and objects through any public bucket or access point policies"
If the bucket has already been created, select the bucket and then select "Permissions". From here, click Edit within the "Block public access (bucket settings)" and ensure there is no tick against "Block all public access" and "Block public and crosss-account access to buckets and objects through any public bucket or access point policies".

AWS Edit block public access

A policy also needs to be added to the bucket for access. Click the bucket that was created and then select the "Permissions" tab. Scroll down to the "Bucket Policy" section. Copy and insert the following text into the Bucket Policy section. Replace the lines highlghted in yellow with your Bucket ARN, which is shown at the top of the "Edit bucket policy" section.

		
{
	"Version": "2012-10-17",
	"Id": "BucketPolicy01",
	"Statement": [
		{
			"Sid": "BucketPolicy01",
			"Effect": "Allow",
			"Principal": "*",
			"Action": [
				"s3:GetObject",
				"s3:GetBucketLocation",
				"s3:ListBucket"
			],
			"Resource": [
				"arn:aws:s3:::p9-cad-stnds/*",
				"arn:aws:s3:::p9-cad-stnds"
			]
		}
	]
}
					

This will show access to the bucket as "Public".

AWS Edit bucket policy

Adding an AWS bucket as a Source in Harmony

Once an AWS bucket and folder for the Standard have been created. A zipped copy of the Standard should be placed in the folder alongside an Instructions file, if required. The following information is required by Harmony when creating a new line in the master catalogue:

Item Value required
AWS Region This is the name of the AWS Region where the bucket was created. Use the drop down to select the same region.
e.g. USEast1
Bucket Name This is the name of the Bucket.
e.g. p9-cad-standards
Folder (Standard) Name This is the name of the folder in the bucket that contains the Standard.
e.g. p9-acad2020
Adding AWS as a source in Harmony

Storing content in Microsoft Azure

Standards can be stored in a Microsoft Azure Container and accessed by anyone through Harmony. The following sections outline the permissions and steps required to successfully setup Microsoft Azure Containers for storing Standards.

Roles and permissions

In order to create Azure Containers, the user must have appropriate permissions. The following roles are the minimum recommended for working with Azure Containers:

  • Storage Account Contributor - Lets you manage Storage accounts, including accessing storage account keys which provide full access to storage account data.
  • Storage Blob Data Owner - Allows for full access to Azure Storage blob containers and data

Further details on the available roles and permissions can be found on the Microsoft Learn site here:

Creating a Storage account and Container

A Storage account is required within which Containers can be created to store Standards. Follow the steps on the pages below create a Storage account and Container and learn how to upload a "blob":

Storage account creation notes
Whilst creating a Storage account, the following are Pencil 9 recommendations for selected sections/tabs. All other items can be configured as required by your organization:

Tab: Section Field Recommendation
Advanced: Security Allow enabling public access on containers Disable to reduce risk from public exposure.
Advanced: Security Enable storage account key access Enabled. Must be enabled as access will be via Access key
Microsoft Azure Create Storage Account

Container creation notes
Consideration should be given to the name of the Container. This will be the name of the folder created on the local machine.
Each Container can have virtual folders, however Harmony can access only the content in the root of the Container. For this reason, it is required to create a new Container for each Standard and have no folders. There will therefore be a Container for every Standard.

Microsoft Azure Containers

Connection string

The Connection string for an Access key will be required by Harmony to access the Container and any content. See the following page to see where this can be obtained. The entire Connection string should be copied and is used wihin Harmony (see next section).

Microsoft Azure Access keys

Adding an Azure Container as a Source in Harmony

Once a Microsoft Azure container has been created. A zipped copy of the Standard should be placed within this alongside an Instructions file, if required. The following information is required by Harmony when creating a new line in the master catalogue:

Item Value required
Azure Connection string Paste the entire connection string copied from the previous step
Container (Standard) Name This is the name of the Container, within which the Standard is stored
e.g. p9-acad2020
Adding Azure as a source in Harmony

Storing content in Google Cloud Platform

Standards can be stored in a Google Cloud Patform (GCP) bucket. The following sections outline the permissions and steps required to successfully setup GCP for storing Standards.

Roles and permissions

In order to create GCP Buckets, the user must have appropriate permissions. The following role is recommended for working with GCP Buckets:

  • Cloud Storage: Storage Admin - Grants full control of buckets and objects. When applied to an individual bucket, control applies only to the specified bucket and objects within the bucket.

Further details on the available roles and granting access to a role can be found on the GCP site here:

Creating a bucket

Follow the steps on the page below create a bucket. Harmony does support buckets that are encrypted and have Object Versioning enabled.

Each bucket can have folders and sub-folders, however Harmony can access only the first level folder within a Bucket. For this reason, it is required to create a first level folder for each Standard and have no sub-folders. With this architecture a single GCP Bucket can house all Standards, each within their own folder.

Google Cloud buckets

Making a bucket public

In order to ensure that all users are able to access the Standard, the allUsers group must be granted Viewer rights. Follow the steps on the GCP website at the link below. The page below outlines the steps to enable this at an individual object or Bucket level.

Google Cloud access made public

Adding a GCP folder as a Source in Harmony

Once a GCP bucket and folder have been created. A zipped copy of the Standard should be placed in the folder alongside an Instructions file, if required. The following information is required by Harmony when creating a new line in the master catalogue:

Item Value required
GCP Bucket Name This is the name of the GCP Bucket exactly as it appears in the Google Cloud Platform.
e.g. p9-cad-standards
Folder (Standard) Name This is the name of the first level folder within the GCP Bucket, within which the Standard is stored
e.g. p9-acad2020
Adding Google bucket as a source in Harmony

Working from ProjectWise

Please ensure that ProjectWise is installed prior to installing Harmony. This will ensure that the Harmony plug-in for ProjectWise is installed. If installing projectwise after Harmony has been installed, simply run the Harmony install again and Harmony will install the ProjectWise plug-in.

When working with Harmony and ProjectWise, there is an extra file that needs to be placed into ProjectWise which provides a fully automated solution for delivering and setting a Standard. This is a Playlist and can be placed in any folder within a ProjectWise Work Area. Once an admin creates and adds a playlist to the project, Harmony will search up the project tree looking for a Playlist when a file is launched. If a Playlist is found, it is processed and Harmony stops looking for additional Playlists. The standards and applications will be automated for the entire team, regardless of the team’s location.

  • See for more information.

Autodesk configuration

Harmony can be used to configure an Autodesk application such as AutoCAD or Civil 3D by delivering resources as well as configuring a profile which is set to use that content. There are no additional requirements to manage content, cui files, lisp files, dll files, and more. The content should be reviewed and organized in the normal manner. Harmony will simply automate delivering this content to your project teams and ensure their applications are configured to use the right content for each project.

Autodesk configuration on a network

To configure an Autodesk standard for use on a network, take the following steps:

  1. Compress your standard and place this in the source location on your network.
  2. Within the Admin screen for Harmony, create an entry in the master standards catalogue. See for more information.
  3. Create an Autodesk instruction file and place this in the source location.
    • See for more information.
    • See for more information.
  4. Check the standard is configured correctly by launching the design application. To launch your design application, select the application from the Launch application dropdown box and then select the button. See for more information.
  5. Within the Admin screen for Harmony, change the status of the entry in the master standards catalogue to Approved to make this standard visible to all users.

The configuration work is complete after changing the status to Approved.

Autodesk configuration on BIM 360

To configure an Autodesk standard for use within BIM 360, take the following steps:

  1. Compress your standard and place this in a folder within BIM 360.
  2. Within the Admin screen for Harmony, create an entry in the master standards catalogue. See for more information.
  3. Create an Autodesk instruction file and place this in the source location.
    • See for more information.
    • See for more information.
  4. Create a Playlist file and place this is the same location as defined in Step 1. See for more information.
  5. To set the standard, click Load Playlist in the Download screen. Navigate to the Playlist file created in the previous step and click Open. This will read the Playlist and set your standard.
  6. Check the standard is configured correctly by launching the design application. To launch your design application, select the application from the Launch application dropdown box and then select the button. See for more information.
  7. Within the Admin screen for Harmony, change the status of the entry in the master standards catalogue to Approved to make this standard visible to all users.

The configuration work is complete after changing the status to Approved.

Autodesk configuration in ProjectWise

To configure an Autodesk standard for use within ProjectWise, take the following steps:

  1. Compress your standard and place this in a folder within ProjectWise.
  2. Within the Admin screen for Harmony, create an entry in the master standards catalogue. See for more information.
  3. Create an Autodesk instruction file and place this in the source location.
    • See for more information.
    • See for more information.
  4. Create a Playlist file and place this in your project. See for more information. Place this in a folder within ProjectWise to automate that folder and its subfolders.
  5. Launch a design file from ProjectWise to confirm the configuration is working.
  6. Within the Admin screen for Harmony, change the status of the entry in the master standards catalogue to Approved to make this standard visible to all users.

Bentley configuration

This guide assumes the user is familiar with the Managed Workspace and the CONNECT edition suite of Bentley Design applications. For the CONNECT Edition suite of Bentley design applications, there are a few critical variables that need to be set for base functionality.

Bentley configuration on a network

To configure a standard for use with Bentley design applications, take the following steps:

  1. Compress your standard and place this in the source location on your network.
  2. Create an entry in the master standards catalogue. See for more information.
  3. Create a Bentley instruction file and place this in the source location. See for more information.
  4. Open the Design application. When launching your application, only the workspace set in the Instruction file is available. Open a file to confirm the standard is being set.
  5. Change the status of the entry in the master standards catalogue to Approved.

Note: Harmony will modify the ConfigurationSetup.CFG file in C:\ProgramData\Bentley\[Application]\Configuration location. The original file is re-named and a new file is generated which includes any configuration changes. Unsetting a Standard or removing a standard re-sets the original file back in place.

Bentley configuration in ProjectWise

There are many ways to configure Bentley applications from ProjectWise with a Managed Workspace. This guide outlines one way in which Harmony can be used to automate the delivery of content and configuration of Bentley CONNECT edition design applications.

In order to utilize Harmony in ProjectWise the following steps are required:

  1. Compress your standard and place this in a folder within ProjectWise.
  2. Create an entry in the master standards catalogue. See for more information.
  3. Create a Bentley instruction file and place this in the source location. See for more information.
  4. Generate a Playlist and place this in a folder within ProjectWise to automate that folder and its subfolders. See for more information.

The next set of steps are to configure the application and then connect this to the managed workspace in ProjectWise.

  1. In your ProjectWise datasource, create a folder away from any projects and create a CFG file,
    E.g. Standards\Managed WorkSpace\PW_Bentley_Common.CFG.
  2. In the PW_Bentley_Common.CFG file, insert the path and name placed in Harmony for CFG Location\name.
    E.g. %include C:\Harmony\Bentley\HarmonyConfigurations.cfg
    .
  3. In ProjectWise Administrator, create a Configuration Settings Block (CSB) in the Predefined or Global level and create a %include statement to the PW_Bentley_Common.CFG file created in Step 1.
    E.g. %include $(dev(_DGNDIR))Standards\Managed WorkSpace\PW_Bentley_Common.CFG
    Save the CSB.
  4. Assign the CSB to your project.
  5. Ensure the rest of the project is configured correctly. At a minimum, a CFG file is required for the location defined in the WorksetsRoot location.
  6. Within the Standards tab of the Harmony Admin screen, select the standard to be automated in ProjectWise and then click Playlist.
  7. Copy the playlist that was created by Harmony into a folder within the Project to automate that folder and its subfolders.
  8. The project is now ready for use. Select a DGN file and open with the appropriate application. Harmony will cache the content locally and create the CFG file with the configuration for the project. ProjectWise will read that CFG file and launch the application with the appropriate settings.

Bentley Standards organization

Organizations can place content in many different locations within the Bentley delivered folder structure, for example within Organization, Organization-Civil or the Workspace.
In managing content for your organization or that delivered by a client organization, it is easiest to leave the folder structure as delivered and make minor changes to incorporate this into your organization.
One method of organizing this is to locate all the Standards within a folder structure that allows easy upgrading and maintenance. One suggestion for a target folder structure is:

C:\Harmony\[OrganizationName]\[ApplicationName_ApplicationVersion]\Configuration

A typical path could therefore be:

C:\Harmony\Org1\OpenRoads Designer_10.08\Configuration

This can be placed in the Configuration Location field in Harmony and the appropriate standard should have this folder structure as well. This allows the segregation of organization and application including the version.

Multiple Bentley applications in a project

If multiple applications are required for use on a project, a variable can be used to to define the application name and thus set the Configuration location accordingly. In this scenario, the following would be placed in the Configuration Location field in Harmony:

C:\Harmony\[OrganizationName]\$(_USTN_PRODUCT_NAME)_10.08\Configuration

The Application name folder must then exactly match the value of the variable for each application being set. Eg the following are the values for _USTN_PRODUCT_NAME for that application; OpenRoads Designer, Microstation.

Autodesk, the Autodesk logo, AutoCAD and Civil 3D are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries.