Posted by & filed under Communication.

This blog post explores introductory concepts and investigations around the use of Labels in managed systems. It focuses principally on the topic of label creation. One of the goals of this blog post is to surface additional requirements and areas of concern. Known “Open Issues” are listed at the end of the document. Please leave comments with any questions or suggestions that you might have, thank you!

Overview

A label is user-defined text that is associated with a managed resource. Labels support richer search and filter options. They are not intended to be unique identifiers, like resource ID’s. Many resources can, and often do, have the same labels applied to them.

Labels enable users to identify and associate resources according to their own model, rather than that of the organization or the semantics of a system. In non-hierarchical systems, labels are a particularly useful tool. They allow users to make associations among resources where explicit object associations might not exist.

  • Use case example:
    A user needs to label resources, that are located in different physical locations, in order to manage maintenance work across these locations. The user creates or selects labels and applies them to the resources. They can then filter by label to the specific servers that they need to manage.

Conceptual Design

The label is a text string, formatted as a key-value pair (KVP). It is presented in the UI as a “key name” preceding a colon separator, followed by a “value” text string after the colon. The use of a colon as a delimiter should be configurable, by the software, to support other technologies.

  • Example:
    Name:Value

There is no requirement to represent a hierarchy or an ordered pairing. The text string could be seemingly arbitrary.

  • Example:
    Fish:Dog = Valid entry

Although whether the text is assigned to a “key name” or a “value” does matter.

  • Example:
    “Dog:Fish” is not equivalent to “Fish:Dog”

Labels that share the same key name may implicitly or explicitly form an association. Using a consistent set of key names makes it easier to identify and manage resources. The onus is on the user to create a consistent set of labels to best support their work-flow and resource types.

  • Examples:
    stage:dev

    stage:test
    stage:prod

Label Syntax Requirements

  • Each label must include a key-value pair delimited by “:”.
  • Labels are case sensitive.
  • Spaces are allowed.
  • Must begin and end with an alphanumeric character.
  • Special characters may be used, provided they are not used at the beginning or end of the label values.

Label Interactions

This initial pattern addresses the action of “Create.” It is intended to be one of a set of actions that will be covered in future patterns, which include:

  • Create/Delete
    Creating a label means adding the label to a stored list of labels. Delete would purge the label from the stored list of labels.
  • Apply/ Remove
    Applying a label means associating that label with a given resource. Removing a label entails removing the association with a resource, but does not purge the label from the stored list of available labels.

Create: Labels are created by entering the KVP text strings into form input boxes. One input box is used for each member of the pair. A read-only colon separates the two input boxes. Every effort should be made to ensure that these input boxes align on the same horizontal line.

Wireframes

1) Creating a new Label.
New Mockup 1

 

2) Using an existing key name and  creating a new value.

Previously created labels appear in a drop-down selection list, within the “create” labels form fields. A drop-down list is presented when a user types-in values which match an existing label. This “type-ahead” functionality is similar to: https://twitter.github.io/typeahead.js/examples/

 

New Mockup 1 copy 4

 

3) Supporting the creation of multiple labels
Users may create more than one label at a time, by clicking a “+” icon button to the right of the form fields. Clicking this button will add a new pair of empty inputs. Alternatively users may clear a label before submitting by clicking the “x” icon button to the right of the form fields.
New Mockup 1 copy

 

Submitting the form creates the label. Placement and terminology for the form submit buttons depends on the context in which the labels form elements are placed. The “Create” inputs could be used in a variety of contexts: Modal Dialogs, Wizards, Pop-up dialog, within another form and etc. Presentation details will be expanded when work around the other Labels actions, particularly “Apply,” commences.

In the interim, if the create-label action is a stand-alone form then the recommendation is to use generic Cancel/Save button labels wherever possible. If it is necessary to use a specific action label, refer to “Terminology and Wording for Action Labels” for more details: https://www.patternfly.org/styles/terminology-and-wording/#terms-and-words.

