Labels
Labels are string identifiers that can be attached to IPs and Libraries. Labels are used to provide a taxonomy for organizing IPs and Libraries in their respective catalogs and can be used to filter results both on PiCLI and IPLM Web. Labels can be assigned a color which will be displayed on IPLM Web.
Labels are pre-defined by an administrator. Users can pick from a list of available labels and attach these to specific IPs or Libraries. Note that both IP and Library labels share the same set of labels, so the same label can be applied to both Libraries and an IPs.
Once applied, Labels can be used to filter the IP catalog both in IPLM Web and in PiCLI, supplying multiple labels filters the catalog by all the labels supplied.
Label configuration fields
| Configuration Option | Required | Description |
|---|---|---|
| name | Required |
|
| description | Optional | A description of the Label |
| color | Optional | The color to use to display the Label in IPLM Web |
| icon | Optional | The icon to use when displaying the Label in IPLM Web (not currently used) |
Permissions and Labels
| Function | Permission Level | Other Requirements |
|---|---|---|
| Label Creation | Administrator | No other label with the same name exists |
| Label Deletion | Administrator | The label isn't attached to any IP or Library |
| Label Edit | Administrator |
|
| Label List | None |
|
| Label Attach/Detatch | Write Permission on the IP or Library |
|
Administering Labels from IPLM Web
Open the Labels page in Administration->Labels.
Creating a new Label
To create a new Label click the Create New Label button.
Add a name for the label and select a color.
Click Save to save the label. The new label is now ready to apply to IPs, see the Applying Labels section below.
Editing existing Labels
Labels are managed on the Labels page under Administration->Labels.
To edit a Label, select one of the existing labels.
In the Editing area of the form, you can change the name of the label (IPs with the label will be unchanged), and change the color of the label.
Click Save to save the label. The edited label can be applied to IPs, see the Applying Labels section below.
Delete a Label
Clicking the selector opens the Labels page. To delete a Label, select one of the existing labels and click the Delete button:
Applying Labels
First Add or Edit the IP you wish to add the label to. On the Add or Edit IP form add the desired labels to the Labels field. Library labels are applied from PiCLI.
Command line
Labels can be managed on the command line using the 'pi label' command.
> pi label -h Usage: pi label [-h] SUBCOMMAND ... Description: Manipulate and list Labels. The Helix IPLM database does not impose any particular hierarchy and Labels can be used to tag Library or IP objects to help organize user IP data. Labels are created by admin users from the command line or from the Web interface. Optional arguments: -h, --help Show this help message and exit Available sub-commands: SUBCOMMAND add Create a new Label. attach Attach an existing Label to a Library or an IP. delete Delete an existing Label (remove from Helix IPLM). detach Detach a Label from a Library or an IP. edit Edit an existing Label. list (ls) List all matching Labels
Adding Labels
The 'pi label add' command brings up a template form that can be filled out to configure the label.
Note
> pi label add -h
Usage: pi label add [-h] [--template TEMPLATE | identifier]
Description: Create a new Label. Only admin users can create Labels. The
command puts the Label specification into a temporary file and invokes the
editor specified by the EDITOR environment variable. Saving the file adds the
Label.
Positional arguments:
identifier Name of the Label being created.
Optional arguments:
--template TEMPLATE, -t TEMPLATE
Use the specified template to add the Label. The
template is an ASCII file that defines the Label. This
can be used to add Labels with a script and avoid the
interactive editor. To read the template from STDIN,
set TEMPLATE='-'.
-h, --help Show this help message and exit
Examples:
# Create Label top_level
pi label add top_level
Deleting Labels
The 'pi label delete' command is used to remove labels that have been added to Helix IPLM. By default if the label has been attached to any IP or Library, Helix IPLM will block the label delete. Use the `–force` option to override this behavior and proceed with the label delete.
> pi label delete -h Usage: pi label delete [-h] [--force] identifier Description: Delete an existing Label (remove from Helix IPLM). Only admin users can delete Labels. Positional arguments: identifier Name of the Label to delete. Optional arguments: --force, -f Complete delete execution (required when Label is attached). -h, --help Show this help message and exit Examples: # Delete detached Label top_level (blocked if attached) pi label delete top_level # Delete Label top_level (complete execution even if attached) pi label delete --force top_level
Editing Labels
The 'pi label edit' command is used to edit existing labels. If a template is provided via the '–template' argument any fields provided by the template will be modified. If a field of the full template is omitted, that field will remain unchanged on the label after edit. If no template is supplied via the '–template' option then a template form is provided via editor to the manually modify the label. Administrator status is required to edit labels.
> pi label edit -h
Usage: pi label edit [-h] [--template TEMPLATE] [identifier]
Description: Edit an existing Label. Only admin users can edit Labels. The
command puts the Label specification into a temporary file and invokes the
editor specified by the EDITOR environment variable. Saving the file edits the
Label.
Positional arguments:
identifier Name of the Label being edited.
Optional arguments:
--template TEMPLATE, -t TEMPLATE
Use the specified template to edit the Label. The
template is an ASCII file that defines the Label. This
can be used to edit Labels with a script and avoid the
interactive editor. To read the template from STDIN,
set TEMPLATE='-'.
-h, --help Show this help message and exit
Examples:
# Edit Label top_level
pi label edit top_level
Listing Labels
The 'pi label list' command is used to list labels that have been added to Helix IPLM.
> pi label list -h
Usage: pi label list [-h]
[--format {csv,json,long,table,template} | --verbose]
[--model MODEL]
[identifier [identifier ...]]
Description: List all matching Labels. A variety of format and filtering
options are supported.
Positional arguments:
identifier Filter Labels by name.
Optional arguments:
--format {csv,json,long,table,template}
Return the results using the specified data structure.
The template format produces files that can be used by
the pi add|edit commands with the --template option.
--model MODEL Use the specified report model (table report only).
--verbose, -v Alias for --format long.
-h, --help Show this help message and exit
Configuring the output format
Helix IPLM can display the list output in a number of different formats
| Command Option | Format | Description |
|---|---|---|
| --format | table | The default format option, a list of values in table format. |
| template | Lists the labels in the 'pi label edit' CLI template format. The template format returns at most one result, and requires an identifier. | |
| long | Displays detailed information about the label, equivalent to --verbose, -v output | |
| json | Display the list of labels in json format. Note that the Helix IPLM API should be used for scripting purposes. | |
| csv | Display the list of labels in comma separated value format. | |
| --verbose, -v |
|
Displays detailed information about the labels, equivalent to --format long output |
| --model MODEL |
|
Display a custom table format MODEL defined in piclient.conf. See here for more information on configuring display models. |
Example label list output:
> pi label list ┌────────────────────┬────────────┬───────────────────────────────┬───────┐ │ NAME │ CREATED BY │ CREATED ON │ COUNT │ ╞════════════════════╪════════════╪═══════════════════════════════╪═══════╡ │ 3rd_party │ admin │ 2020-01-27 06:59:08 -0800 PST │ 120 │ │ ISO26262_compliant │ admin │ 2020-01-27 07:19:12 -0800 PST │ 40 │ │ MS90G │ admin │ 2020-01-27 06:53:52 -0800 PST │ 60 │ │ MS90G_LP │ admin │ 2020-01-27 06:59:09 -0800 PST │ 32 │ │ analog │ admin │ 2020-01-27 06:53:51 -0800 PST │ 26 │ │ digital │ admin │ 2020-01-27 06:53:52 -0800 PST │ 6 │ │ requirements │ admin │ 2020-01-27 07:19:10 -0800 PST │ 91 │ │ project │ admin │ 2020-01-27 06:53:50 -0800 PST │ 21 │ │ shared │ admin │ 2020-01-27 06:53:50 -0800 PST │ 63 │ └────────────────────┴────────────┴───────────────────────────────┴───────┘ Found 9 matching object(s).
Attaching Labels to IPs and Libraries
Labels are attached to IPs and Libraries using the pi label attach command.
Note: To indicate whether a library or an IP is the target of a pi label attach or pi label detach command add a period to the end of Library names and supply both the library and IP name for IPs. Format Libraries as “library_name.” and IPs as “library_name.ip_name”.
> pi label attach -h Usage: pi label attach [-h] object_identifier label_identifier Description: Attach an existing Label to a Library or an IP. Positional arguments: object_identifier Library or IP to attach Label to. label_identifier Name of the Label to attach to Library or IP. Optional arguments: -h, --help Show this help message and exit Examples: # Attach Label top_level to IP foo.bar pi label attach foo.bar top_level
Detaching labels is done via the 'pi label detach' command.
> pi label detach -h Usage: pi label detach [-h] object_identifier label_identifier Description: Detach a Label from a Library or an IP. Positional arguments: object_identifier Library or IP to detach the Label from. label_identifier Name of the Label to detach from Library or IP. Optional arguments: -h, --help Show this help message and exit Examples: # Detach Label USB from Library foo pi label detach foo. USB # Detach Label top_level from IP foo.bar pi label detach foo.bar top_level
Listing IPs and Libraries using Labels
See Listing IPs in the Catalog and Listing Libraries in the System for more information on using Labels to list IPs and Libraries, and to see which labels are applied to a given IP or Library.
