Release Notes of twinsphere Server / API

The twinsphere Server follows the semantic versioning format in the form major.minor.patch: https://semver.org/ ⧉.

Server 1.14

10-Mar-2025

  • [Security] New "showcase mode" removes security layer/need for authentication on a tenant (useful for hackathons etc.)
  • [Docs] Viewer Release Notes are now separated and not included anymore to these Server release notes
  • [Docs] Updated viewer and validator pages

Server 1.13

06-Feb-2025

  • [Auth] Added support for Azure Entra ID authentication federation (enabling SSO for customers)
  • [Auth] Enhanced twinsphere ID login screen with twinsphere branding (logo, colors, ...)
  • [API] Introduced content Modifier $value for a value only representation of submodels / submodel elements
  • [API] Extended the SM repository with an optional kind filter enabling querying of templates or instances only
  • [Push] Introduced push feature for pushing shells, submodels & concept descriptions to configurable targets
    • Currently only Azure blob storage targets supported (MVP)
    • more target types to be added soon (like remote shell/submodel repositories)
  • [Docs] Added technical documentation on twinsphere ID
  • [Docs] Documented reason and workaround for creation of invalid package files by AASX serialization
  • [Bugfix] Prevented returning status code 500 on not decodable twinsphere file paths on file GET, PUT, DELETE endpoints

Server 1.12

28-Nov-2024

  • [Viewer] Authentication by twinsphere ID
    • Basic Auth was removed and replaced by a login button (twinsphere ID user needed)
    • Intial default user created for every tenant
  • [API] Content modifier $metadata, $reference and $path are now fully available
  • [Search] Enhanced security by filtering undesired requests
  • [Auth] Added branding to twinsphere ID login screen and emails
  • [Viewer] Redesigned app navigation
  • [Bugfix] Input parameter(s) assetIds of following endpoints GET /lookup/shells and GET /shells now only accepts valid JSON of type specificAssetId as specified (accepted direct assetId value before)
  • [Bugfix] Adapted viewer to respect input format serialization of assetIds Parameter(s) for discovery endpoint GET /lookup/shells

Server 1.11.1

07-Nov-2024

  • [Bugfix] Viewer now correctly displays internal segments of time series submodels

Server 1.11

06-Nov-2024

  • [API] Introduction of API-Endpoints to interact with submodels on submodel element level (CRUD)
    • Please be aware that change events will not yet be fired when changes on element level take place.
  • [API] Removed SM-Superpaths for now due to Issue #260 · admin-shell-io/aas-specs-api

Server 1.10.1

29-Oct-2024

  • [Viewer] Added rendering of Entity und RelationshipElement types to generic view enabling display of BoM submodels

Server 1.10

09-Oct-2024

  • [Auth] Added the possibility for twinsphere ID human users to login to twinsphere's Swagger UI
  • [Security] Introduced Patch & Update Management Process to keep all component up to date

Server 1.9.4

12-Sep-2024

  • [Search] Added complete end-to-end example for building a search based UI and pagination example in docs
  • [Search] Introduced language specific indexing, increased indexing performance and optimized of index disk size

Server 1.9.3

11-Sep-2024

  • [DevOps] Moved all twinsphere production cloud (shared) tenants to a dedicated kubernetes cluster

Server 1.9.2

28-Aug-2024

  • [Search] We added the real names of the properties in all available languages and the unit of the value from the linked concept description to the collection object
  • [Bugfix] /serialization now complies to the specified file name convention by naming the aas-spec file inside a created package /aasx/data.{xml|json}

Server 1.9.1

13-Aug-2024

Server 1.9

07-Aug-2024

  • [Bugfix] /import now ignores package thumbnails. Instead default thumbnails of assets are used.
  • [Security] Introduced vulnerability & patch level scanning
  • [Search] Extended search index now supports user-defined aggregations on Properties and MultiLanguageProperties of Technical Data submodel
  • [Auth] Introduction of OAuth2 JWT authentication (in addition to Basic Auth)
    • based on a thwinsphere ID identity provider using Azure Entra ID
    • make it possible to use machine identity login with OAuth2 client credentials grant
    • server swagger UI now accepts an JWT token to authenticate (human login via client credentials grant)
  • [Auth] Introduction of mandatory role based authorization for the server (RBAC)
    • added "reader" and "contributor" roles
    • in case of basic auth usage, the granted authoriziation is "contributor". This enables the the further usage of all server api endpoints
  • [Security] Enabled twinsphere ID security logging

