Skip to content

Commit 798a07a

Browse files
wanchoorohanwanchoorohan
authored
Add migration guide for Teamcenter Connector 2606
Added a comprehensive migration guide for upgrading to Teamcenter Connector 2606, including pre-migration checklist, step-by-step process, breaking changes, and deprecated microflows and Java actions.
1 parent d537068 commit 798a07a

1 file changed

Lines changed: 147 additions & 0 deletions

File tree

  • content/en/docs/marketplace/industry/xcelerator/platform-supported/teamcenter-connector/Unified Teamcenter Connector 2606

‎content/en/docs/marketplace/industry/xcelerator/platform-supported/teamcenter-connector/Unified Teamcenter Connector 2606/3-migrate-to-2606.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
2+
## Migrating to 2606
3+
4+
### Migrating from Teamcenter Connector 2512 and Extension v4.x
5+
6+
In version 2606 of the Teamcenter Connector contains both the TcConnector module and the extension, meaning that from this version onwards the Teamcenter Extension doesn't need to be downloaded seperately. If you have an existing app using Teamcenter Connector 2512 and Extension v4.x, you can migrate to version 2606. While this migration involves some breaking changes, the benefits—unified module, modern Extension framework, improved security, and better error handling—make it worthwhile.
7+
8+
**Before you start: Pre-migration checklist**
9+
10+
⚠️ **Follow these steps carefully to avoid issues:**
11+
12+
1. **Upgrade to Mendix 11.12.1 or higher first** — Version 2606 requires Mendix 11.12.1+. If you're on Mendix 10, you must upgrade Studio Pro before importing the new connector. Mendix 10 cannot run 2606.
13+
14+
2. **Have only one developer perform the migration** — If multiple developers migrate simultaneously, you'll end up with duplicate generated artifacts. Coordinate with your team and designate one person to handle the migration, then have others pull the updated code from version control.
15+
16+
3. **Migrate from 2512** - If the project still contains an older version of the Teamcenter Connector (2506 or older) first follow the steps in: https://docs.mendix.com/appstore/modules/siemens-plm/upgrade-teamcenter-connector-2506-to-2512/
17+
18+
4. **Make a backup** — Before starting, either create a full backup of your app or commit all current changes to version control. This gives you a safety net in case you need to roll back.
19+
20+
**Step-by-step migration process**
21+
22+
**Step 1: Prepare your environment**
23+
24+
1. Open your app in Studio Pro 11.12.1 or higher
25+
2. Make sure all changes are committed (if using version control) or backed up
26+
27+
**Step 2: Move the Toolkit contents to the TcConnector module**
28+
29+
3. Remove the old TcConnector module from your project, ignore the errors for now
30+
4. Rename the old TeamcenterToolkit module to TcConnector, then remove the module. By doing this, the old Toolkit references in the project are now pointing to the TcConnector module.
31+
> [!NOTE]
32+
> This step doesn't change the BOMapping, we will fix this in a later step
33+
34+
**Step 3: Import the new connector**
35+
36+
5. Remove the TeamcenterExtension module under add-ons, the old extension is not compatible with the new Teamcenter Connector 2606 module
37+
6. Download the Teamcenter Connector 2606 from the Mendix Marketplace, this now also contains the new version of the extension
38+
> [!NOTE]
39+
> The Teamcenter Extension is not found anymore under Extensions, but it can now be found as a new Service Document, similar as a microflow, it can be found by: Right click > Add other > Teamcenter service__
40+
41+
**Step 4: Resolve breaking changes**
42+
43+
7. Studio Pro will show you errors where your microflows or domain model reference things that have changed. Work through these systematically. The most common issues you'll encounter:
44+
- Errors in microflows that were generated by the Teamcenter Extension can best be re-created by the new version of the extension, see Step 9
45+
- Missing microflows/Java actions can be found in the deprecated table below
46+
- References to `TeamcenterToolkit.*` — Change these to `TcConnector.*` (because Toolkit was merged into TcConnector)
47+
- References to `FileType` — Change these to `NamedReference`
48+
- Microflows that handle the Boolean return value from `Login` — Remove this handling, as `Login` now throws an exception instead
49+
- See the breaking changes reference below
50+
51+
**Step 5: Update security**
52+
53+
8. Click "Update Security" in Studio Pro (open domain model → Update Security), make sure that all atrributes on persistent entities have read-rights
54+
9. Remember: the Administrator role now only has access to Teamcenter Configuration, so assign the User role to module roles that need entity access
55+
56+
**Step 6: Enable React client**
57+
58+
10. Go to Project → Settings → Runtime
59+
11. Make sure "Use React client" is turned on
60+
61+
**Step 7: Create a Teamcenter Service Document**
62+
63+
12. In the module where your Teamcenter integrations live, right-click and select "Add others" → "Teamcenter Service"
64+
13. Give it a name (e.g., "MainIntegrations")
65+
66+
**Step 8: Reconfigure your connection**
67+
68+
14. Open the Teamcenter Service Document and go to the Settings tab
69+
15. Enter your Teamcenter URL and authentication settings
70+
16. Click "Sign In" and login to Teamcenter
71+
72+
**Step 9: Recreate your integrations**
73+
74+
17. Your existing domain model entities and microflows are still in your app—they haven't been deleted. However, you'll want to regenerate them using the new Extension to take advantage of improvements and ensure they're compatible with the new connector
75+
18. In the Service Document, click on '+ Add integration' and start a journey that matches each of your existing integrations
76+
19. Configure it the same way as before (the journey types and options are the same)
77+
20. Click "Generate" to save and generate the integration
78+
21. Replace the old microflows with the new generated microflows
79+
22. You can use the "Duplicate" feature in the History tab to create variations of an integration without reconfiguring from scratch
80+
81+
**Step 10: Test thoroughly**
82+
83+
23. Run each generated microflow against your Teamcenter instance
84+
24. Verify that search, create, update, and retrieval operations work as expected
85+
25. Test error handling by triggering error conditions (e.g., invalid search criteria)
86+
26. If you have automated tests, run them to ensure integration behavior is correct
87+
88+
**Breaking changes reference**
89+
90+
Here's a comprehensive table of breaking changes and what you need to do about each one:
91+
92+
| Area | Change | Action required |
93+
|---|---|---|
94+
| **Teamcenter Toolkit Module** | Module merged into TcConnector; module no longer exists | Update all references from `TeamcenterToolkit.*` to `TcConnector.*` |
95+
| **Entity security** | Create and Delete rights removed from all entities | Remove any UI or microflow logic that relied on client-side Create/Delete; use microflows instead |
96+
| **Input parameter `ConfigName` renamed to `ConfigurationName`** | in generated microflows the input parameter is now called ConfigurationName and is optional | Set the ConfigurationName or leave it empty |
97+
| **Admin role** | Administrator no longer has entity access | Reassign to User role where needed |
98+
| **`FileType` / `File Type`** | Renamed to `NamedReference` / `Named Reference` | Update all references in microflows and mappings |
99+
| **`CreateBOMWindow_Generic`** | Moved to TcConnector; updated to use `CreateOrReconfigureBOMWindows`; pre-configured variants removed | Regenerate BOM microflows via the Extension or update manually to use `TcConnector.CreateBOMWindow_Generic` |
100+
| **`Login` Java action** | No longer returns Boolean; throws exception on failure | Remove Boolean result handling; wrap in error handler |
101+
| **`Logout` Java action** | Now returns Boolean | Update callers if return value was previously ignored |
102+
| **Error messages** | Connector no longer shows in-app messages; throws exceptions instead | Ensure calling microflows have error handlers |
103+
104+
**Deprecated microflows — with replacements**
105+
106+
These microflows still exist in the deprecated folder but can't be used anymore (excluded). Replace them with the recommended alternatives:
107+
108+
| Deprecated | Replacement |
109+
|---|---|
110+
| `AreMultipleTcConfigActive` | No replacement |
111+
| `CloseBOMWindow`| `BOMWindow_Close` |
112+
| `DownloadFile` | `DownloadFile` / `DownloadImage` Java action |
113+
| `ExecuteLogin` | `Login` microflow |
114+
| `ExecuteLogout` | `Logout` microflow |
115+
| `HandleActiveConfigErrors` | No replacement |
116+
| `HandleServiceErrors` | No replacement |
117+
| `RetrieveConfigNameFromSingleActiveConfiguration` | Use `empty` for configurationName parameter in Java actions, Java actions now handles active configuration in the Java code |
118+
| `RetrieveHttpHeaderList` | No replacement |
119+
| `RetrieveTcSessionBasedOnConfigName` | No replacement, TcSession should not be manually consumed; it is automatically handled by the TcConnector module. |
120+
| `RetrieveTeamcenterConifgurationByName` | Use `empty` for configurationName parameter in Java actions, Java actions now handles active configuration in the Java code |
121+
| `RetrieveTeamcenterConifgurationFromTcSession` | No replacement TcSession should not be manually consumed; it is automatically handled by the TcConnector module |
122+
| `ShowPartialErrors` | No replacement |
123+
| `UpdateSession` | No replacement |
124+
125+
**Deprecated Java actions — with replacements**
126+
127+
These Java actions still exist in the deprecated folder but can't be used anymore (excluded). Replace them with the recommended alternatives:
128+
129+
|Java Action | Replacement |
130+
|---|---|
131+
| `PerformAction` | `PerformAction3` |
132+
| `GetWorkflowTemplates` | `GetWorkflowTemplates2` |
133+
| `CreateBOMWindows` | `CreateOrReConfigureBOMWindows` |
134+
| `CreateBOMWindows2` | `CreateOrReConfigureBOMWindows` |
135+
| `WhereUsed` | `WhereUsed2` |
136+
| `ExpandPSOneLevel` | `ExpandPSOneLevel2` |
137+
| `GetTcSessionInfo` | `GetTcSessionInformation` |
138+
| `GetItemFromId` | `GetItemAndRelatedObjects` |
139+
| `RetrieveCookie` | No replacement |
140+
141+
**What carries forward automatically**
142+
143+
The good news: not everything needs to be rebuilt from scratch.
144+
145+
✅ **Your domain model is preserved** — Entities and associations generated by the previous Extension remain in your module. They're part of your app, so they don't disappear during the migration.
146+
147+
✅ **Your microflows are preserved** — Generated microflows remain in your app. Only those affected by specific breaking changes (input entity naming, Toolkit module references) need regeneration or updates.

0 commit comments

Comments
 (0)