How to embed an external form module in a Sapho micro app page

Last update:

With the release of Sapho Employee Experience Portal 4.9, you can now embed a page from a separate web application running on the same application server.

This allows you to provide your users with more complex, use-case specific forms and workflows in Sapho without being limited by the Sapho platform.

Sapho provides a simple Java integration module which handles the authentication, authorization, and interaction of embedded Sapho micro apps. The module is framework-agnostic, so that your application can focus on handling business logic using any framework, as long as the resulting web application can be deployed as a standalone WAR archive.

To embed the form, you'll need to go through several steps:

  1. Set the environment variables:
    • SAPHO_EXTERNAL_FORMS_ROOT_URL - Context root of the form app. This defaults to "forms". Do not use "admin" or "apps".
    • SAPHO_EXTERNAL_FORMS_TOKEN_SECRET - The secret used for JWT token to encrypt and verify user identity. This can be arbitrary, preferably random.external_forms_1.png

  2. Deploy your form application WAR file to the context root defined by SAPHO_EXTERNAL_FORMS_ROOT_URL environment variable to the same application server where Sapho is deployed in root context.

  3. Integrate Sapho’s forms-integration module to authenticate and authorize a user, get a username, email, display name and IdP groups, and to invoke button actions on a micro app embedded page.

  4. Please note the URL, relative to the context root, where your form is accessible. Your app can expose multiple forms on separate URLs.

  5. Add the External Form (1) component from the Beta Components to your page and enter the relative URL as Form Identifier (2) in External Form Properties.

  6. If your form uses the integration module to execute Sapho button actions (3), add the buttons to your micro app page. Please make sure to your labels match with the calls you have set up in your external form’s Java code. Even if your buttons are hidden on the page, the labels will need to match the ones you have set in your code.


Next, you can preview your embedded form in your micro app.
Here is an example of an embedded external form that creates tasks in Asana:

Load the form and submit (we used submitting Asana tasks in our example).


You can then see the task created using the embedded form in Asana.