Table of Contents
Last updated: 10/9/2024

ShareAspace 1.8

Platform

Server 2022

ShareAspace now requires Microsoft Windows Server 2022 as the hosting environment for all ShareAspace out-of-the-box (OOTB) components.

.NET 7

All .NET based ShareAspace components are upgraded to .NET 7 and comes bundled with the framework.

Other

  • Solved race condition issue in the event engine that could prevent events from firing when multiple events fired at the same time.
  • Solved an issue that would prevent Space update if the full-text indexing extension was registered.
  • Changing the owner of a version will now properly propagate the ownership change on everything contained below the version. Before the fix only the version owner was changed but the rule is that the ownership change should always propagate down.
  • When copying a SoftType instance or when creating a new version of a versionable object the checksum attribute of DigitalFile contained within the instance are now correctly replicated as well. Before the fix, the checksum attribute was missing.
  • The authorization.tokenLifeTime can now be set using the collection bootstrap configuration file.
  • The HAETOAS response for the load structure API has a new link navigateRecursive in addition to the previously existing navigate. The new link returns the API route for recursively loading the full structure.
  • Added configuration support for the WorkItemNotification system action in the configuration tool.
  • Solved an issue that prevented events of type WorkItemNotification to be handled by subscription definition / subscription configurations. The event would trigger but never processed.
  • Added support for having spaces in the output filename of DataExchange jobs.
  • Solved an issue in the event evaluation logic that would sometimes give the wrong value for the previous value (i.e. an issue when reading what a value was before a change).
  • It is now possible to index the lockedBy metadata attribute of SoftType instances.
  • It is now possible to update event trigger definitions via a space update.
  • Changed the space/{spaceId}/spaceProfile/person/{email} route to always return a matching ProfilePerson SoftType instance. Before the change the return type would be based on the first PLM object of type Person. Also added a new route /space/{spaceId}//spaceProfile/person/{definitionId}/{email} where definitionId can be used to define the expected SoftType type to get back.
  • Disabled license check on some administration routes in order to prevent catch-22 situations (for the scenario where a license is not provided in the collection bootstrap configuration):
    • /collection/externalExtension
    • /identity/users
    • /authorization/token
  • Solved an issue in the SoftType default presentation builder that could lead to the rendering failed if multiple SoftType reference navigations were required by the presentation configuration.
  • Solved an issue that could prevent an administrator from editing a Personal subscription definition.

User Interface

Other

  • When a user clicks the ShareAspace web module tab refresh button on an extension module ShareAspace web will now always send the refresh message to the extension module. Before the fix the message was only sent if the object info view was activated for the module.
  • Filter settings are now correctly propagating through structure navigations in ShareAspace web, including in the mid-pane-table-view of the structure module.
  • If a user has not set a preferred language in their SpaceProfile ShareAspace web will now default to the language configured as default in the space template.
  • If a user changes the time zone setting under space settings ShareAspace web will now correctly keep this in the information filter used in all API requests.
  • Solved an issue in ShareAspace web that would prevent a user from specifying a custom expiration date when requesting a personal access token.
  • Added support for opening a SoftType based on WorkItem in the WorkItem module from an extension module.
  • It is now possible to delete Participant-queries from the ShareAspace web application (provided that the user has sufficient access to do so).
  • Using the browser refresh while using ShareAspace web will no longer:
    • clear the object selection history.
    • clear the user name presentation in the top right corner.
  • Fixed an issue in the date picker in ShareAspace web. Using a different locale format prevented the date picker from loading.
  • Improved the selection change logic in ShareAspace web in order to make sure that the action ribbon always is in sync with what is selected and displayed in the object information view.
  • Extension modules opened from a ribbon action in ShareAspace web will now default the tab presentation to the extension module title if no other presentation can be found.
  • Solved an issue in ShareAspace web that would prevent a user from closing a message thread.
  • Added functionality for copying DataExchange job instances in the DataExchange module. This should help when scheduling multiple jobs in a row where the user want to reuse previous job configuration parameters. Before this addition each job scheduling would require the user to repeat the configuration steps over and over.
  • Solved an issue in ShareAspace web that could prevent the table paging controls from loading.
  • Solved an issue in the ShareAspace web file module that where clicking the navigation path breadcrumb links sometimes would result in an empty files/folders list.
  • Fixed the positioning of the "three-dot-menu" for "additional contexts" in the message thread module. It was not possible to use the menu before this fix.
  • Solved an issue that could prevent edit forms from opening when clicking an edit action in an object context menu (three dot menu).
  • Enabled collection administrator UI functionality for managing extensions even if there is no license applied.

