Merge pull request mendix#10874 from khode-mx/teamcenter-bom-component

Teamcenter bom component

Author: MarkvanMents

content/en/docs/partners/siemens/teamcenter-bom-component/_index.md

@@ -0,0 +1,38 @@
+---
+title: "Teamcenter BOM Widget"
+url: /partners/siemens/teamcenter-bom-widget/
+weight: 20
+description: "Describes the Teamcenter BOM widget, which enables out-of-the-box visualization of large Bill Of Material (BOM) data sets similar to what is available in Teamcenter's Active Workspace."
+---
+
+## Introduction
+
+The Teamcenter BOM widget brings Teamcenter Bill of Materials (BOM) capabilities into Mendix apps. You can use it to view, edit, configure, and perform property updates on Teamcenter BOM structures directly in Mendix, thus reducing context switches and simplifying product structure tasks.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/bom-widget-studio-pro.png">}}
+
+## Key Capabilities
+
+* Display Teamcenter BOMs – Render complex product structures within Mendix pages.
+* Edit BOM properties – Update BOM line properties from Mendix.
+* Apply a Teamcenter configuration – Use revision rules, effectivities (date/unit), and product variants.
+* Augment with Mendix data – Inject custom client columns alongside Teamcenter properties.
+
+## Prerequisites
+
+* Teamcenter Connector version 2512.0.0 or above. The widget depends on its request handler.
+* Access to a Teamcenter environment in version 2512.0.0 or above with appropriate credentials and permissions. The widget utilizes new APIs introduced in Teamcenter 2512.0.0, hence cannot be used with older versions of Teamcenter.
+* Teamcenter base platform and Structure Management modules installed.
+* Mendix Studio Pro 10.24.12 or above.
+* A Mendix app with the `TcConnector` module added and configured.
+
+## Persistence and Propagation
+
+Edits made through the widget invoke Teamcenter services via `TcConnector`. Changes to BOM line properties are propagated to Teamcenter when the operation is committed and accepted by the server. You must ensure that users have appropriate permissions, and consider requiring explicit save/commit actions through the user interface.
+
+## Best Practices
+
+Mendix recommends applying these best practices to ensure proper performance:
+
+* Keep titles and headers concise and technical. Avoid marketing language in developer documentation.
+* Use unique `WidgetIDs` per page to avoid collisions.

content/en/docs/partners/siemens/teamcenter-bom-component/configuration.md

