External extensions
Introduction
ShareAspace has been designed from the ground up using a service based architecture. Many of the prepackaged components of ShareAspace are standalone services that can be configured to be used by ShareAspace itself. These are components like the file preview renderer, the full text indexing, system mailout, as well as product specific packages linked to the out of the box ShareAspace templates.
ShareAspace components:
- Full-text index
- Full-text search
- File preview
- SMTP mail
- Event logger
- Azure SendGrid mail
The architecture facilitating these out of the box (OOTB) components can also be leveraged by business specific custom extensions. These could be:
- Custom validators for Maturity State Changes
- Custom validators for SharePackage sharing rules
- Custom validators for controlling the visibility of module ribbon menu buttons
- Custom WebHook Event Handlers taking actions based on events happening in ShareAspace
- Custom implementation of External DataExchange Tasks, these could typically be data mapper services that can be used in DataExchange import/export jobs
- Custom Send Mail implementations
- Custom ShareAspace Web UI Modules
- Custom ShareAspace Web UI views
- Custom action logic for performing custom business logic based on
- ShareAspace Web module ribbon button click
- ShareAspace Web form actions. Like creating/updating SoftTypes
- Custom Service for serving allowed properties to the Property Value Set UI control
- Custom service for returning a name value list. (Used for defining value selections for query parameters).
One advantage of this type of extension configuration is to allow a Space Template configuration to use a capability name when configuring the use of an external extension, rather than having to provide an external extension Uri to be "hard coded" into the configuration. This separates the configuration from the actual hosting of a Space based on a configuration. This also allows for changing the External Extension deployment and implementation without having to update the configuration (provided that the supported capability names are kept the same).
Another important reason for this type of configuration has to do with security. One aspect is to make sure that ShareAspace will only communicate with services that have been registered before hand.
Furthermore, this type of secure control over trusted external extensions allows for the possibility to also pass impersonation access tokens to the external services. This allows the external extension to do impersonated operations using the ShareAspace REST APIs. i.e. having the external service act on behalf of a user that triggered an event or a validation.
It is only the installation administrator and the Collection Administrator that can configure these external endpoints.
Note
The architecture also allows for implementing custom Full-text indexing/search and custom File Preview renderer. How to implement these extension types is, however, not covered in the product documentation of ShareAspace.
Redundancy
It is possible to register multiple extensions with the same identifier. It is also possible for multiple instances of the ShareAspace Extensions to provide the same set of resources.
Since the use of an extension is based on its identifier, ShareAspace will distribute the requests over all registered endpoints for a specific id - one at the time.
Having two or more registered extensions that fulfill the same function means that ShareAspace will be able to keep operating even if one of these extensions are deactivated (intentionally for maintenance or unintentionally because of system failure).
WebHooks, event handlers, external modules, external views
For the Custom WebHook Event Handlers and for custom web module extensions there are two different types of endpoint:
External endpoint
The External Endpoint configuration is for when you just want to pass an event to something external like Microsoft Teams, Slack, Azure LogicApps, and/or Azure Functions, etc. (i.e. a configured WebHook or an external component that supports HTTP requests). This can also be used to access an External UI module within ShareAspace Web.
These extensions, could, if necessary, handle authentication and authorization against ShareAspace on their own. This type of extensions does not require to be configured as Trusted Extensions as described in the next section.
Trusted external endpoint
The second type of External Endpoint is the Trusted External Endpoint. This extension is for when you want to be able to pass along a ShareAspace access token in the request to the External Extension, letting the Extension impersonate a user that triggered an action (like an event).
ShareAspace extensions
The ShareAspace Extensions are a set of specialized Trusted Extensions. Compared to the Trusted External Endpoint, the ShareAspace Extensions have a predefined purpose. These extensions also have a specific contract that must be fulfilled.
Common across all of these extensions is that they require a route that will provide ShareAspace with a set of Metadata explaining the resources/endpoints of the extension. When adding one of these extensions ShareAspace will request information from the metadata endpoint of that resource. This process is called "Metadata Exchange".
This metadata exchange allows for the extensions to add more resources/endpoints over time. To make these features available to ShareAspace, a Collection Administrator or an installation Administrator, can refresh an already registered extension. This refresh will trigger a new metadata exchange.
Note
The Metadata Exchange imposes an interface that must be implemented by the External Extension.
Types of extensions
| Extension Type | Description |
|---|---|
| Extension for sending email from ShareApace. OOTB ShareAspace has two implemented extensions for this. One based on SMTP and one specifically built for using Azure SendGrid. | |
| External Event | Extension for taking custom actions based on a configured event being triggered in ShareAspace. |
| External Validation | Extension for doing external validation of entering a Maturity System state, validating whether a SharePackage can be shared, or evaluating whether a ribbon menu button should be visible or not. |
| External Task | Extension that can be called from an External DataExchange Task within a configured DataExchange job. This type is typically used for data mappers in import/export scenarios. For example, a configured DataExchange job for an import that takes a proprietary input format can be configured to call an external service to translate the proprietary format to something readable by a ShareAspace OOTB task or the ShareAspace importer. |
| External Actions | Extension for injecting a "middleware" for custom business logic based on a user click on a ribbon button or a middleware handling the result of a SoftType form (for creating and/or updating SoftType instances). |
| File Preview | Extension for handling the rendering of preview images for file types supported by the extension. |
| Full-text Indexing | Extension for running full text indexing of files supported by the extension. |
| Full-text Search | Extension for running a search in an Extension that can search a full text index. |
The Email, Full-text Indexing, Full-text Search, and File Preview Extension Types would
typically only be setup when configuring a ShareAspace installation, i.e. in most cases these
would be registered by an installation administrator.
The other three types, External Validation, External Event, External Task, and External Action would typically not only be used
for OOTB components but also for custom External Extensions. These could be added both during
installation by the installation administrator as well as at runtime by the Collection Administrator.
Note
It is still possible to register the Email, File Preview, Full-text Indexing, and Full-text Search
types at runtime. This can be done by the Collection Administrator.