Extensions

3D Viewer

  • The 3D-viewer can now support multiple Spaces.
  • The 3D-viewer will now load geometry from the configured port path as initially intended.
  • The 3D-viewer can now be loaded with multiple root geometry files.
  • The 3D-viewer can now be configured to show the geometry model browser.

Event engine

Access to SoftType schemas

The liquid templating language has been updated with two new methods, nova.readSoftTypeJsonCurrent and nova.readSoftTypeJsonPrevious. These methods will print the JSON payload of a SoftType instance into the liquid output.

The methods take two parameters, database id of the SoftType instance (required), and the id of the output schema (optional) to be used when reading the SoftType instance. If the output schema id is not provided the templating engine will default to the output schema that is configured as the default output schema of the SoftType.

The method nova.readSoftTypeJsonCurrent will load the SoftType instance based on how the instance looks like after the change that triggered the event and the nova.readSoftTypeJsonPrevious will load the instance based on what the instance looked like before the change that triggered the event.

Example usages:

Prints the JSON payload for the SoftType instance using the specified output schema with id defaultOut. Note that versionOId is a configured port id and the defaultOut is a configured output schema id on the SoftType.

{{ current.versionOId | nova.readSoftTypeJsonCurrent 'defaultOut' }}

Prints an array with two JSON objects, one for the previous representation of the instance and one for the current representation of the instance. Note that the schema id has been omitted in this example.

[
  {{ previous.versionOId | nova.readSoftTypeJsonPrevious }},
  {{  current.versionOId | nova.readSoftTypeJsonCurrent }}
]

Resilience and backoff strategy

The ShareAspace external extension framework has been updated with a new resilience and backoff strategy approach. Each extension type has a default behavior for handling transient errors. The default behavior can be overridden by a configuration per registered extension.

In ShareAspace a transient error is identified as follows.

  • Connection error: it is not possible to connect to the extension.
  • Request response with status code:
    • Network failures (as HttpRequestException).
    • HTTP 5XX status codes (server errors).
    • HTTP 408 status code (request timeout).

If any of the above is true, ShareAspace will see the failure as transient and will retry depending based on a policy configuration for the extension. The backoff policy used by ShareAspace is exponential up to 5 minutes. After 5 minutes ShareAspace will retry once every 5 minutes.

Administration API

A new administration API has been added for reading and managing the events in the ShareAspace event store. The events in the event store are processed by the ShareAspace event bus.

Logging

Improved logging and error handling

The internal logging and error handling has been greatly improved. This improvement will provide better and more clear logging information in the ShareAspace system logs as well as better error messaging when using the ShareAspace API. The new internal architecture will also allow for continued improvements over the coming minor releases of ShareAspace 1.8.

Improved log performance

  • The compression algorithm for compressing old system logs is changed from ZIP to Brotli.
  • Changed from one compressed file containing all archived log files to one unique compressed file per archived log.
  • Compressed log archive files will now automatically be removed based on what come first between:
    • Archive older than 60 days.
    • The number of archived logs reaches 300 (the oldest is removed).
  • Note that: If logs must be preserved outside of the defined scopes the files must be copied from the ShareAspace log folder.

Correlation id

