Working with Drupal Rules

The Drupal Rules Module provides support for a Drupal site to react to actions taken by users or processes. This can be used in a variety of ways, but one of the most common use cases for Rules is the maintenance of site-wide workflows; e.g., handing off items and notifying relevant users when particular actions are taken.

Several Islandora modules include Rules implementations, including a core implementation that can react to Fedora objects and datastreams being created, manipulated or purged. This document will attempt to cover any Islandora modules that implement rules, and explain what is available to reactions that include them.

The Rules administration page can be found at the menu path admin/config/workflow/rules. Note that this menu path does not appear unless the Rules UI module is enabled; the Rules API functions on its own without the UI enabled.

---

Table of Contents

Common Terms

Event Triggers

Islandora

Islandora Batch Report

Islandora Book Batch

Islandora IP Embargo

Islandora Scholar Embargo

Conditions

Islandora

Actions

Islandora

Islandora DOMXpath

Islandora Scholar Embargo

Islandora XACML API

Islandora-Unique Data Selector Types

islandora_object

islandora_datastream

islandora_domxpath

islandora_domnode

islandora_xacml

---

Common Terms

• Data Selector: a placeholder for a value that was loaded from something. Data selectors can have properties and subproperties. These values, properties and subproperties represented by the data selector can then be used to populate fields in other parts of a rule.
• List: A special type of data selector property that contains multiple values.
• Machine Name: The name of something used internally by the Rules API to distinguish it from other things. These names are used in exported rules JSON and can be used to construct a rules definition by hand.

---

Event Triggers

Event triggers define what a rule will react to. Often, event triggers will also provide data selectors that can then be used to either filter the scope of the reaction or take action as a result of the trigger. The following modules implement Rules reactions:

Islandora

Rule Name	Machine Name	Data Selectors (Type)
Object Ingested	islandora_object_ingested	object (islandora_object)
Object Modified	islandora_object_modified	object (islandora_object)
Object Purged	islandora_object_purged	object (text - the PID of the object)
Datastream Ingested	islandora_datastream_ingested	object (islandora_object), datastream (islandora_datastream)
Datastream Modified	islandora_datastream_modified	object (islandora_object), datastream (islandora_datastream)
Datastream Purged	islandora_datastream_purged	object (islandora_object), datastream (text - the DSID)

Islandora Batch Report (part of Islandora Batch)

Rule Name	Machine Name	Data Selectors (Type)
Prepare Daily Report	islandora_batch_report_prepare_daily_report	report_date_timestamp (date), successful_object_total (text), failed_object_total (text), successful_set_total (text), failed_set_total (text), content_model_successful_ingest_breakdown (text), ready_to_process_sets (text), ready_to_process_objects (text)

Islandora Book Batch

Rule Name	Machine Name	Data Selectors (Type)
Book Ingested	islandora_book_batch_ingested	book_object (islandora_object)

Islandora IP Embargo

Rule Name	Machine Name	Data Selectors (Type)
Embargo to be lifted	islandora_ip_embargo_embargo_to_be_lifted	embargoed_object (islandora_object)

Islandora Scholar Embargo

Rule Name	Machine Name	Data Selectors (Type)
Datastream Embargo Expired	islandora_scholar_datastream_embargo_expired	object (islandora_object), datastream (islandora_datastream)
Datastream Embargo Expiry Approaching	islandora_scholar_datastream_embargo_expiring	object (islandora_object), datastream (islandora_datastream)
Datastream Embargo Expiry Lifted	islandora_scholar_datastream_embargo_lifted	object (islandora_object), datastream (islandora_datastream)
Datastreams Embargo Expired	islandora_scholar_datastreams_embargo_expired	object (islandora_object), datastreams (list:text - the DSIDs of the expired datastreams)
Object Embargo Expired	islandora_scholar_object_embargo_expired	object (islandora_object)
Object Embargo Expiry Approaching	islandora_scholar_object_embargo_expiring	object (islandora_object)
Object Embargo Lifted	islandora_scholar_object_embargo_lifted	object (islandora_object)

---

Conditions

Conditions allow the scope of rules to be filtered from either site-wide variables or from variables that are provided by data selectors. Much filtering can be done using conditions under the Data group, such as comparing text or counting the number of things in a list. However, the following custom conditions are available:

Islandora

Name	Machine Name	Required Variables (Type)
Check for an XPath match in an XML datastream	islandora_rules_datastream_has_xpath	object (islandora_object), datastream_id (text), xpath (text), xpath_namespaces (taxonomy_vocabulary)
Check object for a relationship	islandora_object_has_relationship	subject (islandora_object), pred_uri (text), pred (text), object (text), type (integer describing the object type, where 0 is a URI and 1 is a plain literal)
Check object for existence of a datastream	islandora_object_has_datastream	object (islandora_object), datastream_id (text)

---

Actions

Actions are taken when an event is triggered. They execute in order, and can be weighted to change variables and pass them on to other objects.

Some actions of note that aren't provided specifically by Islandora modules are:

• Add a variable - allows you to add variables of different types to the list of available data selectors for future actions, including data selector types provided by Islandora modules.
• Calculate a value - especially good for manipulating dates
• Send account e-mail - useful for constructing workflows, e.g., by pulling the owner of an object or an email-address from an XML datastream

Islandora

