@ieeesa-npm/groups 0.14.5 → 0.15.0

package/README.md

@@ -19,6 +19,211 @@ After building your library with `ng build groups`, go to the dist folder `cd di
 
 Run `ng test groups` to execute the unit tests via [Karma](https://karma-runner.github.io).
 
+# Groups NPM Package Usage Guide
+
+## 1. Angular versions
+Groups npm package is developed using Angular 16. To use the groups npm package in Angular application, application should be developed with Angular 16 and above version.
+
+## 2. Install groups NPM Package
+You can use the following command to install groups NPM package.
+npm install @ieeesa-npm/groups or npm install @ieeesa-npm/groups@latest or npm install @ieeesa-npm/groups@0.11.4 (in case of particular version)
+
+## 3. Install groups peer dependency NPM Packages
+Following npm packages are dependency for groups module and you can use below commands to install those  NPM packages.
+
+* npm install @ieeesa-npm/presentation
+* npm install @ieeesa-npm/shared-styles
+* npm install @ieeesa-npm/feature
+* npm install @ieeesa-npm/utility
+
+## 4. Import GroupsComponent from installed node_modules
+Import the GroupsComponent to your application component where you want to integrate the GroupsComponent. Refer below snippet to import the groups component. Group Component to be imported from @ieeesa-npm/groups and provided it in the imports array of component decorator.
+
+```typescript
+import { Component, OnDestroy, OnInit, ViewEncapsulation } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { GroupsComponent } from '@ieeesa-npm/groups';
+import { HttpClientModule } from '@angular/common/http';
+import { UserPermissions } from '@core/models/user-permissions.model';
+import { Subject, distinctUntilChanged, takeUntil } from 'rxjs';
+import { BreadcrumbComponent } from '@ieeesa-npm/presentation';
+import { UserInfo } from '@core/models/user-info.model';
+
+@Component({
+  selector: 'committees',
+  standalone: true,
+  imports: [
+    CommonModule,
+    GroupsComponent,
+    HttpClientModule,
+    BreadcrumbComponent,
+  ],
+  templateUrl: './committees.component.html',
+  styleUrls: ['./committees.component.scss'],
+  encapsulation: ViewEncapsulation.None,
+```
+Next, you can integrate the groups component in the html template using groups component selector <ieeesa-groups> </ieeesa-groups>.
+
+```html
+<div class="committees">
+  <div class="committees__breadcrumb px-4 pt-3">
+    <ieeesa-breadcrumb
+      [breadcrumbInitialRoute]="breadCrumbInitialRoute"
+      [breadcrumbInitialRouteLabel]="breadcrumbInitialRouteLabel"
+    ></ieeesa-breadcrumb>
+  </div>
+  <ieeesa-groups
+    [apiBaseURL]="apiBaseURL"
+    [userPermissions]="userPermissions"
+    [userInfo]="userInfo"
+  ></ieeesa-groups>
+</div>
+```
+Next, pass the necessary metadata as an input property to the groups component such as,
+* apiBaseURL
+* userPermissions
+* userInfo
+
+```html
+<div class="committees">
+  <div class="committees__breadcrumb px-4 pt-3">
+    <ieeesa-breadcrumb
+      [breadcrumbInitialRoute]="breadCrumbInitialRoute"
+      [breadcrumbInitialRouteLabel]="breadcrumbInitialRouteLabel"
+    ></ieeesa-breadcrumb>
+  </div>
+  <ieeesa-groups
+    [apiBaseURL]="apiBaseURL"
+    [userPermissions]="userPermissions"
+    [userInfo]="userInfo"
+  ></ieeesa-groups>
+</div>
+```
+## 4.1 apiBaseURL
+API base URL to be passed to the component based on the environment such as dev/qa/uat/prod to get the groups data from server.
+
+* DEV: https://saappsapidev.ieee.org/v1
+* QA: https://saappsapiqa.ieee.org/v1
+* UAT: https://saappsapiuat.ieee.org/v1
+* PROD: https://saappsapi.ieee.org/v1
+
+## 4.2 userInfo
+You can get the logged user information by calling the API https://saappsapiqa.ieee.org/v1/userauth/public/jwt/verify along with passing the JWT token as a bearer token that was generated by the API https://saappsapiqa.ieee.org/v1/configurations/public/saml2/authenticate/QASAAPPSIEEE. This API will verify the validity of the token and respond the following user information when the token verification is successful.
+```typescript
+{
+    "userId": "User_0511a78f",
+    "appId": "SAAPPS",
+    "firstName": "",
+    "lastName": "",
+    "email": "",
+    "token": null,
+    "roles": null
+}
+```
+Logged in user info to be passed to the groups component to identify whether the logged in user is assigned with admin role. Based on the passed user info, groups component does not allow the admin to edit or delete his/her role by himself/herself when the logged in user is admin. Refer to below UserInfo model.
+```typescript
+export interface UserInfo {
+  appId: string;
+  userId: string;
+  ssoId: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+```
+
+## 4.3 userPermissions
+Logged userInfo will be used to get the user roles and permissions. You can get the logged user roles and permissions by calling the API 
+https://saappsapiqa.ieee.org/v1/groups/userPermissions/User_a25979e3-96c5-489c-aed7-7a6948c0fa66 along with passing the JWT token as a bearer token. The userId (User_a25979e3-96c5-489c-aed7-7a6948c0fa66) to be passed as a path parameter to the API.
+
+API will validate the bearer token and userId, and then respond to the API request with following roles and permission information when the token is not expired, and token & userId is valid.
+```json
+{
+  "status": true,
+  "message": "SUCCESS",
+  "body": {
+    "roles": [
+      {
+        "roleId": "ROLE_edaf1dcc",
+        "roleName": "Admin",
+        "permissions": [
+          {
+            "permissionId": "PERM_eebde105",
+            "permissionName": "Manage All Group Details"
+          },
+          {
+            "permissionId": "PERM_fc522748",
+            "permissionName": "Create Parent Group"
+          },
+          {
+            "permissionId": "PERM_741d7504",
+            "permissionName": "View All Group Details"
+          },
+          {
+            "permissionId": "PERM_9ddd51db",
+            "permissionName": "Manage Group Officers"
+          },
+          {
+            "permissionId": "PERM_b322c647",
+            "permissionName": "View Group details"
+          },
+          {
+            "permissionId": "PERM_5a8edb91",
+            "permissionName": "View Group Members"
+          },
+          {
+            "permissionId": "PERM_f80ac8a3",
+            "permissionName": "View Group Officers"
+          },
+          {
+            "permissionId": "PERM_1969fecb",
+            "permissionName": "Manage Group Member"
+          },
+          {
+            "permissionId": "PERM_008229bf",
+            "permissionName": "Delete Group"
+          },
+          {
+            "permissionId": "PERM_8f8a203e",
+            "permissionName": "Create Subgroup"
+          },
+          {
+            "permissionId": "PERM_d64e1f09",
+            "permissionName": "Edit Group Details"
+          },
+          {
+            "permissionId": "PERM_d2c103e9",
+            "permissionName": "Manage System Users"
+          },
+          {
+            "permissionId": "PERM_c05ff592",
+            "permissionName": "View Groups"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+API returns more than one role and associated permissions based on the roles assigned to the user and permissions mapped to each role. You can consolidate all the roles permissions of an user and pass the filtered permissions to the “userPermissions” input property of the groups component.
+
+Logged in user list of permissions to be passed to the component to authorize the user to perform or provide the access appropriate functions such as View Groups, Add Group, Add Subgroup, Edit Group, Delete Group, View/Manage Roster, Manage SUG (System User Group), Manage Group Members/Officers.
+
+The groups component is mapped with associated permissionId and provides access based on the permissionId’s passed to the component. Refer to the UserPermissions model in below. 
+
+```typescript
+export interface UserPermissions {
+  permissionId: string;
+  permissionName: string;
+}
+```
+
+## 5. Send the JWT Token as Bearer Token to every API Request for Authentication & Authorization
+API requires the JWT token of the logged in user as bearer token to authenticate the user for every API request. You can implement Angular Interceptor to pass the bearer token for every API request or reuse the token.interceptor available from @ieeesa-npm/utility NPM package.
+
+## 6. Use constants.json to update the screen texts, labels and error messages
+You can find the screen texts, labels, aria labels, and error messages at **projects/groups/src/lib/assets/constants.json** to update it. You have to publish the packages and integrate the latest version of NPM package to reflect the updates to your application.
+
 ## Further help
 
 To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.