Server 1.8

18-Jul-2024

  • Added logging of all access to key store
  • Introduction of twinsphere's search feature
    • First index on type shell classifications of technical data submodels available (more to follow)
    • New API endpoint /search for posting MongoDB queries based on available indexes
  • Change Events are now an optional tenant feature and deactivated by default (opt-in, saves resource costs)

Server 1.7

23-May-2024

  • Introduction of File Repository for management of files (endpoints /api/v3.0/files…)
    • Files are identified by a so called twinsphere File Path which is valid in the context of a twinsphere tenant
    • Files can be referenced by shells or submodels using their twinsphere File Path
  • Adaption of existing file endpoints
    • DELETE /attachment and DELETE /thumbnail
      • now only remove file references from SM/AAS
      • Deletion of file itself is only possible via DELETE /files (attention: no check for existing references)
    • PUT /attachment and PUT /thumbnail
      • Upload new file and update reference with its new twinsphere File Path
      • Former referenced file stays unchanged and its twinsphere File Path is still valid
    • GET /serialization for AASX packages
      • Packs file which can be found and ignores invalid twinsphere File Paths (non-existing files)

Server 1.6

22-Apr-2024

  • New optional query parameter in GET /shells enables filtering by asset type (e.g. only type shells)
  • Restriction of endpoints with pagination to return a maximum of 250 list elements each (limit parameter)
  • [Bugfix] Endpoints with pagination now no longer return a cursor attribute in the PagingMetadata object when the end of the result has been reached.

Server 1.5.1

15-Apr-2024

  • Introduction of “friendly” tenant names in the URLs: .cloud.twinsphere.io
    • By default, Tenant was accessible via a maximum 6-character
    • Alternatively, now any can be assigned to the URL
    • When using such a , the previous URL remains temporarily accessible until 10-May-2024
  • [Bugfix] /serialization now also generates valid AASX packages in the case of AAS/SM without referenced files

Server 1.5

09-Apr-2024

  • Accessibility of the twinsphere Server API under new domain .cloud.twinsphere.io
    • Previous URL .aas.conplement.cloud remains temporarily accessible until 10-May-2024
  • AAS Registry Service
    • Multiple independent instances can be used, each with a separate database
    • Optional service, must first be set up by the twinsphere team under a freely selectable instance name
    • API accessible at .cloud.twinsphere.io/{instance}/api/v3.0/shell-descriptors
  • Discovery Service
    • Multiple independent instances can be used, each with a separate database
    • Optional service, must first be set up by the twinsphere team under a freely selectable instance name
    • API accessible at .cloud.twinsphere.io/{instance}/api/v3.0/lookup/shells
    • Runs in parallel to “implicit discovery”, which enables a lookup of all assets/AAS contained in the AAS repository (“DiscoveryRead”)
  • [Bugfix] Preflight with direct API access from the browser now possible without any problems

Server 1.4

27-Mar-2024

  • Separation of the submodel repository and conversion of the SM repo superpaths to the original root paths
    • Original SM repo superpaths are still temporarily available via redirects
  • Introduction of referable file paths to reuse uploaded files and avoid file duplicates
  • HTTP Access Headers of the API now allow access from any Orgins (Access-Control-Allow-Origin: *)
    • Facilitates the direct integration of the twinsphere API into frontend applications

Server 1.3.1

15-Mar-2024

Server 1.3

13-Mar-2024

  • Change event mechanism for cyclical information about changes to AAS & SM
    • For setup and usage please refer to Change Events
    • Payload of the event contains changed state of the changed AAS /SMs
  • [Bugfix] GET /shells//submodels now returns none instead of incorrectly all available SMs for shells without SMs

Server 1.2.1

28-Feb-2024

  • [Bugfix] Fixed GetThumbnail operation for existing thumbnails (no more 404 "Document mapping was not found..." )

