Designcenter X Cloud Services Connector

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/)

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/)

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/)