Aliases and IDs
AppBundle and Activity Aliases
In order to be able to use a version of an AppBundle or an Activity, you have to specify an Alias for it. You can view an Alias as a user-friendly name for a specific AppBundle and/or Activity version.
There is no need for a 1-to-1 mapping between versions and Aliases. You can have many versions of an AppBundle and/or Activity and only some of these versions can have an Alias assigned to them.
Also, you can re-assign an existing alias to a different version at any time. This gives you the flexibility to swap, for example, a version of an activity used within your WorkItems without the need to update each and every WorkItem.
An example of the use of Aliases is to have a “Beta” and a “Production” Alias for an AppBundle/Activity. The “Production” Alias is assigned to your stable version of an AppBundle/Activity and the “Beta” Alias is assigned to a newer version of the same AppBundle/Activity. When the “Beta” version becomes stable, you assign the “Production” Alias to this newer version of the AppBundle/Activity.
$LATEST alias
For every AppBundle and Activity, the system always creates a special Alias named “$LATEST”. The main purpose of this Alias is for listing AppBundles and Activities. It can also be used in
- [GET] /appbundles/:id/aliases/$LATEST
- [GET] /activities/:id/aliases/$LATEST
calls. Note however, that it must not be used in other calls where an Alias (as part of fully qualified id, see later) is expected. You must use the real Alias that you created for the AppBundle or the Activity in those calls.
IDs
An ID (id) is a user friendly name you provide for your AppBundle or Activity when you POST them for the first time.
In later calls, you use the id to refer to that AppBundle and/or Activity. Note that the Design Automation API distinguishes between two kinds of such ids:
Unqualified id
Unqualified id is the single string you used during the POST request creating the AppBundle or the Activity.
Fully qualified id
Fully qualified ids consist of three parts:
- your app’s Client ID or its nickname, followed by a period ‘.’
- your AppBundle’s or Activity’s unqualified id, followed by a plus sign ‘+’ and
- the Alias (as described in the above Alias section)
For the nickname, this can be up to 20 characters long consisting of a-z, A-Z, 0-9 and _ (underscore) only.
AppBundle, Activity, Version and Alias names can be up to 40 characters long.
For example, an Inventor App shares an Activity named “Configuration” to other users. “Configuration” is the unqualified id of that Activity. Its fully qualified id is “Inventor.Configuration+prod”, for its production version, and “Inventor.Configuration+Beta” for it’s newer beta version (when there is one).
What form of id to use
Check HTTP Specification pages to find out the correct form of id (unqualified or fully qualified) to be used in a specific call.
As a general rule, you typically use an unqualified id when it is part of a URL or in the request body when creating the AppBundle and/or the Activity (i.e. when the Alias is not known yet). The only exception when a fully qualified id is expected in the URL is the GET call for the AppBundle or the Activity details ([GET] /appbundles/:id and [GET] /activities/:id).
A fully qualified id is returned in most calls that include the id in the response. If an Alias has not been assigned to the AppBundle/Activity yet, the response will contain a fully qualified id without the third part (the Alias).
The fully qualified id is often referred to as “(owner.name+label)” in the HTTP Specification .