# Admin Portal

# Overview

The ABB Ability™ Platform Admin Portal is a web application that enables three different administrator personas to perform various operations on security configuration for selected Ability Platform Multitenant environments. The user interface is dynamically adjusted to any logged user permissions and presents a user-friendly visual form for all Principal Manager API functionality. The following user manual contains information about the application basics, user interface overview, and all required knowledge regarding available workflows. For more information on architectural concepts and related terminology, please reference the other articles in the Multitenancy section.

# Authentication

When you open the Admin Portal, the first thing you need to do is to authenticate with the supported identity provider using a Microsoft B2C component. The user is obligated to specify an organization name (or the tenant's name) to get this process started.

The tenant name used during the last login is remembered.

The renewal process of a user's token is automated. By default it is set to be refreshed every five minutes.

Because of the General Data Protection Regulation made by the European Parliament and Council of the European Union (in effect as of 25 May 2018), every user of the application needs to accept a privacy notice that includes all necessary information about the personal data processing on the portal. User acceptance is required to proceed and start using the portal.

After successfully logging in and accepting the privacy notice, the application will gather data about user authorization and available permissions to present an adjusted and operative user interface.

# User Interface general overview

The application's user interface is built on CommonUX style guide principles which are standardized at the ABB company level. For more, see the CommonUX website.

The application is divided into three main sections:

Navigation tabs (1) allow switching between the Dashboard, Solutions, Tenants, Authentication, IoT Connectivity, Ability Admins, Administration.
User section (2) provides access to notifications, details about the user profile, option to logout from the app or Microsoft account.
Content area (3) presents the data related to the active tab.

TIP

A session expiration counter is displayed when time is less than 10 minutes. Click on refresh icon to extend the session and continue navigating the portal.

# Themes

The Admin Portal UI is available in two styles referenced by the CommonUX:

Dark mode
Light mode

To switch the theme, head to the User section and select the Dark/Light mode. The setting is saved in the local storage of your web browser.

# Tab view

After navigating through the application and choosing a specific entity context, the view separates into compact data panels (1) with tabs that split the operational view into sections (2).

The whole user journey is easily accessible using the available breadcrumb component (3) that shows a nested context of navigation up to the current view (e.g. that we are currently viewing the Administrators group from the selected Ability tenant).

Searching for items within Solutions, Tenants, IoT Connectivity, Groups, Applications, Devices, Roles, Grants, Contracts, Resources, Permissions, and Operations:
- Modified search mechanism; from filtering on the browser's side (based on already retrieved results) to using server-side capabilities of Principal Manager API QEL filters
- At least three characters are required to trigger the server's filtering request; otherwise, a validation message is displayed.
- Currently, QEL filters are case sensitive. Therefore capitalization matters
- Results can be found by entering a partial phrase, doesn't have to contain the whole word
Searching for items within Users:
- In this specific case searching is done on the browser-side on already retrieved results to provide the capability of searching by username (currently not available vie QEL filters)
- No limitation for a minimal amount of characters
- No case sensitivity
- Results can be found by entering a partial phrase, doesn't have to contain the whole word
- Users search field now searches also for emails & user Id
Retrieving data in pages for Tenants, Groups, Devices, and Applications:
- Each page is retrieved from the server separately upon request (by entering the page) instead of preloading all results and keeping them in the browser's memory
- The amount of records per page is defined by the user and saved in local storage
Sorting data within Tenants, Devices, and Applications:
- For Tenants, Applications results are sorted on the server-side and retrieved to the Portal application
- Devices don't have sorting by identity

Filtering via Tags

With the Filtering via Tags feature, you can enhance the searching of items by filtering via tags. Apart from the standard search field, an additional searching option is available in all Admin Portal modules to provide filtering by tags (represented by funnel shape icon).
Perform the following steps to filter items by tags:

Navigate to a particular module of the Admin Portal you want to filter items by tags.
Click the funnel shape icon on the right-hand corner of the screen.
The Enter tags search field is displayed.
Enter the tags of the items you want to filter.
Note: Tags need to be put as exact phrases and are case sensitive.
Press Enter.
The searched item is displayed on the screen.

# Notifications

A component located on the right side of the header allows the application user to browse through all notifications for Principal Manager API actions triggered on the application level (both success and failure scenarios).

The actual status of notifications is represented by the red badge with a sum of available items. After triggering a new action, an application user is alerted with a pulse animation that ends by increasing the total number of items.

The procedure for viewing details requires clicking on the bell icon (1). This triggers the Notification Panel which lists all items (2). Notifications inform the user about PM API action status, detail information, and time of execution. After this, the application user is able to clear the particular item by selecting the X icon to the right of the item or to quickly remove all items by clicking the Dismiss all (3) button.

Correlation ID is displayed in the application/website's footer for logged users.

Correlation ID helps the Ops/Support team to trace issues raised.

# Dashboard tab

The dashboard is a default overview screen that can be treated as an application home page. It contains high-level information about manageable assets (e.g. solutions and tenants) and can be an easy starting point for navigating through concrete application sections.

# Tenants tab

# List page

The list page contains a table view of all accessible tenants with basic information like the number of identity providers, tags, and available actions (based on user permissions - viewing, editing and deleting). After clicking the tenant name, or an eye icon, the user will be redirected into a section with data specific to the selected item known as the tenant context view.

If a user has access to only one tenant and doesn't have rights to create new tenants, the user will be redirected automatically to their one tenant context.

If a user has create permissions, the New tenant button allows the user to create a tenant. By default this is reserved for the Ability Admin persona only.

# Creating a new tenant

To create a new tenant, you need to provide the following:

Name (required)
B2C policy type (required)
- Static
  Static allows you to create a new policy file for the tenant, which will allow you to have more than one provider at the same time, but the number of tenants available will be finite.
- Dynamic
  Dynamic allows you to overcome the limit of tenants by using the existing policy file, but due to the way authentication is set up, only Azure Active Directory will be available to choose from the list of identity providers.
B2C Policy

Changing the B2C policy is possible only if the Tenant is not associated with any identity providers other than Azure Active Directory. Otherwise, the system won't allow changing policy from static to dynamic (first, the Identity Provider needs to be disassociated from this Tenant).
Sign in page URL (optional)
Error page URL (optional)
Tags (optional)
Tags can be provided as free text (Textarea), or they can be provided as tags (Pill). The Textarea setting is useful if users want to enter more content conveniently, including line breaks. The Pill setting is valid for short words, typical tags. Switching from Textarea to Pill will show a warning about losing the line breaks and formatting.
Identity providers (required)
- Azure Active Directory
- Google
Certificates (optional)

# Tenant details page

This area is oriented with a specific tenant context and gives a user the ability to operate on 6 main tabs:

Details
Authentication
Users
Groups
Contracts
Admins

In the next part of this documentation, we will take a deeper look into each of them to describe its meaning and available actions.

# Details

The details section is dedicated for providing the user with most important data about the selected tenant. Based on their permissions, the user is able to see information about the name, ID, and tags.

Note: Authorized users can assign a Tenant Admin grant to other users or groups directly from the Admins tab as well as revoke a Tenant Admin grant from users or groups.

From this page, by clicking the name value from the administrators list, the application user is able to navigate to its details. See the User Details and Group Details sections, below.

Identity provider data information is available in the Authentication tab.

# Authentication

Users can associate (or disassociate) OpenID Authentication and Certificate

Issuer URL field has UX improvement that improves the ease of adding & updating issuer URLs.

Issuer's URL placeholder changed to "INSERT_YOUR_TENANT_ID".
Tooltip message changed to: "Please replace the placeholder part of the URL with real ID of your Identity Provider's Tenant"
Does not allow to save the changes, when the placeholder "INSERT_YOUR_TENANT_ID" is not changed.
When user clicks on the Issuer URL, the placeholder "INSERT_YOUR_TENANT_ID" is highlighted. This enables user to replace the URL.

# Users

The users section contains a list of users associated with/assigned to the operated tenant with quick access to its data, e.g. username and email. Each list item also contains action icons with access to perform procedures like moving to user details, editing, or deleting.

Note: You can delete multiple users through the Delete users feature. See the Multiple Users Deletion section for detailed information.

On the top right corner of the section panel, you can also quickly add new users by following and filling in the necessary inputs related to the user onboarding process based on the Principal Manager API.

# User Details

After selecting the username or an eye icon, the application user is redirected to a page filled with details of the tenant user. For example, the name, and identity provider data.

Note: The list of assigned grants is available in the Grants tab.

# Multiple Users Deletion

With the Delete users feature, you can delete multiple users by selecting check boxes visible on the left of the user's list.
Perform the following steps to delete multiple users:

Navigate to Tenants > Users tab.

Select the check boxes you want to delete.
Click Delete users.
The Delete 3 users? confirmation window is displayed.
Enter Yes for confirmation and click Delete.
Check the status of the request in the Notification panel.

Note: The deletion process may take several minutes. Admin can continue to navigate through the Portal while deletion process; however, logging out from MS SSO will abandon the operation (logging out from the Admin Portal application will allow the delete operation to run in the background). While the users' removal is in progress, deletion candidates are greyed out and can not be modified anymore unless the operation is canceled. In case of cancellation, the unremoved users will remain in the system.

# Groups

The Groups section contains a list of all Ability Platform groups associated with/assigned to the operated tenant with quick access to its data, such as a number of grants assigned to the group and number of its members (defined as both users and devices). From this section, the application user has access to quick actions, followed by action column icons for viewing, editing, and deleting.

At the top right corner of the section panel, you can also quickly add a new group by filling its name and tags in the pop-up triggered by clicking the New Group button.

# Group Details

After selecting the group name or an eye icon, the application user is redirected to a page filled with details of the group, e.g. name and tags.

Note: The list of assigned grants is available in the Grants tab.

From this level, the application user can perform various operations like group mapping, listing, and assigning group members, viewing devices and operating on group-related grants (assigning, revoking).

# Group Mapping

Group Mapping functionality gives application users the possibility to create a direct connection between existing identity provider groups and Ability-based ones. This allows the user to perform multi-assignment for a specific group of users to provide them a set of access rights (grants).

The procedure for adding new mapping requires the user to click the Add Group Mapping button located in top right corner, then to fill out the displayed pop-up form by providing a selection of registered Identity Provider and unique identifier related to its group.

# Contracts

This section is dedicated to managing existing contracts between Ability-based tenants and solutions (consistent with the Multitenancy concept).

From this level, the application user is able to view, add, modify and delete entities of this type by using the list view.

The page contains a table view of all accessible contracts with basic information like the name, solution, tags, and available actions (based on user permissions, i.e. viewing, editing, deleting). After clicking on a contract's name or an eye icon the user will be redirected to a section with data specific to the selected item (contract's context view). If the user has editing permissions, the pencil icon allows them to go to the contract edit mode (by default reserved for Ability Admin persona). If the user has deleting permissions, the bin icon allows them to delete a contract (by default reserved for Ability Admin persona). If a user has create permissions, the New contract button allows them to create a contract (by default reserved for Ability Admin persona).

# Create contract

The user needs to fill out the form in order to create a new Contract in the platform, by providing name, solution, custom sign in, and error page URL, tags.

# Solutions

This page contains a table view of all accessible solutions with basic information like the name, scope, tags, and available actions (based on user permissions, i.e. viewing, editing, and deleting). After clicking the solution name or an eye icon the user will be redirected into a section with data specific to the selected item (solution context view). If the user has editing permissions, the pencil icon allows them to go to Solution Edit mode (by default reserved for Ability Admin and Solution Admin personas). If the user has deleting permissions, the bin icon allows them to delete a solution (by default reserved for Ability Admin persona). If the user has create permissions, the New solution button allows them to create a solution (by default reserved for Ability Admin persona).

# Solution create

The user needs to fill out the form in order to create a new solution in the platform, by providing Name, Namespace, Scope, and Tags.

# Solution details page

This area is oriented to a specific solution context and gives a user the ability to operate on the following main tabs:

Applications
Devices
Roles
Grants
Contracts
Resources
Permissions
Operations

In the next part of this documentation, we will take a deeper look into each of these tabs and describe the meaning of each, along with available actions.