The ShareAspace API has added support for the X-Correlation-Id request header. The X-Correlation-Id is unique for every request. e.g. ShareAspace web will auto generate a GUID that is put on each HTTP request. If the X-Correlation-Id is provided ShareAspace will use this id for all log messages related to the initiating request. If further actions are triggered by a request, like an event being triggered leading to a call to an external extension this same correlation id will be passed on to these extensions. The extensions can then use this same id while logging requests internally within the extension. The extensions can also use the correlation id when reporting back log information to ShareAspace. This way the full impact of a request can be traced in the ShareAspace logs.

Example, X-Correlation-Id request header:

X-Correlation-Id: 5bb3fb20-0f7b-11ee-b090-c9ad50416076

Administration tool

The ShareAspace administration tool has been update with three new features.

  • The administration tool can now run migration scripts, maintenance scripts, and reporting scripts produced by the ShareAspace development tool.
    • Typically the migration and maintenance scripts are produced and provided by Eurostep to be used when upgrading a ShareAspace installation to a later release of ShareAspace or when running a clean up of data in a space, e.g. when low source data quality has led to unwanted data representation in a Space.
  • It is now possible to use the administration tool to set the storage path and file vault path.
  • The administration tool can now search the ShareAspace system logs. The search operates on both the current active log file as well as on all the archived logs.
    • The filtered result can be printed to the console window (default) or to an output file.
    • Supported filtering options.
      • Filter terms - free text filter on log message.
      • Correlation id - correlation id used for finding log information for a chain of events.
      • Log level - All, Critical, Debug, Error, Info, Trace, Warning.
      • Time span - Start to end date time.

As with all the features in the ShareAspace administration tool they are all documented within the tool itself. Using the --help option at root level as well as on sub options brings up the documentation.

Migration and maintenance scripts

PS C:\Program Files\Eurostep\ShareAspace\Host> .\sas.exe run -h
Description:
  Load and run a data maintenance script against a ShareAspace database.

Usage:
  sas run <script.js> [options]

Arguments:
  <script.js>  Name of the script file.

Options:
  --spaceId <spaceId>                    ID of the target space.
  --workingDirectory <workingDirectory>  Working directory for the scripts.
  --whatIf                               Run the script without actually committing the changes.
  --watch                                Run the script every time it changes. Whatch will enable whatIf mode.
  --systemPath <systemPath>              Path to ShareAspace system folder
  -?, -h, --help                         Show help and usage information
  --output <JSON|Table>                  Set output format [default: Table]


PS C:\Program Files\Eurostep\ShareAspace\Host>
Tip

The --watch option will keep the ShareAspace host loaded within the tool allowing execution of updated scripts to run any time the script changes. This cuts host startup lead time from a development process. e.g. When building reporting scripts using the ShareAspace development tool it can be beneficial to let the ShareAspace maintenance tool run the execution of the report using the -watch option instead of running the script execution from the ShareAspace development tool (since the ShareAspace development tool require a host startup for each execution).

Setting paths

PS C:\Program Files\Eurostep\ShareAspace\Host> .\sas.exe system -h
Description:
  Manage ShareAspace storage paths

Usage:
  sas system [command] [options]

Options:
  --systemPath <systemPath>  Path to ShareAspace system folder
  -?, -h, --help             Show help and usage information
  --output <JSON|Table>      Set output format [default: Table]

Commands:
  list-paths              List current configuration
  set-base                Set base storage paths
  set-collection          Set collection storage paths
  set-space <spaceId>     Set space storage paths
  change-path             Change storage or file vault path
  remove-space <spaceId>  Remove space from system

PS C:\Program Files\Eurostep\ShareAspace\Host>

Filter log entries

PS C:\Program Files\Eurostep\ShareAspace\Host> .\sas.exe logs filter --help
Description:
  Filter log entries.

Usage:
  sas logs filter [<term(s)>...] [options]

Arguments:
  <term(s)>  Search for log entries that contain certain word or phrases.

