@abt-desk/apm NPM

Profile manager

This library contains the APM application as a component which can be integrated in different Anywhere Real Estate web systems which use Angular, React or HTML. APM itself consists of 5 different components which are About me, Contact Info, Office, Social Media and Photo.

API Details

We are calling the MDM Agent API to fetch the details into the APM application where data will be loaded when the call is made.
RDM API is available to fetch the types and descriptions for each field.

Note

Extranet sites will not be interacting with the APIs. They are already taken care of in the APM package.
Possible Brand Codes – BHG, ERA, C21 and CBR.
Parent application must leverage okta authentication.

Installation

npm install @abt-desk/apm

Intergrating into a project

Angular

After installing, add the following configurations
Import the following into the main component file

import '@abt-desk/apm/abt-desk-apm';

Include the following in the main template file

<agent-profile-manager brand-code="C21" (apmMessage)="getMessage($event)"></agent-profile-manager>

Include the following in the main styles file

@import '@abt-desk/apm/styles';

Include the following in the angular.json file

    {
        "input": "./node_modules/@abt-desk/apm/icons",
        "glob": "**/*",
        "output": "icons"
    },
    {
        "input": "./node_modules/@abt-desk/apm/tinymce",
        "glob": "**/*",
        "output": "tinymce"
    }

React

After installing, copy the contents from ‘@abt-desk/apm’ from node_modules to the Public folder
Add the following script and styles to the index.html

<script type="text/javaScript" src="./abt-desk-apm.js" defer></script>
<link rel="stylesheet" href="./styles.css" />

Include the following in the main template file

<agent-profile-manager brand-code="C21"></agent-profile-manager>

HTML

After installing, add the following to the main html in body section.

<agent-profile-manager brand-code="C21"></agent-profile-manager>
<script src="scripts/abt-desk-apm.js"></script>

Include the following in the head section

<link rel="stylesheet" href="styles.css" />

Input Configurations

Input Property	Description
`brandCode` (Mandatory)	Type: `string` Brand code of the embedding application. Available brand codes - BHG, C21, CBR and ERA
`authToken` (Mandatory)	Type: `{accessToken: string}` OKTA auth token of the logged in user
`snackbarConfig` (Optional)	Type: `{verticalPosition: string, horizontalPosition: string}` Placement of the snackbar notification. Acceptable `verticalPosition` is `'top' \\| 'bottom'` and `horizontalPosition` is `'center' \\| 'right' \\| 'left' \\| 'start' \\| 'end'`

| adminMode (Optional) | Type: boolean, Default: false If set true it will show the Profile Directory page as the initial view |

| appHeaderId (Optional) | Type: string, Id of the header element of embedding application. if value is passed, will enable the sticky header functionality for apm tabs header |

Angular

<agent-profile-manager
  [brandCode]="'C21'"
  [snackbarConfig]="{verticalPosition: 'top',horizontalPosition: 'right'"
></agent-profile-manager>

React

For string type, the value can be passed in an attribute like below

<agent-profile-manager brand-code="BHG"></agent-profile-manager>

Note: Camelcase needs to be separated with "-"

To pass complex value get the APM DOM element reference and pass value to the property like below

class App extends Component {
  constructor(props) {
    super(props);
    this.apmRef = React.createRef();
  }
  componentDidMount() {
    this.apmRef.current['snackbarConfig'] = {
      verticalPosition: 'top',
      horizontalPosition: 'right'
    };
  }
  render() {
    return <agent-profile-manager brand-code="C21" ref={this.apmRef}></agent-profile-manager>;
  }
}

HTML

For string type, the value can be passed in an attribute like below

<agent-profile-manager brand-code="BHG"></agent-profile-manager>

Note: Camelcase needs to be separated with "-"

To pass complex value get the APM DOM element object and pass value to the property like below

<body>
  <agent-profile-manager id="apm"></agent-profile-manager>
  <script>
    var el = document.getElementById('apm');
    el['snackbarConfig'] = {
      verticalPosition: 'top',
      horizontalPosition: 'right'
    };
  </script>
</body>

Output events

Output event	Description
`apmMessage`	Type: `{errorCode: string, errorSummary: string}` Exception errors thrown from profile manager application
`callbackToClearAPMToken`	Type: `{clearAPMToken: () => void}` Callback function to clear the stored token in the profile manager application
`eventRenewToken`	Type: `{renewToken: (token: {accessToken: string}) => void}` Callback function to set the renewed token in the profile manager application

