How to: Integrate your existing application with the Console UI

The Console UI acts as the glue that binds the application and the end-user together. After you register your App in the OS1 developer portal and integrate it with the Console UI, it is ready to be made available to end-users on their respective landing pages.

For more information about Console UI, see Console UI Overview.

This guide walks through the installation and installation of the Console UI SDK in your application.

Installation

Run the following command in your project to install the console-ui-react-sdk package:

npm install @foxtrotplatform/console-ui-react-sdk

Usage

Step 1: Integrate the SDK

Import the OS1Provider function from the library and use it to enable authentication and render the header and sidebar. Next, pass a function as a prop to your application with a setState method that sets the state of the Console UI instance.

import { OS1Provider } from "@foxtrotplatform/console-ui-react-sdk";

<OS1Provider
  clientId={"platform:app:ui"} // The clientId you receive after creating an app.
  loginRedirectPath={"/success"} // Path to redirect users after successfully logging in for the first time. 
  logoutRedirectPath={"/"} //Path to redirect users after logging out. 
  appId={"SolutionName-appId"} //The appId you recieve after creating an app 
    devOrgName={"delhivery"} // Optional: Only pass this parameter when using development mode.
  
>
  <Initiate setConsole={handleConsoleInstanceChange} /> //Your component for setting the Console UI instance.
</OS1Provider>;

Step 2: Create a Component to use the Console UI Context

Create a component that uses the ConsoleUIContext and sets its state to be used by the client application.

import React from "react";
import { ConsoleUIContext } from "@foxtrotplatform/console-ui-react-sdk";

function Initiate(props) {
  const consoleInstance = React.useContext(ConsoleUIContext);
  if (consoleInstance) {
    props.setConsole(consoleInstance);
  }
}

export default Initiate;

Create a Network Client for API Requests

Use the OS1HttpClient API to set up a network client for API requests, passing the authInitializer property from ConsoleUIContext:

import { OS1HttpClient } from '@foxtrotplatform/console-ui-react-sdk';

class NetworkClient {
  public readonly instance: any;

  constructor(`instanceName`) {
    this.instance = OS1HttpClient.createClient({
     baseURL: `https://abc.preprod.fxtrt.io/core/api/v1/aaa`,
   },`instanceName`);
  }
}

Displaying Toast Notifications

Use the Toast function to display toast notifications in your web application.

const toastConfig = {
   bgColor: "yellow", // background color of the toast [green,red,yellow,black,white]
   message: "Operation Successful", // message that will be shown inside the toast [128 character limit]
   timeout: 10, // time in seconds after which toast will disappear
   icon: "error", // icon that will be appearing before the message [info,error,warning,success,failure,none]
   closeButton: true, // denotes whether the close button will be present on the right of the toast
}

<OS1Toast clientId={"platform:app:ui"} loginRedirectPath={"/fms/success"} logoutRedirectPath={"/"} devOrgName={"delhivery"} appId={"Single Leg-app:435858a9-1238-5ca9-b100-a5d46d108910"} elementId={"toastElement"} toastConfig={toastConfig} />

📘

Each toast element should have a unique elementId.


Add Modal Components

Utilize the modal function to incorporate modal components into your webpage:

const modalConfig = {
  title: "Deactivate", // Title of the modal [96 characters limit]
  message: "Do you want to continue?", // message that will be appearing on the modal
  icon: "info", // icon that will be appearing along with the message [info,error,warning,success,failure,none]
  buttons: [
    // maximum two buttons allowed
    {
      id: "button-element-1", // unique id of the button
      backgroundColor: "green", // background color of the button
      text: "Cancel", // text appearing on the button
      event: "upEvent", // unique name of the custom event that will be triggered on click
    },
  ],
};
<OS1Modal
  clientId={"platform:app:ui"}
  loginRedirectPath={"/fms/success"}
  logoutRedirectPath={"/"}
  devOrgName={"delhivery"}
  appId={"Single Leg-app:435858a9-1238-5ca9-b100-a5d46d108910"}
  elementId={"modalElement"}
  modalConfig={modalConfig}
/>;