Name	Machine Name	Variables (Type)	Provides Data Selector (Type)
Add a relationship to an object	islandora_object_add_relationship	subject (islandora_object), pred_uri (text), pred (text), object (text), type (integer describing the object type, where 0 is a URI and 1 is a plain literal)	N/A
Load a datastream from an object	islandora_rules_datastream_load	object (islandora_object), datastream_id (text)	datastream (islandora_datastream)
Remove a relationship from an object	islandora_object_remove_relationship	subject (islandora_object), pred_uri (text), pred (text), object (text), type (integer describing the object type, where 0 is a URI and 1 is a plain literal)	N/A
Set value in elements matched by an XPath in an XML datastream	islandora_rules_datastream_set_xpath	object (islandora_object), datastream_id (text), xpath (text), xpath_namespaces (taxonomy_vocabulary), value (text - the value to set)	N/A

Islandora DOMXpath (provided by Islandora)

Name	Machine Name	Variables (Type)	Provides Data Selector (Type)
Load a DOMXpath for a given XML	islandora_rules_datastream_load_domxpath	datastream (text - the XML)	islandora_domxpath (islandora_domxpath)
Load a DOMXpath from a datastream	islandora_rules_datastream_load_xpath	datastream (islandora_datastream - containing XML)	islandora_domxpath (islandora_domxpath)
Query nodes from DOMXpath instance	islandora_rules_datastream_query_xpath	xpath (islandora_domxpath), query (text), context_node (islandora_domnode; optional)	nodes (list:islandora_domnode)
Register namespaces on a DOMXpath instance	islandora_rules_datastream_load_namespace_vocab	value (islandora_domxpath), xpath_namespaces (taxonomy_vocabulary)

Islandora Scholar Embargo

Name	Machine Name	Variables (Type)	Provides Data Selector (Type)
Lift an Embargo	islandora_scholar_embargo_lift_embargo	object (islandora_object), datastream (islandora_datastream or list:text of DSIDS; optional)

Islandora XACML API

Name	Machine Name	Variables (Type)	Provides Data Selector (Type)
Load the XACML "POLICY" stream from the given object	islandora_xacml_api_rules_load	object (islandora_object)	xacml (islandora_xacml)
Save a loaded policy back to its object	islandora_xacml_api_rules_save	xacml (islandora_xacml)

---

Islandora-Unique Data Selector Types

Rules uses the format selector:property:subproperty when being notated.

Any other types one may encounter when creating rules are inherited from other modules, and those modules' documentation should be consulted to determine how their data selector types work.

Note that some data selectors provide lists that have multiple accessible data.

islandora_object

Name	Description
object	The Fedora object in question.
object:id	The object PID.
object:label	The label of the object.
object:owner	The owner of the object.
object:state	The object state.
object:models	The object's list of content models.
object:models:n	A selected content model, where 'n' is the index of the content model in the object's models array.
object:createdDate	The createdDate of the object.

islandora_datastream

Name	Description
datastream	The datastream in question.
datastream:id	The datastream DSID.
datastream:state	The datastream state initial.
datastream:label	The label of the datastream.
datastream:mimetype	The datastream's mime type.
datastream:parent	The parent object to which this datastream belongs. This value represents an islandora_object data selector, and can be used as such.
datastream:content	The content of the datastream.

islandora_domxpath

Name	Description
islandora_domxpath	The loaded DOMXPath object.
islandora_domxpath:content	The XML representation of the object.

islandora_domnode

Name	Description
islandora_domnode	A list of XML nodes found from a query.
islandora_domnode:n	The nth XML node found from a query.

islandora_xacml (provided by Islandora XACML API)

Name	Description
xacml	The loaded XACML policy.
xacml:manage	The XACML 'Manage' rules.
xacml:manage:users	A list of users the 'Manage' rules apply to.
xacml:manage:users:x	The user x from the 'Manage' users list.
xacml:manage:roles	A list of roles the 'Manage' rules apply to.
xacml:manage:roles:x	The role x from the 'Manage' roles list.
xacml:view	The XACML 'View' rules.
xacml:view:users	A list of users the 'View' rules apply to.
xacml:view:users:x	The user x from the 'View' users list.
xacml:view:roles	A list of roles the 'View' rules apply to.
xacml:view:roles:x	The role x from the 'View' roles list.
xacml:datastream	The XACML 'Datastream' rules.
xacml:datastream:users	A list of users the 'Datastream' rules apply to.
xacml:datastream:users:x	The user x from the 'Datastream' users list.
xacml:datastream:roles	A list of roles the 'Datastream' rules apply to.
xacml:datastream:roles:x	The role x from the 'Datastream' roles list.
xacml:datastream:mimes	A list of mime types applied to datastream rules.
xacml:datastream:mimes:x	Mime type x from the list of datastream mime types.
xacml:datastream:mimeregexs	A list of mime type regexes applied to datastream rules.
xacml:datastream:mimeregexs:x	The mime type regex x from the list of mime type regexes.
xacml:datastream:dsids	A list of DSIDs applied to datastream rules.
xacml:datastream:dsids:x	DSID x from the list of datastream DSIDs.
xacml:datastream:dsidregexs	A list of DSID regexes applied to datastream rules.
xacml:datastream:dsidregexs:x	The DSID regex x from the list of DSID regexes.