App

An appbundle is the package of binaries and supporting files which make your Revit Addin application.

Appbundle Structure

Design Automation API for Revit expects your appbundle to be a zip file with certain contents. Here is the zip file for a sample appbundle called DeleteWallsApp.zip:

DeleteWallsApp.zip
|-- DeleteWalls.bundle
|   |-- PackageContents.xml
|   |-- Contents
|   |   |-- DeleteWalls.dll
|   |   |-- DeleteWalls.addin

The top-level folder needs be named *.bundle. In *.bundle put a PackageContents.xml file that contains the description of the appbundle and the relative path to its .addin file.

<?xml version="1.0" encoding="utf-8" ?>
<ApplicationPackage>
  <Components Description="Delete Walls">
    <RuntimeRequirements OS="Win64" 
                         Platform="Revit" 
                         SeriesMin="R2018" 
                         SeriesMax="R2018" />
    <ComponentEntry AppName="DeleteWalls" 
                    Version="1.0.0" 
                    ModuleName="./Contents/DeleteWalls.addin" 
                    AppDescription="Deletes walls" 
                    LoadOnCommandInvocation="False" 
                    LoadOnRevitStartup="True" />
  </Components>
</ApplicationPackage>

Note: SeriesMin and SeriesMax both refer to Revit 2018 as R2018. As of September 2018, Design Automation for Revit supports appbundles which run on Revit R2018 and R2019.

In the *.bundle\Contents folder, put the addin file and the application DLL and its dependencies.

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="DBApplication">
    <Name>DeleteWalls</Name>
    <Assembly>.\DeleteWalls.dll</Assembly>
    <AddInId>d7fe1983-8f10-4983-98e2-c3cc332fc978</AddInId>
    <FullClassName>DeleteWalls.DeleteWallsApp</FullClassName>
    <Description>"Walls Deleter"</Description>
    <VendorId>Autodesk</VendorId>
    <VendorDescription>
    </VendorDescription>
  </AddIn>
</RevitAddIns>

Note: Type must be DBApplication. Design Automation for Revit doesn't support applications that need Revit's UI functionality.

Assembly must be a relative path to the DLL.

Examples of the format for the *.bundle folder and PackageContent.xml file can been found in the presentation on Autodesk Exchange Revit Apps here. While PackageContents.xml from existing Autodesk Exchange Revit apps can be used as-is, Design Automation for Revit only reads the RuntimeRequirements and ComponentEntry blocks which are circled in the image below.

Publish an Appbundle

APIs for app

This page explains the following appbundle APIs:

• Command – Endpoint URL – Description
• POST – /v3/appbundles – Creates a new app.
• POST – /v3/appbundles/{id}/aliases – Creates a new alias for this app.
• POST – /v3/appbundles/{id}/versions – Creates a new version of the app.
• PATCH – /v3/appbundles/{id}/aliases/{aliasId} – Modify alias details.

The base URL is https://developer.api.autodesk.com/da/us-east.

More APIs for app can be found here.

Create a New App

To publish your appbundle to Design Automation, you need to POST your appbundle's identity and upload its package.

This example creates a new app DeleteWallsApp by posting its identity. The target engine of Revit running in Design Automation for this example app is Revit 2018.

curl -X POST \
  https://developer.api.autodesk.com/da/us-east/v3/appbundles \
  -H 'Authorization: Bearer LongStringAccessTokenObtainedDuringAuthenthication' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DeleteWallsApp",
  "engine": "Autodesk.Revit+2018",
  "description": "Delete Walls app based on Revit 2018"
}'

• id – The name given to the new app.
• engine – The engine running in Design Automation used by the app.

Response

{
  "uploadParameters": {
    "endpointURL": "https://dasdev-store.s3.amazonaws.com",
    "formData": {
      "key": "apps/Revit/DeleteWallsApp/1",
      "content-type": "application/octet-stream",
      "policy": "eyJleHBpcmF0aW9uIjoiMjAxOC... (truncated)",
      "success_action_status": "200",
      "success_action_redirect": null,
      "x-amz-signature": "6c68268e23ecb8452... (truncated)",
      "x-amz-credential": "ASIAQ2W... (truncated)",
      "x-amz-algorithm": "AWS4-HMAC-SHA256",
      "x-amz-date": "20180810... (truncated)",
      "x-amz-server-side-encryption": "AES256",
      "x-amz-security-token": "FQoGZXIvYXdzEPj//////////wEaDHavu... (truncated)"
    }
  },
  "engine": "Autodesk.Revit+2018",
  "description": "Delete Walls app based on Revit 2018",
  "version": 1,
  "id": "YourNickname.DeleteWallsApp"
}

