How to set up and edit an app integration

A guide to setting up and editing app integrations

How to set up an app integration

To set up a new custom app, click the "Create app"-button located at the top right of the "Installed apps"-page. If no apps are installed, this button will also appear at the center of the page.

Installed apps page

This will present you with the "Create app"-page.

App creation - General settings page

During app creation, you must enter a name for the app. You can optionally provide a description to help identify the app’s functionality. The messaging version is automatically set to the latest version of the API used for communication. You can also choose whether the app should be active. Above you can see an example of the setup.

Once done you can proceed by clicking the "Next"-button in the bottom right corner.

Extension points setup page

You will now be taken to the "Extension points setup"-page.

Here you can add a new extension point by clicking the "Add extension point"-button in the center of the screen.

Added extension point

When creating an extension point, you must provide a label. This label is used both for identification and for key generation to ensure version matching across upgrades. You can also add a description to further clarify its purpose.

You must then select a type for the extension point. The selected type determines where in the PIM the extension can be used. For example, it can be a widget displayed on the dashboard or a tab added to a data model in product structures.

Extension point setup example

Above you can see an example of an extension point. After selecting a type, you are required to enter an embed URL, which specifies where the app is hosted. Optionally, you can provide a thumbnail URL, which will be displayed when, in this example, adding the widget to the dashboard.

The URLs configured for the app must point to a running application. In this example, the app is run locally for development purposes. In a production setup, the app should be deployed and accessible by Struct PIM.

For more info about the fields see: Apps details

Once done you can proceed by clicking the "Save"-button.

How to edit an app integration

To edit a custom app in click the three dots icon at the top right of the app you want to edit. From here click the "Details"-button.

In order to delete an app from the PIM click the "Delete"-button instead.

Example of custom app

In order to add custom app to the PIM some steps need to be taken. In this guide, we will expand on the steps outlined in the quickstart guide.

Setting up the app

To integrate an app into the Struct PIM, start by setting up a TypeScript project. In this example we are using Vite.

We start with creating and navigating to the project folder:

mkdir my-pim-integration
cd my-pim-integration

We then initialize the project with Vite:

npm create vite@latest .

During initilization there are various framworks and variants to choose from. In this example we select the following options:

• vanilla for the framework.

• Set the variant to typeScript.

In this example the name given to the project is my-pim-integration.

This setup will create a framework-agnostic TypeScript project ready for further development.

From here we can open the project in VS Code by typing the following in the terminal.

code .

Now in the project you need the following SDK package in order to connect with the PIM. There are also two other packages, one for UI and one for icons in order to style app in a way that matches the PIM.

Proceed to install the packages through the following command:

npm install @structdk/ui @structdk/struct-icon @structdk/extension-sdk

Once the required packages have been installed, import them at the top of your src/main.ts file:

import '@structdk/ui/dist/struct-ui.css';
import '@structdk/struct-icon/font/struct-icon-24.css';
import { createStructSDK } from '@structdk/extension-sdk';
import type { TabContextPayload } from '@structdk/extension-sdk';

With the dependencies in place, the next step is to create a minimal extension by setting up a SDK instance.

This sets up a minimal app that connects to the PIM. For more details on each method, refer to the SDK documentation.

import '@structdk/ui/dist/struct-ui.css';
import '@structdk/struct-icon/font/struct-icon-24.css'
import { createStructSDK } from '@structdk/extension-sdk';
import type { TabContextPayload } from '@structdk/extension-sdk';

async function init() {
  // SDK instance
  const struct = createStructSDK({ hostOrigin: 'https://your-struct-instance.struct.com' });
  
}

// Initialize app on window load
window.addEventListener('load', () => {
  init();
});

Enclose the code within an init() function to allow the use of async/await. This is useful when calling asynchronous methods such as getContext(), if your extension needs access context data provided by the PIM.

The window.addEventListener() ensures the app initializes only once the page is fully loaded. This guarantees accurate embedding and proper refreshing on page reloads.

With this setup in place we can now begin customizing the app. In this case we will be keeping it simple by simply adding a hello world component.

Adding a component

To begin customizing the app, we’ll create a simple Hello World component. We define it as a function that takes a container element and a click handler. This makes the component self-contained and reusable, allowing it to insert its HTML directly into the container while keeping UI logic separate from the SDK:

export function HelloWorld(container: HTMLElement, onClick: () => void) {
  container.innerHTML = `
    <div class="card p-4 space-y-4">
      <h1 class="text-xl font-semibold">Hello World</h1>
      <button class="btn btn-primary">
        <span class="si-24 si-button-play" aria-hidden="true"></span>
        Click me
      </button>
    </div>`;

  const button = container.querySelector<HTMLButtonElement>('.btn');
  button?.addEventListener('click', onClick);
}

Once the component is defined, we render it in src/main.ts. We create a sub-containers for the components and insert them into the root container app defined in the index.html.

const app = document.getElementById('app');
if (app) {
  
    const helloContainer = document.createElement('div');
    app.appendChild(helloContainer);

  HelloWorld(helloContainer, () => {
    struct.actions.showSnackbarMessage({
      message: 'Hello World clicked!',
      placement: 'top',
      isError: false
    });
  });
}

// 7. Initialize app on window load
window.addEventListener('load', () => {
  init();
});

When the button is clicked, the handler runs and triggers an SDK action, showing a snackbar message in the PIM.

Now the app is ready to be integrated into the PIM. Now all you need is to ensure that all dependecies are installed by entering the following command:

npm install

With this you can now run the app through the following command and integrate it with the presented localhost URL into the app by following the guide above.

npm run dev