Product Description

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

JTBsync contains two core commands: JTBsync Export and JTBsync Import.

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

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

JTBsync Excel is the resultant Microsoft Excel Workbook that JTBsync Export creates. It is specially-formatted to preserve the integrity of the JTBsync 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 JTBsync.)
2. Open any non-3D view in the Revit Project.
3. Select JTBsync Export command from the Add-ins menu, External Tools drop-down listing.
4. Configure the JTBsync 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 JTBsync Export, and refrain from working in Autodesk Revit until JTBsync 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 JTBsync.)
9. Select JTBsync Import command from the Add-ins menu, External Tools drop-down listing.
10. Locate the MS Excel Import Source File through the JTBsync Import user interface, and configure customizable import settings as needed.
11. Select ‘OK’ to proceed with JTBsync 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, JTBsync 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 JTBsync Import Actions to the active Revit project, click ‘OK’.
14. After JTBsync 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 JTBsync 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.

JTBsync Export

JTBsync Export is the command to define a Revit data export scenario, and execute the extraction to Microsoft Excel. JTBsync 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 JTBsync 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, JTBsync 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, JTBsync 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 JTBsync 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: JTBsync 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 JTBsync Export operation. Additionally, JTBsync 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 JTBsync 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 JTBsync 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 JTBsync Export operation. When working with very large datasets, please be patient, and allow JTBsync 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 JTBsync 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 JTBsync, or an existing file, which will be overwritten by JTBsync. The resultant file will be of Microsoft Excel format, and may be opened and examined from Excel, after JTBsync 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, JTBsync 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 JTBsync 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 JTBsync.
    1. OK When the Export operation is executed, the main JTBsync Export user interface will close, and JTBsync will begin analyzing the included Revit documents to gather qualifying Elements for data extraction, and a new JTBsync Export Progress dialog will appear. The Progress dialog will inform you of JTBsync’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 JTBsync 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 JTBsync, and no Export will occur.

JTBsync Excel

The resultant output from JTBsync 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 JTBsync 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 JTBsync Export there may be a varying number of <Category> Worksheets, depending upon the configuration of the JTBsync Export scenario from Revit. Each <Category> worksheet is named after the Revit Category it represents – for either Types or Instances. Also each JTBsync 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 JTBsync 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 JTBsync 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 JTBsync 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 JTBsync 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 JTBsync 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 JTBsync constants listed above.

Special Functions

Aside from editing existing Property and Parameter values, you may perform a few additional “Special Functions” on the JTBsync 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 JTBsync 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 JTBsync 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 JTBsync to remove this parameter from the Project Category or Element Family, depending upon the Parameter Definition type.
Fig. 2.3 – Delete parameter example

JTBsync Import

JTBsync Import is the command to define a Revit data import scenario, and execute the import of data from Microsoft Excel to Autodesk Revit. JTBsync Import reads a Microsoft Excel file created by JTBsync 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 JTBsync 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 JTBsync 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 JTBsync 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 JTBsync Import operation.
    1. Create log file When this item is checked, JTBsync 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 JTBsync encountered while attempting to access and/or change the Revit document. Note: The log file is auto-named in the format: <DateTimeCode> - JTBsyncImport.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 “JTBsync 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 “JTBsync 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 JTBsync 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 JTBsync.
    1. OK When the Import operation is executed, the main JTBsync Import user interface will close, and JTBsync will begin comparing the data in the MS Excel file to matching Elements in the Active Revit Document; and a new JTBsync Import Progress dialog will appear. The Progress dialog will inform you of JTBsync’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 JTBsync 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 JTBsync, and no Import will occur.

Import Summary Review

The Import Summary Dialog is presented to the User, after JTBsync 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.
JTBsync 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 JTBsync 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 JTBsync 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 JTBsync.
    a. OK When the Import operation is executed, the main JTBsync Import Summary Review user interface will close, and JTBsync will begin editing the Active Revit Document; and a new JTBsync Import Progress dialog will appear. The Progress dialog will inform you of JTBsync’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 JTBsync, 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 JTBsync Import, it will be “skipped” and logged as such in the JTBsync Import log file, and will be displayed as an error in the final JTBsync Import summary.

Please contact us with your interest in JTBsync.