@@ -0,0 +1,48 @@
+---
+title: "Teamcenter BOM Widget Configuration"
+url: /partners/siemens/bom-widget-configuration/
+weight: 2
+description: "Configuration instructions and explanation for the usage of the Teamcenter BOM widget."
+---
+
+## After Startup
+
+The Teamcenter BOM widget relies on specific connections to and from your Teamcenter instance.     
+To ensure that everything is properly set up, you must add the `Startup` microflow that is provided by the `TcConnector` module to your project's [After startup settings](/refguide/runtime-tab/#after-startup). This microflow registers the required request handlers used by the Teamcenter BOM widget.
+
+## Teamcenter BOM Widget Tabs
+
+The following sections describe the tabs of the Teamcenter BOM widget.
+
+### General Tab
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/bom-widget-configuration-general.png">}}
+
+Configure the following properties on the widget:
+
+* **Widget identifier** – The unique identifier for this instance of the widget. This is useful if your app includes multiple Teamcenter BOM widgets that need to display different data. You can use this ID to differentiate and return the appropriate data.
+* **Product UID** – The Teamcenter UID of the product (item or assembly) whose BOM will be displayed.
+* **Configuration settings** – Comma-separated options to control the loading and the display of the BOM. For details, refer to [Configuration Settings](#config-settings).
+* **Revision rule UID** – The Teamcenter UID of the revision rule to apply when loading the BOM.
+
+#### Configuration Settings {#config-settings}
+
+By default, all configuration options are shown in the configuration header menu: variants, arrangements, partitions, unit effectivity, date effectivity configuration.    
+To hide any option, use the corresponding values as a comma-separated list in **Configuration settings**.     
+These are the supported **Configuration settings** values:
+
+* `HideVariantConfiguration` – Hides variant-based configuration.
+* `HideArrangementConfiguration` – Hides arrangement-based configuration.
+* `HidePartitionConfiguration` – Hides partition-based configuration.
+* `HideUnitEffectivityConfiguration` – Hides unit effectivity configuration.
+* `HideDateEffectivityConfiguration` – Hides date effectivity configuration.
+
+### Selection Tab
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/bom-widget-configuration-selection.png">}}
+
+The widget supports cross-selection to coordinate with other page components. The cross-selection is one-way, and selecting a BOM line in the BOM populates its properties on a configured entity. 
+
+* **Selected UID** – The UID of the `ItemRevision` that was last selected in the BOM.
+* **Selected Item ID** – The ID of the `ItemRevision` that was last selected in the BOM.
+* **Selected Item Revision ID** – The revision ID of the `ItemRevision` that was last selected in the BOM.

content/en/docs/partners/siemens/teamcenter-bom-component/customization.md

@@ -0,0 +1,83 @@
+---
+title: "Advanced Customization Options"
+url: /partners/siemens/bom-widget-customization/
+weight: 3
+description: "Describes the customization capabilities that allow developers to add data from external systems, and how these can be combined into the Teamcenter BOM widget."
+---
+
+## Augmenting with Mendix Data
+
+Client columns allow you to display custom data next to Teamcenter properties in the BOM view. The widget calls the following two microflows:
+
+* `CUSTOM_RetrieveClientColumnDefinitions` – Microflow to retrieve the client column definitions: client column name, width, and column order.
+* `CUSTOM_RetrieveClientColumnData` – Microflow to retrieve the additional cell data to display for the BOM lines and client columns. 
+
+As a developer, you are free to implement this according to your own needs. Additional data includes calculated values, third-party data, or data from the database.
+
+### CUSTOM_RetrieveClientColumnDefinitions
+
+This microflow is invoked by the Teamcenter BOM widget to retrieve the definitions of the client columns to display in the widget.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/custom-retrieveclientcolumndefinitions.png">}}
+
+#### Input Parameter
+
+* **Object**: `MendixColumnRoot`
+* **Attribute**:
+  
+    * `WidgetId` is a unique identifier for the specific Teamcenter BOM widget instance that is making the request. This is useful if your app includes multiple Teamcenter BOM widgets that need to display different columns. You can use this ID to differentiate and return the appropriate data.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/domain-model-mendixcolumnroot.png">}}
+
+#### Return Value
+
+* **Object**: `List of ClientColumn`
+* **Attributes**:
+
+    * `Name` – The name of the client column. This name is used in the UI of the Teamcenter BOM widget as the column title.
+    * `ColumnOrder` – The order of the column within the widget, respectively. Teamcenter columns also have their own order, so this needs to be filled in conjunction. If the order is identical, Teamcenter columns take priority.    
+    The first column should be object_string, which is already defined.    
+    All Mendix client columns must start with `columnOrder 2` and will be displayed before the Teamcenter columns.    
+    Mendix columns are sorted based on their `columnOrder` parameter.    
+    Teamcenter columns are displayed after the client columns.     
+    The `columnOrder` for Teamcenter columns is defined by the Teamcenter administrator using the column configuration utilities in the Teamcenter Admin Console.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/domain-model-clientcolumn.png">}}
+
+### CUSTOM_RetrieveClientColumnData
+
+This microflow is invoked by the Teamcenter BOM widget to retrieve the data to be rendered in the BOM tree. It gathers cell data for specific BOM lines and any client columns.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/custom-retrieveclientcolumndata.png">}}
+
+#### Input Parameter
+
+* **Object**: `MendixDataRoot`
+* **Attributes and associations**:
+
+    * `WidgetId` – A unique identifier for the specific Teamcenter BOM widget instance that is making the request. This is useful if your app includes multiple Teamcenter BOM widgets that need to display different data. You can use this ID to differentiate and return the appropriate data.
+    * Associated `MendixDataColumnName` objects – This list specifies which custom columns the widget is configured to display. Each object has a `Name` attribute, representing the identifier of a custom column.
+    * Associated `MendixDataBOMLine` objects – This list contains the specific BOM lines for which the widget requires data. Each object includes attributes such as `ItemId`, `RevisionId`, `RevisionUId`, and `BOMlineUid` to identify the BOM line and its `ItemRevision`.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/domain-model-mendixdataroot-with-associations.png">}}
+
+#### Return Value
+
+* **Object**: `List of ClientDataResponse`
+* **Attributes**:
+
+    * `Value` – The value to display in a targeted cell in the BOM.
+    * `ClientColumnName` – The name of the column of the targeted cell.
+    * `ItemRevisionUID` – The item revision UID of the corresponding BOM line of the targeted cell.
+
+{{< figure src="/attachments/partners/siemens/teamcenter-bom-component/domain-model-clientdataresponse.png">}}
+
+### ClientColumn Overview Page
+
+For convenience, the `TcBOMModule` includes overview and edit pages to define and manage `ClientColumns`.
+
+## Upgrade Note
+
+Please be aware that any direct modifications made to this specific microflow within the `TcBOMModule` will be overwritten and lost during future upgrades of the `TcBOMModule`.
+
+To ensure your custom data retrieval logic is preserved across upgrades, Mendix highly recommends that you to create two new microflows in your own module to fetch the column definition and cell-data, and to return a list of `ClientColumn` objects and `ClientDataResponse` objects, respectively. These microflows can then be called in `CUSTOM_RetrieveClientColumnDefinitions` and `CUSTOM_RetrieveClientColumnData`.