Angular:

<agent-profile-manager
  (apmMessage)="getMessage($event)"
  (eventRenewToken)="eventRenewToken($event)"
></agent-profile-manager>

export class EmbeddingComponent {
  apmRenewToken;

  getMessage(ev) {
    // Handle the exception message triggered from profile manager
    if (ev.detail.errorCode === 'login_required') {
      this.oktaAuth.signOut();
      this.router.navigateByUrl('/');
    }

    if (ev.detail.errorCode === 'token_expired') {
      const renewedToken = { accessToken: '', idToken: '' };
      this.apmRenewToken(renewedToken);
    }
  }

  eventRenewToken(ev) {
    // Assign callback function to the class property to call it later
    this.apmRenewToken = ev.detail.renewToken;
  }
}

React:

class App extends Component {
  constructor(props) {
    super(props);
    this.apmRef = React.createRef();
    this.apmRenewToken;
  }
  componentDidMount() {
    this.apmRef.current.addEventListener('apmMessage', ({ detail }) => {
      // Handle the exception message triggered from profile manager
      if (detail.errorCode === 'login_required') {
        this.props.oktaAuth.signOut();
        this.props.history.push('/login');
      }

      if (detail.errorCode === 'token_expired') {
        const renewedToken = { accessToken: '', idToken: '' };
        this.apmRenewToken(renewedToken);
      }
    });

    this.apmRef.current.addEventListener('eventRenewToken', ({ detail }) => {
      // Assign callback function to the class property to call it later
      this.apmRenewToken = detail.renewToken;
    });
  }
  render() {
    return <agent-profile-manager brand-code="C21" ref={this.apmRef}></agent-profile-manager>;
  }
}

HTML:

<body>
  <agent-profile-manager id="apm" brand-code="BHG"></agent-profile-manager>
  <script>
    var el = document.getElementById('apm');
    var apmRenewToken;

    el.addEventListener('apmMessage', function (ev) {
      // Handle the exception message triggered from profile manager
      if (ev.detail.errorCode === 'login_required') {
        oktaSignIn.signOut();
        window.location.href = '/login';
      }

      if (ev.detail.errorCode === 'token_expired') {
        const renewedToken = { accessToken: '', idToken: '' };
        apmRenewToken(renewedToken);
      }
    });

    el.addEventListener('eventRenewToken', function (ev) {
      // Assign callback function to the variable to call it later
      apmRenewToken = ev.detail.renewToken;
    });
  </script>
</body>

Profile manager width setting

By default profile manager will take 100% parent element width in embedded application. This can be modified using css like below

<agent-profile-manager class="apm-root-wrapper"></agent-profile-manager>

.apm-root-wrapper {
  display: block;
  width: 80%;
  margin: 0 auto;
}

Note to parent application

The okta session will be handled by the parent application.
In case of okta session expiry, we will be creating an interface to inform the application about the exception failures, and they will be responsible for the reauthentication.
Header and footer will not be included as part of the APM package.

Exception handling

login_required

If the user is not logged into okta and tries to login to the application, then the application will send an error code as 'login_required' based on which the user is redirected back to the sign in page.

token_expired

If the token gets expired then the application will send an error code as 'token_expired' based on which the embedding application can renew the token and set it back to the profile manager application.

access_denied:

If the user doesn’t have access to the NPM application. We will show the error saying, 'Sorry, but you don't have access to this application.' Parent must get access to the application to be able to login. In other case, if a C21 user is trying to login to CBR brand page, we can expect this scenario. Since this exception can’t be handled by the parent application, we will be showing an error message.

generic_error:

When API’s are down, or server is down, the parent application won’t be able to do anything but wait. Since this exception can’t be handled by the parent application, we will be showing an error message.

Configuration Timelines:

Okta configurations - Any application planning to embed profile manager should provide the prod URL's and plan 2 weeks prior to launch.
APIGEE config - All the Prod URL's should be allowed traffic to be allowed to the API's and need to be configured in APIGEE portal. Requests should be made 2 weeks ahead of launch.
ClientID Config - The application clientid should be provisioned access to call mdm api's.