Request

Response

    Task 3 – Upload an AppBundle to the Automation Service

    An AppBundle is a zipped folder containing the TypeScript file. The file is saved to a specific structure, and is accompanied by a file named PackageContents.xml, which describes the content of the folder.

    A script uses the Fusion API to add new functionality to Fusion in the form of custom commands.

    Information on how to create a Fusion script, can be found here.

    For information on creating, debugging, and remotely running an Automation API-ready Fusion TypeScript script, see TypeScript.

    By the end of this task you will be able to:

    • Describe what an AppBundle is.
    • Explain the role of PackageContents.xml file
    • Upload an AppBundle to the Automation Service.
    • Create an alias for a version of the AppBundle.

    You will use the following operations to handle AppBundles in this task:

    HTTP RequestDescription
    POST /appbundles Registers a new AppBundle.
    POST /appbundles/{id}/aliases Creates a new alias for the AppBundle.
    POST /appbundles/{id}/versions Creates a new version of the AppBundle.
    PATCH /appbundles/{id}/aliases/{aliasId} Modify alias details.
    • More information on AppBundles can be found here.

    Step 1 - Download or build an Fusion AppBundle

    • Download the AppBundle, ConfigureDesign.zip from here.

    Step 2 - Understand the Structure of the AppBundle

    A Fusion AppBundle is a zipped package of a TypeScript file stored according to a specific structure. The following code block shows the structure of the AppBundle ConfigureDesign.zip, which you downloaded in Step 1.

    ConfigureDesign.zip
    |-- ConfigureDesign
    |   |-- PackageContents.xml
    |   |-- Contents
    |   |   |-- main.ts
    

    FileDescription
    PackageContents.xml Contains a description of the add-in, including the GUIDs and relative path to the add-in. For more information on PackageContents.xml, see PackageContents.xml Format Reference
    main.ts The TypeScript file that will be executed with the fusion api

    Step 3 - Register the AppBundle

    Before you upload the AppBundle to the Automation Service, you must register the AppBundle.

    • Register an AppBundle named ConfigureDesignAppBundle as per the following example. It uses the latest Fusion engine as the target engine:

    Request

    curl -X POST \
      'https://developer.api.autodesk.com/da/us-east/v3/appbundles' \
      -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
      -H 'Content-Type: application/json' \
      -d '{
            "id": "ConfigureDesignAppBundle",
            "engine": "Autodesk.Fusion+Latest",
            "description": "My first fusion appbundle based on the latest Fusion engine"
          }'
    
    Show More

    AttributeDescription
    id The name given to the AppBundle.
    engine The engine that the AppBundle must be loaded on; Fusion latest in this case. For more information on engine aliases, see the Additional Notes section at the bottom of this page.

    Response

    {
        "uploadParameters": {
            "endpointURL": "https://dasprod-store.s3.amazonaws.com",
            "formData": {
                "key": "apps/<YOUR_NICKNAME>/ConfigureDesignAppBundle/1",
                "content-type": "application/octet-stream",
                "policy": "eyJleHBpcmF0aW9uIjo... (truncated)",
                "success_action_status": "200",
                "success_action_redirect": "",
                "x-amz-signature": "27e07941f952... (truncated)",
                "x-amz-credential": "ASIATGVJZKM3N... (truncated)",
                "x-amz-algorithm": "AWS4-HMAC-SHA256",
                "x-amz-date": "20191128T083159Z",
                "x-amz-server-side-encryption": "AES256",
                "x-amz-security-token": "IQoJb3JpZ2luX2VjEGgaC... (truncated)"
            }
        },
        "id": "<YOUR_NICKNAME>.ConfigureDesignAppBundle",
        "engine": "Autodesk.Fusion+Latest",
        "description": "Change Parameters AppBundle based on the latest Fusion engine",
        "version": 1
    }
    
    Show More

    AttributeDescription
    endpointURL The URL you must upload the AppBundle zip file to.
    version The version number of the AppBundle created by the POST request. For new AppBundles, the returned version is always 1.
    formData The form data that must accompany the AppBundle when you upload it to endpointURL. formData expires in 3600 seconds.

    Step 4 - Upload the AppBundle

    Upload the AppBundle to the signed URL returned by endpointURL in the previous step.

    curl -X POST \
      'https://dasprod-store.s3.amazonaws.com' \
      -H 'Cache-Control: no-cache' \
      -F key=apps/da4fusion_app/ConfigureDesignAppBundle/1 \
      -F content-type=application/octet-stream \
      -F policy=eyJleHBpcmF0aW9uIjoi... (truncated)  \
      -F success_action_status=200 \
      -F x-amz-signature=27e07941f952d73d57eca... (truncated)  \
      -F x-amz-credential=ASIATGVJZKM3NNGDUZMR/20191128/us-east-1/s3/aws4_request/ \
      -F x-amz-algorithm=AWS4-HMAC-SHA256 \
      -F x-amz-date=20191128T083159Z \
      -F x-amz-server-side-encryption=AES256 \
      -F 'x-amz-security-token=IQoJb3JpZ2luX2VjEGgaCXVzLWVhc3QtMSJ... (truncated) ' \
      -F success_action_redirect= \
      -F file= @path/to/your/Script/ConfigureDesign.zip
    
    Show More

    Note: Ensure that all the form-data from the Register AppBundle response is included in your request.

    Step 5 - Create an alias for the AppBundle

    When you registered the AppBundle in step 2, it was registered as version 1 of the AppBundle. In this step, you create an alias named my_working_version to reference that version. You can think of the alias as a tag that points to a version of an AppBundle.

    curl -X POST \
      'https://developer.api.autodesk.com/da/us-east/v3/appbundles/ConfigureDesignAppBundle/aliases' \
        -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
        -H 'Content-Type: application/json' \
        -d '{
              "version": 1,
              "id": "my_working_version"
            }'
    
    Show More

    Note:

    If you make changes to the AppBundle later, you must register it as a new version and then upload it. You can then update the alias to point to the newer version of the AppBundle. Consequently, endpoints referencing the AppBundle using the alias get access to the updated version of the AppBundle.

    Additional notes

    Auxiliary files in Contents

    Besides main.ts and other TypeScript modules, you can include JSON, CSV, images, and similar files under Contents/. They are not transpiled as modules. On the Automation Service worker, read them from your script using the read-only appbundle:// URI scheme so you do not depend on version-specific deployment paths. See Auxiliary Files in AppBundles in the TypeScript developers guide.

    Notes on Engines

    • Each AppBundle POST request specifies an engine on which the application runs. The following table shows the keywords to specify for the available Fusion engines.
    • It is recommended to always choose the Autodesk.Fusion+Latest engine.
    • In rare cases, you might want to access an older engine version. You can obtain the list of available engines using the operation listed here.

    Notes: