Getting Started Guide

Contents Downloading & Updating .......................................................................................................................... 2

Installing .................................................................................................................................................... 2

General Overview and Terminology: ........................................................................................................ 3

Functional overview: ................................................................................................................................. 5

A bit more about mappings ...................................................................................................................... 8

Projects and Guardian Registration .......................................................................................................... 9

Mapping Configurations ......................................................................................................................... 11

Other Settings ......................................................................................................................................... 12

User Behaviors ........................................................................................................................................ 13

Protected Pins ......................................................................................................................................... 15

Project Properties ................................................................................................................................... 16

Downloading & Updating The most recent version of Guardian can be downloaded at any time from the following link:

https://www.iconicbim.com/downloads. As new versions are released, a button will automatically

appear in your Revit Ribbon allowing you to easily download the latest version. Larger releases will be

accompanied with an email notification to all admin user accounts. Guardian actively provides current

version information to the licensing service. If your installed version falls behind too far, you will receive

an email notification asking you to update. A report of installed users and their versions may be

requested from the support team at support@iconicbim.com.

Installing Guardian is designed to fit a variety of scenarios:

▪ Company-wide deployments for normal users. Contact our support team for assistance with

wide scale deployment. Guardian fully supports traditional style deployments, but you must

configure the .msi installer with the proper flags for company ID, Admin/User install, etc.

▪ Single installations utilize the installer referenced above. By default, Guardian will automatically

run as ‘normal user’. Administrators should activate additional functionality by entering their

credentials inside the Licensing dialog (see screenshot below)

The installer for individual PCs follows these steps:

▪ Choose whether to install for the current user or all windows users on the PC.

▪ Choose which Revit versions to install it for. Currently supports Revit 2017, 2018, 2019, 2020.

Guardian will always be available for the three most recent Revit releases. Guardian will always

support the 4 most recent Revit releases.

▪ Provide Company ID. This is provided to you via email. During installation, a .key file is placed

on the computer that contains the ID that uniquely identifies your company. The location for

this file is:

o If installed for all users: C:\ProgramData\Guardian\Guardian.key

o If installed for the current user: C:\Users\<Current User>\AppData\Roaming\Guardian

▪ Guardian registers users based on this ID and the username provided inside the Revit options.

There is NO user management required in Guardian for normal users – allowing very fast and

easy administration.

When running Revit, Guardian will automatically authenticate the user based on the company ID found

on the computer and immediately start. The user will then see this when going to the licensing dialog:

Administrators of Guardian should activate the additional functionality by clicking on “Admin Login”

where they then enter their credentials provided by email. Upon successful login, administrator

functionality is automatically enabled.

General Overview and Terminology: Guardian is an automated service that monitors, applies treatment, and gets smarter as content is

added to your Revit projects and families. Decisions for what is allowed into these files are best made

when they are first introduced, not later. Guardian allows the person responsible for bringing in the

content to make certain decisions, because they know best what they need and don’t need from the

content. The following terminology will provide a background on how Guardian works. How it is used is

covered in a later section.

▪ Document: The document that is affected by incoming properties. These are either Projects

(.rvt) or families (.rfa).

▪ Supported Transactions: Those user actions that caused content to be loaded into projects.

o Load Family (from ribbon, drag-and-drop, reload, load from family environment)

o Copy-paste from document to document

o Load from file

o Insert from file

o Transfer project standards

o Bind Revit links

o Import / Link CAD

o Explode CAD instances

o <Custom transactions defined by you!>

▪ Property Types: Those properties that are currently supported for treatment by Guardian.

These are:

o Loadable Family Types

o System Family Types

o Shared Parameters

o Materials

o Fill Patterns

o Line Patterns

o Object Styles

o Line Styles

o View Templates

o View Filters

▪ Mapping Configuration: This is a remembered set of processing instructions (mappings and

removals) for Guardian to complete when it discovers new properties have been added to the

project. Each project is assigned a mapping configuration by Administrator users. Multiple

projects may share the same mapping configurations. The Mapping Configuration dialog can be

accessed from the Settings ribbon and looks like this:

▪ Mapping: The process of converting a property’s value into that of another. When performing a

mapping, Guardian finds all locations where the property is utilized, replaces the value stored

for a given property for that of another and then removes the existing property. For example:

MaterialA is mapped to MaterialB. Guardian will replace all occurrences where MaterialA is

assigned to elements and change it to MaterialB. Because MaterialA is no longer being used,

Guardian will then remove Material A. In cases where MaterialB is not in the project, Guardian

will simply rename the MaterialA to MaterialB.

▪ Removal: When properties are deselected, these will be remembered for removal in the future

