Configuration
Configuration tool
In the out of the box Space Template configuration files there are a set of SoftTypes that are considered System SoftTypes. These should not be modified. For event related system functions these SoftTypes are:
- SoftTypeTriggerDefinition
- SystemTriggerDefinition
- GeneralSubscriptionDefinition
- PersonalSubscriptionDefinition
- GeneralSubscription
- PersonalSubscription
For managing the event configurations in a Space configuration template
there is a section in the Configuration Tool called Events.
This part of the Configuration Tool is a set of specialized views for managing instances of the SoftTypes listed above. Instances of these SoftTypes are what makes up the event configuration for a Space.
Instances of TriggerDefinitions can only be configured using the Configuration Tool, while instances of the SoftTypes GeneralSubscriptionDefinition, PersonalSubscriptionDefinition, GeneralSubscription, and PersonalSubscription can be added at runtime within a Space.
SoftType trigger definition
To define a new SoftTypeTriggerDefinition Instance, click the add button at
the bottom left. Select Type SoftTypeTriggerDefinition and give the instance
a unique id. Click ok to create the instance skeleton.
| Attribute | Description |
|---|---|
| Owner | Reference to a Participant instance. This Participant will be the owner of the Trigger Definition. If left empty the Space will become the owner. |
| Creator | Reference to a SpaceProfile instance. This SpaceProfile (user) will be logged as the creator of the Trigger Definition. |
| Id | A unique identifier of the Trigger Definition. |
| Name | A name for the Trigger Definition. |
| Category | A category tag for the Trigger Definition. |
| Description | A description for the Trigger Definition. |
| Contract | SoftType selection: The Contract defines one or more SoftTypes that are in scope for the Trigger, i.e. for which SoftTypes should this Trigger trigger events. |
Port Selection: The port selection defines which common ports should be made available when defining filtering events triggered by this definition. The port selection is also a mapping of a port path to a friendly name. This friendly name is intended to help the end user to define the filter when setting up a Subscription. To add a port mapping, click the add softtype port plus button in the right hand side pane. |
|
| Action Criteria | The action criteria defines what action will trigger the event. If left empty events will trigger when the instances of the listed SoftTypes are Created, Updated, or Deleted. By clicking the add action criteria plus button in the right hand side pane you can add a configuration limiting the trigger to only trigger events for one of Created, Updated, or Deleted. |
| Attribute Value Criteria | The attribute value criteria allows additional filtering to determine when the trigger should trigger an event. You can add a criteria by clicking the add attribute value criteria plus button in the right hand side pane. The criteria will be AND operated. See table below for details on the criteria parameters. |
| Attribute Action Criteria | With the attribute action criteria you can further detail the rules for when to trigger an event. It allows you to detail specific ports and the type of action that happened on that port (Create, Update, Delete), e.g. you could specify that event should only be triggered when the name of a documented was updated. You can add a attribute action criteria by clicking the add attribute action criteria plus button in the right hand side pane. |
Attribute value criteria
| Attribute | Description |
|---|---|
| Value Type | The value type of the port used in the filtering. All types but the Port type will have the Value field active and the Port Id and Port Context inactive. Changing to Port will deactivate the Value field and activate the Port Id and Port Context fields. |
| Port | The port path to the value that should be evaluated. |
| Context | Current, the new value of the port after the commit. Previous, the value of the port before the commit. |
| Operator | Logic operator for the comparison with the specified value/(Port Id Port Context). |
| Value | The specified value to compare to. |
| Port Id | The port path of a value on the same instance to compare with. |
| Port Context | The context for the Port Id. Current/Previous. |
System trigger definition
To define a new SystemTriggerDefinition Instance, click the add button at
the bottom left. Select Type SystemTriggerDefinition and give the instance
a unique id. Click ok to create the instance skeleton.
| Attribute | Description |
|---|---|
| Owner | Reference to a Participant instance. This Participant will be the owner of the Trigger Definition. If left empty the Space will become the owner. |
| Creator | Reference to a SpaceProfile instance. This SpaceProfile (user) will be logged as the creator of the Trigger Definition. |
| Id | A unique identifier of the Trigger Definition. |
| Name | A name for the Trigger Definition. |
| Category | A category tag for the Trigger Definition. |
| Description | A description for the Trigger Definition. |
| Contract | SoftType selection: The Contract defines one or more SoftTypes that are in scope for the Trigger, i.e. for what SoftTypes should this Trigger trigger events. |
| Action Criteria | The action criteria defines what action will trigger the event. This value must be set. Possible choices are: UserLogin, UserInvitedToSpace, UserRemovedFromSpace, ManagedFileDownload, ManagedFilePreview, ManagedFileDelete, UnmanagedFileDownload, UnmanagedFilePreview, UnmanagedFileDelete, UserOKConsent, UserCancelledConsent. |
Subscription definition
To define a new SubscriptionDefinition Instance, click the add button at
the bottom left. Select Type GeneralSubscriptionDefinition/PersonalSubscriptionDefinition and give the instance
a unique id. Click ok to create the instance skeleton.
| Attribute | Description |
|---|---|
| Owner | Reference to a Participant instance. This Participant will be the owner of the Subscription Definition. If left empty the Space will become the owner. |
| Creator | Reference to a SpaceProfile instance. This SpaceProfile (user) will be logged as the creator of the Subscription Definition. |
| Trigger Definition | The Trigger definition to be used for this Subscription Definition. |
| Id | A unique identifier of the Subscription Definition. |
| Name | A name for the Subscription Definition. |
| Description | A description for the Subscription Definition. |
| Aggregate | Indicates if multiple events triggered in a commit should be handled as single events or as a group of events. |
| Active | Indicates if the Subscription Definition should be active or not. |
| Externals | The configuration of the signal that should be used for a triggered event. Could be a HTTP request (External) or an Email. It is possible to have multiple signal methods. To add a method, use the add external/add email plus buttons on the right hand side pane. |
External
| Attribute | Description |
|---|---|
| Extension Id | The identifier of the extension to use. It is required that the collection is configured with an External Endpoint or a Trusted External Endpoint or that there is a registered Extension that has a resource with this Id. |
| Name | A display name for the handler. |
| Description | A description of the handler. |
| Body | The body to be used in the HTTP request. Note that Extensions only can handle JSON. |
| Headers | HTTP Headers to be used in the HTTP request. |
| Attribute | Description |
|---|---|
| Extension Id | The identifier of the Extension resource that can send email messages. |
| Name | A display name for the handler. |
| Description | A description of the handler. |
| From | The email address that the email will be sent from. |
| To | The email address to where the email will be sent. |
| Subject | The subject of the email. |
| Body | The body of the email. This can be a formatted body, e.g. HTML. |
Loggings
| Attribute | Description |
|---|---|
| Extension Id | The identifier of the Extension resource that can handle log information. |
| Name | A display name for the handler. |
| Description | A description of the handler. |
| Action | The trigger for the log entry. |
| Context | Context information for the log entry. |
| Body | The log body. |
Note
ShareAspace comes with a logger component out of the box that will log events to the Windows event log.
Registering this Extension, configuring this logging and using the "Event Id" EventLogging will
activate this component.
Examples
| Attribute | Value |
|---|---|
| Extension Id | EventLogging |
| Name | Windows logging |
| Description | Logging all user login. |
| Action | {{action.name}} |
| Context | {{action.context}} |
| Body | <Data>user {{action.target}} just loged in</Data> |
| Attribute | Value |
|---|---|
| Extension Id | EventLogging |
| Name | Part or Document Updated |
| Description | Logging that a part or document was updated. |
| Action | PartDocUpdated |
| Context | {{collection.space}} |
| Body | <Data>A {{current.softType}} was updated by {{current.requestor.email}}.</Data> |
Subscription
To define a new Subscription Instance, click the add button at
the bottom left. Select Type GeneralSubscription/PersonalSubscription and give the instance
a unique id. Click ok to create the instance skeleton.
| Attribute | Description |
|---|---|
| Owner | Reference to a Participant instance. This Participant will be the owner of the Subscription. If left empty the Space will become the owner. |
| Creator | Reference to a SpaceProfile instance. This SpaceProfile (user) will be logged as the creator of the Subscription. |
| Id | A unique identifier of the Subscription. |
| Name | A name for the Subscription. |
| Subscription Definition | The Subscription Definition that handles the rules and signal method for the Subscription. |
| Criteria | The filter criteria that will be combined with the criteria defined in the Subscription Definition. It uses the same type of configuration as described for the Subscription Definition. |
Liquid
To be able to handle dynamic values when defining messages for the event signaling methods (HTTP Request or Email), ShareAspace has an implementation that supports the Liquid templating language. To support Liquid we are using the Scriban framework together with a set of ShareAspace specific extensions.
Tip
You can read more about the Liquid templating language here.
Tip
When writing Liquid templates there is a Scriban highlighting extension for Visual Studio Code.
Accessing event data
In addition to the scope documented and explained in the Liquid documentation. ShareAspace has a set of APIs for accessing dynamic information that can be used when defining a Liquid template.
The templating language can be used for all configuration parameters of
HTTP Requests and Email messages. For example, it is possible to use the templating
language when defining the "to" email address.
When defining the signal method in the Subscription Definition you have access to the ShareAspace Liquid APIs (described below). These will give access to information about:
- The Trigger Definition
- The Subscription Definition
- The object instance that triggered the event
- Who triggered the event, what information filter was used etc.
- System data that can be of use when defining the message
- Methods for special formatters to easily write out the default presentation of an instance according to the SoftType configuration
Non aggregated data
If the Subscription Definition is configured to handle each event separately
you will have access to the instance that triggered the event using the
variables current and previous.
The current variable gives you access to the SoftType instance data for
how the data looks like after the commit. From the variable you can access
the values of all ports defined in that SoftType.
The previous variable gives you access to the SoftType instance data for
how the data looked like before the commit.
Example
Say we have a Document SoftType that has the ports id and name. If we
want to write out a string like "id - name" we would use:
{{current.id}} - {{current.name}}
output
0034 - My Document
Aggregated data
If the Subscription Definition is configured to aggregate data you will be able to access the whole set of objects that triggered an event within a changeset. e.g. You have a trigger for "Document Created" and you run an import that creates 100 Documents. If the Subscription Definition is configured to be aggregated, all 100 new Documents will be handled once (compared to the non aggregated setting where each single event would be handled separately).
To access the array with SoftType instances that triggered the event
you can use the variable aggregate. If you chose to iterate over the
array, defining a variable item for each item in the array, you can access
the old and new instance using item.current and item.previous respectively.
From here, it would work exactly as for the non aggregated.
Example, array size
{{aggregate.size}} Documents created in space {{nova.space.id}}.
output
100 Documents created in space MySpace.
Example, JSON array
[
{{for item in aggregate-}}
{
"id": "{{item.current.id}}",
"name": "{{item.current.name}}",
"description": "{{item.current.description}}"
}
{{-if !for.last -}}
,
{{-end-}}
{{-end-}}
]
output An example output for aggregate containing 3 objects.
[
{
"id": "id1",
"name": "name1",
"description": "description1"
},
{
"id": "id2",
"name": "name2",
"description": "description2"
},
{
"id": "id3",
"name": "name3",
"description": "description3"
}
]
Example HTML table
<table>
{{for item in aggregate-}}
<tr>
<td>{{item.current.id}}</td>
<td>{{item.current.name}}</td>
<td>{{item.current.description}}</td>
</tr>
{{-end-}}
</table>
output An example output for aggregate containing 3 objects.
<table>
<tr>
<td>id1</td>
<td>name1</td>
<td>description1</td>
</tr>
<tr>
<td>id2</td>
<td>name2</td>
<td>description2</td>
</tr>
<tr>
<td>id3</td>
<td>name3</td>
<td>description3</td>
</tr>
</table>
Note
There are more efficient ways for handling HTML using the Liquid templating language. Please refer to the Scriban documentation.
ShareAspace specific
nova functions
nova.endpointnova.defaultPresentationnova.informationFilter.timeOffsetnova.informationFilter.timeZonenova.informationFilter.languagenova.informationFilter.culturenova.informationFilter.ownernova.informationFilter.idContextnova.informationFilter.effectivity.enablednova.informationFilter.effectivity.datenova.informationFilter.effectivity.rolenova.informationFilter.effectivity.modenova.readSoftTypeJsonCurrentnova.readSoftTypeJsonPreviousnova.space.idnova.space.namenova.space.descriptionnova.space.startDatenova.web.endpointnova.web.currentSpace
nova.endpoint
Description
Get the configured ShareAspace REST API endpoint.
Examples
input
{{ nova.endpoint }}
output
https://xyz.eurostep.com/api
nova.defaultPresentation
Description
Get the default presentation, for the Unit-of-Information instance from a provided ObjectId.
Arguments
objectId: A text representation
Returns
An textual default representation of the entry that the ObjectId refer to. Empty string if there is no access or the
object does not exist.
Examples
input
{{ objectId | nova.defaultPresentation }}
output
0002, OEM, A, OEM
nova.informationFilter.timeOffset
Description
Get the triggering user's timeOffset setup in the information filter settings.
Examples
input
{{ nova.informationFilter.timeOffset }}
output
-2
nova.informationFilter.timeZone
Description
Get the triggering user's timeZone setup in the information filter settings.
Examples
input
{{ nova.informationFilter.timeZone }}
output
Europe/Stockholm
nova.informationFilter.language
Description
Get the triggering user's language setup in the information filter settings.
Examples
input
{{ nova.informationFilter.language }}
output
English (United States)
nova.informationFilter.culture
Description
Get the triggering user's culture as defined in the information filter settings.
Examples
input
{{ nova.informationFilter.culture }}
output
en-US
nova.informationFilter.owner
Description
Get the triggering user's owner as defined in the information filter settings, this is the Participant ObjectId.
Examples
input
{{ nova.informationFilter.owner }}
output
0003423.....234234
nova.informationFilter.idContext
Description
Get the triggering user's idContext as defined in the information filter settings.
Examples
input
{{ nova.informationFilter.idContext }}
output
TODO
nova.informationFilter.effectivity.enabled
Description
Get effectivity filtering enabled status.
Examples
input
{{ nova.informationFilter.effectivity.enabled }}
output
true
nova.informationFilter.effectivity.date
Description
Get the filtering effectivity date used when the event triggered.
Examples
input
{{ nova.informationFilter.effectivity.date }}
output
2018-12-05T14:11:12
nova.informationFilter.effectivity.role
Description
Get the role used for effectivity filtering.
Examples
input
{{ nova.informationFilter.effectivity.role }}
output
Actual
nova.informationFilter.effectivity.mode
Description
Get the mode used for effectivity.
Examples
input
{{ nova.informationFilter.effectivity.mode }}
output
Live
nova.readSoftTypeJsonCurrent
Description
Get the JSON body of a SoftType instance loaded using a specified output schema. Output is based on how the instance looked like before the change that triggered the event. The output schema id parameter is optional. ShareAspace will load using the configured default output schema for the SoftType if no schema id is provided.
Examples
input
{{ current.versionOId | nova.readSoftTypeJsonCurrent 'defaultOut' }}
output
{
"id": "001",
"name": "Name 1",
...
}
nova.readSoftTypeJsonPrevious
Description
Get the JSON body of a SoftType instance loaded using a specified output schema. Output is based on how the instance looked like before the change that triggered the event. The output schema id parameter is optional. ShareAspace will load using the configured default output schema for the SoftType if no schema id is provided.
Examples
input
{{ previous.versionOId | nova.readSoftTypeJsonPrevious 'defaultOut' }}
output
{
"id": "001",
"name": "Name 1",
...
}
nova.space.id
Description
Get the id of the current space.
Examples
input
{{ nova.space.id }}
output
space1
nova.space.name
Description
Get the name of the current space.
Examples
input
{{ nova.space.name }}
output
Space Name
nova.space.description
Description
Get the description of the current space.
Examples
input
{{ nova.space.description }}
output
This is a test space.
nova.space.startDate
Description
Get the start date of the current space.
Examples
input
{{ nova.space.startDate }}
output
2018-12-05T14:21:05
nova.web.endpoint
Description
Get the configured ShareAspace Web Application endpoint.
Examples
input
{{ nova.web.endpoint }}
output
https://xyz.eurostep.com/sasweb
nova.web.currentSpace
Description
Get the configured ShareAspace Web Application endpoint, including the route to the Space where the event was triggered.
Examples
input
{{ nova.web.currentSpace }}
output
https://xyz.eurostep.com/sasweb/#/space/space1
event functions
event.triggeredByevent.triggeredevent.triggerDefinition.idevent.triggerDefinition.nameevent.subscription.idevent.subscription.nameevent.subscription.ownerevent.subscription.creatorevent.subscriptionDefinition.idevent.subscriptionDefinition.nameevent.subscriptionDefinition.descriptionevent.subscriptionDefinition.aggregationevent.aggregated
event.triggeredBy
event.triggeredBy
Description
Get the email address of the user that triggered the event.
Examples
input
{{ event.triggeredBy }}
output
admin@eurostep.com
event.triggered
event.triggered
Description
Get the date and time for when the event was triggered.
Examples
input
{{ event.triggered }}
output
2018-12-05T14:11:12
event.triggerDefinition.id
Description
Get the identifier of the current TriggerDefinition.
Examples
input
{{ event.triggerDefinition.id }}
output
OnMaturityChanged
event.triggerDefinition.name
Description
Get the display name of the current TriggerDefinition.
Examples
input
{{ event.triggerDefinition.name }}
output
Maturity state has changed
event.subscription.id
Description
Get the identifier of the current Subscription.
Examples
input
{{ event.subscription.id }}
output
OnMaturityChanged
event.subscription.name
Description
Get the display name of the current Subscription.
Examples
input
{{ event.subscription.name }}
output
Maturity state has changed
event.subscription.owner
Description
Get the ObjectId of the Participant that owns the subscription
Examples
input
{{ event.subscription.owner }}
output
0003423.....234234
event.subscription.creator
Description
Get the email address of the user that created the subscription.
Examples
input
{{ event.subscription.creator }}
output
admin@eurostep.com
event.subscriptionDefinition.id
Description
Get the identifier of the current SubscriptionDefinition.
Examples
input
{{ event.subscriptionDefinition.id }}
output
OnMaturityChanged
event.subscriptionDefinition.name
Description
Get the display name of the current SubscriptionDefinition.
Examples
input
{{ event.subscriptionDefinition.name }}
output
Mail sent on maturity change
event.subscriptionDefinition.description
Description
Get the description of the current SubscriptionDefinition.
Examples
input
{{ event.subscriptionDefinition.description }}
output
If subscribing to this event an email will be sent to you when any maturity is changed.
event.subscriptionDefinition.aggregation
Description
Determine if the SubscriptionDefinition is setup to aggregate multiple events into a single instance.
Examples
input
{{ event.subscriptionDefinition.aggregation }}
output
true
event.aggregated
Description
Determine if the SubscriptionDefinition is setup to aggregate multiple events into a single instance.
Examples
input
{{ event.aggregated }}
output
true
action functions
Used for triggers.
action.name
For SoftTypeTriggerDefinition this is {softTypeId}.{triggerType}, e.g. DesignPart.Update.
For SystemTriggerDefinition this is {triggerName}, e.g. UserLogin.
action.context
For SoftTypeTriggerDefinition this will always be the space id.
For SystemTriggerDefinition this can be the space id or collection depending on where the event was triggered.
action.target
For SoftTypeTriggerDefinition this will always be the oid of the object that triggered the event. For SystemTriggerDefinition this can be the oid of the object that triggered the event. It can also be the location string for unmanaged files.