Using IP aliases
Aliases provide a way to apply a meaningful name to particular IP releases, and enable the Moving Alias flow. Any user with write permissions on the IP Line can alias any version of that IPV to any string.
Alias naming restrictions
Alias names have the following restrictions:
- Cannot contain special characters: ".", "@", "#", "/", "\", "?", or "*"
- Cannot contain any whitespace
- Must contain at least one non-digit in order to distinguish it from a fixed release number
- The leading "+" is not included in the alias name when running
pi alias addwith the--uniqueflag - The '+' character can be used in alias names as long as it is not the first character in the alias name
Viewing existing aliases on IPLM Web
Select the IP Version in the dropdown on the navigation panel to see the Aliases on the IPVs of an IP. In the example below, tutorial@14 has the alias 'LATEST' applied, tutorial@13, tutorial@12, and tutorial@10 have no aliases applied, and tutorial@11, tutorial@7, and tutorial@6 have the 'GOLD' alias applied.
The 'LATEST' alias is always present on the most recent IPV for any given IP, and is maintained by the system. The 'HEAD' alias is also always present and maintained by the system.
Aliases visible on a particular IPV are also shown on the IP Version info tab on the Details page of each release (tutorial.tutorial@11.TRUNK [GOLD]):
Editing aliases on IPLM Web
To edit aliases, open the IPV where you want to edit the aliases, then open the IP Versions menu in the Details tab. Select the Edit aliases icon 
next to the list of aliases.
Note: Aliases can be locked and unlocked through the CLI. See Locking and unlocking an alias.
The Edit aliases window opens, and user defined aliases can be removed or added and system defined aliases can be seen.
.jpg)
Once changes are finished, you can mark the alias as Unique. Select Save.
.jpg)
Once applied, the new alias can be seen on the IP Version info tab in the Details tab:
IP aliases using CLI
It is not required for Aliases to be pre-defined. Any user with write permissions on the IP Line can alias any version of that IPV to any string. PiCLI sub-commands used to configure Aliases are under the pi alias command.
pi alias Sub-commands
> pi alias -h
Usage: pi alias [-h] SUBCOMMAND ...
Description: Commands related to Aliases. These subcommands are used to add,
delete, lock and unlock Aliases.
Optional arguments:
-h, --help Show this help message and exit
Available sub-commands:
SUBCOMMAND
add Add Aliases to IP Versions.
delete (del, remove, rm)
Remove Aliases from IP Versions.
lock Lock an Alias.
move (mv) Move an Alias to another IP Version.
unlock Unlock an Alias.
More information and documentation available at:
https://help.perforce.com/methodics/
Copyright © 2010-2024 Perforce, Inc.
Adding a new alias
> pi alias add -h Usage: pi alias add [-h] [--unique] identifier alias Description: Add Aliases to IP Versions. Positional arguments: identifier The IP Version the Alias is added to. alias The name of the alias. Optional arguments: --unique Add an alias, unique to the entire IP. -h, --help Show this help message and exit
The identifier argument is an IPV FQN (fully qualified name), ie LIB.IP@VERSION.LINE
> pi alias add LIB.IP@VERSION.LINE mynewalias Successfully added alias 'mynewalias' on 'LIB.IP@VERSION.LINE'.
Delete an existing alias
> pi alias del -h Usage: pi alias delete [-h] identifier alias Description: Remove Aliases from IP Versions. Positional arguments: identifier The IP Version the Alias is removed from. alias The name of the alias. Optional arguments: -h, --help Show this help message and exit More information and documentation available at: https://help.perforce.com/methodics/ Copyright © 2010-2024 Perforce, Inc.
The identifier argument is an IPV FQN (fully qualified name), ie LIB.IP@VERSION.LINE
> pi alias del LIB.IP@VERSION.LINE mynewalias Successfully deleted Alias 'mynewalias' from 'LIB.IP@VERSION.LINE'.
Locking and unlocking an alias
Aliases are either locked or unlocked to keep an alias on a particular IP Line from being modified (added or removed from any IPVs) or to again allow them to be modified.
> pi alias lock -h Usage: pi alias lock [-h] alias Description: Lock an Alias. A locked Alias cannot be added to or removed from any IP Version in the Line. This ensures that the current Version the Alias refers to will not change, unless the Alias is unlocked first. Positional arguments: alias The full name of the Alias. Optional arguments: -h, --help Show this help message and exit Examples: # Lock the Alias ALIAS in the lib.ip@.TRUNK line. pi alias lock lib.ip@ALIAS.TRUNK
> pi alias unlock -h Usage: pi alias unlock [-h] alias Description: Unlock an Alias. This allows users to add the Alias to (or remove it from) IP Versions of the same line again. Positional arguments: alias The full name of the Alias. Optional arguments: -h, --help Show this help message and exit Examples: # Unlock the Alias ALIAS in the lib.ip@.TRUNK line. pi alias unlock lib.ip@ALIAS.TRUNK
Alias lock/unlock example:
> pi alias lock tutorial.tutorial@GOLD.TRUNK Successfully locked Alias 'tutorial.tutorial@GOLD.TRUNK'. > pi alias add tutorial.tutorial@5.TRUNK GOLD ERROR:Client error : 400 Client Error. The Alias 'GOLD' is locked for Line 'tutorial.tutorial@.TRUNK'. > pi alias unlock tutorial.tutorial@GOLD.TRUNK Successfully unlocked Alias 'tutorial.tutorial@GOLD.TRUNK'. > pi alias add tutorial.tutorial@5.TRUNK GOLD Successfully added alias 'GOLD' on 'tutorial.tutorial@5.TRUNK'.
Unique alias examples
Unique aliases can be set on at most one IPV on one Line of a given IP. They can be moved between IPVs and Lines using the pi alias move command.
Referencing unique aliases
Because unique aliases are only set on a single IPV on a single Line of a given IP at any time, the Line of the IP is not specified when using the alias, as in when the alias is used in a list command, or when the alias is used in a resource definition. The IPV is addressed with just the Library, IP, and the unique alias like this:
LIB.IP@+UNIQUE_ALIAS
When IPVs using unique aliases are referenced (as in a pi ws st output) both the line and version referenced by the alias are displayed:
LIB.IP@+GOLD [@10.LINE3]
Modifying unique aliases
When first created, or after being moved, Unique Aliases are locked (see Locking and Unlocking Aliases above). Moving a unique alias from one IPV/Line combination to another IPV/Line combination on the IP is a two step process, as the alias first must be unlocked with the pi alias unlock command. The pi alias move command is then used to move it to a new IPV/Line on the same IP.
Moving unique aliases
To change the Unique Alias to point to a different IPV on the same or different line of the IPV use the 'pi alias move' command.
> pi alias move -h Usage: pi alias move [-h] identifier alias Description: Move an Alias to another IP Version. (This command is restricted to unique Aliases only) Positional arguments: identifier The IP Version the Alias is moved to. alias The name of the Alias. Optional arguments: -h, --help Show this help message and exit
Example alias move
> pi alias move tutorial.tutorial@4.TRUNK +RC1 ERROR:Client error : 400 Client Error. The Alias '+RC1' is locked for Line 'tutorial.tutorial@.TRUNK'. > pi alias unlock tutorial.tutorial@+RC1 Successfully unlocked Alias 'tutorial.tutorial@+RC1'. > pi alias move tutorial.tutorial@4.TRUNK +RC1 Successfully moved unique alias '+RC1' to 'tutorial.tutorial@4.TRUNK'. > pi alias move tutorial.tutorial@5.TRUNK +RC1 ERROR:Client error : 400 Client Error. The Alias '+RC1' is locked for Line 'tutorial.tutorial@.TRUNK'.
Deleting unique aliases
To remove a unique alias entirely, it must first be unlocked using pi alias unlock, then it can be deleted using pi alias delete.
> pi alias unlock tutorial.tutorial@+RC1 Successfully unlocked Alias 'tutorial.tutorial@+RC1'. > pi alias delete tutorial.tutorial@4 +RC1 Successfully deleted Alias '+RC1' from 'tutorial.tutorial@4.TRUNK'
