diff --git a/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/_index.md b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/_index.md new file mode 100644 index 00000000000..3c937c00ab8 --- /dev/null +++ b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/_index.md @@ -0,0 +1,71 @@ +--- +title: "Designcenter X Cloud Services Connector" +url: /appstore/industry/siemens/designcenter/ +weight: 40 +description: "Describes how to install and configure the Designcenter X Cloud Services Connector in a Mendix app." +--- +## Introduction + +Designcenter X Cloud Services are scalable, cloud-hosted services that expose Siemens Designcenter's design intelligence and high-compute analysis capabilities on demand. Enterprise apps, dashboards, and automated workflows can all consume these capabilities. + +## Key Capabilities + +The connector focuses on two high-value capabilities: + +1. Visual reporting data – generated from Designcenter part files in Teamcenter and available through APIs to build rich, design-aware experiences for customers. +2. High-compute design analysis – runs assembly clearance (clash) detection in the cloud so that users can offload large assembly analysis to the cloud. + +The [Designcenter X Cloud Services connector](placeholder) on Mendix Marketplace makes these services available in any Mendix app through ready-to-use microflows. The connector handles authentication, session management, and data exchange so developers can focus on delivering business value rather than managing infrastructure. + +## Typical Use Cases + +The connector supports scenarios such as: + +* Enterprise dashboards that correlate design data (parts, assemblies, BOM structure) with enterprise data such as cost, supplier, quality, or program status. +* Historical clash result management – store, search, and trend clearance analysis results over time across releases, programs, or product lines. +* Design analytics – run analytics over visual report data and clash history to show design quality KPIs, regression detection, and rework hotspots. +* Engineering automation – trigger high-compute analyses, such as clash detection, on entire assemblies directly from Mendix workflows, with execution governed by business rules. +* Cross-discipline collaboration – make Designcenter intelligence accessible to non-CAD users, such as program managers, quality, and manufacturing teams, within the apps they already use. + +{{% alert color="info" %}} +The connector is licensed under the Apache 2.0 License. +{{% /alert %}} + +## Prerequisites + +* Studio Pro 10.24 and above +* A valid Siemens Enterprise Cloud Account (ECA) with an entitlement to a Designcenter X product tier and value-based licensing tokens +* Access to the [Siemens Admin Console](https://cloud.sws.siemens.com/admin/) to provision server users and credentials +* Built-in Data Management (Teamcenter X Essentials) or a higher Teamcenter X tier (Standard, Advanced, or Premium) + +## Dependencies {#dependencies} + +You must have the following Marketplace modules installed: + +* [Community Commons](https://marketplace.mendix.com/link/component/170) +* [Mx Model Reflection](https://marketplace.mendix.com/link/component/69) +* [Events (widget)](https://marketplace.mendix.com/link/component/224259) +* [User Commons V2.3.0 or above](https://marketplace.mendix.com/link/component/223053) +* [OIDC SSO V4.5.0 or above](https://marketplace.mendix.com/link/component/120371) + +## Installing the Connector + +To install the Designcenter X Cloud Services Connector in your Mendix app, follow these steps: + +1. Install the modules listed in the [Dependencies](#dependencies) section. +2. Follow the instructions in [Using Marketplace Content](/appstore/use-content/) to import the [Designcenter X Cloud Services Connector](placeholder) into your app. +3. Configure the connector as described in the [Configuring the Connector](#configuration) section. + +## Configuring the Connector {#configuration} + +To configure the Designcenter X Cloud Services Connector in your app, follow these steps: + +1. Create a server user in the Siemens Admin Console and obtain client credentials. +2. Configure your Mendix app (modules, security, navigation, and constants). +3. Configure OIDC SSO in your Mendix app. + +For more information, see [Configuring the Connector for Single Sign-On](/appstore/industry/siemens/designcenter/sso/). + +## Read More + +* [Using Designcenter X Cloud Services Connector](/appstore/industry/siemens/designcenter/using-designcenter/) diff --git a/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/designcenter-sso.md b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/designcenter-sso.md new file mode 100644 index 00000000000..d4f8f9584da --- /dev/null +++ b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/designcenter-sso.md @@ -0,0 +1,118 @@ +--- +title: "Configuring the Connector for Single Sign-On" +url: /appstore/industry/siemens/designcenter/sso/ +weight: 50 +description: "How to configure OAuth single sign-on (SSO) for the Designcenter X Cloud Services Connector in a Mendix app." +--- + +## Introduction + +This page explains how to configure OAuth single sign-on (SSO) so your Mendix app can access Designcenter X Cloud Services without requiring users to sign in separately. After importing the Designcenter X Cloud Services Connector into your app, follow the steps in this document to complete the SSO configuration. + +## Creating a Server User + +To create a server user and obtain client credentials, follow these steps: + +1. Sign in to the [Siemens Admin Console](https://cloud.sws.siemens.com/admin/) and navigate to **Designcenter X** under **Products**. +2. Open **Server Users** and click **Create server user**. +3. Fill in the **Name**, **Tier**, and **Role** fields. Enter *Application Owner* as the **Role** and click **Create**. +4. Click **Download Credentials** and save the file securely. The file contains the **Client ID** and **Client Secret**. + +## Configuring the Mendix Application + +### Configuring Security + +1. Open **Security** from the **App Explorer**. +2. Set the **Security level** to **Production**. +3. In the **User roles** tab, edit the **Administrator** role and assign the OIDC, UserCommons, and Designcenter X Cloud Services Connector **Administrator** module roles. +4. Edit the **User** role and assign the OIDC and Designcenter X Cloud Services Connector **User** module roles. + +{{< figure src="/attachments/partners/siemens/designcenter/app-security-roles.png" alt="app security configuration" >}} + +### Configuring Navigation + +1. In **Navigation**, add a **New Menu Item** named *Designcenter Admin* and set the **On-click** action to **Show a page**. +2. Search for and select the `ServerUserConfiguration` page under **Designcenter_Connector** > **USE_ME** > **OIDC**. +3. Set the **Atlas ‘cog’** icon for the menu item. +4. Add a **Sign out** menu item for the sign-out action, set the **Atlas ‘logout’** icon, and click **OK**. + +### Configuring Constants + +1. Open **Settings** from the **App Explorer** and click **Edit** on the default configuration. +2. Go to the **Constants** tab and set the `OIDC.EncryptionKey` constant to a 32-character encryption key. For more information, see [Setting the Encryption Key](/appstore/modules/oidc/#setting-encryption-key). + +{{% alert color="info" %}} +Keep the encryption key private and store it securely in your environment settings. +{{% /alert %}} + +## Configuring OIDC SSO + +1. Run the app locally and sign in as an administrator. For more information, see [Administrator](/refguide/administrator/). +2. Navigate to the **Designcenter Admin** page and create a new server configuration using the following values: + + * Client ID – the application identifier downloaded from the Siemens Admin Console. + * Client Secret – the authentication key generated from the Siemens Admin Console. For more information, see the [Creating a Server User](#creating-a-server-user) section above. + * ECA ID – your Enterprise Cloud Account identifier. + * Region – the region where your Designcenter X product was provisioned in the Siemens Admin Console. + + {{< figure src="/attachments/partners/siemens/designcenter/configure-sso.png" alt="SSO configuration" >}} + +3. Save the configuration. The primary and secondary fields are now populated. Sign out of the app. + +## Validating the Configuration + +1. Run the app locally or open `http://localhost:8080/oauth/v2/login` in a browser. The sign-in page appears. +2. Sign in via SSO to verify that the app loads successfully and connector operations can establish a Teamcenter session. + +## Rotating the Credentials + +Rotate credentials every six months for better security. During initial setup, the server user is provisioned with two client credentials: Primary and Secondary. By default, the Primary credential is active. To rotate credentials, follow these steps: + +1. Sign in as the Mendix administrator. +2. Navigate to the **Designcenter Admin** page. The page displays the Primary and Secondary client credentials. +3. Click **Rotate Credentials** and enter the server user details from the Siemens Admin Console. +4. Click **Rotate**. The Secondary credential becomes active and a new Primary credential is generated. +5. To rotate the Secondary credential, repeat the same steps. + +## Troubleshooting + +If you encounter issues with the Designcenter X Cloud Services Connector, the following sections describe common errors and how to resolve them. + +### Application Runtime Errors + +#### Widgets or Grid Errors + +If Studio Pro reports widget or grid errors after importing the connector, do the following: + +1. Right-click the error and update all widgets. +2. Convert the grid to Data Grid 2 to eliminate grid errors. + +#### Invalid Client Error During SSO + +If you receive an "Invalid client" error during SSO, the cause is one of the following: + +* The client ID and secret pair is invalid. +* The server user has been deleted in the Admin Console. + +To resolve this, recreate the server user and update the server configuration in your Mendix app. + +#### No Roles from Token + +The browser may be caching a session from another Enterprise Cloud Application (ECA). To resolve this, sign in using incognito mode or clear your browser cache and try again. + +#### Authentication Failed + +If you see "Authentication failed! Please check with your System Administrator," the authentication credentials are not properly configured. + +To resolve this, go to the **Designcenter Admin** page, click **Delete Client Credentials** to remove the existing credentials, then reconfigure the server user to generate new credentials. + +### Mendix Studio Console Errors + +#### Server User Is Already Configured + +This error occurs when the same server user is already configured by another user in the same app. To resolve this, go to the **Designcenter Admin** page, click **Delete Client Credentials** to remove the existing credentials, then reconfigure the server user. + +## Read More + +* [Designcenter X Cloud Services Connector](/appstore/industry/siemens/designcenter/) +* [Using Designcenter X Cloud Services Connector](/appstore/industry/siemens/designcenter/using-designcenter/) \ No newline at end of file diff --git a/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/using-designcenter.md b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/using-designcenter.md new file mode 100644 index 00000000000..15e0ca788ef --- /dev/null +++ b/content/en/docs/marketplace/industry/xcelerator/siemens-supported/designcenter/using-designcenter.md @@ -0,0 +1,191 @@ +--- +title: "Using Designcenter X Cloud Services Connector" +url: /appstore/industry/siemens/designcenter/using-designcenter/ +weight: 60 +description: "How to build Mendix apps using the Designcenter X Cloud Services Connector, including available microflows, inputs and outputs, and best practices." +--- + +## Introduction + +This page guides you through building Mendix apps on top of the [Designcenter X Cloud Services Connector](placeholder). It covers the available microflows, their inputs and outputs, a worked end-to-end example, and best practices for production use. + +## Prerequisites + +Configure the OIDC SSO and required constants in your app. For more information, see [Configuring the Connector for Single Sign-On](/appstore/industry/siemens/designcenter/sso/). + +To help you develop your app, familiarize yourself with the [Mendix Studio Pro Guide](/refguide/), especially the following topics: + +* [Studio Pro Overview](/refguide/studio-pro-overview/) +* [Data in the Domain Model](/refguide/domain-model/) +* [Pages](/refguide/pages/) +* [Microflows and Nanoflows](/refguide/microflows-and-nanoflows/) +* [Development Best Practices](/refguide/dev-best-practices/) + +## Concepts + +* Session – a handle that ensures the same Teamcenter server is used across service calls. The `EstablishSession` microflow either creates a new session or returns an existing one, so the same handle can be reused safely across operations. +* Environment (Tenant) – the Teamcenter X environment that the session targets. A single user or ECA may have access to multiple environments. +* Job – an asynchronous unit of work (for example, a visual report run or a clearance analysis). A job returns a Job ID immediately and completes in the background. +* Domain mapping – job results are returned as JSON. The connector ships helpers that convert these JSON payloads into Mendix domain objects (`VisualReportData`) for easy querying and persistence. + +## Using Microflows + +The following sections provide more information about using all operations available in the microflow toolbox and under the **USE_ME** folder of the connector module. + +### Session Lifecycle + +#### `POST_EstablishSession` + +Call `POST_EstablishSession` to create a new session or return an existing one, ensuring the same Teamcenter server is used across service calls. + +* **Input**: Session name (string) +* **Output**: Session object + +#### `GET_TenantEnvironments` + +Call `GET_TenantEnvironments` to list environments the session can target. + +* **Input**: Session +* **Output**: List of Environment + +#### `POST_InitializeTeamcenterSession` + +Call `POST_InitializeTeamcenterSession` to bind the session to a specific Teamcenter X environment. + +* **Input**: Session, Environment +* **Output**: Initialized Session + +{{% alert color="info" %}} +A session must be initialized against an environment before any data or analysis operation can be +called. +{{% /alert %}} + +### Query Operations + +#### `GET_QueryPartIdFromName` + +Call `GET_QueryPartIdFromName` to find part documents by name (supports wildcards, for example, Bracket_*). + +* **Input**: Session, PartName (string) +* **Output**: List of PartDocument + +### Analysis Operations (asynchronous) + +#### `GET_VisualReportNames_Request` + +Call `GET_VisualReportNames_Request` to list available visual report definitions for the tenant. + +* **Input**: Session +* **Output**: List of report IDs and display names + +#### `POST_GenerateVisualReport_Request` + +Call `POST_GenerateVisualReport_Request` to run one or more visual reports against a part or assembly. + +* **Input**: Session, PartID, ReportIDs, ProcessingType +* **Output**: JobID + +#### `POST_ClearanceAnalysisRequest` + +Call `POST_ClearanceAnalysisRequest` to run clearance (clash) analysis. + +* **Input**: Session, PartID, ProcessingType +* **Output**: JobID + +{{% alert color="info" %}} +Analysis operations are asynchronous. They return a Job ID immediately; the actual computation runs +in the cloud. +{{% /alert %}} + +### Job Retrieval + +#### `GET_JobsByTypes` + +Call `GET_JobsByTypes` to list jobs the current user can see, filtered by type. + +* **Input**: Session, Type (visualreports or clearance) +* **Output**: List of JobID + +#### `GET_DataForJobId` + +Call `GET_DataForJobId` to fetch the raw result payload for a job. + +* **Input**: Session, JobID +* **Output**: JSON string + +#### `GET_VisualReportDataListFromJobId` + +Call `GET_VisualReportDataListFromJobId` to convert a visual report job's payload into domain objects. + +* **Input**: Session, JobID +* **Output**: List of VisualReportData + +## Connector Integration Workflow + +The diagram below shows the sequence of interactions between the Mendix app, the connector, Teamcenter, and Designcenter X Cloud Services. + +{{< figure src="/attachments/partners/siemens/designcenter/workflow.png" alt="connector workflow" >}} + +### Polling vs. User-Driven Retrieval + +The connector does not push notifications when a job finishes. You have two options: + +* User-driven – show the user a **Refresh results** button that re-runs `GET_JobsByTypes` and `GET_VisualReportDataListFromJobId`. This is simple and adequate for most analytical workflows. + +* Scheduled poll – use a scheduled event microflow to poll outstanding job IDs (stored in your domain) every N seconds or minutes, fetch results, and update status. This approach works best for fire-and-forget workflows where the result feeds another process. + +## Working with Job Results + +`GET_DataForJobId` returns raw JSON, which is useful when you want to store the full payload (for example, for audit) or post-process it yourself. + +For visual reports, prefer `GET_VisualReportDataListFromJobId`. It maps the payload onto the `VisualReportData` domain entity that ships with the connector. Typical attributes include: + +* Part identifier and revision +* Report definition reference +* Aggregated metrics (counts, totals, classification) +* Component-level rows for assembly runs + +{{% alert color="info" %}} +Persist `VisualReportData` into your own domain entities if you intend to run analytics across many runs. The Connector's domain is best used as a landing zone, not the long-term system of record. +{{% /alert %}} + +## Troubleshooting + +This section describes the most common failure modes and their solutions. + +### Session Expired + +If any operation fails after `POST_InitializeTeamcenterSession`, the session may have expired. Call `POST_EstablishSession` again and retry the failed call. + +### Environment Not Authorized + +If `POST_InitializeTeamcenterSession` fails with an authorization error, have the user select a different environment and verify the Enterprise Cloud Account (ECA) entitlement in the Siemens Admin Console. + +### Invalid Part ID + +If `POST_GenerateVisualReport_Request` or `POST_ClearanceAnalysisRequest` fails due to an invalid part ID, validate the part ID against the result of `GET_QueryPartIdFromName` before submitting the request. + +### Job Not Found or Not Ready + +If `GET_DataForJobId` or `GET_VisualReportDataListFromJobId` returns a job-not-found error, the job may still be running. Treat the response as in-progress, wait, and retry. + +### Authentication Error + +If any operation returns an authentication error, confirm that the `OIDC.EncryptionKey` constant and connector constants are correctly set, and verify that the server user is still active in the Siemens Admin Console. + +A small reusable sub-microflow that centralizes "re-establish session and retry once" pays for itself quickly. + +## Best Practices + +* Always pass `ProcessingType` explicitly. For assemblies, use `ProcessComponentsInAssembly` in most cases. + +* Cache report definitions: `GET_VisualReportNames_Request` results change infrequently. Cache them for the duration of the user's app session to avoid unnecessary calls. + +* Page large result sets: Visual reports on large assemblies can return thousands of rows. Page or stream results into your domain model rather than loading the full list into memory at once. + +* Isolate connector calls in a service layer: Wrap each connector microflow in a thin custom microflow (for example, `SUB_RunVisualReport`) so that future connector upgrades only affect one layer of your app. + +## Read More + +* [Designcenter X Cloud Services Connector](/appstore/industry/siemens/designcenter/) +* [Configuring the Connector for Single Sign-On](/appstore/industry/siemens/designcenter/sso/) diff --git a/static/attachments/partners/siemens/designcenter/app-security-roles.png b/static/attachments/partners/siemens/designcenter/app-security-roles.png new file mode 100644 index 00000000000..4b9ed779e92 Binary files /dev/null and b/static/attachments/partners/siemens/designcenter/app-security-roles.png differ diff --git a/static/attachments/partners/siemens/designcenter/configure-sso.png b/static/attachments/partners/siemens/designcenter/configure-sso.png new file mode 100644 index 00000000000..d2943db7047 Binary files /dev/null and b/static/attachments/partners/siemens/designcenter/configure-sso.png differ diff --git a/static/attachments/partners/siemens/designcenter/workflow.png b/static/attachments/partners/siemens/designcenter/workflow.png new file mode 100644 index 00000000000..c860c0d5274 Binary files /dev/null and b/static/attachments/partners/siemens/designcenter/workflow.png differ