Fixing mistakes - IP Rename, Delete, Obliterate, rm-from-filelist

This section describes fixing mistakes made entering Helix IPLM data, including renaming, deleting, and obliterating IPs, IP Lines, and IPVs. The pi ip rm-from-filelist command is also detailed. It can be used to remove a file from an existing IPV release to align the release with a DM level removal of an already released file.

Renaming IPs

Objects in Helix IPLM are internally referenced by their UUID (universally unique identifier) rather than their name, so it is possible to rename them as needed. One consequence of doing this arises when the old IP name is loaded in a workspace, the IP name is changed, and then the workspace is updated. The workspace behavior in this situation is described below.

Workspace with a renamed IP before update

If a workspace has an IP loaded under its old name and the IP has been renamed on the Helix IPLM server, when queried via pi ws status, Helix IPLM reports the renamed IP as having a 'Missing' status in the workspace. This status is based on the fact the IP is renamed on the server, and pi ws status checks the workspace against the new IP name. The data under the old IP directory remains in place in the workspace, and can be resolved and removed as needed. See the next section for more details.

Workspace update of a renamed IP

If an IP is loaded in a workspace, and then is subsequently renamed, a pi update on the workspace will populate the IP under the new name, but it will leave the old IP directory in place.

The old directory name will still be included in the p4 client spec (if a Perforce type IP). Because Helix IPLM doesn't track the IP rename directly, it treats the old IP name directory as a manual user modification of the p4 client, after the update there will be two lines in the workspace's p4 client View spec pointing to the same IP repo path (assuming the repo-path has not also been changed). If any unmanaged data or open data remains in the old workspace location, it should be checked in, reverted, or moved to a new location. After this is complete the old path's view entry should be manually removed from the p4 client view spec, and the old IP directory removed from the workspace.

Deleting IPs, Lines, and IPVs

Helix IPLM is a hierarchical IP management system, so some care needs to be taken when deleting IPs, IP Lines, and IPVs. Often, there are consequences to deleting IPs, since any version of any IP on any line can be used as a resource by another IP. There are two separate ways to delete IPs: delete and obliterate. Delete removes all of the IP's Lines and the IPVs on those Lines. Obliterate removes an IP, all its lines and releases from the database as if the IP never existed.

Permissions and IP, Line, and IPV deletion

Permissions needed to delete IP components are shown below:

Delete using IPLM Web

In IP details, select Delete.

Delete using CLI

IP and IP Line Delete

An IP or line in Helix IPLM can be deleted as long as

1. None of its IPVs are used by any other IP as a resource
2. None of its IPVs are loaded into a workspace
3. None of its IPVs are used in snapshots
   

The operation is atomic, if any IPV cannot be deleted, no IPVs (or Lines) will be deleted and the pi ip delete command will fail.

IPV Delete

An IPV has additional restrictions around deletion. IPVs can only be deleted if:

1. The IPV has not been used as a resource of another IPV
2. The IPV has not been loaded into a (still existing) workspace
3. The IPV is not referenced by a snapshot
4. The IPV is the latest IPV in its line (aliased by @LATEST)
5. The IPV is not at version 0
6. The IPV has not been assigned a unique alias
7. The IPV has not been assigned a moving alias, that moving alias is only set on the IPV, and that alias is referenced as resource by another IPV
8. If the user attempting the delete has only a level of permission that has been blocked for deleting IPVs by a Helix IPLM administrator.
9. The IPV has not been copied to another IP or Line
10. The IPV is not populated in IPLM Cache

The permission level required to delete an IPV is globally configurable in Helix IPLM via the pi-admin command. The required permission can be set to:

• admin only
• line write permission or greater
• line owner permission 

See the pi-admin Global Configuration page for information on configuring the permission level needed to delete an IPV.

> pi ip del -h
Usage: pi ip delete [-h] [--yes] identifier

Description: Delete an IP, Line or IPV. Deleting an IP deletes all of its
Lines and the IPVs on those Lines. When deleting a Line, all of its IPVs are
deleted. If any IPV to be deleted is a Resource of another IPV or is used in a
Workspace or Snapshot, the entire command will fail, and nothing will be
deleted. By default delete will run in dry-run mode only.

Positional arguments:
identifier Identifier of the IP, Line or IPV to delete.

