Merge pull request #374 from entando/ENDOC-373

ENDOC-373 customer-portal.md

vuepress/docs/.vuepress/next.js

@@ -298,6 +298,10 @@ module.exports = {
                     {
                         title: 'Standard Banking Demo',
                         path: path + 'samples/install-standard-demo.md',
+                    },
+                    {
+                        title: 'Customer Portal',
+                        path: path + 'samples/customer-portal.md',
                     }
                 ]
             },

vuepress/docs/next/docs/component-generator/blueprint-features.md

@@ -20,7 +20,7 @@ The Entando Blueprint uses JHipster technology based on Embedded JavaScript (EJS
 
 For more information:
 * Install [JHipster Entando Blueprint](https://github.com/entando/generator-jhipster-entando/blob/master/README.md)
-* Try implementing an Entando Blueprint-- [Create microservices and micro frontents](../../tutorials/micro-frontends/react.html)
+* Try implementing an Entando Blueprint-- [Create microservices and micro frontents](../../tutorials/micro-frontends/react.md)
 
 ## Premade Widgets
 When you create an entity using the Entando Blueprint, it generates a few
@@ -53,7 +53,7 @@ point at
 > Custom element names require a hyphen like `conference-details` (kebab-case)--they cannot be single words.
 
 For more information about web components, custom elements and micro
-frontends, refer to [Create a React micro frontend widget](../../tutorials/micro-frontends/react.html).
+frontends, refer to [Create a React micro frontend widget](../../tutorials/micro-frontends/react.md).
 
 
 ### Authentication
@@ -73,7 +73,7 @@ authentication provider, but you can add any provider as needed.
     );
 
 For more information about the authentication process, please refer
-to the [Authentication section](../reference/identity-management.html#authentication).
+to the [Authentication section](../reference/identity-management.md#authentication).
 
 ### Custom events
 
@@ -87,7 +87,7 @@ To add more event listeners, add the event types to
 it to the listener list. To remove the event, simply remove the element from the list.
 
 For more information about custom events and widget communication,
-please refer to the section on [Widget communication](../../tutorials/micro-frontends/communication.html).
+please refer to the section on [Widget communication](../../tutorials/micro-frontends/communication.md).
 
 ### Tests and mocks
 

vuepress/docs/next/docs/component-generator/component-gen-tech.md

@@ -7,7 +7,7 @@ When generating a microservice using the Entando Component Generator there are a
 * Microservice code
   * The Component Generator currently only supports the generation of Spring Boot microservices but will support the generation of Quarkus based services soon. 
   * If you're interested in using Quarkus in your Entando app, contact us on the [Forum](https://forum.entando.org/) or [Community Slack](https://join.slack.com/t/entandocommunity/shared_invite/zt-g609owdv-2K~YRh8zrI6lqlWo4aFWUw) and we'll help you get started.
-  * If you're considering non-Java based microservices, [here is a definition of an Entando plugin](../ecr/ecr-bundle-details.html#plugin), including information on the runtime contract required to use them. 
+  * If you're considering non-Java based microservices, [here is a definition of an Entando plugin](../ecr/ecr-bundle-details.md#plugin), including information on the runtime contract required to use them. 
 * Database type
   * Entando recommends standardizing your choice of database to simplify operational maintenance but you do have the ability to use different databases for different microservices if you choose.
   * Supported choices are none, MySQL, and Postgres. Enterprise customers can choose Oracle but should contact Entando Support for details.
@@ -25,6 +25,6 @@ When generating a microservice using the Entando Component Generator there are a
   * Users can optionally choose to generate micro frontends for entities generated via the blueprint.
   * The Entando Component Generator only provides micro frontends in React from the generation flow but developers can create and bundle micro frontends using other technologies as well. 
 
-If you want to try out these choices follow the tutorial on [creating Entando microservices and micro frontends using the component generator](../../tutorials/backend-developers/generate-microservices-and-micro-frontends.md)
+If you want to try out these choices follow the tutorial on [creating Entando microservices and micro frontends using the component generator](../../tutorials/backend-developers/generate-microservices-and-micro-frontends.md).
 
 

vuepress/docs/next/tutorials/samples/customer-portal.md

@@ -0,0 +1,169 @@
+---
+sidebarDepth: 2
+---
+
+# Entando Customer Portal 
+## Overview
+The Entando Customer Portal enables an organization to quickly provide a modern, self-service customer-facing application for management of subscriptions. It includes a lightweight integration to Jira Service Management for access to service tickets and a Role Based Access Control (RBAC) design for granting users varying levels of access.
+
+Key Features:
+
+* Customizable service ticket and tracking system with Jira Service Management
+* Role based access control (RBAC) with Entando Identity Management System
+* Integrated user, customer, project, and subscription management 
+
+This tutorial covers: 
+1. [Installation](#installation)
+2. [Configuration](#configuration)
+4. [Managing the Customer Portal](#managing-the-customer-portal)
+5. [Using the Customer Portal](#using-the-customer-portal)
+6. [Resources](#resources)
+
+## Installation
+### Prerequisites
+* A working instance of Entando running on Kubernetes. See [Getting Started](../../docs/getting-started/) for more information or [install Entando on any Kubernetes provider](../#operations). 
+* Use the Entando CLI command `ent check-env develop` to verify all dependencies.
+* A Jira Service Management account.
+
+### Automatic Install with Entando App Builder
+Install the Customer Portal in two simple steps by integrating the Entando Hub into your App Builder. 
+1. From your App Builder, go to the `Repository` from the sidebar. Select `Entando Hub` at the top right side of the page if it has already been configured. If it has not been configured, enter Entando Hub and the API URL to initialize the Hub.
+
+2. Deploy and `Install` the two Customer Portal bundles from the Catalog. 
+
+3. To navigate to your Portal: 
+   * From the sidebar →  `Page` → `Management` 
+   * Find the `Customer Portal` page
+   * From the `Actions` pull-down menu →  `View Published Page`
+
+![Customer Portal Landing Page](./images/cp-public-landing-page.png)
+
+### Manual Install 
+1. To install the Customer Portal, run the following commands in the order listed. Edit the `-n entando` option for each command to match your namespace or project.
+
+``` bash
+ent bundler from-git -r https://github.com/nshaw/customerportal-wip-bundle.git -d | ent kubectl apply -n entando -f - 
+```
+
+``` bash
+ent bundler from-git -r https://github.com/nshaw/customerportal-content-bundle.git -d | ent kubectl apply -n entando -f - 
+```
+2. Log into the App Builder.
+
+3. Go to `Repository` from the left navigation bar. Two Customer Portal bundles will be visible there. `Install` the latest version of both bundles.
+
+4. To navigate to your Portal: 
+   * From the sidebar →  `Page` → `Management` 
+   * Find the `Customer Portal` page
+   * From the `Actions` pull-down menu →  `View Published Page`
+
+## Configuration
+### Administrators
+In order to configure the Customer Portal and its users, the administrator will need Jira Service Management and Entando Identity Management System credentials. The administrator can create and configure users and groups, assign roles and projects, and track service tickets.  They can also customize the ticketing system. 
+
+::: tip Notes:
+* The built-in mapper for email must be enabled on the server client so that user accounts can be retrieved from Jira and new tickets can use that account information.
+
+* Use the cp_admin_config.page to configure the Customer Portal to connect to Jira Service Management. 
+
+* Configure the Customer Portal to accomodate a specific Jira Service Management instance.
+::: 
+
+### Jira Service Management 
+
+The administrator utilizes Jira Service Management to create users, projects, define the organization, and configure the service ticket system.
+
+Users who need access to the Customer Portal, beyond subscription and project information, must have a Jira Service Management account.
+
+1. Go to Customers to add organizations and projects. Once added, click on the name of the organization to get the ID, needed later, from the URL. \
+ e.g. example.com/jira/servicedesk/projects/ECS/organization/3 → the organization ID is “3”
+
+### Entando Identity Management System 
+Logging into the Entando Identity Management System, you will see the landing page shown below. Like the App Builder, the left navigation bar is your guide for managing users, groups, and most importantly, roles. Using the RBAC model, define what access users have by the roles and groups they are assigned. Some important guidelines are noted below. 
+
+![Entando Identity Management System](./images/cp-idmanagement-main.png)
+
+* **Define the Realm Setting**. \
+The `Realm` is a set of users, credentials, roles, and groups. A user belongs to and logs into a `Realm`. 
+
+* **Create 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 for a single customer
+    * `cp-partner` - assigned directly to specific projects for multiple customers
+    * `cp-support` -  read only view of all customer projects
+    * `cp-admin` - admin access for the Customer Portal
+
+* **Create New Users**: 
+     1. From the sidebar, go to `Users`. Click `Add User` at right.
+     2. Complete the form as needed but note the requirements for these fields:\
+       `Username`: a unique name\
+       `Email`: must use the same address used in Jira\
+       `User Enabled` → On\
+     `Save`
+
+     3. Send an email to the user to activate their account and set a new password: \
+     Go to `Credentials` header. \
+     Under `Credential Reset`, in the `Reset Actions` → `Update Password`.  \
+     Click `Send Email`. \
+
+     4. Go to Role Mapping. \
+     Select the appropriate roles from `Available Roles` and click `Add Selected` to assign. 
+     * Choose `entandodemo-customerportal-server` from the `Client Roles` pull-down menu to use the default roles. 
+     * A full administrative user will need `realm-admin` role under `realm-management` Client Roles in order to manage users in the Portal. 
+     * Check the `Effective Roles` column on right to ensure the correct roles have been assigned.
+
+![Entando ID Management Role Mapping](./images/cp-identity-userrole.png)
+
+  5. Under `Groups`, assign roles to groups as needed. Roles are additive.
+
+
+
+## Managing the Customer Portal
+
+As administrator for the Customer Portal, you can create and manage: users, customers, projects, and subscriptions. You can also assign projects to users who have activated their account on Jira and have been assigned roles in the Entando Identity Management System. 
+
+The administrator needs a Jira account and the appropriate role assignment in the Entando Identity Management System as well.
+
+![Customer Portal Landing Page](./images/cp-landing-page.png)
+
+* **Create a Customer or Partner**\
+Creating a `Customer` or `Partner` is a similar process. Below are the steps for adding a `Customer`. Please follow the same procedure for adding a `Partner`.
+1. Click `Add a Customer`
+2. Fill in the details. Note the following:
+     * The `Customer Number` must be unique 
+     * The `Notes` field is visible only to Support and Admin users 
+
+ ![Customer Portal Add Customer](./images/cp-add-customer.png)   
+
+* **Create & Assign Projects**
+1. From the landing page, click on any customer to see the associated project list.
+2. To create a new project, click `Add a Project`
+    * Enter the `Project` information
+    * Provide the Organization ID from Jira. Each project must have a unique Organization ID.
+    * Click `Save`
+3. To assign `Projects`:
+	* Use the drop-down menu under `Action` on the right → `Manage Users`
+    * Select the user for the `Project`  → `Submit` 
+
+* **Manage Partners and Subscriptions** \
+Use the drop-down menu under `Action` to manage Partners, and request and manage subscriptions. 
+
+## Using the Customer Portal
+
+Customer Portal users need access provided by your organization administrator. You can request and track subscriptions as well as create and track service tickets.
+
+Once you login to the Customer Portal, you will see a list of customers. Click on any customer to see their details and track their projects.
+
+1. To create a `Service Ticket` for a project, use the `Action` pull-down menu  → `Open Ticket`
+
+![Customer Portal Open Ticket](./images/cp-open-ticket.png)
+
+2. To request a Subscription or track Tickets, use the `Action` pull-down menu and select the corresponding option.
+
+## Resources
+* Go to [Jira Service Management](https://www.atlassian.com/software/jira/service-management) for more information.
+
+
+* Source Code\
+The source for the Entando Customer Portal can be found with our other open source examples and tutorials on GitHub at: [https://github.com/entando-samples/customer-portal/](https://github.com/entando-samples/customer-portal/)
+