• endpointURL – This is the URL to which you must upload your app's ZIP file.
• version – The version number for the app created by the POST request. For the Post request creating a new app, version always returns 1.
• formData – The form data that needs to be sent back when uploading the file in the following POST request.

Upload app zip file

Now you can upload your app's ZIP to the signed URL returned by endpointURL:

curl -X POST \
  https://dasdev-store.s3.amazonaws.com \
  -H 'Cache-Control: no-cache' \
  -F key=apps/Revit/DeleteWallsApp/1 \
  -F content-type=application/octet-stream \
  -F policy=eyJleHBpcmF0aW9uIjoiMjAxOC... (truncated) \
  -F success_action_status=200 \
  -F x-amz-signature=6c68268e23ecb8452... (truncated) \
  -F x-amz-credential=ASIAQ2W... (truncated) \
  -F x-amz-algorithm=AWS4-HMAC-SHA256 \
  -F x-amz-date=20180810... (truncated) \
  -F x-amz-server-side-encryption=AES256 \
  -F 'x-amz-security-token=FQoGZXIvYXdzEPj//////////wEaDHavu... (truncated)' \
  -F 'file=@path/to/your/app/zip'

This is a curl example. You can use other way, e.g. Postman, to do the uploading. Just remember to include all form-data in your request.

Create an Alias for the App

The new version of your app will be referenced via an alias.

This example creates an alias with id test. This alias labels version 1 of app DeleteWallsApp.

curl -X POST \
  https://developer.api.autodesk.com/da/us-east/v3/appbundles/DeleteWallsApp/aliases \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer LongStringAccessTokenObtainedDuringAuthenthication' \
  -d '{
      "version": 1,
      "id": "test"
    }'

Update an Existing App

Create a New Version Number

To update an existing app, you need to create a new version for the app and then upload the updated zip package.

If you still do the Post request for creating a new app above , you will get a 409 Conflict error.

This Post creates a new version for the app DeleteWallsApp.

curl -X POST \
  https://developer.api.autodesk.com/da/us-east/v3/appbundles/DeleteWallsApp/versions\
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer LongStringAccessTokenObtainedDuringAuthenthication' \
  -d '{
      "id": null,
      "engine": "Autodesk.Revit+2018",
      "description": "Delete Walls app based on Revit 2018 Update"
    }'

Response

{
    "package": "https://dasprod-store.s3.amazonaws.com/appbundles/xxxxxxxx",
    "engine": "Autodesk.Revit+2018",
    "description": "Delete Walls app based on Revit 2018",
    "version": 2,
    "id": "YourNickname.DeleteWallsApp"
}

The response to the app version post includes:

• package – This is the signed URL to which you must upload your updated app package ZIP file.
• version – The new version number for the app created by the above POST request.

Now you can upload the updated app's zip file to the new signed URL returned by package same as above.

Assign an existing alias to another version of an app

You can update an existing alias to point to another version of an app.

For example, after you post a new version of an app, you may wish to assign an existing alias to point to that new app's version.

Here is an example where alias test labels version 1 of an app DeleteWallsApp. A new version 2 has been posted for this app, but no alias labels version 2:

• id – alias – version
• DeleteWallsApp – test – 1
• DeleteWallsApp – n/a – 2

You can reassign alias test to label app version 2:

• id – alias – version
• DeleteWallsApp – n/a – 1
• DeleteWallsApp – test – 2

To update the alias, you can either

• Delete the existing alias and recreate it with the version which you want to label.
• Do a PATCH request:

curl -X PATCH \
  https://developer.api.autodesk.com/da/us-east/v3/appbundles/DeleteWallsApp/aliases/test \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer LongStringAccessTokenObtainedDuringAuthenthication' \
  -d '{
      "version": 2
    }'

Engine Version Aliases

Each app POST request specifies the engine on which the application will run. Different Design Automation engine version aliases correspond to different releases of Revit. The specified engine needs to be compatible with your app's PackageContent.xml SeriesMin and SeriesMax.