Adding an Entity

How to help users add a new entity or space accurately and successfully

The UI pattern for Add new project is a unique onboarding experience and will be excluded here.

In Octopus, our users rely on creating spaces, projects and related entities in order to run their deployment processes smoothly and efficiently.

Whether it’s adding a new user, space, project, certificate or account, users need to create and manage multiple types of entities and often in a short span of time. They could also be adding multiples of the same entity. All of these factors can add up to a tedious experience.

When designing the user flow for adding a new entity, our goal is to ensure that users enter information accurately and successfully, contributing to the overall product goal of helping them achieve reliable continuous deployments.

Definitions

Projects gather all the processes, releases, and runbooks for an application or service. “Add a new project” is excluded from this UI pattern as it relies on a unique onboarding component.

An entity is anything that is not a project, and could be: a process, release, runbook, account, variable, credential, environment, feed, package, etc.

Spaces are the home of projects, releases, runbooks and entities specific to them.

The user journey for adding a resource typically, if not always, starts from an Add or + button in the interface.

Best practices

General

Help the user scan content in sections or pages

Avoid crowding the user’s mental load with too many fields or items to consider, as they may miss details, be unsuccessful and abandon the workflow

Keep the experience aesthetic and usable, to help the user follow the entire user journey

Do not disable buttons until the form is filled, as it creates an accessibility issue that something is blocked and the user won’t understand why. Instead, show error states upon saving if the form has been incorrectly filled.

Microcopy

Be clear and concise about the data the user needs to fill in

The title of the component should always describe what the user is adding, e.g. “Add Git Credential”

Forms

Input field labels should be short and descriptive, as per the form structure guidelines

Input field placeholders should show an example of the input, e.g. GitHub URL

Button microcopy guidelines should be observed

Form guidelines should be observed

Autosaving

We do not currently provide autosave functionality in our forms, but this is a desired future state.

High level addition flow

All addition flows should follow the high level journey as illustrated below.

The user journey usually starts from a page where the user can add the entity using one of the solutions listed below, and concludes with informing the user of success, error and abandonment.

Flowchart of a user journey from navigating to a page, adding an entity and the possible outcomes

High level user journey for adding an entity

Types of addition flows

When selecting the type of addition flow, consider:

Number of entities to choose from, whether single or multiple

Density of information, whether it requires denser fields to complete or can be lightweight with just a few fields

The components below describe how each pattern is used, not their layouts or visual design. For more on those, please go to their respective component guides.

Adding a single entity

Artwork for a dialog with a few form fields

The user adds a single entity with a few fields using a dialog

Number of entities to choose from	One
When to use	Adding a singular entity with a form; for longer forms, consider the On-page (Single)
Can contain	Title, description, form fields, buttons, multiple steps
Example	A new runbook needs to be added, with a few fields to start.
User flow	The user fills in details in the dialog to continue or finish the journey.

Artwork for a single page form with multiple fields and dense help text

The user adds a single entity that contains more than a few fields, with dense help text

Number of entities to choose from	One
When to use	Similar to Dialog (Single) but with a higher amount of fields with dense information.
Can contain	Title, description, form fields, buttons, multiple steps
Example	A new scheduled trigger needs to be added, with 5+ fields that have contextual information near the fields.
User flow	The user fills in details in the page to continue or finish the journey.

Artwork for a drawer interface with multiple fields and buttons

The user adds a secondary entity to an existing entity they are already in the process of adding

Number of entities to choose from	One or multiple
When to use	Adding another entity to an existing entity
Can contain	Title, description, form fields, buttons
Example	When an account is being added to a new step in the Process Editor; the new step is the primary entity being added, and the account is the secondary entity.
User flow	The user adds details for a new secondary entity and continues via the page below the drawer for the primary entity.

Adding multiple entities

Artwork for an interface with a dropdown containing a few items

The user chooses from multiple entities that have self-explanatory titles and brief descriptions

Number of entities to choose from	Multiple
When to use	Adding multiple types of resources that can be explained with just a label per type
Can contain	Title, one-line description
Example	A new account needs to be added from a list. Each account may vary in the number of fields needed. The accounts in the dropdown have self-explanatory labels and do not need further explanation.
User flow	The user selects an entity from the dropdown and progresses to either Dialog (Single) or On-page (Single) to fill in the details.

Artwork for a dialog with a grid of images and text

The user chooses from multiple entities using a dialog

Number of entities to choose from	Multiple
When to use	Adding multiple types of entities in a grid
Can contain	Title, description, a grid of icons, titles and descriptions, multiple steps
Example	A new trigger needs to be added, with multiple types of triggers to choose from.
User flow	The user selects an entity from multiple types and progresses to either Dialog (Single) or On-page (Single).

Artwork for a page containing tabs and a grid of images and text

The user chooses from multiple entities and tabs

Number of entities to choose from	Multiple
When to use	Similar to Dialog (Multiple) but with an extra layer of organization of the entities, e.g. categories or tabs
Can contain	Title, description, tabs, a grid of icons, titles and descriptions, multiple steps
Example	A new step template needs to be added, with multiple categories to consider.
User flow	The user selects an entity from multiple types and progresses to either Dialog (Single) or On-page (Single).

Choosing the most appropriate solution

To help you decide which approach is most appropriate, here’s a decision tree with checkpoints on:

Type and number of entities being added

Density of information in the form fields

Whether light organization of the entities is required

This decision tree is not foolproof, however. You may still come across patterns in existing workflows that can be substituted by another.

Flowchart for decision tree of which component to use for adding an entity

Form degradation

These are examples of cases where a critical system error is preventing the flow from working as intended. In all cases, best practices for error handling should be followed.

Server degradation

If the user is trying to submit the form but it cannot be saved, do not clear the form fields or disable the button. Instead, retain the form information and inform the users via a callout explaining the form cannot be saved.

No form data is available

If the form is not available, do not show the form fields or buttons. Instead, show an empty state explaining why the form is unavailable.

More information on server-side and client-side validation can be found in Forms UI pattern.

Form success

Once the form has been successfully submitted, clear the form and communicate success on the page.