diff --git a/.gitignore b/.gitignore index dd915994..5eca79d4 100644 --- a/.gitignore +++ b/.gitignore @@ -112,4 +112,8 @@ markdown-help/** ## downloaded assets models -*.mdsp.assetmodel/** \ No newline at end of file +*.mdsp.assetmodel/** + +url-migration-review.md + +.DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index 1cc90e50..c42629ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 4.0.0 - (unreleased) + +- BREAKING CHANGE: Insights Hub URLs are migrating from the `mindsphere.io` domain to the new `siemens.app` scheme (work in progress on this branch). Version 4.0.0+ only works with the new `siemens.app` URLs - use the `3.x` release line if your tenant/gateway still uses `mindsphere.io` URLs. +- Bumped in-range dependencies and fixed resulting TypeScript strictness issues + ## 3.24.2 - Coconut Vienna - June 2024 - Restored previous behavior for Billboard URLs in Event Management and Asset Management Client diff --git a/README.md b/README.md index 566a923a..53cd9842 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,31 @@
+> [!WARNING] +> ### Breaking change starting with version 4.0.0 +> +> Insights Hub URLs are migrating from the `mindsphere.io` domain to the new `siemens.app` scheme. **Version 4.0.0 and above only work with the new `siemens.app` URLs** and are **not compatible** with tenants/gateways still using the old `mindsphere.io` URLs. +> +> - If your tenant/gateway already uses the new `siemens.app` URLs, install `@mindconnect/mindconnect-nodejs@^4.0.0`. +> - If your tenant/gateway still uses the old `mindsphere.io` URLs, keep using `@mindconnect/mindconnect-nodejs@^3.0.0` (the `3.x` line will continue to work with the old URL scheme). +> +> **4.0.0 is best-effort compatible with the new Xcelerator gateway** - it has been tested against the current public-cloud regions, but the migration is still in progress and some backend behavior (see below) is known to differ across deployments. **For on-premise/private-cloud installations we recommend staying on the `3.x` line** until the Xcelerator migration and this library's support for it have stabilized. + +## Migrating to the Xcelerator gateway (4.0.0) + +Version 4.0.0 talks to the new Xcelerator gateway (`siemens.app`) instead of the classic Insights Hub gateway (`mindsphere.io`). A few things changed as a consequence, and a couple of rough edges (outside this library's control) are worth knowing about: + +- **Tenant name vs. tenant/identity-zone id (CLI/SDK credentials only)**: Xcelerator distinguishes between the tenant **name** (used in asset-model qualified names, e.g. `mytenant.MyAspectType`) and a numeric **identity-zone/customer tenant id** (required by the OAuth token endpoint). This only concerns `mc service-credentials` (APP/SERVICE credentials used by CLI/SDK commands like `mc aspects`/`mc assets`) - it has no effect on agent onboarding/`mc agent-token`, which derives its tenant identity entirely from the onboarding response instead. Older configurations that only set a single `tenant`/`usertenant` value may need to also set `--customer-tenant-id`/`--core-tenant-id` when adding credentials, e.g.: + + ```bash + mc service-credentials --mode add --type APP --tenant mytenant --usertenant mytenant \ + --customer-tenant-id