20 Oct 2021

localName, pathInZip, zip

Often there is a bit of confusion around how the localName attribute of an input/output parameter is being used exactly. The main purpose of it is to enable your app bundle to access input and output files in a consistent way: no matter what the original file is called on the cloud storage, locally, in the current directory used by the running work item, they will be available using the name you provide in the localName parameter - see picture on top showing that though in the cloud storage the file is called input2.ipt, it will be downloaded to the Design Automation server as input.ipt and that's how your app bundle will be able to find it and open it. 

If you pass the file name in the commandLine (e.g. /i \"$(args[input].path)\") then you might not need to set localName since Design Automation will resolve the correct path for you. If you don't provide a localName then the name in the URL used to access the file will be used. 

If you want to pass the path of a file from an input zip inside the commandLine attribute, then you'll also need to provide the pathInZip attribute which will be appended to the path of the folder where the zip will be extracted.


In the case of a zip file (zip: true), the localName will provide the name of the folder the contents of the zip file should be extracted to - see Open file from zip

There is also a useful table on the relationship between the zip and pathInZip attributes of input/output parameters here in the argumentsXrefTreeArgument > pathInZip section: https://forge.autodesk.com/en/docs/design-automation/v3/reference/http/workitems-POST/#body-structure 

One thing that sometimes people miss is that an output parameter can also be set as zip: true. In that case, Design Automation will look for a folder in the Current Directory being used by the work item with the name that you provided in the localName attribute and will zip up its contents before uploading it to the url that you provided. In the above example, you can see that we use the same folder name for both the input and output zip file. So when the work item starts the zip file gets extracted to the folder named input, and once the app bundle code finished, the same folder will be zipped up and uploaded to the url we provided. 

Worth noting that localName can be overridden in the work item parameters list. So if each time you are working with a different file and you need to keep that file name even while working with it on Design Automation, that is possible too. 

Related Article