Events

The Helix IPLM Events platform publishes the events that occur in the platform. These events can be subscribed to, and are processed by a dedicated event consumer. These event consumers can format, aggregate, and distribute the published events to support a variety of automation applications.

Events overview

Helix IPLM event and messaging system is a flexible way of generating real-time notifications about events related to Helix IPLM objects. In addition, the event system is designed to be easily integrated with third-party tools that can consume real-time information from Helix IPLM. The event system has been designed using the industry-standard Redis Pub/Sub mechanism. A fully functional Redis instance is included in the Helix IPLM package.

Event format

Each event emitted by Helix IPLM event system follows a pre-defined format, and includes a set of available data fields.

Common fields included for all events

In addition to this list, some specific event types include contextual fields.

Available event types

The following is the list of available channels and event types.

Custom-defined object events

Note:  In cases when multiple objects are updated as part of a single transaction, a failed transaction produces a single event. A successful transaction produces a multiple events, one per affected object. 

A failed attempt to:

• create an IPLV (POST iplvs, POST iplvs/<id>/copy-to-new-ip) , will fire a pi_add_ip event.
• edit an IPLV (PUT iplvs/<id>), will fire a pi_edit_ipv event (to be added in the next phase of events implementation).

{
    "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "event_type": "string",
    "timestamp": 1536341270801,
    "duration_ms": 20,
    "client_ip_address": "xxx.xxx.xxx.xxx",
    "component": "CLI",
    "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "user_name": "bob",
    "object_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "object_name": "drinks.vodka@1.TRUNK",
    "status_code": 400,
    "errors": [
        {
            "message": "NoPermissionError"        },
        {
            "message": "ValidationIllegalFieldError"        }
    ]
}

Subscriptions and email notification

Helix IPLM's Subscription and email notification service permits users to manage event subscriptions and receive event notifications by email. The Email Notification service connects to your preferred SMTP server to send the notifications. The email service is not enabled by default. The example Email Notification service is provided by the piextras package using the events_handler email plugin.

Manage event subscriptions

Event subscriptions are managed using 'pi subscription edit'  commands:

'pi subscription edit' command opens a subscriptions template. The template contains subscription configurations, one per line.

pi subscription edit [-h] [--user user] [--group group] [--template TEMPLATE]

• User and Group are optional parameters. Default (no parameters) subscribes only for currently logged in user.
• System Administrator can modify subscription for other users and groups.
• Individual (non-administrative) users can only modify their own subscriptions. 

[Libraries]
drinks = pi_add_ip    # Get a notification when a new IP is added to library drinks

[IPs]
* = all   # Get a notification for all events on all IPs
drinks. = all #All IPs in drinks library. Should follow 'pi ip list' patterns.

[Lines]

# add multiple wildcard targets

* = pi_adv_ipv

    pi_edit_line

    pi_release_ip

    pi_remove_files_from_line

 Users can subscribe to any object or topic, regardless of permission. For objects that user does not have at least ‘read’ permission, the user will not receive any notifications for that object.

Subscription Rule Examples

drinks.* = pi_edit_alias (All aliases in "drinks" library)
drinks.vodka@*.martini = pi_lock_alias (All aliases on Line "martini")

group1 = pi_disable_group

drinks.vodka = pi_add_line ("vodka" IP)

drinks.vodka@1.* (IP versions 1 on all Lines in "drinks.vodka")
drinks.vodka@* (All IPVs in "drinks.vodka")

label_name* = pi_delete_label

drinks = pi_add_ip (all IPs in "drinks" library)

* = pi_acquire_license

drinks.* = pi_edit_line (All Lines in "drinks" library)
drinks.vodka@.* = pi_add_ipv (All Lines in "vodka" IP)
drinks.@.martini = pi_release_ip (Lines named "martini" in Library "drinks")
.@*.martini = pi_release_ip (All Lines named "martini" )

my_property_def = pi_add_property_definition

my_property_set = pi_add_property_set

my_query = pi_set_query_attribute

* = pi_login

* = all

my_username = pi_enable_user

my_workspace = pi_load_ip

List subscriptions

pi subscription ls lists user's current subscriptions, including group subscriptions. Output generates two sets of subscriptions under "Individual" and "Group" headers. If a user is subscribed via sub-group, the subscribed group name is displayed.

pi subscription list, ls [-h] [--user user] [--group group] 

SUBSCRIPTION      | OBJECT CATEGORY   | SUBSCRIBED BY | GROUP NAME
* = pi_add_library| Library           | Individual    | - 
* = pi_add_library| Library           | Group         | Group1
* = all           | IP                | Individual    | -
drinks. = all     | Library           | Group         | Group2

Email notifications

To receive email notifications, configure an event consumer as shown below in Developing a custom event consumer.

Subscriptions API

A subscription API is available for retrieving a list of users for a given event type. For usage and additional details, refer to Public API documentation included with Helix IPLM installation.

Developing a custom event consumer

The piextras package includes a sample Event Consumer, events_handler.

The events_handler is a framework for Redis event consumer plugins and is provided by the piextras package. The piextras package contains example code that you can use out-of-the-box or as a guide for custom development.

The event_handler provides two example plugins with source code located in .../piextras/event_handler/plugins:

• json_plugin.py - example to write the event payload to a JSON file

• email_plugin.py - example email generation based on user subscriptions

The events_handler plugin framework passes user subscriptions to the plugin.

For more information, refer to the README files in the events_handler and plugins folders in piextras package.

Configuration options

System Administrators have global control over the Events system, using 'pi-admin' tool.

pi-admin settings edit

[SYSTEM]

# Helix IPLM events. Possible choices:
#  none        Disable events (default)
#  all         Enable all Helix IPLM events
#  write_only  Enables events that result in a Write operation
#              and disables all other events
EVENTS.enable = all

Running the commands above, will trigger the event:

piadmin_configure_events 

Current limitations

1. The status code of the events pi_attach_license_event and pi_detach_license_event will reflect the status code of the main operation if the main operation fails. 
2. Attaching and detaching licenses are triggered by operations that require licenses (main operation). If the main operation fails, the status code for the pi_attach_license_event and pi_detach_license_event will also report failure even though the license was successfully attached/detached.
3. Undefined Attribute Events are fired when the server does not have enough information to distinguish which object the attribute is attached to. Undefined Attribute Events belong to Undefined Event Context.
4. Since events are generated by the server, client-side validations which short-circuits execution do not trigger events. Therefore, attempts to edit IP/Line/IPV from CLI which fail due to validation errors do not trigger edit events.

Helix IPLM server configuration 

Some additional PiServer configuration is required to use events. More details on configuring events are at Events Administration.