@bcone/neo-app-sdk

NEO App SDK

This NPM package contains Bristlecone NEO® starter kit components which includes User Authentication with Single Sign-On and Aws Cognito, Claims Management and Tableau widget.

It contains inbuilt services like AuthGaurd for authorization, Login Service, Message Service, Neoutil Service, HTTP Interceptor Service.

Dependencies

Library	Version
@aws-amplify/auth	1.2.24
@aws-amplify/core	1.0.28
@ng-bootstrap/ng-bootstrap	4.2.2
ngx-alerts	3.4.5
angular-oauth2-oidc	8.0.4
apollo-angular	1.8.0
apollo-cache-inmemory	1.6.5
apollo-client	2.6.8

Creating an app using the NEO® App SDK Starter Kit

If you are creating an app using the NEO® App SDK repo https://github.com/BconeLabs/neo-app-sdk.git then do the following

1. Register your app using NEO® Developer App (https://developer.<tenant>-neo.bcone.com)
2. Create a empty environment configuration with a name.
3. Update the environment.ts with the values configured in above steps

export const environment = {
    ...
    ...
    application_id: '', // Application id used in Step #1 
    config_fetch_env: '', // Environement name used in Step #2
    graphql_url: '' // https://graphql.<tenant>-neo.bcone.com
    ...
}

To override the default app configurations, login to NEO® Developer App and change the following values.

<i>client_id</i> - client id that has access to the cognito pool    
<i>pool_id</i> - cognito pool id that authenticates the user

Creating/Modifying existing angular application

neo-app-sdk@2.1.x is compataible with Angular version 7.2.x . If in your project is using Angular version below 7.2.x please update Angular & typescript using step 1 and 2.

1. Update Angular core and Angular cli

   ng update @angular/cli@7.2.11 @angular/core@7.2.11
   

2. Update typescript version

   npm install --save-dev typescript@3.1.6
   

If you are creating or modifying an existing app that has not used this npm package follow the below mentioned steps.

1. Install neo-app-sdk npm package

   npm install --save @bcone/neo-app-sdk
   

   npm install --save angular-oauth2-oidc@8.0.4  apollo-angular@1.8.0  apollo-cache-inmemory@1.6.5  apollo-client@2.6.8 
   

2. Update app.module.ts

   Import the following in app.module.ts

   import { InitConfigService } from '@bcone/neo-app-sdk';
   import { TokenInterceptor } from '@bcone/neo-app-sdk';
   import { MessageService } from '@bcone/neo-app-sdk';
   import { NeoAppsdkLoginModule } from '@bcone/neo-app-sdk';
   import { AuthGuard } from '@bcone/neo-app-sdk';
   import { NeoUtilService } from '@bcone/neo-app-sdk';
   

   Add the following code in @NgModule imports section

   imports: [
       ...
       ...
       NeoTableauModule,
       NeoAppsdkLoginModule.forRoot(appEnv)
   ]
   

   Inject following services in @NgModule Providers of app.module.ts

   providers: [
       ...
       ...
       AuthGuard,
       MessageService,
       InitConfigService,
       NeoUtilService,
       {
           provide: APP_INITIALIZER,
           useFactory: (config: InitConfigService) => () => config.load(),
           deps: [InitConfigService],
           multi: true
       },
       {
           provide: HTTP_INTERCEPTORS,
           useClass: TokenInterceptor,
           multi: true
       }
   ]
   

3. Create/Update login component

   Create login (do not change the name) component if it does not exist

   ng g c login
   
   

   Add login component as a parent

   const routes: Routes = [
       ...
       ...
       {
           path: 'login',
           component: LoginComponent,
       }
   ]
   

   In login.component.html replace the content with the following directive/component

   <ngx-neo-appsdk-login [enableCognito]="true" [enableSso]="true"></ngx-neo-appsdk-login>
   

   enableCognito (Boolean) - To enable/disable cognito login

   enableSso (Boolean) - To enable/disable SSO login

4. Privacy Policy acceptance

   To enable Privacy Policy acceptance use the following tag in app.component.html file

   <ngx-neo-app-privacy-policy [enablePrivacyPolicy]="true"></ngx-neo-app-privacy-policy>
   

   enablePrivacyPolicy (Boolean) - To enable/disable privacy policy acceptance

5. Customize default login screen (Optional)

   To customize Login Page UI use html injection. For Sidebar injection use loginSidebar attribute in div tag. For header injection use loginHeader attribute in div tag.

   <ngx-neo-appsdk-login>
       <div loginSidebar>
       // insert login sidebar HTML content here
       </div>
       <div loginHeader>
           // insert login header text here
       </div>
   </ngx-neo-appsdk-login>
   

6. Customize default header (Optional)

   To inject custom UI in header, use the following section

   <ngx-neo-app-header>
       <div headerLogo>
           <div class="d-inline">
           <span class="app-logo">
               <img src="<path-to-the-logo>">
           </span>
           </div>
       </div>
       <div navigationLink>
           <ul class="customNav">
           <li>...</li>
           <li>...</li>
           </ul>
       </div>
   </ngx-neo-app-header>
   

7. Implement checkFragmentUrl()

   Invoke checkFragmentUrl() if SSO Login is used to display or hide intermediate screen or navigation based on fragment

   
   ngOnInit() {
       ......
       ......
       if(this.neoUtilService.checkFragmentUrl()) {
               this.showSideBar = true; // Here We enable sidebar during SSO login
       } else {
           this.showSideBar = false; //Here We disable sidebar during SSO login
       }
   }
   
   

Tableau Widget

To use Tableau feature import NeoTableauModule in respective components module.ts file

import {  NeoTableauModule } from '@bcone/neo-app-sdk';

imports: [
    ...
    ...
    NeoTableauModule
]

In components html file add the following section

<div *ngIf="tableauConfig" >
<ngx-neo-tableau  [tableauConfig]="tableauConfig"></ngx-neo-tableau>
</div>

In components ts file define tableauConfig

const tableauConfig ={
    userName="",
    tenantName="",
    dashboardPath="",
    tableauProxyApi="",
    tableauServer=""

}

Services

MessageService

Method	Type	Description
getEnv(keyName)	-	Provides option to fetch environment data using keyname.
getClaimObj()	-	Method to fetch ClaimObject of application that contains details such as userClaims, full configuration of app, userInfo, userRoles, tenantinfo.

NeoUtilService

Method	Return Type	Description
fetchMenu(graphqlurl: optional)	Observable	Method is used to fetch app menu items. By default it is invoked.
ssoLogin()	-	To login in to the app using SSO credentials.
checkFragmentUrl()	-	To avoid intermediate login or Navigation. It returns true or false based on login state.
cognitoSignIn(email,password,initialRoute)	-	To login in to the app using Cognito credentials. Default value of intialRoute is '/'
isValidAccessToken()	boolean	To check if the token is still valid
getAccessToken()	string	To get the access token
getIdToken()	string	To get the id token
getUserClaim()	json	To get the claim associated with the logged in user
getUserName()	string	To get the full name of the logged in user
getUserEmail()	string	To get the email of the logged in user
getUserRole()	string	To get the role of the logged in user in the app
isCognito()	boolean	To check if the login is with SSO or cognito mode. If true it is cognito mode else it is SSO.
signOut()	-	To logout of the app

Customize redirection to the landing page

If an app wants to redirect logged in user to a different landing page based on custom logic (Based on role, user profile, etc.) use the following approach.

Define custom logic shown below

dynamicRouteFn(claim: any): string {
    // claim contain roles, userprofiles, etc.
    let redirectUrl = '' // Set default url if is not matched
    if(claim.roles && claim.roles.legth > 0) {
        claim.roles.foreach((role) => {
            if(role === 'Developer') {
                redirectUrl = 'developer-landing-url'
            }
            if(role === 'Data-scientist') {
                redirectUrl = 'data-scientist-landing-page';
            }
        });
    }
    return redirectUrl;
}

Inject defined callback function into ssoreturn() method & cognitosignin() of NeoUtilService Class. this.neoUtilService.ssoReturn(this.dynamicRouteFn); this.neoUtilService.cognitoSignIn(this.dynamicRouteFn);

How to use claim object in component or Html

Claims which are permissions on features can be configured in NEO® App Developer.

For configure please follow product handbook below given link
https://docs.bristleconeneo.com/202003/neo_handbook/ProviderDeveloper.html

After configuration claim object is available in the below given format based on the role of the user

claims:{ 
      "page.page-name.view":true,
      "entity.entity-name.edit": true,
      "component.component-name.view": true,
   }

Claim object contains three part, first is compononent type like page/component/entity, second consists name of component and last part of claim object contains CRUD(Create, Read, Update & Delete) operation of component of HTML.

For example, the claim for page aboutUs and has view permission. The claim for that particular page would be

page.aboutUs.view = true;

Component conditioning based on claim object can be implemented as below

<app-aboutUs-component *ngIf="page.aboutUs.view"> </app-aboutUs-component>

TableauJS component

TableauJS component is useful to display Tableau Chart using tableau js api. It provide refresh, revert, extract option.

Use

index.html

........
........
 <script src="https://public.tableau.com/javascripts/api/tableau-2.min.js"></script>

Paste the above script in index.html

To use Tableau feature import NeoTableauModule in respective components module.ts file

import {  NeoTableauJSModule } from '@bcone/neo-app-sdk';

imports: [
    ...
    ...
    NeoTableauJSModule
]

In components ts file define tableauConfig

xyz.component.ts

import { NgOnint } from '@angular/common';
.......................
.......................

const declare tableau : any; 


export class XyzComponent implements OnInit {
    ................
    ................
    tableau = tableau;
    tableauConfig
    tabOption = {
        .....
        height: '500px',
        .....
    }

    constructor() {

    }

    ngOninit() {
        const tableauConfig ={
            userName="",
            tenantName="",
            dashboardPath="",
            tableauProxyApi="",
            tableauServer=""
        }
    }
}

In components html file add the following section

xyz.component.html

<div *ngIf="tableauConfig" >
<neo-tableau-js  [tableauConfig]="tableauConfig"  [tableauInstance]="tableau" [tabOption]="tabOption"></ngx-neo-tableau-js>
</div>

Styling button

Refresh, Revert, the export button has refresh-btn, revert-btn, export-btn class with help of css class button can customize according to requirement.

tabOption

Name	Type	Description
disableUrlActionsPopups	bool	Indicates whether to suppress the execution of URL actions. This option does not prevent the URL action event from being raised. You can use this option to change what happens when a URL action occurs. If set to trueand you create an event listener for the URL_ACTION event, you can use an event listener handler to customize the actions. For example, you can direct the URL to appear in an iframeon your web page
hideTabs	bool	Indicates whether tabs are hidden or shown.
hideToolbar	bool	Indicates whether the toolbar is hidden or shown.
instanceIdToClone	string	Specifies the ID of an existing instance to make a copy (clone) of. This is useful if the user wants to continue analysis of an existing visualization without losing the state of the original. If the ID does not refer to an existing visualization, the cloned version is derived from the original visualization.
height	string	Can be any valid CSS size specifier. If not specified, defaults to the published height of the view.
width	string	Can be any valid CSS size specifier. If not specified, defaults to the published width of the view.
device	string	Specifies a device layout for a dashboard, if it exists. Values can be default, desktop, tablet, or phone. If not specified, defaults to loading a layout based on the smallest dimension of the hosting iframe element.

|