Guest Collection Activity Notifications

1. Overview

Transfer can send completion emails for tasks involving guest collections to identities in addition to the task’s owner. This document shows how to enable this feature and specify whom to notify.

2. How Notifications Are Configured

Notifications are enabled by specifying an activity notification policy on the guest collection. This can be done by any user with the administrator role on the guest collection, using either the Web App or command line interfaces.

Policies constrain notifications based on collection transfer usage (source or destination) and task completion status (SUCCEEDED or FAILED). Multiple data flows and statuses may be specified.

2.1. Using the Web App

Both GCS and GCP guest collections may be configured through the Web App. From the guest collection’s overview page, click on the "Edit Attributes" button. Locate the section of radio buttons with the label "Activity Notification Policy". The default will be set to no notifications.

Begin by choosing the transfer usage to notify on. Clicking a radio button will expose another set of radio buttons to choose the completion status that should be notified on.

Once these have been specified, click on the "Save Changes" button at the bottom of the page to apply the policy to the collection.

2.2. Using Command Line Interfaces

GCS guest collections may be configured using the GCS CLI while logged on as the collection administrator.

globus-connect-server collection update COLLECTION_ID \
  --activity-notifications VALUES

GCS guest collections also may be configured using the Globus CLI.

globus collection update --activity-notifications VALUES COLLECTION_ID

GCP guest collections are configured using the Globus CLI, but through a different sub-command.

globus gcp update guest --activity-notifications VALUES COLLECTION_ID

In all three cases, VALUES is a string that specifies the uses and statuses that should trigger notifications. The special value all may be used to notify in all cases.

Specifying a single use type and no status (e.g. destination) implies that notifications will be sent for all tasks where the collection is used as such in the transfer. Specifying a single status (e.g. failed) implies that notifications will be sent for all transfer tasks where the completion status is the given value.

Mixed cases can be specified through comma-separated values. For example, to send notifications for transfers where the collection is the source and the task completes with SUCCEEDED status, use the value source,succeeded

To reset back to no notifications, use consecutive double quotation marks ("").

3. Who Receives Notifications

Notification emails are sent to principals who have an activity-monitoring role on the guest collection. Activity-monitoring roles are activity_monitor, activity_manager, and administrator.

Role principals may be Globus Auth identities or Globus Groups. The role must be specified explicitly on the collection itself. Roles inherited from a parent collection or endpoint do not get notified.

Roles to be notified are determined at transfer task submission time. Group memberships are determined when a notification email is sent. This means that roles added to the collection during a transfer task will not receive notifications for that task, but changes to a Group membership with a role will be heeded.

If a task owner also has an activity-monitoring role on a collection, Transfer will send only the task owner notification email to minimize redundant communication.

Note
Guest collection activity notification emails look very similar to the emails sent to the task owner when a task has completed. One key difference is that the monitor emails include an extra field showing the identity that submitted the task. The other difference is that collection information may be redacted if a collection has been configured as private and the monitor does not have a role on that collection.

When granting roles for notification, please double check that all principals have email addresses. Login identities should have an email address, but confidential clients will not.

If you are unsure whether an identity has an email address, you can use the Globus CLI to retrieve identity information.

globus api auth GET /v2/api/identities/IDENTITY_UUID

The response will include an email member. This is the value that Transfer uses to send the notification email.

{
  "identity": {
    "identity_provider": "fcac0a3c-7157-4570-b8d0-5aba90bebaed",
    "status": "used",
    "id": "224656ea-64e7-4898-8f93-c00d38eb5f61",
    "name": "Ari Searchar",
    "email": "asearchar@example.edu",
    "identity_type": "login",
    "organization": "Example University",
    "username": "asearchar@example.edu"
  }
}