Server 1.2

27-Feb-2024

  • Introduction of a change log
    • Logging of any creation, modification and deletion of AAS and SM
    • Purely internal function required by the change events mechanism
  • Job Scheduler component “Weaver”
    • Necessary structures for setting up regularly running jobs
    • e.g. in preparation for the change events mechanism
  • Change Log Cleanup Job
    • Regularly cleans up the change log and thus saves storage costs
  • Extension of internal service monitoring
  • Improved validation by updating to the latest metamodel aas-core3.0-csharp v1.0
  • [Bugfix] Prevention of multiple output of file attachments during serialization
  • [Bugfix] Exclusive inclusion of referenced concept descriptions in serialized AASX packages
  • [Bugfix] Extent modifier now only filters blobs and no more Base64 strings (“StatusValue” bug)
  • [Bugfix] AASX package serialization no longer returns a 404 error code for assets without thumbnail

Server 1.1.3

15-Feb-2024

  • [Bugfix] Fixed missing query param assetIds for API endpoint /shells/$references

Server 1.1.2

12-Feb-2024

  • [Bugfix] /serialization now produces correct results for request on only AAS- or SM-IDs
  • [Bugfix] a revised swagger.json now also enables automated client generation with NSwag

Server 1.1.1

07-Feb-2024

  • [Bugfix] Correction of our monitoring components (only internal)

Server 1.1

15-Feb-2024

  • Serialization interface to output specific asset administration shells and submodels in the desired format
    • Return formats include JSON, XML and AASX
    • Realizes the download of AASX packages, including those that only (should) contain a subset of SMs
    • Returned either with or without concept descriptions
  • Pagination for page-by-page retrieval of list data
    • All GET operations that can potentially return larger data sets have been equipped with pagination
  • Extent modifier for filtering BLOB elements for certain requests
    • Binary data embedded in submodels does not have to be retrieved/serialized if required
  • Content modifier $metadata
    • Only returns meta information of an element, not its value.
  • Content modifier $reference
    • Only returns the reference to found elements
  • Content modifier $path
    • Returns the idShort of the requested element and a list of idShort paths to subordinate elements.

Server 1.0.2

16-Jan-2024

  • [Bugfix] Spec-compliant result objects are now returned for unsuccessful API requests
  • [Bugfix] API now supports Base64URL-encoded identifiers with and (new) also without padding

Server 1.0

22-Dez-2023

  • Creation and deletion of submodel references in an existing AAS
  • Concept Description Repository
    • Create, modify, delete and retrieve concept descriptions
  • Import endpoint now also processes the concept descriptions of an AASX package
  • [Bugfix] POST/PUT methods produce an error 500 with invalid JSON (e.g. only {}) in case of an error

Server 0.4

12-Dez-2023

  • Creation, modification and deletion of asset administration shells
  • Retrieving and changing the asset information of an AAS
  • Creation, modification and deletion of submodels
  • Modification and deletion of thumbnails and other files/documents

Server 0.3.4

10-Nov-2023

  • [Bugfix] Optional XML prolog in aas-spec file within AASX package now possible

Server 0.3.3

07-Nov-2023

  • [Bugfix] Sphere import endpoint does now overwrite shell/submodel data.

Server 0.3.2

06-Nov-2023

  • [Bugfix] return pageable at GetAllSubmodellReferences
  • Enhanced Swagger API documentation

Server 0.3

31-Oct-2023

  • AASX Import (Part 2: without Concept Descriptions)
    • Included AAS, submodels and files are imported
    • Currently no processing of concept descriptions
  • Discovery from globalAssetId or specificAssetId to aasId (for QR code resolution)
  • Retrieval of AAS, submodels, thumbnails and other files/documents

Server 0.2

20-Oct-2023

  • Basic Auth for (initially simple) access protection of the API
  • Upload and retrieval of AAS
  • Import AASX package (part 1: processing of AAS and SM only)
    • Proprietary endpoint for upload via SDK

Server 0.1

09-Oct-2023

  • Architecture of the platform
  • Automation of the infrastructure as infrastructure-as-code
  • Setting up build servers and CI/CD pipelines