Extension Planning Guide

Anthony Hand, PayPal DPE UX Team

Congratulations on deciding to create a Console Extension to better serve your customers in a modern, secure web app platform. You might be asking yourself, "Now what...?"

The Console Experience

The Console is a critical platform for delivering value and customer satisfaction to support an enhanced DevOps experience at PayPal. It’s imperative that Console Extensions follow UI Guidelines during the implementation phase in order to:

• Increase quality
• Shorten delivery time
• Ensure consistent, predictable user experiences across Extensions
• Satisfy customers

Leverage the information in this guide to start planning where you'd like to go with your Extension.

Getting Started

You're not doing this alone! The good news is that you have an entire team of Console folks behind you, both on the development and UX sides. See the side bar for links to take advantage of their office hours and slack channels. Also, there's a growing collection of teams that have already developed extensions, and you can leverage their expertise.

If you haven't done so already, connect with the Console UX Team: We can save you a ton of time and potentially wasted effort. We can help you explore your options, discuss their pros and cons, and make good decisions that get you on a path for success.

Your Extension - What is the "Why"?

First, sit down and write a brief statement about why people will use your extension. As a web app that serves a business purpose, that purpose must be clear in this kind of a statement. The text used in this statement also offers explicit clues as to what the use cases are going to be. For example:

"To create and manage protected environments for testing an app either alone or in association with other apps."

As you may have noticed, this statement might be similar to what the Test Environments team wrote when they started planning their extension. Reviewing this statement, let's pull out the key words:

• Create: This verb indicates that users can create protected testing environments. So obviously, one use case we'll need to cover is "Create a test environment."
• Manage: This verb is just one word, but it refers to the "rud" in "CRUD" (Create, Read, Update, Delete). CRUD use cases are universal to any abstract notion of an entity or a collection, which is what a database of test environments is. Specifically, "manage" indicates that:
  1. People need to see information about a test environment, update the list of apps in it as well as its basic configuration, and delete it.
  2. The system may also automatically delete test environments once certain conditions are met.
• Alone or... [with] other apps: This means that each test environment can contain multiple apps. It also implies that there needs to be at least one app in a test environment to actually be useful.

What is the "Entity of Interest" (EI)?

Most extensions are tightly focused on a single "Entity of Interest," or "EI." Examples of EIs include: apps, pipelines, crypto scenarios, etc.

You need to figure out what the EI is for your Extension that your users will interact with. Your extension's statement of purpose likely references it; here it is from our example above:

The Entity of Interest is environments for testing -> a test environment

Your extension's Site Map (or information architecture) centers on its EI and should also be tightly focused. Many extensions have only 2-3 pages! For example, here are common pages and the primary use case each page supports:

• Home Page: Show me EIs most relevant to me. (Such as my favorites.) Help me search for other EIs.
• Filtered List of EIs: Many extensions benefit from showing a filtered list of entities. This is why SDLC Extensions commonly have a common “List of” page for any App
• Entity Details Page: Show me information about this entity, such as its status and logs. If I have correct privileges, allow me to manage this object. (Update, delete, etc.) If there is a one-to-many relationship with related entities, show them.
  1. For a simple object, a single page is sufficient.
  2. A more complex entity, such as a Resource Pool, needs multiple pages. The first (default) page shown should an Overview page that summarizes the EI's key information, then multiple sibling pages can offer more details and support additional use cases.

What Kind of Site Map Does the Extension Need?

Most Extensions will follow one of these simple site map patterns, but there are occasional exceptions. Be sure to discuss your approach to you extension's Site Map with the UX Team.

Each blue box represents one "logical page" -- that is, a unique web page that needs to be coded. Most Extensions only have 2-3 logical pages, but each page needs to handle multiple use cases with grace, including viewing restrictions, security privileges, and entity states and statuses.

Security Considerations

The last topic we'll discuss here is security. Even though the Console requires SSO authentication for end users to access it, each Extension has its own additional security considerations that the dev team must clearly understand before starting. Let's explore the different aspects. Remember CRUD from above: Each of these use cases can have different considerations.

