HelpDesk App Framework SDK

1.0.16 · active · verified Tue Apr 21

The HelpDesk App Framework (BAF) SDK, currently at version 1.0.16, is a JavaScript library designed to streamline cross-frame communication for applications integrated into the HelpDesk helpdesk platform. It provides a unified interface for apps running within iframes to interact seamlessly with the host framework. Key capabilities include secure data access (retrieving and updating ticket, contact, and chat information), robust event handling for platform events, managing app instances, and accessing runtime context and metadata. This SDK primarily targets developers building custom applications that need to embed and interact deeply within the HelpDesk ecosystem, simplifying complex cross-origin communication patterns.

Common errors

```
BAFClient is not defined
```
cause The SDK script (or ESM module) was not correctly loaded or imported before `BAFClient.init()` was called.

fix Ensure `<script src="path/to/baf_sdk.min.js"></script>` is loaded before your app script in HTML, or `import BAFClient from 'helpdesk-app-framework-sdk';` is at the top of your module.
```
TypeError: client.get(...).then is not a function
```
cause Attempted to use asynchronous API methods (like `client.get()`) without correctly handling the returned Promise object.

fix Wrap asynchronous calls in `async/await` or chain `.then()` and `.catch()` to handle the Promise resolution.
```
npm ERR! code E404 npm ERR! 404 Not Found - GET https://registry.npmjs.org/helpdesk_app_framework_sdk
```
cause Used the incorrect package name `helpdesk_app_framework_sdk` (snake_case) instead of `helpdesk-app-framework-sdk` (kebab-case) during installation.

fix Use the correct npm package name: `npm install helpdesk-app-framework-sdk`.
```
Failed to initialize HelpDesk SDK: Parent frame not found or invalid origin.
```
cause The SDK could not establish a secure connection with the parent HelpDesk App Framework, likely due to the app not being embedded correctly or origin mismatch.

fix Verify that your app is properly embedded as an iframe within the HelpDesk platform and that the host page's origin is allowed for communication.

Warnings

gotcha The package name on npm is `helpdesk-app-framework-sdk` (kebab-case), but the `npm install` command shown in the README is `npm install helpdesk_app_framework_sdk` (snake_case). Using the incorrect package name will result in installation failure.
Fix: Always use `npm install helpdesk-app-framework-sdk` for installation.
gotcha This SDK is designed for integration within the HelpDesk app framework's iframed environment. Attempting to use it outside of this specific host context will lead to initialization failures and communication errors, as it relies on specific parent-frame messaging protocols.
Fix: Ensure your application is embedded as an iframe within the official HelpDesk app framework. Do not run it standalone for full functionality.
gotcha The SDK relies heavily on asynchronous operations, especially for data access (`client.get()`). Developers must handle Promises correctly with `.then().catch()` or `async/await` to ensure data is retrieved and errors are managed gracefully.
Fix: Always chain `.then()` and `.catch()` to Promise-returning methods or use `await` inside an `async` function.
gotcha The `engines.node` requirement of `>=18` indicates a preference for modern Node.js environments and likely ESM usage. While browser usage via `<script>` tag is supported, developers targeting Node.js should configure their projects for ESM compatibility.
Fix: For Node.js projects, ensure `type: 'module'` is set in `package.json` or use `.mjs` extensions. For older Node versions, consider a polyfill or stick to browser-only usage.

Install

npm install helpdesk-app-framework-sdk npm
yarn add helpdesk-app-framework-sdk yarn
pnpm add helpdesk-app-framework-sdk pnpm

Imports

BAFClient
wrong:
```
const BAFClient = require('helpdesk-app-framework-sdk');
```
correct:
```
import BAFClient from 'helpdesk-app-framework-sdk';
```
The SDK is primarily designed for ESM environments, especially given the `engines.node` requirement `>=18`. While a global `BAFClient` is available when loaded via `<script>`, direct Node usage typically prefers ESM.

Quickstart

Initializes the BAF SDK, logs basic context information, and demonstrates fetching data after successful initialization.

import BAFClient from 'helpdesk-app-framework-sdk';

const client = BAFClient.init((context) => {
  console.log('App initialized and ready!');
  console.log('Current Module:', context.module);       // E.g., 'ticket', 'contact', 'chat'
  console.log('Object ID:', context.objectId);          // ID of the current object being viewed
  console.log('User Name:', context.user.name);
  console.log('User Email:', client.context.getUserEmail()); // Access context details directly from client instance

  // Example: Fetching ticket subject after initialization
  client.get('ticket.subject').then(data => {
    console.log('Ticket Subject:', data['ticket.subject']);
  }).catch(error => {
    console.error('Failed to get ticket subject:', error);
  });
});

view raw JSON →