JTB Sync for Revit

Product Description

JTB Sync is a powerful Autodesk Revit app which enables you to export parameter and property data from your Revit® project model to an external file in tabular format, process the data in Microsoft Excel, and then import the information back into Revit and instantly realize changes. Aside from simply extracting common data from the building model, JTB Sync also has the ability to create informational associations between Elements contained in separate projects, by recognizing and processing embedded Revit Links. With the power of JTB Sync, your ability to effectively manage and leverage model data is extended far beyond the native capabilities of Autodesk Revit, providing the means to more seriously engage the ”I” portion of Building Information Modeling (BIM).

Looking for an alternative to Ideate BIMLink or Autodesk Revit DBLink? If so, contact us with your interest in JTB Sync. Element properties like Materials Properties, Fill Pattern Properties and Line Pattern Properties are supported. Functionalities like Create/Delete Element Parameters, Rename Family Types, Manage Materials properties, Manage Fill Pattern/Line Pattern Properties are available.

JTB Sync contains two core commands: JTB Sync Export and JTB Sync Import.

JTB Sync Export is the command to define a Revit data export scenario, and execute the extraction to Microsoft Excel.

JTB Sync Import is the command to bring the Microsoft Excel data back into Autodesk Revit, after it has been processed.

JTB Sync Excel is the resultant Microsoft Excel Workbook that JTB Sync Export creates. It is specially-formatted to preserve the integrity of the JTB Sync data, while allowing controlled edits and processing.

Typical Workflow Summary

1. Open an Autodesk Revit project (*.rvt). (It is recommended to execute a “Save” before starting JTB Sync.)
2. Open any non-3D view in the Revit Project.
3. Select JTB Sync Export command from the Add-ins menu, External Tools drop-down listing.
4. Configure the JTB Sync Export user interface settings to create an export scenario, and define the name and location of the MS Excel (*.xls) file to create and export to.
5. Select ‘OK’ to proceed with JTB Sync Export, and refrain from working in Autodesk Revit until JTB Sync Export completes.
6. Browse to the location of the newly-created MS Excel file and open it.
7. Review and edit the data as required. Save the file.
8. Return to Autodesk Revit, and verify that the correct project file (*.rvt) is open and active. (It is recommended to execute a “Save” before starting JTB Sync.)
9. Select JTB Sync Import command from the Add-ins menu, External Tools drop-down listing.
10. Locate the MS Excel Import Source File through the JTB Sync Import user interface, and configure customizable import settings as needed.
11. Select ‘OK’ to proceed with JTB Sync Import, and wait for the Add-in to analyze the MS Excel data as it relates to the active Revit project.
12. When completed with the data analysis, JTB Sync Import will present the User with an Import Summary. By default, all pending changes will be selected to be made. Please review this information and de-select any pending changes you wish not to occur.
13. When ready to invoke CHANGE, ADD, and/or DELETE JTB Sync Import Actions to the active Revit project, click ‘OK’.
14. After JTB Sync Import completes, it will present the User with a final summary, listing any errors or difficulties the Addin encountered while accessing the Revit model.
15. You may examine the Revit model after JTB Sync Import closes to verify changes. Once satisfied, simply save the model to commit these changes, or exit without saving to preserve the model in its pre-import state.

JTB Sync Export

JTB Sync Export is the command to define a Revit data export scenario, and execute the extraction to Microsoft Excel. JTB Sync Export reads the qualifying Property and Parameter data from Elements of the selected Revit Documents and Categories, and writes that information to the designated Microsoft Excel file (*.xls) in a standardized tabular format.

Upon starting the command, users are presented with a graphical interface before executing the extraction, which contains settings and controls to configure the export scenario with regard to: Revit Category Filters, Parameter Type Filters, Revit Link Controls, Room/Space Location Criteria, and MS Excel Output File. Please refer to the diagram below to become familiar with the user JTB Sync Export user interface:

Features Description

