Embedding a micro frontend in an InsuranceSuite application

InsuranceSuite (IS) applications render their pages from PCF configuration files. You can embed Jutro micro frontends into InsuranceSuite pages using PCF templates and the Microfrontend SDK in context isolation mode. This section describes the recommended approach, which uses a web component.

The web component encapsulates all micro frontend (MFE) initialization logic: static ESM import, lifecycle management (auto-unmount on navigation), and router integration. This is the recommended approach for InsuranceSuite embedding.

The sample-jutro-mfe name used throughout this section is an example. Give the web component a name that describes your specific micro frontend, such as fnol-wizard-mfe, and update the element name, class name, and customElements.define call to match. Custom element names must contain a hyphen.

Important: You can embed the same MFE on multiple pages by adding the same <sample-jutro-mfe> element to each page. If you want to embed multiple unique MFEs (different apps), each one requires its own unique class and HTML tag name. Once a web component is defined, it cannot be overridden.

Prerequisites

In order to embed a micro frontend into an IS application, you need the following prerequisites:

• A working IS application
• Access to Guidewire Studio

For more information about Guidewire Studio, see The Studio development environment.

Step 1: Create the Gosu template

Using Guidewire Studio, create a new template.

1. In the Project pane within the gsrc section, right-click a package.
2. Select New > Gosu Template.
3. In the New Gosu Template dialog, type a meaningful name such as SampleJutroMfe.gst, and then select OK.

For more information about creating a new Gosu template, see Create and use a template file in Gosu.

Step 2: Add the sample web component

1. Add the following content to the template:

SampleJutroMfe.gst

<%@ params(mfeUrl : String, mfeScope : String) %>

<sample-jutro-mfe></sample-jutro-mfe>
<script type="module">
  import { JutroMicroFrontends } from '${mfeUrl}/jutro-micro-frontends.esm.js';

  class SampleJutroMfeElement extends HTMLElement {
    connectedCallback() {
      this._container = document.createElement('div');
      this.appendChild(this._container);

      this._renderer = JutroMicroFrontends.createRoot(
        this._container,
        '${mfeScope}@${mfeUrl}'
      );

      this._renderMFE();
    }

    _renderMFE() {
      this._renderer.render({
        jutro: {
          iframeAttributes: {
            allow: 'clipboard-write; clipboard-read',
          },
        },
      });
    }

    disconnectedCallback() {
      if (this._renderer) {
        this._renderer.unmount();
        this._renderer = null;
      }
    }
  }

  if (!customElements.get('sample-jutro-mfe')) {
    customElements.define('sample-jutro-mfe', SampleJutroMfeElement);
  }
</script>

Step 3: Create the PCF page

1. In the Project screen, navigate to configuration > config > Page Configuration, and expand it.
2. Select the node in which you want to create the new PCF file.
3. Right-click and select New > PCF file.
4. Enter the file name in the New PCF File dialog, such as JutroMFEPage.pcf.
5. For the PCF file type, select Page.

For more information about creating a PCF page, see Creating a new PCF file.

Step 4: Add the sample content

Add the following content to the PCF file:

JutroMFEPage.pcf

<?xml version="1.0"?>
<PCF
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="pcf.xsd">
  <Page
    id="JutroMFEPage"
    title="&quot;Jutro MFE&quot;">
    <Variable
      name="mfeUrl"
      type="String"
      initialValue="&quot;https://your-jutro-app.example.com/jutro-micro-frontend&quot;" />
    <Variable
      name="mfeScope"
      type="String"
      initialValue="&quot;jutroapp&quot;" />
    <Screen flexContainer="true">
      <TemplatePanel
        renderCall="web.pcf.jutroapps.SampleJutroMfe.render(__writer, __escaper, mfeUrl, mfeScope)">
      </TemplatePanel>
    </Screen>
  </Page>
</PCF>

Key features

• Reusable: You can embed multiple MFEs by adding <sample-jutro-mfe> elements on different pages. Each unique MFE should define its own custom component.
• Auto-cleanup: The MFE is automatically unmounted when the element is removed from the DOM during InsuranceSuite navigation.
• ESM isolation: Each MFE loads its own SDK version through a static import, so there are no global conflicts. The ESM module build is available starting from Jutro 10.14. The same embedding approach also works with older versions, but there might be version clashes when multiple MFEs are embedded, because they all import the Jutro MFE SDK library under the shared global variable JutroMicroFrontends. In that case, use import '${mfeUrl}/jutro-micro-frontends.js'; instead.
• flexContainer="true" on the Screen PCF element: By default, the Screen widget renders with display: inline-block, which prevents the MFE from filling the page. Setting flexContainer="true" switches it to display: flex, so the MFE expands naturally without CSS workarounds.
• <script type="module"> for initialization: Module scripts run after DOM construction is complete, so you don't need DOMContentLoaded listeners or onload callbacks.

Note: InsuranceSuite re-renders only the parts of a page that change, and it swaps out the underlying DOM to do so. A user action elsewhere on the page can therefore remove and recreate the template panel's DOM even though the user has not navigated away. When this happens, the Web Component's disconnectedCallback and connectedCallback run again, so the micro frontend is unmounted and reloaded, and any in-memory state is lost. Keep the micro frontend's state on the server or in the URL rather than relying on it persisting across renders, and avoid placing the micro frontend on pages with frequent partial updates.

Integrations

By default, the MFE runs in isolated mode and all Jutro integrations are disabled. For example, if you need to pass auth tokens from the InsuranceSuite application to the MFE instead of allowing it to handle its own auth lifecycle, you need to enable the auth integration. For more information about configuring integrations for the Microfrontend SDK, see the following pages:

• Exposing and embedding with the Microfrontend SDK
• Micro frontend API reference

Router integration

By default, an embedded MFE does not integrate its router with the host. It always renders the app's default route and manages routes internally. This works well for simple MFEs that don't need routing capabilities.

However, if you need to render a non-default route or pass query parameters, you must use a different integration pattern. IS applications don't support browser navigation, they keep navigation state on the server side and the URL updates from the MFE which causes the app to redirect to non-existing pages. In this case, you need to enable an in-memory router for the micro frontend.

To do this, update the web component from Step 2 so that _renderMFE accepts a route, sets integrateRouter: true, and provides the desired route in router.location:

connectedCallback() {
  this._container = document.createElement('div');
  this.appendChild(this._container);

  this._renderer = JutroMicroFrontends.createRoot(
    this._container,
    '${mfeScope}@${mfeUrl}'
  );

  // Example: render the initial route with query parameters
  this._renderMFE('/summary?param=value');
}

_renderMFE(route = '/') {
  this._renderer.render({
    jutro: {
      iframeAttributes: {
        allow: 'clipboard-write; clipboard-read',
      },
      integrateRouter: true,
      router: {
        location: route,
        onLocationChange: (newLocation) => {
          // updates location on MFE navigation
          this._renderMFE(newLocation);
        },
      },
    },
  });
}