# Villanova Customer Portal

# Overview

The Villanova Customer Portal enables an organization to quickly provide a modern, self-service, customer-facing application for managing subscriptions. It includes lightweight integration to Jira Service Management for service ticket tracking and role based access control (RBAC) for a collaborative environment.

Key Features:

  • Customizable service ticket tracking system with Jira Service Management
  • Role based access control with Villanova Identity Management System
  • Integrated user, customer, project, and subscription management

This tutorial covers:

  1. Installation
  2. Configuration
  3. Managing the Customer Portal
  4. Using the Customer Portal
  5. Resources

# Installation

# Prerequisites

# Automatic Install via the Villanova Hub

# A. Integrate the Villanova Hub into your App Builder

  1. Log in to your App Builder and go to Hub → Select Registry
  2. Select Villanova Cloud Hub if it has been configured, otherwise:
    1. Choose New Registry
    2. In the pop-up window, enter the following:
      -Name: Villanova Cloud Hub
      -URL: https://auth.entando.com/entando-hub-api/appbuilder/api
      then click Save
    3. Click on the Cloud Hub in the Registry

# B. Install the Customer Portal

  1. From the Hub Catalog, click the Customer Portal Application Bundle, and Deploy and Install it in the pop-up window.
  2. Repeat for the Content Bundle. The order is important because the Content Bundle cannot be installed without the Application Bundle.

# C. Assign Roles to Configure the Service

  1. Log in to your Keycloak instance as an admin
  2. Give at least one user the ability to manage the Customer Portal:
    • Assign the user the cp-admin role for the pn-a71d68dd-166dc0f4-entandodemo-customerportal-server client. (See Role Assignment in ID Management for more details.)
    • Assign the user the view-users role for the realm-management client. This role is necessary when assigning users to a Customer Portal project.

# D. Navigate to Your Customer Portal

  1. From the App Builder sidebar, go to Page → Management.
  2. Find the Customer Portal folder.
  3. From the corresponding Actions drop-down menu, go to View Published Page. You can set this as your homepage by going to Page → Settings, and choosing Customer Portal from the Homepage pull-down options.

Customer Portal Landing Page

# Manual Install

  1. To install the Customer Portal manually, run the following commands in this order:
ent ecr deploy --repo="https://github.com/entando-samples/customerportal-application-bundle.git"

ent ecr deploy --repo="https://github.com/entando-samples/customerportal-content-bundle.git"

  1. Log in to the App Builder

  2. Go to the Hub from the left sidebar. The bundles should be displayed in the Local Hub as Deployed. Click the customerportal-application-bundle and then Install. Repeat for the customerportal-content-bundle.

  3. Navigate to your Customer Portal:

    1. From the sidebar, go to Page → Management
    2. Find the Customer Portal folder
    3. From the Actions pull-down menu, go to View Published Page

# Configuration

# Administrators

To configure the Customer Portal and its users, the administrator needs Jira Service Management and Villanova Identity Management System credentials. The admin can then connect the Customer Portal to Jira and customize its features.

TIP

The built-in mapper for email must be enabled on the server client so that user accounts can be retrieved from Jira and service tickets can use that account information.

# Jira Service Management

Users who need access to the Customer Portal, beyond subscription and project information, must also have a Jira Service Management account. The administrator utilizes Jira Service Management to create users and projects, define the organization, and configure the service ticket system.

TIP

The password for the Ticketing System Connection is requested by the Customer Portal administrator and must be an API token generated by Jira (opens new window). For more information, go to Manange API tokens at Atlassian Support (opens new window).

The Jira Service Management REST API should follow the pattern https://YOUR-JIRA-SERVICE-MANAGEMENT-URL/rest/api/latest/. For reference, see Jira Service Management Cloud REST APIs (opens new window).

# A. Add Organizations and Projects in Jira:

  1. Go to Customers
  2. Add organizations and projects by completing the required fields
  3. Click on the name of each added organization to retrieve its ID from the URL. This is required to create and assign projects in the Customer Portal
    • e.g. example.com/jira/servicedesk/projects/ECS/organization/3 → the organization ID is “3”

# Configure the Customer Portal

