From ab096a86acc071f6384c6fe2920f989b8117b200 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Fri, 27 Jan 2023 11:13:31 -0800 Subject: [PATCH] ENDOC-647 Apply PR feedback --- .../tutorials/solution/customer-portal.md | 47 +++++++++++-------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/vuepress/docs/next/tutorials/solution/customer-portal.md b/vuepress/docs/next/tutorials/solution/customer-portal.md index 3ca5a93d33..a481a5bbd3 100644 --- a/vuepress/docs/next/tutorials/solution/customer-portal.md +++ b/vuepress/docs/next/tutorials/solution/customer-portal.md @@ -24,7 +24,7 @@ This tutorial covers: * 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](../../docs/getting-started/entando-cli.md) command `ent check-env develop` to verify dependencies * A Jira Service Management account -* A [Keycloak server](https://www.keycloak.org/docs/15.0/server_admin/#_email) configured with the SMTP settings to enable email verification for users +* A [Keycloak server](https://www.keycloak.org/docs/15.0/server_admin/#_email) configured with the SMTP settings to enable email verification for users ### Automatic Install via the Entando Hub @@ -38,7 +38,7 @@ This tutorial covers: #### Install the Customer Portal From the Hub Catalog, `Deploy` and `Install` the Customer Portal application first, then the content bundle -#### Set up permissions to configure the service +#### Assign Roles to Configure the Service 1. [Log in to your Keycloak instance](../../docs/consume/identity-management.md#logging-into-your-keycloak-instance) as an admin 2. Give at least one user the ability to manage the Customer Portal by granting the `cp-admin` role - The `cp-admin` role is assigned from the `pn-a71d68dd-166dc0f4-entandodemo-customerportal-server` client. See [Role Assignment in ID Management](../../docs/consume/identity-management.md#authorization) for more details. @@ -47,7 +47,7 @@ From the Hub Catalog, `Deploy` and `Install` the Customer Portal application fir 2. Click the `Service Account Roles` tab at the top of the page and select `realm-management` from the `Client Roles` field 3. Choose `realm-admin` from `Available Roles`, then click `Add selected`. It should appear as an `Assigned Role`. -#### Navigate to your Customer Portal +#### 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` @@ -83,11 +83,13 @@ In order to configure the Customer Portal and its users, the administrator needs Users who need access to the Customer Portal, beyond subscription and project information, must 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. ->Note: The password for Jira Service Management must be an [API token generated by Jira](https://id.atlassian.com/manage-profile/security/api-tokens). For more information, go to [Manange API tokens at Atlassian Support](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). +::: tip +The password for Jira Service Management must be an [API token generated by Jira](https://id.atlassian.com/manage-profile/security/api-tokens). For more information, go to [Manange API tokens at Atlassian Support](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). +::: 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](https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/). -#### To add organizations and projects in Jira: +#### Add Organizations and Projects in Jira: 1. Go to Customers 2. Add organizations and projects as needed 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](#create-and-assign-projects) @@ -99,7 +101,7 @@ The Customer Portal must be configured for a specific Jira Service Management in To access the `CP Admin Config` page, you must be given the `cp-admin` role in the [Entando Identity Management System](#entando-identity-management-system) as [described above](#set-up-permissions-to-configure-the-service). -#### To view the `CP Admin Config` page: +#### View the `CP Admin Config` Page 1. In the App Builder, go to `Pages` and select `Management` 2. Open the Customer Portal folder and find `CP Admin Config` 3. From the `Action` drop-down menu on the right, go to `View Published Page` @@ -108,7 +110,9 @@ To access the `CP Admin Config` page, you must be given the `cp-admin` role in t 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. Open each section with the down arrow to add and edit the fields as needed. ->Note: The password for the Ticketing System Connection is requested by the Customer Portal administrator and must be an [API token generated by Jira](https://id.atlassian.com/manage-profile/security/api-tokens). For more information, go to [Manange API tokens at Atlassian Support](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). +::: tip +The password for the Ticketing System Connection is requested by the Customer Portal administrator and must be an [API token generated by Jira](https://id.atlassian.com/manage-profile/security/api-tokens). For more information, go to [Manange API tokens at Atlassian Support](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). +::: ### Entando Identity Management System Log in to the Entando 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. @@ -158,7 +162,7 @@ As administrator for the Customer Portal, you can create and manage users, custo ![Customer Portal Landing Page](./images/cp-landing-page.png) #### Create a Customer or Partner -The processes to create customers and partners are similar. Below are the steps to add a `Customer`. Follow the analogous procedure to add a `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 @@ -166,17 +170,22 @@ The processes to create customers and partners are similar. Below are the steps ![Customer Portal Add Customer](./images/cp-add-customer.png) -#### Create and Assign Projects -From the Customer Portal landing page, click on a customer to see the associated project list. -- To create a new project: - 1. Click `Add a Project` - 2. Enter the `Project` information - 3. Provide the [Organization ID](#jira-service-management) retrieved from Jira. Each project must have a unique Organization ID. - 4. Click `Save` -- To assign `Projects`: - 1. From the `Action` drop-down menu, select `Manage Users` - 2. Select the user for the `Project` - 3. Click `Submit` +#### 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](#jira-service-management) retrieved from Jira. Each project must have a unique Organization ID. +6. Click `Save` + +#### 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` #### Manage Partners and Subscriptions Use the `Action` drop-down menu to manage Partners or request and manage subscriptions.