From 3abdf8fbe4af69a233bca1fb2527b4fc8181c5dd Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.co> Date: Fri, 19 Jun 2026 10:16:50 +0000 Subject: [PATCH] Document Mendix inside Teamcenter (public Beta, 11.12) --- .../refguide/runtime/mendix-client/_index.md | 2 + .../mendix-client/mendix-inside-teamcenter.md | 205 ++++++++++++++++++ 2 files changed, 207 insertions(+) create mode 100644 content/en/docs/refguide/runtime/mendix-client/mendix-inside-teamcenter.md diff --git a/content/en/docs/refguide/runtime/mendix-client/_index.md b/content/en/docs/refguide/runtime/mendix-client/_index.md index c7fafd036a0..47973660a81 100644 --- a/content/en/docs/refguide/runtime/mendix-client/_index.md +++ b/content/en/docs/refguide/runtime/mendix-client/_index.md @@ -19,6 +19,8 @@ The React client replaces [Dojo](https://dojotoolkit.org/) with [React](https:// Other components of the Mendix Client are the same in both the React and Dojo client. See [Mendix React Client](/refguide/mendix-client/react/) for more information. {{% /alert %}} +For information about embedding a Mendix web app as a native component inside Siemens Teamcenter Active Workspace, see [Mendix inside Teamcenter](/refguide/mendix-client/mendix-inside-teamcenter/). + ## Description {#description} The Mendix Client is a part of every application built with Mendix: both web and mobile. diff --git a/content/en/docs/refguide/runtime/mendix-client/mendix-inside-teamcenter.md b/content/en/docs/refguide/runtime/mendix-client/mendix-inside-teamcenter.md new file mode 100644 index 00000000000..459b1bdf64b --- /dev/null +++ b/content/en/docs/refguide/runtime/mendix-client/mendix-inside-teamcenter.md @@ -0,0 +1,205 @@ +--- +title: "Mendix inside Teamcenter" +url: /refguide/mendix-client/mendix-inside-teamcenter/ +description: "Describes how to embed a Mendix web app as a native component inside Siemens Teamcenter Active Workspace using the embedded client." +weight: 40 +beta: true +--- + +## Introduction + +Mendix inside Teamcenter lets you embed a Mendix web app as a native component inside Siemens Teamcenter Active Workspace (AWC). The Mendix app runs directly in the AWC page as a micro-frontend using the [Embedded Client](/refguide/mendix-client/embedding-the-client/) feature. + +This integration requires the [Teamcenter Connector](/appstore/modules/siemens-plm/teamcenter-connector/) to connect the Mendix app to Teamcenter data and to handle authentication. + +{{% alert color="info" %}} +Mendix inside Teamcenter is in public Beta. See the [prerequisites](#prerequisites) for required versions. +{{% /alert %}} + +## Prerequisites {#prerequisites} + +The following versions are required: + +| | Mendix | Teamcenter | Teamcenter Connector | +| --- | --- | --- | --- | +| **Beta** | 11.12 | 2512 | 2512.1.0 or above | +| **GA (planned)** | 11.18 | 2612 | TBD | + +In addition, the following requirements must be met: + +* The Teamcenter Active Workspace instance is customizable and can be rebuilt and redeployed. +* The Teamcenter Content Security Policy (CSP) is configurable. +* The Mendix app is registered with the identity provider used by Teamcenter Security Services (TcSS). +* The browser allows cross-site cookies for the Mendix domain. This can be configured per-domain via organization policy (for example, using Intune). +* There is bidirectional network connectivity between the user's browser and both the Mendix runtime and the Teamcenter server. + +For Teamcenter Connector prerequisites, see [Teamcenter Connector](/appstore/modules/siemens-plm/teamcenter-connector/). + +## Setting Up the Mendix App + +### Adding an Embedded Navigation Profile + +The Mendix app must have an Embedded navigation profile. When this profile exists, the Mendix runtime exposes the `/dist/embedded-index.js` bundle that Active Workspace loads. + +To add an Embedded navigation profile: + +1. In Studio Pro, go to **App** > **Navigation**. +2. Click **Add navigation profile**. +3. Select **Embedded** and click **OK**. +4. Configure the **Default home page** for the embedded app. + +For more information about navigation profiles, see [Setting Up the Navigation Structure](/refguide/setting-up-the-navigation-structure/). + +### Configuring CORS + +The Mendix app must allow cross-origin requests from Active Workspace, because the browser loads the Mendix client bundle from the Mendix runtime origin while the page is served from the Teamcenter origin. + +Configure the following [custom runtime settings](/refguide/custom-settings/). Replace `https://your-teamcenter.example.com` with the actual origin of your Active Workspace deployment, including scheme and port if applicable. + +#### Runtime Settings + +| Name | Value | +| --- | --- | +| `com.mendix.core.SameSiteCookies` | `None` | + +#### Custom HTTP Response Headers + +| Header | Value | +| --- | --- | +| `Access-Control-Allow-Credentials` | `true` | +| `Access-Control-Allow-Headers` | `Content-Type, x-csrf-token` | +| `Access-Control-Allow-Methods` | `POST, GET, OPTIONS` | +| `Access-Control-Allow-Origin` | `https://your-teamcenter.example.com` | + +{{% alert color="info" %}} +Both the Mendix runtime and the Active Workspace server must be served over HTTPS. When `SameSiteCookies` is set to `None`, the `Secure` attribute is automatically added to cookies, which requires HTTPS on both origins. +{{% /alert %}} + +Restart the Mendix app after changing these settings. For background on how CORS works in the Mendix runtime, see [Configuring CORS](/refguide/configure-cors/). + +## Installing the Mendix Component in Active Workspace + +The Mendix-inside-Teamcenter AWC component (`MendixEmbedded`) is a custom Active Workspace web component that loads the Mendix embedded client bundle and mounts the Mendix app inside the AWC page. + +### Adding the Component to Active Workspace + +1. Obtain the `MendixEmbedded` component from [GitHub](TBD). +2. Install the component into your Active Workspace stage repository under `src/repo`. +3. Configure the component with the URL of your Mendix runtime. +4. Optionally, set up context passing. For more information, see [Passing Context from Teamcenter](#passing-context). +5. Rebuild Active Workspace. + +To verify the component was picked up correctly, check that its view model entry exists in the `pathMap.json` registry file in the build output. + +### Registering the Component on a Page + +To display the Mendix app on an Active Workspace page, add a card definition for it to the relevant `layoutsViewModel.json` file in your AWC stage repository. Set `declarativeKeyContext` to the URL of your Mendix runtime: + +```json +"Mendix": { + "title": "Mendix", + "view": "MendixEmbedded", + "anchor": "", + "props": { + "subPanelContext": { + "declarativeKeyContext": "https://your-mendix-runtime.example.com" + } + } +} +``` + +Add `"Mendix"` to the relevant layout handler grid and rebuild Active Workspace. If the Mendix card does not appear after rebuilding, clear the browser cache to ensure the new chunk is loaded. + +Detailed AWC customization and build steps are outside the scope of this documentation. Refer to the Siemens Active Workspace documentation for instructions. + +## Configuring the Content Security Policy in Teamcenter + +Active Workspace enforces a Content Security Policy that must be updated to allow Mendix content to load. + +In your Teamcenter gateway configuration (`gateway/config.json`), add the Mendix runtime URL to the following directives: + +* `script-src` +* `script-src-elem` +* `font-src` +* `connect-src` +* `img-src` +* `style-src` + +Use the browser console CSP errors to identify any additional directives that still need the Mendix origin for your specific setup. + +After updating the CSP, restart the Teamcenter Process Manager for the changes to take effect. + +{{% alert color="warning" %}} +If Teamcenter returns `HTTP 401 Unauthorized` with a JWT signature error after restarting the Process Manager, restart the entire Teamcenter server. +{{% /alert %}} + +## Configuring Authentication {#authentication} + +During Beta, authentication uses the Teamcenter Connector's Teamcenter SSO flow. The Mendix app login page shows an SSO button. When a user clicks it, they are redirected to Teamcenter Security Services (TcSS) for authentication. After a successful login, TcSS redirects back to the Mendix app, where the user is provisioned or matched to an existing Mendix account and a Teamcenter Connector session is established. + +{{% alert color="info" %}} +Because the Mendix app runs inside Active Workspace, the SSO redirect opens in a popup window. The popup can be automated to require zero additional clicks after the user is already signed in to TcSS. The planned GA release targets a fully invisible authentication flow with no popup. +{{% /alert %}} + +Follow these steps to configure authentication. Steps 1–3 require Teamcenter administrator access. + +1. **Register the Mendix App with Teamcenter Security Services**: + + Register the Mendix app in the Teamcenter Deployment Center so TcSS can authenticate it. For instructions, see [Registering Your App for Teamcenter SSO](/appstore/modules/siemens-plm/configuring-connection-2512/#register-your-app-for-teamcenter-sso). + +1. **Configure the Teamcenter Connector Connection**: + + In your Mendix app, configure a Teamcenter Connector connection using **Teamcenter SSO** as the authentication method. For instructions, see [Configuring the Connection to Teamcenter](/appstore/modules/siemens-plm/configuring-connection-2512/). + +1. **Configure User Provisioning**: + + Set up user provisioning so that Mendix accounts are matched to Teamcenter users on login. For instructions, see [User Provisioning for SSO](/appstore/modules/siemens-plm/configuring-connection-2512/#user-provisioning-for-sso). + +1. **Add an SSO Login Button to the Login Page**: + + Add a Teamcenter SSO login button to the Mendix app's `login.html` so users can initiate the TcSS authentication flow. For instructions, see [Adding an SSO Login Button to Your Login Page](/appstore/modules/siemens-plm/configuring-connection-2512/#add-sso-login-button). Optionally, use JavaScript to trigger the authentication automatically. Note that browsers may block the popup unless it is triggered directly by a user action. + +## Passing Context from Teamcenter {#passing-context} + +The `MendixEmbedded` AWC component passes Teamcenter object context to the Mendix app as startup parameters. These are configured in the AWC component and forwarded to the Mendix `render()` call as the `parameters` object. + +The following example shows how the AWC component passes a selected Teamcenter item UID to the Mendix app: + +```js +const MENDIX_URL = "https://your-mendix-runtime.example.com/"; + +export async function mountMendixInTeamcenter(container, tcContext) { + const embeddedModule = await import(`${MENDIX_URL}dist/embedded-index.js`); + return embeddedModule.render(container, { + remoteUrl: MENDIX_URL, + minHeight: "620px", + parameters: { + itemUID: tcContext.selected.uid + } + }); +} +``` + +The `parameters` object is available to the Mendix app at startup. Use a JavaScript action on the home page to read parameters and pass them to your application logic. + +For the full `render()` API, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/). + +### Best Practices for Context Parameters + +* **Use persistable object IDs only.** Pass Item UIDs or ItemRevision UIDs. These are stable and unique across sessions. +* **Avoid non-persistable IDs.** BOM line IDs are runtime calculation results that lose synchronization when Teamcenter configuration rules change. Do not use them as parameters. +* **Prefer Item IDs over ItemRevision IDs** where possible. Item IDs are context-independent and do not depend on the revision rule in effect. +* **Discover available parameters** by referring to the Active Workspace documentation for a list of available context parameters. + +## Known Limitations (Beta) + +* **Cross-site cookies:** The browser must allow cross-site cookies for the Mendix domain. This is required because the Mendix app runs on a different origin than Active Workspace. Configure this per-domain via organization policy (for example, Intune). +* **Authentication popup:** During Beta, the Teamcenter Connector SSO flow opens a popup window. This can be automated to require zero additional clicks after the user is already authenticated with TcSS. +* **Optional parameters fallback:** If an optional startup parameter is omitted, the embedded client shows the fallback page rather than using the parameter's default value. This is a known limitation of the embedded client. See [Embedding the Client](/refguide/mendix-client/embedding-the-client/). + +## Read More + +* [Embedding the Client](/refguide/mendix-client/embedding-the-client/) +* [Teamcenter Connector](/appstore/modules/siemens-plm/teamcenter-connector/) +* [Setting Up the Navigation Structure](/refguide/setting-up-the-navigation-structure/) +* [Configure CORS](/refguide/configure-cors/)