1. Revit Category Filters This cascading tree-view control allows you to specify exactly which Revit elements you would like to export property and parameter data from, by filtering the selection using Revit Categories. Each item listed in the treeview represents a standard Revit Category of Elements that can be included or excluded from the Export. Items that are checked will be included, and those un-checked will be excluded. For the selected (checked) Categories, JTB Sync will scour the Revit Documents included in the export (see user interface key #3 below…) and retrieve property and parameter data from all Element Types and Element Instances of the Category. Note: there are two required groups of Categories that are selected by default and may not be omitted from the export: “Required Categories” and “Required Properties”. All other items may be selected/deselected as needed.
   1. Do not export empty Categories By default, JTB Sync will not create an Blank MS Excel worksheet for selected Categories that do not contain any Elements in any of the included Documents. This setting is displayed for informational purposes only, and may not be changed.
   2. Only export Types with model Instances This setting controls whether JTB Sync includes Element Types found in the included Documents, that do not have any Instances placed in the Model. Use this feature to prevent “empty” Element Type data from being written to the export. This may be beneficial when leveraging the Excel data to tabulate quantities, cost, etc.
2. Parameter Type Filters There are three types of Parameters used in Autodesk Revit: System or Built-in parameters, Project Parameters, and Family Parameters. Also, with regard to Project and Family types, a Parameter may be derived from a Shared Parameters definition or simply defined within the Project of Family itself. This control allows users to filter the export data to include/exclude certain Parameter data based upon its Parameter type and/or its Shared status. Note: JTB Sync requires Built-In Parameters to be included in the export. This checkbox control is displayed for informational purposes only, and may not be changed.
3. Revit Link Controls By default, Elements contained in the Active Document will be contained in the JTB Sync Export operation. Additionally, JTB Sync has the (optional) ability to include data from Elements embedded in any of the Revit links associated with the active Revit project, as part of the Export data. Tip: Activating this control is a beneficial time-saver when working on large, complex Projects where multiple associated Revit Links are utilized to piece together the complete Building Model.
   1. Include Linked Files This checkbox control determines if JTB Sync will include Revit links in the export data, or not. When this control is checked, the listing of Revit Links associated with the active project will become activated. Once activated, you may select each of the Revit Links you wish to be included.
4. Room/Space Location Criteria JTB Sync will “locate” Revit Element Instances to the Room and/or Space that it exists within, when applicable to the type of Element. With this control, you have the option of only locating Elements within Rooms/Spaces that are of the same Revit document (*.rvt), or you may specify one or more documents to search, and attempt to locate Elements from one document within Rooms/Spaces contained in another. The location data exported to the MS Excel output file will be the ElementID of the containing Room/Space. With regard to Phasing, typically, an Element will be matched to the “most recent” Room/Space that the Element exists.
   1. Search each element’s own project With this option, an Element’s location search criteria will be limited to Rooms/Spaces that exist in the same project as the Element. Example: An Element in Document “A” will only “locate” to Rooms/Spaces that also exist in Document “A”. If more than one Document is included in the Export (see Revit Link Controls), this rule still applies. Active Document “A” Elements will only “locate” to Active Document “A” Rooms/Spaces, Revit Link “B” Elements will only “locate” to Revit Link “B” Rooms/Spaces, etc.
   2. Search selected projects With this option, users may specify and restrict location criteria to Rooms/Space that exist in certain Revit documents. This option is beneficial when Rooms are defined in a Revit Link, but not in the Active Document, and you wish to associate the location of Elements in the Active Document with those Rooms contained within a Revit link. Example: The Active Document “A” and Revit Link “B” are selected in the search criteria. An Element in Document “A” will attempt to find a Room/Space of a suitable Phase in Document “A”. If a match is found it will record that Room/Space ElementID. If no match is found it will move to Document “B” and will attempt to find a Room/Space of a suitable Phase there. And so on… Note: Regarding the order in which an Element searches Documents: An Element will always search its own Document first, if that Document is selected in the list. From there it will search each remaining selected document in the list, until it either finds a match or has iterated though all possible Documents. Tip: Selecting this option may add considerable processing time to the JTB Sync Export operation. When working with very large datasets, please be patient, and allow JTB Sync to complete.
      
      Important Note: When designating a Revit Link for Room/Space Location Criteria, it must be set as “Room Bounding” in the Active Revit Document, or it will be ignored by JTB Sync Export. Please refer to the Revit help documentation for more information of setting a link to be Room Bounding.
5. MS Excel Output File Use this control to specify the name and path to the external file you wish to export to. You may specify a new file, which will be created by JTB Sync, or an existing file, which will be overwritten by JTB Sync. The resultant file will be of Microsoft Excel format, and may be opened and examined from Excel, after JTB Sync Export has completed. Tip: Click on the ellipsis button […] to browse your computer when specifying file name and path.
   Note: In the case of overwriting a file, JTB Sync does not append the data, but rather re-creates the file. No data pre-existing in the overwritten file will be preserved.
6. OK/Cancel Once an JTB Sync Export scenario is configured, and an MS Excel Output File has been determined, click the OK button to execute the Export operation. If you wish not to proceed with the export, click the Cancel button to close JTB Sync.
   1. OK When the Export operation is executed, the main JTB Sync Export user interface will close, and JTB Sync will begin analyzing the included Revit documents to gather qualifying Elements for data extraction, and a new JTB Sync Export Progress dialog will appear. The Progress dialog will inform you of JTB Sync’s progress, while it iterates through Type and Instance Elements of each qualifying Revit Category, and the writes their property and parameter data to MS Excel.
      When complete, the JTB Sync Export Progress dialog will close, and a final Export Summary Dialog will appear, displaying some statistics about the Export.
   2. Cancel Selecting Cancel will close JTB Sync, and no Export will occur.

JTB Sync Excel

The resultant output from JTB Sync Export in Microsoft Excel represents the data portion of your Revit project, organized into a tabular spreadsheet. By consolidating this information into rows and columns on Category-specific Worksheets, it becomes much easier to visualize, manage, and leverage property and parameter data within a familiar software environment that was designed precisely for this purpose.

Formatting

The Microsoft Excel (*.xls) file created by JTB Sync Export is custom-formatted to make editing the Revit data in tabular format as intuitive as possible.
The Excel Workbook is comprised of multiple Worksheets of two basic Types: <Category> and Parameter Definitions. In any JTB Sync Export there may be a varying number of <Category> Worksheets, depending upon the configuration of the JTB Sync Export scenario from Revit. Each <Category> worksheet is named after the Revit Category it represents – for either Types or Instances. Also each JTB Sync export will always include one ‘Parameter Defintions’ Worksheet, which contains a listing and associated information about each unique parameter definition contained in the total of <Category> Worksheets.
Fig. 2.1 – Worksheet Tabs example

There are two Header rows on each Worksheet. The first row represents the various Property and Parameter names that were exported for the Category, and the second row contains a unique numerical identifier that JTB Sync creates at time of Export to link the parameter name on a Category Worksheet to the listing of all parameters found on the “Parameter Definitions” Worksheet. Note: only Parameters contain numerical data in header row number two, Properties do not.
Below the Header rows, the data contained in each qualifying Element encountered for the Category is organized by row, with each column representing the value of the corresponding Property or Parameter name.
Fig. 2.2 – Header row example

Within each Column, special data-protections and formatting may be applied, based upon the Read-only and/or Shared status of each Parameter as it exists in the originating Revit Document (*.rvt): Shared data: are formatted to be in italics. Read-only data: are protected from edit, and the cell backgrounds are lightly shaded.

Working with Excel Data

The amount of data found in the Excel Workbook created by JTB Sync Export is to be thought of as “fixed”, in the sense that you may not manually create any new Worksheets, or any new rows or columns on any existing Worksheet within the Workbook. This restriction is to insure that the data retains its integrity and will be recognizable by JTB Sync when and if you import it back into Autodesk Revit. There are protections auto-applied to the Workbook to help insure that these types of unanticipated changes are not made. But aside from that simple restriction, any cell left unprotected is eligible to be edited.

Cell Values

To change the value of a Property or Parameter to be later imported back into Autodesk Revit, simply select any un-protected cell and edit the data. Once the Workbook is saved with this change, the next time it is selected for import, the existing value for the parameter in Revit will be compared to the import value in Excel; and if they differ, the Excel value will overwrite the Revit value.
The editable values that appear in the cells are of three distinct data types: String, Integer, or Double. When editing a value, MS Excel will require you to maintain that data type, so replace a string with a string, integer with an integer, double with a double.
There are three special cell value constants that JTB Sync applies to the Export data under certain circumstances:
*NA* - indicates that the Parameter does not exist for that particular Element. *ERROR* - indicates that a handled exception occurred during the JTB Sync Export operation, and therefore the parameter value could not be reported. <none> - indicates that a valid value was not found for the Parameter
Important Note: Never manually change the value of a cell to that of one of the JTB Sync constants listed above.

Special Functions

Aside from editing existing Property and Parameter values, you may perform a few additional “Special Functions” on the JTB Sync Excel Workbook:
Change Type Name – On Type Category Worksheets, the ‘TypeName’ column of data is left unprotected. You may edit the names of Element Types in Excel and these edits will be supplied to Autodesk Revit the next time the Workbook is selected for Import.

Add Parameter/Value – In any unprotected Cell that contains the value *NA*, you may change that value, which will alert JTB Sync to create that Parameter for the Element and assign it the designated value upon the next Import:
1. If the Parameter is a Project Parameter, it will be created for the Revit Category and will subsequently now be applied to all qualifying Elements of that Category in the Document. The designated value, however, will only be applied to the Element for which it was entered in Excel. All other Elements that were assigned the new Parameter will receive the default value, if any.
2. If the Parameter is a Family Parameter, it will be created for the Family Definition, and will subsequently now be applied to all Types and Instances of that Family in the Document. The designated value, however, will only be applied to the Type or Instance for which it was entered in Excel. All other Elements that were assigned the new Parameter will receive the default value, if any.

Delete Parameter – On the ‘Parameter Definitions’ Worksheet, each row represents a unique Parameter Definition encountered by JTB Sync Export. If the Parameter is of the Project or Family type, the Cell in the ‘Key’ column of data will be unprotected. When you click on this cell, a drop-down list will appear, and you may change the value of the cell from its unique numerical identifier, to *DELETE*. This will alert JTB Sync to remove this parameter from the Project Category or Element Family, depending upon the Parameter Definition type.
Fig. 2.3 – Delete parameter example

JTB Sync Import

JTB Sync Import is the command to define a Revit data import scenario, and execute the import of data from Microsoft Excel to Autodesk Revit. JTB Sync Import reads a Microsoft Excel file created by JTB Sync Export, and compares the data contained in that file, to the data in the Active Revit document. Allowed differences in the data are grouped into three “Import Actions”: CHANGE, ADD, and DELETE.
CHANGE actions represent differences in parameter values. The value imported from MS Excel will overwrite the existing parameter value for the Element in Revit.
ADD actions represent parameters (with new values assigned) that will be created for qualifying Categories or Families in the active Revit document, depending upon if the new parameter to be created is of the Project or Family Parameter type.
DELETE actions represent parameters (and current values) that will be removed from applicable Categories or Families in the active Revit document, depending upon if the existing parameter to be removed is of the Project or Family Parameter type.
Important Note: Regardless of the number of Revit documents that comprised the JTB Sync Export that created the MS Excel data, only that data whose project information matches the Active Revit document will be considered for import.

Import Scenario Configuration

Upon starting the command, users are presented with a graphical interface before executing the import, which contains settings and controls to configure the import scenario with regard to: Import Source File, Create Log File, Allow creation/deletion of Parameters, Allow Element Type renaming. Please refer to the diagram below to become familiar with the user JTB Sync Import user interface:

Features Description

1. Import source file Use this control to specify the name and path to the external file you wish to import from. Tip: Click on the ellipsis button […] to browse your computer when specifying file name and path. Note: The Microsoft Excel file that you specify must have been previously created by JTB Sync Export.
2. Import Settings This grouping of controls provides the user with some global control over how certain potential changes to the active Revit document are handled, and whether a text-based log file is created to document the changes made as a result of an JTB Sync Import operation.
   1. Create log file When this item is checked, JTB Sync will create a text-based log file that documents all CHANGE, ADD, AND DELETE actions applied to the Active Revit document, as well as any difficulties or errors JTB Sync encountered while attempting to access and/or change the Revit document. Note: The log file is auto-named in the format: <DateTimeCode> - JTB SyncImport.log and is always placed in the same location as the MS Excel file used to derive the import from.
   2. Allow creation/deletion of Parameters As documented in the section “JTB Sync Excel”; users can determine Parameters and values to be created for Elements, as well as Parameters to be deleted from Elements, by the manner in which the MS Excel data is edited. This setting gives global control over the Import to block ADD and DELETE Actions in the active Revit Document, and serves as an override to the changes defined in the Excel file.
   3. Allow Element Type renaming As documented in the section “JTB Sync Excel”; users can change the names of Element Types, and invoke those changes in Revit upon next import. This setting gives global control over the Import to block these renaming Actions in the active Revit Document, and serves as an override to the changes defined in the Excel file.
3. OK/Cancel Once an JTB Sync Import scenario is configured, and an MS Excel Input Source File has been determined, click the OK button to execute the Import operation. If you wish not to proceed with the Import, click the Cancel button to close JTB Sync.
   1. OK When the Import operation is executed, the main JTB Sync Import user interface will close, and JTB Sync will begin comparing the data in the MS Excel file to matching Elements in the Active Revit Document; and a new JTB Sync Import Progress dialog will appear. The Progress dialog will inform you of JTB Sync’s progress, while it iterates through Type and Instance Elements of each qualifying Revit Category, and records potential changes to the Revit document. When complete, the JTB Sync Import Progress dialog will close, and an Import Summary Dialog will appear, displaying the potential changes for the user to approve and/or omit.
   2. Cancel Selecting Cancel will close JTB Sync, and no Import will occur.

Import Summary Review

The Import Summary Dialog is presented to the User, after JTB Sync has compared the data from the Import Source File to the Elements in the Active Revit Document. This summary lists all of the potential Import Actions to the Revit document.
JTB Sync Import Actions are grouped into three categories: CHANGE, ADD, and DELETE:
CHANGE –will change the value of pre-existing parameters. ADD – will create new parameters/values for Elements. DELETE – will remove parameters from Categories/Elements.
By default, all Actions are selected to be executed. Please review this summary and omit any that you prefer not to take place.

Features Description

1. Import Action Review This expandable treeview control displays all of the Import Actions that JTB Sync Import plans to execute in the Active Revit Document.
   It is displayed in the format: <Action> <Category> <Element> <Parameter> Items checked at the <Parameter> level represent each individual Action to be executed. Parent Items to the <Parameter> level (<Element>, <Category>, <Action> ) serve as logical “containers” to assist with group selection of the <Parameter> nodes. Example: In the example UI scenario (above), there are CHANGE, ADD, and DELETE actions set to be executed. Under the CHANGE Action, changes to the value of the Parameter “Comments” for three separate instances of the Door “Single Flush - 36”x84” are indicated. Under the ADD Action, a Project Parameter named “SoundTransmissionClass” is indicated to be added and bound to the “Walls” Category. Under the DELETE Action, a Project Parameter named “MyComments” is set to be removed (unbound) from the “Doors” Category; and a Project Parameter named “IncludeInSchedules” is set to be removed (unbound) from the “Walls” Category.
2. Information/Tips This section of the User Interface is purely informational. It includes a key to the format of the Import Action Review treeview control, as well as some important tips on how to use the control effectively.
   a. Key This serves as a visual reminder to users, regarding the format of the displayed nodes in the Import Action review treeview control.
   b. Select/Deselect Checkboxes… This note to Users serves as reminder for how to include/excluded planned actions in the Active Revit Document.
   c. Select a Node to review… This note reminds users that they may review additional information about a node by selecting it. (see item #3, below)
   d. Right-click a <parameter> node to… This note reminds users of useful, time-saving right-click selection features, when using the Import Action Review treeview control:
   i. Right-Click, <parameter> node This will display a cursor menu, allowing the User to affect the
   checked/unchecked status of all parameters that match the selected parameter, in the current Action tree.
   ii. Right-Click, <Category>, <Element> nodes This will display a cursor menu that allows the user to Expand/Collapse All child nodes below the selected node.
3. <selected node> Information This section of the User Interface is purely informational. When the User selects any node in the Import Action Review treeview control, additional information about the Action or Revit Element associated with that node is displayed. Example: In the example UI scenario (above), the <Parameter> node “Comments” is selected, and information about that Element and the proposed Action are displayed. The Current Value of the Parameter in the Active Revit Document is <nothing>, and the Change to Value is “TEST1”.
4. OK/Cancel Once the proposed JTB Sync Import Summary Review Actions are configured to your satisfaction, click the OK button to execute the selected Actions in the Active Revit Document. If you wish not to proceed with the import, click the Cancel button to close JTB Sync.
   a. OK When the Import operation is executed, the main JTB Sync Import Summary Review user interface will close, and JTB Sync will begin editing the Active Revit Document; and a new JTB Sync Import Progress dialog will appear. The Progress dialog will inform you of JTB Sync’s progress, while it iterates through the selected Import Actions. When complete, the progress dialog will close, and a final Import Summary Dialog will appear, displaying the potential changes for the user to approve and/or omit.
   b. Cancel Selecting Cancel will close JTB Sync, and no Import Actions will occur.

Known Limitations

1. Non-Shared Project Parameters Currently, the Revit API does not allow for the Creation and/or Deletion of non-shared Project Parameters. If a new parameter of this kind is indicated within an ADD and/or
DELETE Action in JTB Sync Import, it will be “skipped” and logged as such in the JTB Sync Import log file, and will be displayed as an error in the final JTB Sync Import summary.

Please contact us with your interest in JTB Sync or want help with custom programming for Revit.