Questions/Open Issues

  • Question: Our rationale for using the term Label rather than Tag is due to the semantics of a name:value pairing. Does this resonate with others?
  • Open Issue:  Is the label “Value” a required field, or just the “Key Name? Different technologies/products seems to enforce different requirements.
  • Open Issue:  Should it be possible to “Create” a label without having to “Apply” it to a resource?
  • Open Issue:  If Delete purges the label throughout –  in a multi-user application, how do I know if others are using the label so that I don’t get a purge/cascade effect?
  • Open Issue: Additional syntax requirements:
    • * Maximum number of labels?
    • * Maximum key length—127 Unicode characters in UTF-8?
    • * Maximum value length—255 Unicode characters in UTF-8?
    • * Any reserved keys that can’t be used.
    • * Are labels specific to a user or a global-wide per resource?
  • Open Issue: Where does one go to manage all the labels (see the full list)?

8 Responses to “Let’s talk about Labels”

  1. Hey Liz,

    really great post. I’m facing a similar issue in the WildFly management console. I need a way to manage properties on resources. Just like labels properties contain a key and a value, but are normally bound to specific resources and are not meant to be used across resources. Adding new properties should be straightforward and align with the overall form L&F.

    I came across Tag Manager [1] which I found extremely helpful. It’s normally used to manage tags (single values), but you could also use it to enter labels as “key:value” and parse them later on. It also comes with support for suggestions (typeahead.js). The downside of having just one input field is that you no longer can provide separate suggestion lists for keys and values.

    Just some food for thought.

    Best
    Harald

    [1] https://maxfavilli.com/jquery-tag-manager

    Reply
  2. Matt Carrano

    In a scenario where the user is adding multiple labels at once, you might want want to consider persisting at least the “key” portion of the key:value pair. For example, a user might enter labels for a set of datacenters, datacenter: boston, datacenter:nyc, datacenter:ralsigh, etc. In this case when the user clicks the “+” button the last value entered into the key field (“datacenter” in this case) will be copied into the new field that is created. In this way the user does not need to re-enter it each time. They can of course change this value, and then that becomes the new default.

    Reply
  3. Hey Liz,

    good post! In the questions you ask if it should be possible to only create a new label, but not directly apply it. I think that both ways should be possible. In fact it should be even possible to have labels that no (end) user has set up. Let me write up some examples

    – end user can put arbitrary labels on a resource. That ususally happens by standing on a resource and then just typing away. Later the user can chose that label in the selector and apply it to other entities
    – system administrator (primus inter pares) sets up a key with a list of possible values (‘department:finance’ or ‘department:r&d’) – users can apply those labels, but can not modify them or add their own values to the values side
    – “the system” has hardcoded labels, that can be only applied but not modified. Take for example the alert subsystem that uses labels for priority and severity, where also possible reactions are triggered by evaluating the labels.

    In the later two cases it is also possible that internal and external clients process the labels. In this case it is important that they have known values, as otherwise the processing may fail. Just take the example of piority in alerts. In English one may have “priority:medium”. If now that would be free form, a German user would potentially put in “Priorität:Mittel”.

    With regards to deletion, I believe the constraints of creation apply as well. The system should In the 1st case reject deletion by default if the label is still applied. It could either be overriden via a flag “yes create havoc” or after showing a screen with usages of the label. If a label is not applied, then it could be deleted right away – even without confirmation as re-creation is cheap.

    Question is probably if in a case of one key with many values, it is possible to delete the key to delete all key-value pairs or not (I think it should delete all, if not in use).

    Heiko

    Reply
  4. Christoph Görn

    Why do you think there should be a maximum length of key or value? In the past 30 years e have made pretty bad experience with maximum (made up) sizes… like 640KB for memory

    If you need to limit it, please come up with a shortening algorithm rather than a limit.

    Reply
    • Thanks for questioning max length as a “requirement,” and offering feedback. To your point, rather than declaring requirements we could offer “ease of use” design recommendations.

      In the wireframe examples, above, the content area and the widget itself might effectively limit how much of the label can be displayed within the input field. To work within this constraint we could consider using truncation (or etc.) to support long strings. Was that what you had in mind wrt a “shortening algorithm”?

      For these user generated labels, the onus is on the user to create labels that will be meaningful and usable as a system. So perhaps rather than a max char requirement, one of the design recommendations should be to encourage the use of more succinct labels to support ease of use. Wdyt?

      Reply

Leave a Reply

(will not be published)