Parent App Integration

ProcessFactorial Forms can be embedded in a parent application — typically a React single-page app. This article documents the contracts the parent app must fulfil for the form to work correctly.

1. Provide an authentication token (required)

For authenticated forms, the parent app must expose window.pfGetJWTToken as a global function. The Form Engine calls this whenever it needs a JWT token to authorise API requests.

Required for authenticated forms

If window.pfGetJWTToken is not defined, the form throws an error and cannot render.

Contract

/**
 * @returns {Promise<string> | string} A JWT token string
 */
window.pfGetJWTToken = async () => {
    // Return the current user's JWT token from your auth system
    const token = await yourAuthProvider.getToken();
    return token;
};

Example with MSAL (React)

import { useMsal } from '@azure/msal-react';
import { useEffect } from 'react';

function App() {
    const { instance, accounts } = useMsal();

    useEffect(() => {
        window.pfGetJWTToken = async () => {
            const response = await instance.acquireTokenSilent({
                scopes: ['api://your-app-registration/access_as_user'],
                account: accounts[0]
            });
            return response.accessToken;
        };
    }, [instance, accounts]);

    // ... render the DEM snippet
}

---

2. Receive host events from the form (optional)

The Form Engine sends postMessage events to the parent window when the user navigates, changes fields, or triggers custom button actions.

For the full message schema and a copy-paste listener example, see Parent Event Notifications.

---

3. Use the Forms Engine API (optional)

window.pfFormsEngine.v1 is available for reading and writing field values, injecting custom HTML, and triggering form events programmatically.

For a complete walkthrough and API reference, see Injecting Custom HTML.

---

Troubleshooting

• Authenticated forms require the parent web app to expose window.pfGetJWTToken
  • The form requires authentication but window.pfGetJWTToken is not defined. See above.
• Events never arrive in the parent listener
  • Confirm you registered window.addEventListener('message', ...) in the parent window.
  • If using an iframe, ensure your listener is on the parent window and event.origin is checked.