Events and event handlers

Events are a simple data structure, which can be created either using docuteam feeder 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 viewd 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.

In the field Attribute from payload to pass as SIP to workflow execution it is possible to define which event property should be transferred to the workflow. If this property does not exist in an event, no workflow will be started. If a SIP or a deposition should be transferred to the workflow, use the value resource.

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 API).

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 bridge 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 API

Until now it was not possible to deposit different package formats with docuteam feeder 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:

{
  "source": "internal",
  "event_type": "WorkflowExecution Status Change",
  "new_status": "failed",
  "resource_type": "deposition",
  "resource_value": 1,
  "workflow_execution_id": 2
}

Explanation of the properties:

• source: Always internal, as the event is created by feeder.
• new_status: Either failed or finished.
• resource_type "sip" for SIP in the workbench, "depositions" for depositions.
• resource_value: SIP name or deposition ID.
• workflow_execution_id: workflow execution ID which created the event.

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": "MatterhornMets",
  "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.