Vim Docs

Appearance

Creating your Settings Application ​

On top of using VimOS.js to integrate your application's iframe within Vim Connect and display it in the Vim Hub on EHRs, you can also inject an additional optional iframe into the Vim Console. This allows you to create a dedicated Settings Application where organization administrators can customize and configure your main application.

In order to implement your Settings Application app you need to install our VimAppSettings.js package. We provide two ways to install the sdk into your application: Via a script tag in your html, and via a public npm package.

Script tag ​

Include the VimAppSettings.js script on each page of your application to incorporate VimAppSettings.js into your application. It should always be loaded directly from https://console.getvim.com rather than included in a bundle or hosted yourself.

html
<head>
  ...
  <script src="https://console.getvim.com/app-settings-sdk/v1.x.x/app-settings-sdk.umd.js"></script>
  ...
</head>
<body>
  ...
</body>

tip

TIP

  • If you are building a multi page application, you should include the script on each page of your application, not just the main page.
  • Make sure to add the script tag before any script code that uses VimAppSettings.js; this ensures VimAppSettings.js is loaded when your code uses it.

NPM ​

We also provide an alternative method to incorporate VimAppSettings.js with an npm package making it easier to load and use VimAppSettings.js as a module. Using the npm package allows you also to leverage TypeScript powerful auto-completion capabilities. When working with TypeScript in an integrated development environment (IDE) such as Visual Studio Code, the IDE can use the type information defined in VimAppSettings.js npm package to offer auto-completion suggestions.

To use VimAppSettings.js as a module and leverage TypeScript auto-completion capabilities, you can install it in your tech stack like this:

bash
npm install vim-app-settings
bash
yarn add vim-app-settings
bash
pnpm add vim-app-settings

minimum requirements

INFO

VimAppSettings.js TypeScript works with TypeScript V5 and above.

Initializing the VimAppSettings SDK from your app ​

ts
const vimAppSettingsSDK = await window.appSettingsSdk.initializeVimSettingsSDK();
// Use vimAppSettingsSDK instance for further interactions with VimAppSettings.js
ts
import { loadSettingsSdk } from 'vim-app-settings';

async function init() {
  const vimAppSettingsSDK = await loadSettingsSdk();
  // Use vimAppSettingsSDK instance for further interactions with VimAppSettings.js
}
init();

Authentication flow ​

The authentication flow for the Settings Application sdk is similar to the VimOs.js authentication flow

tip

TIP

You can reuse the same launch and token endpoints for both your main application and Settings Application, this requires some modifications:

  1. The launch endpoint for the setting application has a ?launch_type=APP_SETTINGS query param. In your launch endpoint implementation, check for this parameter. Based on the parameter value, set the appropriate redirect_uri when calling the oauth/authorize endpoint: If launch_type=APP_SETTINGSs, use your Settings Application URL Otherwise, use your main application URL

This way, a single set of endpoints can handle both application contexts.

  1. Since the token endpoint will be called with your app settings as the origin, you need to add CORS support to the token endpoint if your app settings does not share the same origin as your backend.

Get idToken and organization id ​

The Settings Application runs within the Vim Console in a specific organization's context. The organization id is embedded within an id token.

After successful authentication and settings SDK initialization, retrieve the session id token using the getIdToken function. To obtain the organization id, decode the idToken and extract the organization id from the https://getvim.com/organizationId claim in the token.

ts
import jwt_decode from 'jwt-decode';
const ORGANIZATION_ID_KEY = 'https://getvim.com/organizationId';

const idToken = vimAppSettingsSDK.getIdToken();
const decodedToken = jwt_decode<{ [key: string]: string }>(idToken);
const organizationId = decodedToken[ORGANIZATION_ID_KEY];