Options:
  --path <path>                                          Log file(s) source path.
  --correlationId <correlationId>                        Search for log entries that contain specified correlation ID.
  --level <All|Critical|Debug|Error|Info|Trace|Warning>  Filter by log level. [default: All]
  --start <start>                                        Get log entries that occured after a specified date and time.
  --end <end>                                            Get log entries that occured before a specified date and time.
  --outFile <outFile>                                    Send output to a file.
  --systemPath <systemPath>                              Path to ShareAspace system folder
  -?, -h, --help                                         Show help and usage information
  --output <JSON|Table>                                  Set output format [default: Table]

Example, filtering out Critical log entries mentioning /collection that were logged after 2023-06-22T03:00:00Z.

PS C:\Program Files\Eurostep\ShareAspace\Host> .\sas.exe logs filter "/collection" --level Critical --start 2023-06-22T03:00:00Z

Model updates

The following changes have been made to the underlying ShareAspace data model:

  • ProjectReferenceSelect extended with:
    • ProductConfiguration
    • ProductConcept
  • ProductConfigurationReferenceSelect extended with:
    • DocumentVersion
    • DocumentDefinition
    • PartVersion
    • PartViewDefinition
  • Added Verification to:
    • ClassificationSelect
    • ContractReferenceSelect
    • DateTimeAssignmentSelect
    • PersonOrganizationReferenceSelect
    • ProjectReferenceSelect
    • PropertyReferenceSelect
    • DocumentReferenceSelect
  • Added properties to ExternalEndpoint and TrustedExternalEndpoint:
  • retryForever: bool?
  • rateLimitNumberOfExecutions: int?
  • Added properties to TrustedResource:
    • requestTimeout: int?
    • retryForever: bool?
    • rateLimitNumberOfExecutions: int?

Checkpoint

The ShareAspace checkpoint API has been updated with new API routes. It is now possible to list all available checkpoints, delete a specific checkpoint, and to download a specific checkpoint.

Read more.

Security

  • ShareAspace web no longer use the session storage for storing JSON Web Tokens (JWT). The JWT is only stored in a secure cookie.
  • ShareAspace web no longer makes use of the Authorization HTTP request header when making calls to the ShareAspace REST API. Instead all REST API calls relies on the secure cookie containing the JWT. Note that the API still support the use of the Authorization header.
  • ShareAspace web no longer passes temporary impersonation JWTs to web based extensions using query string parameters. Instead a message is sent from ShareAspace web to the IFRAME hosting the web extension once the IFRAME has loaded. This is a breaking change (read more in the breaking changes section).
  • Service accounts can now be impersonated by registered trusted extensions (and Nova-extensions). Before this update service accounts could for example not run DataExchange jobs that used external tasks.

Migration

  • Migration path not yet available.

Breaking changes

  • Web extension modules no longer accept query parameters. Initialization data is passed as message to the extension instead. See web extensions.

Deprecation

System preparation tool

The system preparation tool that was used for moving a ShareAspace storage from one environment to another has been deprecated. It has been replaced by the ShareAspace administration tool.

Snapshot

The snapshot API and the snapshot based backup and restore process has been deprecated. Use the file based backup scenario or the checkpoint API based backup scenario instead.

Elastic 6

The full text indexer based on Elastic version 6 is deprecated. Replaced by full text indexer based on Elastic 8.

Developer tooling

A new development SDK is introduced with ShareAspace 1.8.0. It is available as a Nuget package Eurostep.SAS.Logging.ShareAspace.1.8.0.xyz.nupkg and can be used by .NET 7 based custom extension implementations.

The package adds the ability to include a ShareAspace logger (ShareAspaceLogger), implemented on the ILogger interface, to a custom extension. For ShareAspace Nova based extensions the logger will pickup the id of the request sent to an external extension and use that as the X-correlation-id when reporting back logging information from the extension to ShareAspace. For extensions based on the external endpoint and trusted external endpoint ShareAspace web will provide the X-correlation-id header. The X-correlation-id is picked up by the ShareAspace logger.

Documentation