Optional arguments:
--yes, -y Confirm that we want to run the command.
-h, --help Show this help message and exit

Examples:
# Delete the IP lib1.ip and all its Lines and Versions.
pi ip delete lib1.ip1

# Delete the Line lib1.ip@.LINE and all its Versions.
pi ip delete lib1.ip1@.LINE

# Delete the IP Version lib1.ip@1.LINE.
pi ip delete lib1.ip1@1.LINE

Example usage:

> pi ip delete drinks.beer
This operation cannot be reverted. Are you sure you want to proceed (yes/no)? yes
Successfully deleted IP drinks.beer

Obliterating IPs

Often IPs need to be deleted that do not meet the conditions above. For example, an IP that has been created and accidentally used before it can be deleted. In these cases, Helix IPLM has a special admin-only operation called 'obliterate'. Obliterate removes an IP, all its lines and releases from the database as if the IP never existed. It modifies all IPs that use this IP as a resource (without creating new versions of those IPs). There is one requirement for obliterating IPs

1. It cannot be loaded into a workspace

Thus, to obliterate an IP, users need to delete workspaces associated with the IP. IPs can only be obliterated at the IP, not the line level.

> pi ip obliterate -h
Usage: pi ip obliterate [-h] [--yes] identifier

Description: Obliterate an existing IP. This is a permanent deletion. This
command is a more powerful form of the "delete" command. It can only be run by
Helix IPLM admins. This command can be used to delete IP under most
circumstances - even if the IP has been used as a
resource by another IP. Obliterating an IP will fail if there is an existing
Workspace in the system that includes an IPV from that IP. The Workspace must
be removed manually first before the IP can be obliterated. By default
obliterate will run in dry-run mode only and report its effect on other IPs in
the system

Positional arguments:
  identifier  Identifier for IP

Optional arguments:
  --yes, -y   Confirm that we want to run the command.
  -h, --help  Show this help message and exit

Examples:
# Obliterate IP proj.adc1
  pi ip obliterate proj.adc1

Example usage:

> pi ip obliterate tutorial.trc
The IP 'tutorial.trc' is not used by any top level IP.
The IP 'tutorial.trc' is not used in any Workspace.
This was report mode. Rerun with --yes to obliterate IP 'tutorial.trc'.
> pi ip obliterate tutorial.trc --yes
The IP 'tutorial.trc' was obliterated from Helix IPLM.

Removing a File from a Released Filelist

It is sometimes necessary to remove a particular file from the filelist of already released IPVs. Usually this is because the file has been obliterated by the 'p4 obliterate' command and is no longer present in the Perforce repo.

In the case of 'p4 obliterate' having been run on the file at the DM level, if the file is missing Helix IPLM commands involving that release may fail or behave unpredictably. Helix IPLM provides the 'pi ip rm-from-filelist' command to bring the existing releases on a particular line back into alignment with the data in the DM system.

If no line is provided to the command it will assume TRUNK. Omitting the file version will remove all file versions.

> pi ip rm-from-filelist -h
Usage: pi ip rm-from-filelist [-h] [--yes] identifier file

Description: Remove a file from the filelists of IPVs on a Line. This is an
irreversible command that changes otherwise immutable information in existing
IP Versions. It can only be run by Helix IPLM admins. It is intended for use
only when a file has been 'obliterated' from the DM repository.

Positional arguments:
  identifier  Identifier of an IP or an IP Line. Line defaults to TRUNK if it
              is the only Line.
  file        Full repository path to the file to be removed. To remove a
              specific version of a file, append #<version>.

Optional arguments:
  --yes, -y   Confirm that we want to run the command.
  -h, --help  Show this help message and exit

Examples:
# Dryrun to remove version 1 of a file from IPVs in the A1 line of proj.adc1
  pi ip rm-from-filelist proj.adc1@.A1 //depot/proj/adc1/trunk/myfile#1

# Remove all versions of a file from IPVs in the TRUNK line of proj.adc1
  pi ip rm-from-filelist proj.adc1 //depot/proj/adc1/trunk/myfile --yes

Note:  'pi ip rm-from-filelist' modifies otherwise immutable Helix IPLM releases, so it should be used sparingly, and is only available to Helix IPLM administrators.