DS Event Mappings

Configure Creation of Events

From the 3DEXPERIENCE™ application, you can configure that events should be generated for certain operations and by so notify some external application, e.g. TIF, through an event within the message bus.

Within the 3DEXPERIENCE™ application you define when an event from the application should be published onto the DS Message Bus. Per default no events will be generated unless you have configured the 3DEXPERIENCE™ application to do so.

The image below shows the Event Publishing widget available in the 3DDashboard.

ds event publishing
Figure 1. Event Publishing Configuration

For different types, there are different options available for when an event could be generated.

Typically, you will be able to publish events related to creation and/or status changes.

Be aware of that the events are not instantly published onto the message bus once the operation is performed.

There is always a delay from the 3DEXPERIENCE™ application as it needs to ensure the data is in its search index.

This delay may vary but expect at least a 5-minute delay under normal circumstances.

DS Event Mappings in TIF

Within TIF, you must create so-called Event Mapping entities. Such mapping is used to specify what event to react upon, but also some additional criteria to be fulfilled, such as some specific status or similar.

One single event from the 3DEXPERIENCE™ message bus results in one TIF Job per event mapping being fulfilled.

E.g. one event may generate > 1 TIF Job.

Within the Administration UI, you need one "service" to be created. See this page how to understand the services within TIF.

An Event Mapping can be created from two different locations. Either you start from the service and from the "Actions" menu choose "Map" → "Event". Or, via the root category "Mappings" choose the tab "Event Mapping", which will show all Event mappings added.

Now, you can create a new Event mapping.

create event mapping
Figure 2. Create Event Mapping

The following properties are available on the Event mapping:

Property Description Required

Name

Gives the event mapping a name

Yes

Description

Some useful description

No

Enabled

Whether the Event mapping is active or not

Yes

Agent

Declares what 3DEXPERIENCE™ Agent to be used when querying for data from the 3DEXPERIENCE™ platform.

Yes

Event Class / Type

Defines the kind of event to react upon. Possible values depends on the Type, but could be one of

  • Created

  • Status Changed

  • Updated

  • Disconnected

  • Connected

  • Computed

Yes

Configuration

Specify what configuration to be used. See this document for more information about Configurations.

Yes

Authorization Filter

Declares a filter expression to filter out

See below for details.

No

State Filter

For status change events, provide what states to react upon.

Multiple states are accepted and in the UI use comma (,) to separate each value.

No. Default will be all states.

Type Filter

Specify what type the object causing the event must be of

Multiple types are accepted and in the UI use comma (,) to separate each value.

No. Default all types are accepted

Security Context

Declares a specific 3DEXPERIENCE™ security context to be used for the Agent. Optional. See below for further information.

No

Authorization Filter

The Authorization Filter is applied to the value of the authorization field in the incoming event data. If the value for this filter is empty, then the filter will not be evaluated. Otherwise, the filter must evaluate to true in order for the event mapping to generate a Job from the event.

The event data snippet below illustrates how the authorization value is sent. E.g. it is available via the "data" → "authorization" path.

{
    "specversion": "1.0.0",
    "type": "statusChanged",
    "id": "68AB96EAEAEAEAEAEA5D6520001D62FF",
    "time": "2021-10-06T08:58:08.961+0000",
    "timestamp": 1633510688961,
    "metadata": {
        "serviceId": "3DSpace",
        "geoId": "euw1",
        "tenantId": "R11111111111111111111111"
    },
    "contenttype": "application/json",
    "data": {
        "eventClass": "Engineering Item",
        "eventType": "statusChanged",
        "eventTime": 1633510688961,
        "authorization": "VPLMProjectLeader.Company Name.Common Space"
    }
}

The authorization value consists of three parts:

  • Role

  • Company

  • Collaborative Space

The authorization filter on the event mapping may contain multiple items, separated with a comma (,) character when defined in the Admin UI. An item may start with the exclamation mark (!) to indicate negated match. Each item is evaluated separately according to these rules:

  • If a negated item is matching → authorization filter is rejected

  • At least one item matches → authorization filter is accepted

Each item in the filter must contain three fields separated with a dot (.), however, an item may in turn contain wildcards (*) for accepting any value for that particular field.

Example:

Example Description

*.*.Space1,*.*.Space2

Accepts if authorization value relates to either collaborative space with name Space1 or Space2.

!VPLMProjectAdministrator.*.*

Accept all authorization values exception if role is VPLMProjectAdministrator

!*.*.R&D

Accept all authorization values, except those related to the Collaborative space named R&D.

!*.*.R&D,!*.*.External,VPLMProjectLeader.\*.Shared

Accept all authorization values, unless related to the Collaborative space named R&D or Externa, but accepts if role is VPLMProjectLeader and collaborative space is Shared.

If the rules for deciding if the event should be processed or not cannot be expressed with the above syntax, or for example you need to get some attribute value from the object in question to do the evaluation - then you need to perform that logic as part of your Job execution.

And if the criteria is not met for fulfilling the integration use case, you can cancel the job execution by marking the job as being cancelled.

Security Context

The security context defines what access rights you have when working with the 3DEXPERIENCE™ REST API’s. A security context is a combination of a Role / Organization and Collaborative Space.

On the event mapping, you can set a specific security context to be used. If you leave it empty, the same security context as available on the source event will be used. If you use the special value "DEFAULT", then the default security context will be used for the user behind the Agent will be used.

You may also override certain fields of the security context by using the asterisk symbol: *. For example setting the Security Context to this:

VPLMProjectLeader.*.*

Would override the role but keep the organization and collaborative space from the originating event.

The agent you are using is operating on behalf of a specific user.

This user needs to be member of the collaborative space being referenced in the Security Context.