📘

Listen for the event when a button is clicked; `event.details will contain the modal element ID.

Customize Header Controls

Customize the header by passing injectable controls as props to the OS1Provider component.

import { OS1Provider } from "@foxtrotplatform/console-ui-react-sdk";

 const controls = [{
     type: "AutoComplete", //Type can be TextBox,TextBoxButton,DropDown, SearchBox, AutoComplete
     width: 100, // width as percentage of the maximum width that is assigned to injectable component
     placeholder: "Search Items", // placeHolder text
     id: "AutoComplete1", //Unique Id which distinguish it with other injectable controls.
     float: "left", // Option to align items left or right
     functionBoundOption: autoComplete(), // Function that returns a value as an array of object in the form of [{ value: string, text: string }]
 }]
  <OS1Provider clientId={"platform:app:ui"} loginRedirectPath={"/fms/success"} logoutRedirectPath={"/"} devOrgName={"delhivery"} controls ={controls} appId={'SolutionName-appId'}>
             <Initiate setConsole={handleConsoleInstanceChange} />
 </OS1Provider>

📘

You can have up to 3 injectable controls, and each must have a unique ID.

Events from Injectable Controls

Use the ConsoleUIContext state variable to listen for events emitted by injectable controls.

const { consoleInstance } = props;
if (consoleInstance) {
  consoleInstance
    .eventBus()
    .on(consoleInstance.events().OnChangeEvent, (e) =>
      window.console.log(e)
    );
}

📘

_Exposed events include OnChangeEvent, OnBlurEvent, OnScrollEvent, OnClickEvent, and OnFocusEvent for injectableID


Console Settings

Configuring Request Headers

TheNetworkClient automatically configures the following headers for requests:

  • x-coreos-access (Access token)
  • x-coreos-tid (Tenant ID)
  • x-coreos-userinfo (User info)
  • x-coreos-auth (Auth token)

You can manage these headers using the following options:

  • withAccess
  • withTid
  • withUserInfo
  • withAuth

Notes

  1. By default, all headers are set to true. To remove a header from a request, set its value to false.
  2. Access tokens are verified and regenerated (if expired) every time an API request is made.
  3. The x-coreos-userinfo header contains the user ID.
  4. The x-coresos-auth header contains the ID token.

See the sample snippet:

import NetworkClient from "./networkClient";

const handleClick = () => {
//here consoleInstance is the state variable of ConsoleUIContext;
    if (consoleInstance) {
        const client1 = new NetworkClient(consoleInstance.authInitializer); //consoleInstance.authInitializer is an instance of AAA class that we get from ConsoleUi Context
        const reqHeaders: any = {
            withAccess: false,
            withTid: false,
            withUserInfo: false,
            withAuth: false,
        };
        client1.users.('45', reqHeaders).catch(function (err) {
        console.log('errr', err);
        console.log('error', JSON.stringify(err));
        });
    };
};

Contact Us Page

You can provide a support link for customers by using the Contact Us page. We provide the following:

  • A text area describing user's issues in detail
  • An option to upload a screenshot that may help clarify a user's issue.

This will then create a ticket to track the support request.

Timezone Settings

Users can change the application's timezone. Initially, the timezone is set according to the tenant's preferences, but users can change it according to their needs. The chosen timezone will be stored in the browser's local storage.

Time Conversion and Retrieval

The SDK exposes the converTime and currentTimeZone functions:

  • convertTime: Converts the time in your application to your desired format.
  • currentTimeZone: Returns the current timezone stored in the browser.
const { consoleInstance } = props;
if (consoleInstance) {
  console.log(
    consoleInstance.convertTime("2014-06-01 12:00", "MM-DD-YYYY HH:mm:ss")
  ); // In this 2nd parameter i.e. format in which we want to convert time is optional.
  console.log(consoleInstance.currentTimeZone());
}

Customizing App Navigation

End users can choose what happens when they click on an app in the Console side navigation menu. They can select whether they would like to open it in the current window or a new tab by opening the 'User preferences' in the profile dropdown and selecting the desired option under Set App Redirect Behavior.