Openness & Collaboration vs. Sensitivity

Generally, the Console follows the principle of Qualified Openness as a way to err on the side of empowering collaboration while balancing security requirements around sensitive information.

Practically, Qualified Openness means that any PayPal user who can access the Console should be able to view non-sensitive information. This policy increases collaboration velocity, allowing teams to work together more quickly to debug issues and find key stakeholders to contact for more information.

The "Hide First" Model

When building web applications, always assume the lowest level of privileges for any user, unless proven otherwise. Follow this simple decision tree to determinewhether or not to show and enable sensitive contents and commands which trigger CRUD/etc. use cases.

DISPLAY A COMMAND?
If the user has privileges for viewing a page's contents, then for each command (that is, button or link which triggers a CRUD, etc. use case), determine whether the user has suitable privileges for initiating the command's use case. For example, for the Edit Button, and if the user is on an object's Owner's List, then it may be suitable to display the Edit Button in the UI. Otherwise, hide it.

ENABLE A COMMAND?
For each command that is shown in the UI, determine whether it should be enabled or disabled. By default, the command should be disabled. Only enable the command if "the system" indicates that it would be OK to proceed with the use case it triggers.

For example, let's say that the user has just clicked on the "Save" button in adialog to update an entity's configuration. That data was just submitted to the underlying system and typically takes ~45 seconds to fully process and providea callback on the successful outcome of the update. During this window when the underlying system is doing work on the entity, the user should see that the Edit Button is shown but disabled. In addition, the user may see that the commands for other entity management use cases, such as "run", "disable" or "delete", are also shown as disabled. Once the page receives the callback that the object entity process was successful, then the page may re-enable the related command(s).

A CRUD-y Look at Security

Let's take a look at each letter of CRUD and how you should think about security for the Entity of Interest which is central to any Extension's purpose.

"C": Create
Who can create a new Entity of Interest? (E.g., a pipeline, test environment,crypto scenario.) For most Extensions, the answer is generally: Anyone who can view the Extension can create a new object. In special cases, there may be extra layers of security.

"R": Read
Who can view information about an Entity of Interest? Refer to our principle of "Qualified Openness" from above. In most cases, anyone who can access the Console should be able to view information about any Entity of Interest in Console Extensions. Practically speaking, it means that the Extension displays meta-data in a read-only format. In some cases, an Extension may need to hide specific bits of info, or even all info, about an Entity of Interest. See the Console UX Development Guide for more details.

• Partially Hidden Info: If your Extension needs to restrict some bits of meta-data from a given user, while showing other bits, the Console UX team recommends "silently hiding" such info: Hide the info, and do not notify the user that some info is hidden.
• Restricted Info as a Page: If the user is restricted from clicking on a command (e.g., button or link) to view some info, then hide the command from view.
• Entity Details Page: If the Object of Info has a distinct URL for viewing it, but a given user is restricted from seeing anything on that page, then render the page with all info hidden and show a Banner notification with a suitable message.

"U": Update
Who can update an Entity of Interest? The verb "update" includes synonymslike "edit" and refers to changing an object's configuration in whole or in part. Most Extensions rely on the concept of an owners list: These users are explicitly identified as caretakers of an entity who are entrusted with the entity's full lifecycle (Create → Update → Delete). Therefore, only users in the owners list should see actions (e.g., links or buttons) for modifying the object, such as changing its name, modifying configuration info, updating the owners list, disabling/pausing or enabling/reactivating, etc. etc. Users who are not owners should not be allowed to fundamentally change or update the entity.

"D": Delete
Who can delete an Entity of Interest? In most cases, if a user can update an object, then the same user can also delete the object. In rare cases, the delete privilege may have additional restrictions due to potential business impact, for example.

Next Steps

Write a draft set of requirements for your Extension from a user experience perspective before diving into designing or programming its UI. Note that the UI design can also have a huge impact on technical diagrams and database design.

The requirements exercise can be done in as little as an hour, and will help you and your team have a better understanding of what you're building, which will in turn also better inform the technical architecture and related underpinnings.