Events and event handlers

Events are a simple data structure, which can be created either using docuteam feeder Event API or generated internally by feeder. With event handlers it is possible to define rules, which automatically start a workflow or multiple workflows if an event with specific property occurs.

Events are displayed in the tab "Events". The event properties can be viewed by clicking on show.

Event handlers can be mananged in the admin tab under "Event handlers".

Event structure

An event has always at least two properties:

• source: The source of the event. The source of events created by feeder is always set to internal.
• event_type: The event type. When creating an event by API, an arbitrary type can be defined. The event types created by feeder are documented further below.

Configuration of an event handler

When creating an event handler at least a name and the workflow which is started by the event handler has to be defined. Such a minimal handler would then start the chosen workflow when any event occurs.

The amount of fields shown in the section Attributes to pass depend on the selected workflow. For each parameter that the selected workflow requires, a property of the event needs to be defined, which value should be passed as parameter to the workflow. Please note that if this property does not exist in an event, no workflow will be started.

Creator of events allows to define an authentication which needs to have created the event (this is only relevant for events created by the Event API of docuteam feeder).

With Workflow that emitted the event a workflow can be chosen which needs to have created the event. This can be usefull, if one would like to run a cleanup workflow if another workflow has been finished.

By clicking on Add new rule additional event properties can be checked.

Please note that the rules are joined using a logical AND and are always compared exactly. If an event handler looks for events with type test type, but the event is created with type test-type, no workflow will be executed by the event handler.

Use cases

Migration from Fedora 3 to Fedora 6

In order to migrate data from Fedora 3 to Fedora 6, feeder needs to know which PIDs are present in Fedora 3 and which PIDs already present in Fedora 6. Based on this information, a DIP is created and migrated for all PIDs, which are not yet present in Fedora 6.

For this, actions.js communicates with the two Fedora systems and uses docuteam feeder API to create an event per migratable PID with the PID and the type MigratablePID. In feeder an event handler can be created, which checks for the type MigratablePID and starts the migration workflow with the PID as SIP parameter. Thus one can make sure that the DIP is only created for packages which are migrated at this very moment, instead of creating DIP for all objects at once.

{
  "PID": "CH-002003-9:1553",
  "source": "actions.js",
  "event_type": "MigratablePID"
}

Deposition of different package formats using docuteam feeder Deposition API

Until now it was not possible to deposit different package formats with the Deposition API, as only one specific workflow was available to process the depositions.

With the event features, creating a deposition generates an event which contains the package format as a property. This way it is possible to define seperate event handlers looking for events with the type Deposition Creation, one for each package format. These event handlers then start different workflows which can process the formats in question.

Events generated by feeder

As mentioned, feeder generates internal events, which can be used to define event handlers.

Workflow execution status change

If the status of a workflow execution changes, an event with type WorkflowExecution Status Change is created by feeder.

This event contains the following properties:

{
  "event_type": "WorkflowExecution Status Change",
  "new_status": "failed",
  "source": "internal",
  "workflow_execution_id": 7,
  "workflow_id": 1,
  "sip": 4,
  "sip_type": "deposition"
}

Explanation of the properties:

• source: Always internal, as the event is created by feeder.
• new_status: Either failed or finished.
• workflow_execution_id: workflow execution ID which created the event.
• workflow_id: ID of the workflow which was used in the workflow execution that created the event.

All other properties afterward depend on the parameters of the used workflow. In general, for each parameter, feeder will add a property to the event. In case a parameter is of type file or folder, feeder will add an additional property named type which is either deposition or other.

Deposition created

If a deposition is created in feeder (either using the feeder web interface in the depositions tab or using the Depositions API an event with the type "Deposition Creation" is created.

This event contains the following properties:

{
  "source": "internal",
  "event_type": "Deposition Creation",
  "resource_type": "deposition",
  "package_format": "MatterhornMETSv1.0",
  "resource_value": 12
}

Explanation of the properties:

• source: Always internal, as the event is created by feeder.
• resource_type: Always deposition.
• resource_value: Deposition ID.
• package_format: Package format of the deposition.