Calc IDs vs Persistent Calc IDs
We can access an ArupCompute calculation using its calculation ID or its UUID (aka its persistent calc ID).
What is a Calc ID?
A calculation ID is associated with a specific library version and changes each time a library is published. When you access or execute a calc by calcId, you access or execute a specific version of the calculation. If you have a script that executes calcs by calcId, you need to manually update the calcIds used in order to execute newer versions of the calcs. For a library which is published often (ex. DesignCheck), keeping track of new calcIds and continually updating different scripts and tools to match can be time consuming and inefficient.
The calcID, which is unique to each calculation version (ie. changes every time a library version is published), can be easily found in the URL of the ArupCompute Web UI
What is a Persistent Calc ID?
A calculation UUID, which is its persistent calculation ID, is a constant identifier that does not change across library versions. It is used to track a calculation across ArupCompute, even if the calculation's name, folder/namespace, inputs, description etc. change. When you access a calc by persistent calcId, you look up the latest version of a calc or a particular version of the calc based on version criteria. Using persistent calcIds can make it easier for you to write and maintain scripts, as they give you a simple way of finding and accessing new calculation versions.
The persistent calcID, or calc UUID, is unique to each calculation but remains constant across library versions. It can be easily found on the ArupCompute Website in the information tab of each calculation:
Not all ArupCompute calculations have a persistentCalcID yet (most DesignCheck calculations do though). We're currently reviewing the libraries and calcs with no persistent IDs and will add these where possible.
How is a persistent calc ID mapped to a specific calc version?
We can specify version criteria for the specific calc we want to look up by providing major, minor and patch version information. If no version criteria is provided, ArupCompute will lookup the latest stable version of a calculation by default. Persistent calc IDs cannot be be used to access beta versions of a calculation since these are WIP calcs that change frequently (ie. not versioned as stable calcs are).
Consider the diagram below. ArupCompute uses semver for version numbering. A change in major version generally involves breaking changes and a bump in minor version generally corresponds to added functionality without breaking changes. Say we have a script set up to specifically use the 1.0.x version of our calculation (ie. it's compatible with patch changes). Combining our persistent calcId (b408ee23-2cfb-32fa-a107-4606a70b6069) with a major version of 1 and minor version of 1 maps to the calcId (4002566) for the latest v1.0.0 calc (in library version 107.0.0). With persistentCalcId and our version criteria, we can make sure we fetch and execute only the latest calc with a major revision of 1 and minor version of 1 (ignoring newer versions of the calc if they exist).
If no version criteria is provided, ArupCompute will access and/or execute the latest version of a calculation by default.