The Customer Portal must be configured for a specific Jira Service Management instance. The CP Admin Config page is where you establish the Jira connection, manage product versions, define subscription levels, and customize ticket types.

To access the CP Admin Config page, you must be given the cp-admin role in the Villanova Identity Management System as described above.

# A. View the CP Admin Config Page

  1. Go to Pages → Management
  2. Expand the Customer Portal folder and find CP Admin Config
  3. From the corresponding Action drop-down, go to View Published Page

Customer Portal Admin Config page

Once the Ticketing System Connection is set up with Jira and the correct URL, default parameters such as product versions and ticket types will be displayed. Expand each section with the down arrow to add and edit the fields as needed.

# Villanova Identity Management System

Log in to the Villanova Identity Management System to arrive at the landing page shown here. Use the left navigation bar to manage users, groups, and roles. Using the RBAC model, define what access users have by the roles and groups they are assigned. Some important information is noted below.

Villanova Identity Management System

# A. The Realm Setting

The Realm is a set of users, credentials, roles, and groups. A user belongs to and logs in to a Realm.

# B. Default Roles

You can use the default roles by clicking on Client Roles and choosing entandodemo-customerportal-server. Access for each role is defined as follows:

  • cp-customer: Assigned directly to specific projects of a single customer
  • cp-partner: Assigned directly to specific projects of multiple customers
  • cp-support: Read only view of all customer projects
  • cp-admin: Admin access to the Customer Portal

# C. Create New User

  1. From the sidebar, go to Users
  2. Click Add User on the right
  3. Complete the form as needed, but these fields are required:
    • Username: A unique name
    • Email: Must use the same address used in Jira
    • User Enabled: Set to On
  4. Click Save
  5. Send an email to the user to activate their account and set a new password:
    1. Go to the Credentials header
    2. Under Credential Reset, go to Reset Actions → Update Password
    3. Click Send Email

# D. Assign Roles to Users

  1. Click the Role Mapping tab on top
  2. Select the appropriate role(s) from Available Roles and assign them to a user by clicking Add Selected:
    • To assign default roles, choose entandodemo-customerportal-server from the Client Roles pull-down
    • To manage users in the Customer Portal, a user will need the view-users role under Client Roles → realm-management
  3. Check the Effective Roles column on the right to ensure the correct roles have been assigned

Villanova ID Management Role Mapping

# E. Assign Roles to Groups

Under Groups, assign roles to groups as needed. Multiple roles can be assigned to a single group.

# Managing the Customer Portal

As administrator for the Customer Portal, you can create and manage users, customers, projects, and subscriptions. You can assign projects to users who have activated their account on Jira and have been assigned roles in the Villanova Identity Management System.

Customer Portal Landing Page

# A. Create a Customer or Partner

The processes to create customers and partners are similar. Below are the steps to add a Customer. A Partner is added the same way.

  1. Click Add a Customer
  2. Fill in the customer details. Note:
    • The Customer Number must be unique
    • The Notes field is visible to only support and admin users

Customer Portal Add Customer

# B. Create a Project

  1. Go to the Customer Portal landing page
  2. Click on a customer to see the associated project list
  3. Click Add a Project
  4. Enter the Project information
  5. Provide the Organization ID retrieved from Jira. Each project must have a unique Organization ID.
  6. Click Save

# C. Assign a Project

  1. Go to the Customer Portal landing page
  2. Click on a customer to see the associated project list
  3. From the Action drop-down menu, select Manage Users
  4. Select the user for the Project
  5. Click Submit

# D. Manage Partners and Subscriptions

Use the Action drop-down menu to manage Partners or request and manage subscriptions.

# Using the Customer Portal

To access the Customer Portal, your organization administrator needs to provide you with the proper user credentials. Once you log in to the Customer Portal, you will see a list of customers. Click on an entry to view customer details and track projects. You can create and track service tickets, as well as request subscriptions.

To create a Service Ticket for a project: Go to the Action pull-down menu and select Open Ticket

Customer Portal Open Ticket

To request a Subscription or track Tickets: Go to the Action pull-down menu and select the corresponding option

# Resources

← Villanova Hub →