3.3.1   Subscriptions Tool

This tool has id 'portal_subscriptions'.

API:

• notify_event:

  def notify_event(self, event_type, object, infos):
  """Standard event hook.
  
  Get the applicable subscriptions. Sends the event to the
  subscriptions.
  
  For workflow events, infos must contain the additional
  keyword arguments passed to the transition.
  """
  

• getSubscriptionsFor:

  def getSubscriptionsFor(self, event_type, object, infos):
  """Get the subscriptions applicable for this event.
  
  Some of the parameters may be None to get all subscriptions.
  """
  

Also needed API

• To what local subscription lists can the user subscribe?

3.3.2   Subscription

API:

• isInterestedInEvent:

  def isInterestedInEvent(self, event_type, object, infos):
  """Is the subscription interested in the given event."""
  

• sendEvent:

  def sendEvent(self, event_type, object, infos):
  """Send an event to the subscription."""
  

• getRecipientsRules:

  def getRecipientsRules(self, ...):
  """Get the recipients rules objects...
  
  XXX matching what ?
  """
  

• setters/getters for the properties.

A Subscription instance has the following properties:

• Event filtering:

  • filter_event_types -- The event types on which to react.

    Examples: workflow_create, workflow_in_publish

  • filter_object_types -- The types of the objects concerned by the subscription. The subscription is valid only if the context object's portal_type is in object_types.

• Recipient filtering:

  • recipient_emails_black_list -- The emails the subscription is blocking.

• Notifications:

  • notification_types -- What kinds of action are taken for the recipients:
    • 'tales': Call notification_expression.
    • 'email': Send an email to each recipient, according to notification_email_expression.
  • notification_expression -- A TALES expression called for each recipient. In the expression, the same namespace as in ComputedRecipient is available, with in addition:
    • email: The recipient's email.
    • member: The member if the recipient is a member, or None.
  • notification_email_expression -- A TALES expression returning the email headers and body as a string. No mail is sent if it returns a false value. In the expression, the same namespace as in action_expression is available.

3.3.3   Recipients

There are different ways of getting recipients. The following classes subclass RecipientsRule and implement different strategies. Their properties are described below.

API:

• getRecipients:

  def getRecipients(self, event_type, object, infos):
  """Get the recipients.
  
  Returns a mapping with 'members' and 'emails' as keys.
  """
  

ComputedRecipientsRule:

expression -- A TALES expression returning a mapping with recipients. In the expression, the following namespace is available:

• portal: The portal object.
• context: The context object (proxy) where the triggering event occurred.
• proxy: Alias for context.
• doc: context.getContent().
• container: The context's container.
• ancestor: If 'ancestor_local' or 'ancestor_merged' was used for recipient_roles_origins, that object, else None.
• event_type: The triggering event type.
• triggering_user: The user who triggered the original action.
• DateTime: A DateTime constructor.

ExplicitRecipientsRule:

• members -- The ids of the members subscribed manually.
• members_allow_add -- Whether members are allowed to subscribe / unsubscribe manually to the Subscription (adding themselves to recipient_members).
• groups -- The ids of the groups subscribed manually.
• emails -- The emails subscribed manually.
• emails_allow_add -- Whether anonymous visitors are allowed to subscribe / unsubscribe manually to the Subscription (adding themselves to recipient_emails).
• emails_confirm -- Whether the emails have to be confirmed before being used. XXX this may be better as a global flag of portal_subcriptions instead..
• emails_pending_add -- The emails subscribed manually but not yet confirmed.
• emails_pending_delete -- The emails pending deletion from recipient_emails but not yet confirmed.

RoleRecipientsRule:

• roles -- The roles subscribed.
• origins -- A sequence describing how roles are looked up. It can contain the following keys:
  • 'local': Direct local roles from the context object are used.
  • 'merged': All merged local roles of the context object are used.
  • 'ancestor_local': Direct local roles found on an ancestor object of type in ancestor_object_types. Only the closest matching ancestor object is used.
  • 'ancestor_merged': Idem but with merged local roles.
• ancestor_object_types -- The portal types of the ancestor where a lookup of local roles is done if origins contains 'ancestor_local' or 'ancestor_merged'.

WorkflowImpliedRecipientsRule:

• origins -- A sequence of keys used to determine which object's workflow is queried for recipients. It can contain the following keys:
  • 'context': The context object.
  • 'container': The container.
  • 'ancestor': Direct local roles found on an ancestor object of type in ancestor_object_types. Only the closest matching ancestor is used.
• ancestor_object_types -- The portal types of the ancestor where workflow is queried for recipients.
• history_lookup -- Determines what part of the history we lookup for the transition of type matching 'transitions':
  • 'last': The last transition of matching type is used.
  • 'all': All transitions of matching type are used.
• transitions -- The name of the transitions examined for variables. '*' means all transitions. If the first element of the list is '-', then all types except the ones following it are used.
• variables -- The workflow variables containing used recipients (string or list). (Will often be ['actor'].)