when they are encountered. Certain properties cannot be removed, such as family types that

already have instances placed in the project. Shared parameters, when deselected, will simply

become family parameters to preserve the full functionality of the family. These remembered

removals can be viewed at any time in the Mapping Configuration dialog as seen in the above

screenshot.

Functional overview: As new properties are recognized, Guardian can respond by removing, renaming, or mapping certain

properties. Each action can be remembered for later the next time those same properties are

discovered. How and when it responds is up to you, the administrator! In order to understand the

different options, you must understand the following dialog. This is at the core of all Guardian

functionality as it relates to property management. Guardian detects many different property types

when introduced into projects and can display them to you in the following dialog:

1. In use / Not Used Buckets:

Properties such as materials, parameters and objects styles are often introduced by the loading

of carrier properties (ex: Materials have fill patterns associated with them), families, etc. Other

times, properties come as a result of transferring project standards, etc. Regardless, Guardian

can detect whether each new property is actually used by anything else. For example, a family

may have 100 materials loaded, but only one may be applied somewhere in the family (whether

through geometry assignment, through a parameter, etc.) In this case, Guardian will split these

materials into these two separate lists, allowing you to easily remove the unused properties

without affecting any function of the family itself. Note that the dialog above also appears

when loading in batches of families or properties. If a property is used by only one family in a

loaded batch, it will still appear as used.

2. Property listings

The properties appear in tree-view with common expand / contract, multiple select / deselect

controls. Properties that you do not want in the project, simply uncheck them.

3. Property treatment tasks. You must have one or more property selected when using these.

a. Button1 = Rename – You may rename certain property types by selecting them and

toggling this button or use the F2 shortcut. By default, Guardian remember this rename

action the next time it encounters the old name. You may uncheck this box (shown

below) to perform the rename this time only.

b. Button2 = Edit Mapping – Brings up the following Mapping Dialog, which allows you

choose a single property to convert your selection to. By default, the list is filtered to

only show properties that existed in the project before the load action. You can include

the new properties by toggling “Show All”. If you want to remove the properties, select

[Remove]

c. Button3 = Remove Mapping – Once a mapping is applied, this button will remove the

mapping and return the checkbox for the property back to a checked state.

d. Button4 = Toggle one time/remembered nature of mapping – Once a mapping is

applied, Guardian will by default remember it by storing a rule in the cloud. Toggling

