Document Mendix inside Teamcenter (public Beta, 11.12)

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/). This requires you to be using Mendix version 11.12.0 or above.
+
 ## Description {#description}
 
 The Mendix Client is a part of every application built with Mendix: both web and mobile.

content/en/docs/refguide/runtime/mendix-client/mendix-inside-teamcenter.md

@@ -0,0 +1,284 @@
+---
+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
+
+{{% alert color="info" %}}
+Mendix inside Teamcenter is available in Mendix version 11.12.0 and above and is currently in public Beta. See the [prerequisites](#prerequisites) for more version requirements.
+{{% /alert %}}
+
+Mendix inside Teamcenter lets you embed a Mendix web app as a native component inside Siemens Teamcenter Active Workspace. The Mendix app runs directly in the Active Workspace 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.
+
+## Prerequisites {#prerequisites}
+
+The following versions are required:
+
+| | Mendix | Teamcenter | Teamcenter Connector |
+| --- | --- | --- | --- |
+| **Beta** | 11.12 | 2512 | 2606.0.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 Navigation](/refguide/setting-up-the-navigation-structure/).
+
+### Configuring Cross-Origin Resource Sharing (CORS)
+
+The Mendix app must allow cross-origin resource sharing (CORS) from Active Workspace. This allows the browser to load the Mendix client bundle from the Mendix runtime origin from a page that is served from the Teamcenter origin. You will need to set up the following:
+
+#### Runtime Settings
+
+Configure the following [custom runtime setting](/refguide/custom-settings/). 
+
+| Name | Value |
+| --- | --- |
+| `com.mendix.core.SameSiteCookies` | `None` |
+
+#### Custom HTTP Response Headers
+
+Configure the following HTTP Response Headers in your [local runtime configuration](/refguide/configurations-tab/#headers) or your cloud environment. Replace `https://your-teamcenter.example.com` with the actual origin of your Active Workspace deployment, including scheme and port if applicable.
+
+| 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" %}}
+For the Mendix public cloud do not use the HTTP Header configuration in the cloud portal. Instead set the custom runtime configuration setting `Headers` to the following:
+```json
+{
+  "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"
+}
+```
+See [custom settings](https://docs.mendix.com/refguide/custom-settings/#Headers) for details.
+{{% /alert %}}
+
+{{% 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 %}}
+
+#### CORS for TcSSO Published REST Service
+
+Configure the [CORS settings](/refguide/cors-settings/) for the TcSSO Published REST Service that is included in the Teamcenter Connector and add your teamcenter host `https://your-teamcenter.example.com` to the Allowed Origins.
+
+Restart the Mendix app after changing these settings. For background on how CORS works in the Mendix runtime, see [Configuring CORS in the Mendix Runtime](https://docs.mendix.com/refguide/configure-cors/).
+
+## Installing the Mendix Component in Active Workspace
+
+The Mendix-inside-Teamcenter Active Workspace component (`MendixEmbedded`) is a custom Active Workspace web component that loads the Mendix embedded client bundle and mounts the Mendix app inside the Active Workspace 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 using `awbuild.cmd`.
+
+To verify the component was picked up correctly, check that its view model entry exists in the `src/repo/out/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 Active Workspace 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 Active Workspace 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. Upon accessing the Mendix application, a popup is opened automatically for authentication. After successful login (which in most cases will happen automatically), the popup is closed and the Mendix application and Teamcenter Connector are authenticated.
+
+{{% alert color="info" %}}
+For the GA release we plan to offer an alternative authentication flow that is fully invisible and does not require a 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).
+
+    This step requires administrator access to Teamcenter.
+
+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/).
+
+    This step requires administrator access to your Mendix application.
+
+1. **Configure User Provisioning**:
+
+    Set up user provisioning by example of the `EXAMPLE_UserProvisioningAnonymous` Microflow so that Mendix accounts are matched to Teamcenter users on login. Anonymous users should be disabled in the Mendix application. For instructions, see [User Provisioning for SSO](/appstore/modules/siemens-plm/configuring-connection-2512/#user-provisioning-for-sso).
+
+1. **Add the following required customizationss**:
+
+    - Create a JavaScript action called JS_CloseWindow with the following:
+        ```
+        export async function JS_CloseWindow() {  
+            // BEGIN USER CODE  
+            window.close();  
+            // END USER CODE  
+        }
+        ```
+    - Add a Nanoflow that calls this JavaScript action
+    - Add an empty page called `AuthSuccess` to the application which contains an `Component load` event that calls this Nanoflow
+    - Change the `DL_HandleSSOLoginMicroflow` to show `AuthSuccess` instead of the home page as the last action in the Microflow.
+    - 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` Active Workspace component passes Teamcenter object context to the Mendix app as startup parameters. These are configured in the Active Workspace component and forwarded to the Mendix `render()` call as the `parameters` object.
+
+The following example shows how to change the Active Workspace component to pass the selected Teamcenter item UID to the Mendix app (the required changes are prefixed with `>>`):
+
+```js
+export const mendixRenderFunction = (props) => {
+    const [error, setError] = useState(null);
+    >> const selectedItem = props.ctx?.selected?.uid ?? '';
+
+    const mendixUrl = getMendixUrl(props);
+    if (mendixUrl === undefined) {
+        setError('There is no Mendix URL configured. Contact support to resolve this issue.');
+    }
+
+    const retryError = () => {
+        setError(null);
+    };
+
+
+    const load = useCallback(async (container) => {
+        mendixCleanupFunction();
+
+        if (!container) {
+            return;
+        }
+
+        try {
+            if (REQUIRE_SESSION) {
+                await ensureHasValidSession(mendixUrl);
+            }
+
+            const app = await import(/* webpackIgnore: true */ `${mendixUrl}dist/embedded-index.js`);
+            const cleanup = await app.render(container, { remoteUrl: mendixUrl, minHeight: '100vh',
+            >> parameters: { SelectedItem: selectedItem }
+            });
+
+            const onReload = () => load(container);
+            container.addEventListener(RELOAD_EVENT, onReload, { once: true });
+
+            currentMendixCleanup = () => {
+                container.removeEventListener(RELOAD_EVENT, onReload);
+                cleanup?.();
+            };
+        } catch (error) {
+            setError(error);
+        }
+    }, [mendixUrl, 
+        >> selectedItem
+    ]);
+
+    if (error) {
+        if (error.code === 'POPUP_BLOCKED') {
+            return <PopupBlockedView subPanelContext={{ retry: retryError }} />;
+        }
+
+        return <GeneralErrorViewModel subPanelContext={{ errorMessage: error.message ?? 'An unexpected error occurred.', retry: retryError }} />;
+    }
+
+
+    return <div ref={load} style={{ width: '100%', height: '100vh' }} />;
+};
+```
+
+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/)