Using argument "adskDebug" to troubleshot failure job of Design Automation

Debugging the Design Automation job is always a challenge since all the work is done in the cloud engine, and the Design Automation cloud sandbox will be destroyed as soon as the job is finished.

A couple months ago, our Design Automation engineering team implemented a new feature to enable the user to collect debugging info for DA jobs, this was used only by Autodesk internal users. But we found it is a very useful feature, and could help external Design Automation developers to diagnose their failed jobs much easier, so we decided to make it public to everyone. And the flag works for all the Design Automation engines.

The flag is very straightforward to be used, just add the following argument when you post your DA workitem,

"adskDebug": {
"uploadJobFolder": true
}

As one of Revit engine example, the workitem payload is like:

{
    "activityId": "Revit.RvtIOCountItActivity2022+prod",
    "arguments": {
        "rvtFile": {
                "url": "…/sample.rvt",
                "verb": "get"
            },
        "countItParams": {
                "url": "data:application/json,{'walls': false, 'floors': true, 'doors': true, 'windows': true}"
            },
        "result": {
                "url": "…/result.txt",
                "verb": "put"
            },
        "adskDebug": {
                "uploadJobFolder": true
            }
    }
}

With this argument, when the job failed, developer can get a link to a zip file by "debugInfoUrl" from the response of GET Workitem as follow for an example(it can be either found from the report log file):

Debug Info Url

By downloading the zip file, you will see it contains debugging bits, e.g. Revit journals, downloaded inputs, etc., this helps a lot to track what happened on the Design Automation cloud engine.

Debug Info

NOTE

If you'd like to enable debugging capabilities such as downloading the entire job folder after execution, you can pass an adskDebug argument to the WorkItem payload. While this feature may not yet be available in the official SDK, you can implement it yourself by creating a custom class that conforms to the IArgument interface.

This approach demonstrates how you can stay ahead of SDK rollouts by customizing and extending SDK behavior using Autodesk APS Design Automation documented payload format.

// Define the custom debug argument by implementing IArgument.
public class DebugArgument : IArgument
{
    [DataMember(Name = "uploadJobFolder", EmitDefaultValue = false)]
    public bool UploadJobFolder { get; set; }

    public override string ToString()
    {
        return JsonConvert.SerializeObject(this, Formatting.Indented);
    }
}

// Prepare the input and output arguments for the WorkItem.
XrefTreeArgument inputFileArgument = new XrefTreeArgument()
{
    Url = await GetObjectId(bucketKey, inputFileNameOSS, oauth, fileSavePath),
    Headers = new Dictionary<string, string>()
    {
        { "Authorization", "Bearer " + oauth.access_token }
    }
};

XrefTreeArgument outputFileArgument = new XrefTreeArgument()
{
    Url = await GetObjectId(bucketKey, outputFileNameOSS, oauth, fileSavePath),
    Headers = new Dictionary<string, string>()
    {
        { "Authorization", "Bearer " + oauth.access_token }
    },
    Verb = Verb.Put
};

// Construct the WorkItem payload with all required arguments, including adskDebug.
WorkItem workItemSpec = new WorkItem()
{
    ActivityId = activityName,
    Arguments = new Dictionary<string, IArgument>()
    {
        { "inputFile", inputFileArgument },
        { "outputFile", outputFileArgument },
        { "adskDebug", new DebugArgument()
            {
                UploadJobFolder = true
            }
        }
    }
};