this button, you can have it perform the mapping or removal “This time only”. (Icon will

have a #1 appear beside it )

4. Suggestions and Mappings dialogs

You may click on ‘Mappings’ to view the entire mapping configuration for reference or create

manual mappings. “Suggestions” will suggest which properties to map to others based on if it

finds duplicate properties elsewhere in the project.

5. Save changes to files

Once ‘OK’ is clicked, Guardian will perform a targeted clean-up on any relevant family files, then

reload them back into the project, then clean up the properties that are now undesired. If this

box is checked at the time of clicking ‘OK’, Guardian will add the additional step of exporting the

affected families back to their original loaded location.

Note that during a copy-paste scenario from project to project, Guardian will follow the same

steps, except it does not always have access or knowledge of the loaded path of the affected

files. In this case, you will see this checkbox text change to “Export affected files” and you will

have the option to save a .zip file containing the files.

This option only appears to company admins.

6. Filter Menu

“Show additional mapping insight” will add additional context into what Guardian will perform

during processing.

A bit more about mappings Mappings in Guardian are very powerful! Guardian has an extensive knowledge base of places to look

when swapping out values. Furthermore, when processing families that have complex nested structures

and hierarchy, it intelligently targets areas of interest and only goes as deep into these levels as it needs

to go in order to address the values. This keeps things running as fast as possible.

Guardian will also ‘edit’ the boundaries of certain things like masking regions and detail items in order to

swap out values for line styles, etc. Groups in Revit are not supported in the API which can result in

Guardian not being able to perform mappings on grouped elements. For example, if Guardian is

processing a mapping of MaterialA to Material B, it will scan through the entire set of new instances and

properties, searching for places where MaterialA is applied – then swap the values in those places.

During this process, it will miss grouped elements before making the swap and deleting the property.

Here is how to read the symbols and colors:

A mapping that appears like this: is indicating that ‘Movement’

will become ‘Elevation Swing’. A new rule will be created to perform this action the next time

Guardian sees ‘Movement’.

A mapping that appears like this: is indicating that ‘Movement’

will become ‘Elevation Swing’, but that this rule existed prior to the current Guardian session.

A mapping that appears like this: is indicating that ‘Symbol’ will become

‘Plan Swing’, but this time only. No rule will be saved.

Note: the mapping symbol can be clicked on to open the mapping dialog at any time.

The following dialog will appear FIRST when new properties are recognized. As a Guardian

administrator, you have full control whether ANY dialogs at all are presented to your users. See section

“Guardian Settings”.

The first option is a shortcut to remove all unused properties AND process any mapping rules that

have been stored.

The second option will simply display the list of new properties and allow you to manually decide

what to allow or create new rules for.

Projects and Guardian Registration Only Guardian administrators have access to the projects dialog:

Projects must be registered before Guardian will do anything in that project. There are settings that can

control how and if projects self-register when projects are opened or created. (See later section)

This dialog displays a list of all currently registered projects, including who registered them, when and

what Mapping Configuration will be used when new properties are recognized.

Projects can be manually registered by clicking the large Guardian icon button, if it hasn’t automatically

registered already. Projects can be unregistered by also clicking this large button again or selecting it in

the list and clicking ‘Unregister’.

When the projects list becomes too long to manage, projects can be ‘Archived’. Toggle ‘Show Archive’

to expose these projects in the list.

Each project may have a mapping configuration applied, as indicated by this button. (See next section)

You have full control over how or if your projects are automatically registered, and what mapping

configurations are applied, with the following settings dialog:

Mapping Configurations

The Mapping Configurations dialog can be accessed by administrators through the Projects dialog by

clicking the button for any project. Doing so will automatically select the applied configuration on the

left for that project.

There is no limit to how many configurations a company can have. It is common to have very few,

usually one for each discipline or disparate groups. Some have configurations for Metric and Imperial,

others have configurations for specific clients that maintain their own graphical and data standards.

This dialog can also be accessed from the Guardian ribbon as well by both company admins or normal

users.

When normal users click on Mappings, they will only see the portion of the dialog

on the right side – the rules that only pertain to the project that they have open.

Rules can be edited and created and deleted using the three buttons at the bottom.

It is common practice to let the rules populate as administrators load content into

projects and determine how to handle their accompanying properties. However, it

may be helpful to occasionally create a manual rule here without having to load an

undesired property just to create a rule.

Other Settings With the following settings dialog, you have full control over what actions Guardian should be interested

in. The left column lists the transactions that it ‘listens’ to for new properties. These names are

identical to those that you see on the undo/redo menus.

Because new properties are added to projects through a variety of methods AND 3rd party tools,

Guardian allows you full ability to add or remove monitored transactions from this list. This is especially

helpful as some 3rd party addins utilize their own transaction names when loading content into projects.

Furthermore, you have full control over what the user experience should be when these transactions

are used. Here is the dialog that appears when clicking the button. You can multi-select to apply a

mode to projects.

User Behaviors Here are some additional commands that you can customize for your users:

The above settings will, when enabled, affect the user experience when users attempt the indicated

command. This is a great opportunity, for each command, to customize the message the users will see.

This is done by clicking ‘Edit’ for each command:

When users attempt the actions, Guardian will send an email notification to all administrators of

Guardian. (if the option is enabled in the above dialog)

Protected Pins This feature allows administrators to pin elements in such a way that users cannot unpin them (or at

least see a message before unpinning). It’s very simple to use, but the below setting must be enabled:

When administrators pin elements, Guardian will provide the following prompt:

Choosing ‘Yes,..’ will then allow the administrator to enter a message that will appear to the users when

they attempt to unpin these properties. At any time, administrators can view a list of elements that are

protected in the project from this dialog:

Project Properties

This dialog is very powerful. There are many of the same UI elements and functions on this dialog as

there is for the dialog that appears when properties are entering projects (see ‘Functional Overview’).

Only those that are unique here are mentioned.

This dialog basically allows a deep cleansing of existing projects and provides insight into the actions of

users in the project as it relates to properties that have been added, modified and deleted.

1. History panel: As users add properties, modify properties or delete properties, a history item

will appear here. Clicking on a history item will filter the properties (#2) to reveal them.

2. An entire list of supported property types in the project. These properties default to a ‘Not

analyzed’ state as Guardian doesn’t yet know if they are used or unused.

3. Once properties are marked for removal or mapping, they are ready to process. Click on

‘Review Changes’ to review before processing.

4. This will scan the entire project for all property usage. Depending on the size of the project, this

can take a very long time (over an hour in some cases). This will be an area of improvement in

the next release.

5. This panel will reveal the areas in a project that is using a selected property. Multiple properties

may be selected at a time and toggled using the menu below.

6. This panel will reveal the dependent properties. For example, if a material is selected, this panel

will reveal any fill patterns that are applied to the material.