Exchange Apps – Information for Revit developers

By Stephen Preston

This guide is for developers and content providers new to publishing plug-ins and other content on Autodesk® Exchange Apps – either free, trial or for fee versions. It outlines best practice guidelines and a few requirements for publishers to follow when creating products for the Autodesk Exchange Apps. These guidelines are designed to ensure that users on Autodesk Exchange have a consistent experience when downloading multiple products from the store.

Requirements

You will be presented with a detailed list of requirements for publishing on Exchange when you first register to be a publisher on Autodesk Exchange Apps. The information that follows is a summary specific to Revit. For All Content Types Most of the information we need from you is collected from the product submission form that you complete in the publisher system. This includes gathering information to auto-generate a ‘quick start’ page in HTML format that is included with the download of your product and is viewable online. Other requirements are: Compatibility: Your product must be relevant to (and usable with) Revit® 2013, and must run on any Windows operating system supported by Revit® 2013 (including 32- and 64-bit versions). Your product may be compatible with any Revit® 2013 based vertical application (i.e., Autodesk® Revit®, Autodesk® Revit® Architecture, Autodesk® Revit® Structure, and Autodesk® Revit® MEP). If it is not compatible with all Revit verticals, then please specify in your submission which Revit vertical it is compatible with. HTML help page: The documentation information you provide as part of the submission process is used to populate a standard, auto-generated HTML page. This information must allow the user to quickly understand how to use your product. You can reference additional information (for example, additional help files posted on your website) from this standard documentation documentation. The auto-generated HTML page will be populated using information you provide when submitting your product to the store – you will be prompted to supply it as part of the submission process. User privileges: The default user privilege for the store apps is Windows 7 Standard User. If your product or installer requires elevated user privileges, or if you don’t use the standard installer template we provide, then this must be very clearly documented in the description of your product displayed on the store. Ready to run: Your product must be “ready to run” as soon as it’s installed. It must not require the user to manually copy or register files, or manually edit Revit setting (such as support paths). If you use a licensing system, then it must allow your product to run as soon as it is installed by the user. This means that your application allows either instant activation (e.g., online activation), or full functionality with a time-bombed “grace period” that is long enough for you to send activation information to the customer. Product Stability: Your product should be stable, and not behave or alter the behavior of Revit in a way that we deem unsuitable (for example, blocking standard Revit functionality, blocking the functionality of another plug-in, causing data loss, etc.). Plug-ins Additional requirements for plug-ins are: You must use an add-in manifest as the loading mechanism. Your plug-in must include a ribbon button to access your main command. If your application has many buttons, you may also choose to have a separate custom ribbon tab. Family Libraries Additional requirements for family libraries are: Your Family Library must include a ribbon button to the Revit ribbon bar. The ribbon bar UI must either provide access to the family library or launch a help file explaining how to access it. Your family libraries (in rfa file format) must be installed in the following folder: Windows 7/Vista: %PUBLIC%\Documents\Autodesk\Downloaded Content (typically C:\Users\Public\Documents\Autodesk\Downloaded Content). Windows XP: %ALLUSERSPROFILE%\Documents\Autodesk\Downloaded Content (typically C:\Documents and Settings\All Users\Documents\Autodesk\Downloaded Content) Note: This is to be consistent with other Autodesk products - for a repeatable cross-product user experience (for example, when using products in a Suite). Again, we’ll create the installer for you and we can help you modify your libraries so that they work in this new location. Standalone Applications and Other Contents There are no additional requirements for products that are not integrated with Revit. If you wonder what kinds of products this might include – consider eBooks, video tutorials, industry specific calculators, connectors to Cloud based services and the like.

 

Guidelines

 

Use of the Add-in Manifest

As a default location, we’ll be using per-user location to place the add-in manifest:

%appdata%\Autodesk\Revit\Addins\2013

In addition to the add-in manifest, a folder containing all the supporting materials that your plugin-in needs will also be placed in the same location. The name of the folder is exactly the same as the name of the add-in manifest except that it has “.bundle” instead of “.addin”. e.g.:

The Add-in manifest accepts relative path in the <Assembly/> tag:

<Assembly>.\ADNPlugin-RoomRenumbering.bundle\ADNPlugin-RoomRenumbering.dll</Assembly>

In this way, your plug-in can be simply installed by copying files without requiring the add-in manifest to be modified during installation.

To see how this looks, you can download some of the free plug-ins already available on Autodesk Exchange store and study their format. For example, the following Autodesk Plugins of the Month are currently available:

• Duct Fitting Table Viewer
• Filer Upgrader
• String Search
• Wall Opening Area

Use a Registered Developer Symbol

We strongly recommend you prefix your filenames with your Registered Developer Symbol (RDS) to avoid potential naming conflict with other plug-ins. You can reserve an RDS for free at www.autodesk.com/symbolreg. (If you don’t use an RDS, and your plug-in files clash with another plug-in, then we will ask you to rename your files).

This applies to contents (such as family libraries) as well as plug-in modules.

Use the Ribbon

Using ribbon elements for your application is requirement, but how you do this will depend on your plug-in design. As a minimum, every plug-in or family library must add a panel to the ‘Add-Ins’ tab that either invokes the main command defined by the plug-in or displays a help file explaining how to use the family library.

However, if your plug-in defines more than one command, then you will have to create ribbon layout for your plug-in in a way that is most helpful to the user (for example, using large buttons for most frequently used commands and small buttons for lesser used commands).

• Plug-ins that install a single panel should normally add that panel to the ‘Add-Ins’ tab.
• Plug-ins that creates several ribbon bar panels may prefer to create a new tab specific to that Plug-In (and preferably with the Tab name being the name of the plug-in).

Use the Contextual Help (F1 Help) with a Ribbon Item

Contextual or F1 Help support is a new feature in Revit 2013 API. Please refer to the RibbonItem.SetContextualHelp() method and the ContextualHelp class in the Revit API documentation. The Autodesk Plug-in of the Month sample apps posted to the Exchange Apps store demonstarte how to implement F1 help.

We encourage you to use a help mechanism that is consistent with the Revit help, such as tooltips and contextual help placed on a ribbon item. The options supported for contextual help include linking to an external URL, launching a locally installed help file, or linking to a topic on the Autodesk help wiki.

End User License Agreement

The installer that the ADN team creates for your app includes a button that allows the user to view the standard End User License Agreement (EULA) during the app installation. This EULA is NOT modifiable. If you wish to include your own EULA to your app, you can either: 1) reference your EULA from the standard HTM help file text, or 2) display your EULA when the app runs for the first time, and require the user to accept it before the app will work.

Special Considerations

If your app or content has any special requirements and the standard installer template cannot handle as is, please talk to us. For example, we understand that for a large application, installing to all-user location may be desirable. It is possible to install at: %programdata%\Autodesk\Revit\Addins\2013.

For any other special needs that require a custom installation, you can provide them in the form of Windows Installer Merge Modules (.msm) files. We will merge your msm file with the Windows Installer (.msi) file that we create for your app. Examples of such a scenario would be: writing entries to the registry for a licensing system you are using, installing dependent components by other vendors, and running custom scripts. For additional information, please contact us at [email protected].

More information

 

The ADN team is here to help you be a successful publisher on Autodesk Exchange store. We’ll do whatever we can do to help you. You are welcome to email [email protected] if you have any further questions after reviewing these guidelines and the other documentation on www.autodesk.com/developapps.

Thank you for participating on Autodesk Apps.