Package com.bonitasoft.processbuilder.extension

Class EmailRecipientsHelper

java.lang.Object
com.bonitasoft.processbuilder.extension.EmailRecipientsHelper
public final class EmailRecipientsHelper extends Object
Utility class for retrieving email addresses from Bonita Identity API.

This class provides thread-safe and stateless methods for:

  • Retrieving email addresses by user ID or manager ID
  • Extracting recipient information from JSON action parameters
  • Processing user IDs from step execution results (DAO-independent)
  • Processing membership-based user lookups (DAO-independent)
  • Validating and filtering email addresses

Design Philosophy: All methods receive their dependencies as parameters, making them easily testable and independent of specific DAO implementations. Methods that process step or membership data accept generic types with extractor functions, allowing scripts to pass BDM objects without compile-time dependencies.

Usage Example (Groovy Script):


 // Extract userId from step results
 def steps = pBStepProcessInstanceDAO.findLastByRefStepAndRootProcessInstanceId(
     rootProcessInstanceId, stepIdParam, 0, 1)
 Long userId = EmailRecipientsHelper.extractUserIdFromFirstStep(steps, { it.userId })

 // Get email for user
 Optional<String> email = EmailRecipientsHelper.getEmailByUserId(identityAPI, userId)
Since:
1.0
Author:
Bonitasoft
See Also:

  • Method Details

    • getEmailByUserId

      public static Optional<String> getEmailByUserId(org.bonitasoft.engine.api.IdentityAPI identityAPI, Long userId)
      Retrieves email for a single user ID.
      Parameters:
      identityAPI - the Bonita Identity API
      userId - the user ID (must be positive)
      Returns:
      Optional containing the email if found and valid

    • getManagerEmailByUserId

      public static Optional<String> getManagerEmailByUserId(org.bonitasoft.engine.api.IdentityAPI identityAPI, Long userId)
      Retrieves manager's email for a given user ID.
      Parameters:
      identityAPI - the Bonita Identity API
      userId - the user ID whose manager email is requested
      Returns:
      Optional containing the manager's email if found

    • getEmailsByUserIds

      public static Set<String> getEmailsByUserIds(org.bonitasoft.engine.api.IdentityAPI identityAPI, Collection<Long> userIds)
      Retrieves emails for multiple user IDs in batch.
      Parameters:
      identityAPI - the Bonita Identity API
      userIds - collection of user IDs
      Returns:
      Set of unique, valid email addresses (preserves insertion order)

    • extractUserIdsFromParameters

      public static List<Long> extractUserIdsFromParameters(com.fasterxml.jackson.databind.JsonNode parameters)
      Extracts user IDs from JSON parameters (RECIPIENTS_USER_IDS).
      Parameters:
      parameters - the JSON parameters node
      Returns:
      List of valid user IDs

    • extractMembershipRefs

      public static String[] extractMembershipRefs(com.fasterxml.jackson.databind.JsonNode parameters)
      Extracts membership reference IDs from JSON parameters.
      Parameters:
      parameters - the JSON parameters node
      Returns:
      Array of membership reference strings

    • extractSpecificEmails

      public static Set<String> extractSpecificEmails(com.fasterxml.jackson.databind.JsonNode parameters)
      Extracts specific email addresses from JSON parameters.
      Parameters:
      parameters - the JSON parameters node
      Returns:
      Set of valid email addresses

    • getStepIdParameterKey

      public static String getStepIdParameterKey()
      Gets the step ID parameter key.
      Returns:
      the step ID parameter key

    • processUsersRecipients

      public static Set<String> processUsersRecipients(org.bonitasoft.engine.api.IdentityAPI identityAPI, com.fasterxml.jackson.databind.JsonNode parameters)
      Processes user IDs from parameters and returns their emails.
      Parameters:
      identityAPI - the Bonita Identity API
      parameters - the JSON parameters node
      Returns:
      Set of email addresses

    • addEmailForUser

      public static void addEmailForUser(Set<String> emails, org.bonitasoft.engine.api.IdentityAPI identityAPI, Long userId, boolean fetchManager)
      Processes a single user ID and adds email (direct or manager) to the set.
      Parameters:
      emails - the set to add the email to
      identityAPI - the Bonita Identity API
      userId - the user ID
      fetchManager - if true, fetch manager's email; otherwise fetch user's email

    • filterValidEmails

      public static Set<String> filterValidEmails(Collection<String> emails)
      Filters and validates a collection of email strings.
      Parameters:
      emails - collection of email strings (may contain nulls/blanks)
      Returns:
      Set of valid, non-blank email addresses

    • joinEmails

      public static String joinEmails(Collection<String> emails)
      Joins email addresses into a comma-separated string.
      Parameters:
      emails - collection of emails
      Returns:
      comma-separated string of unique emails

    • isValidUserId

      public static boolean isValidUserId(Long userId)
      Validates if a userId is valid (non-null and positive).
      Parameters:
      userId - the user ID to validate
      Returns:
      true if valid, false otherwise

    • isValidEmail

      public static boolean isValidEmail(String email)
      Validates if an email string is valid (non-null and non-blank).
      Parameters:
      email - the email to validate
      Returns:
      true if valid, false otherwise

    • extractUserIdFromFirstStep

      public static <T> Long extractUserIdFromFirstStep(List<T> steps, Function<T,Long> userIdExtractor)
      Extracts the user ID from the first element of a step results list.

      This method is designed to work with DAO query results without requiring a compile-time dependency on BDM types. It accepts a generic list and a function to extract the user ID from each element.

      Usage Example (Groovy Script):

      
 // Query the DAO for step instances
 def steps = pBStepProcessInstanceDAO.findLastByRefStepAndRootProcessInstanceId(
     rootProcessInstanceId,
     EmailRecipientsHelper.getStepIdParameterKey(),
     0, 1
 )

 // Extract userId using a closure as the extractor function
 Long userId = EmailRecipientsHelper.extractUserIdFromFirstStep(steps, { step -> step.userId })

 // Alternative syntax with property access
 Long userId = EmailRecipientsHelper.extractUserIdFromFirstStep(steps, { it.userId })
      Type Parameters:
      T - the type of elements in the list (e.g., PBStepProcessInstance)
      Parameters:
      steps - the list of step process instances from a DAO query (may be null or empty)
      userIdExtractor - a function that extracts the user ID from a step object
      Returns:
      the user ID from the first step, or null if the list is null/empty or the extractor returns null

    • extractUserIdsFromMembershipResults

      public static <T> Set<Long> extractUserIdsFromMembershipResults(Collection<T> userLists, Function<T,Long> userIdExtractor)
      Extracts user IDs from a collection of membership-based user list objects.

      This method processes membership query results and extracts unique user IDs using the provided extractor function. It's designed to work with BDM objects like PBUserList without requiring compile-time dependencies.

      Usage Example (Groovy Script):

      
 // Get membership references from action parameters
 String[] refMemberships = EmailRecipientsHelper.extractMembershipRefs(pbActionContent.parameters)

 // Query user lists from DAO
 def userLists = pBUserListDAO.findByProcessIdAndRefMemberships(
     processId, refMemberships, 0, Integer.MAX_VALUE
 )

 // Extract user IDs using a closure
 Set<Long> userIds = EmailRecipientsHelper.extractUserIdsFromMembershipResults(
     userLists,
     { userList -> userList.userId }
 )

 // Get emails for all extracted user IDs
 Set<String> emails = EmailRecipientsHelper.getEmailsByUserIds(identityAPI, userIds)
      Type Parameters:
      T - the type of elements in the collection (e.g., PBUserList)
      Parameters:
      userLists - the collection of user list objects from a DAO query (may be null or empty)
      userIdExtractor - a function that extracts the user ID from each user list object
      Returns:
      a set of unique, valid user IDs extracted from the user lists; returns an empty set if the input is null/empty

    • processStepBasedRecipients

      public static <T> Set<String> processStepBasedRecipients(org.bonitasoft.engine.api.IdentityAPI identityAPI, List<T> steps, Function<T,Long> userIdExtractor, boolean fetchManager)
      Processes step-based recipients and retrieves their email addresses.

      This is a convenience method that combines step user ID extraction with email retrieval. It supports both direct user emails and manager emails based on the fetchManager flag.

      Usage Example (Groovy Script):

      
 // For STEP_USERS recipients type
 def steps = pBStepProcessInstanceDAO.findLastByRefStepAndRootProcessInstanceId(
     rootProcessInstanceId, stepIdParam, 0, 1
 )
 Set<String> emails = EmailRecipientsHelper.processStepBasedRecipients(
     identityAPI, steps, { it.userId }, false  // false = user email
 )

 // For STEP_MANAGERS recipients type
 Set<String> managerEmails = EmailRecipientsHelper.processStepBasedRecipients(
     identityAPI, steps, { it.userId }, true  // true = manager email
 )
      Type Parameters:
      T - the type of elements in the steps list
      Parameters:
      identityAPI - the Bonita Identity API for email lookup
      steps - the list of step process instances from a DAO query
      userIdExtractor - a function that extracts the user ID from a step object
      fetchManager - if true, retrieves the manager's email; otherwise retrieves the user's email
      Returns:
      a set containing the email address (empty if not found or invalid)

    • processMembershipBasedRecipients

      public static <T> Set<String> processMembershipBasedRecipients(org.bonitasoft.engine.api.IdentityAPI identityAPI, Collection<T> userLists, Function<T,Long> userIdExtractor)
      Processes membership-based recipients and retrieves their email addresses.

      This is a convenience method that combines membership user ID extraction with batch email retrieval. It processes all user IDs from the membership results and returns their corresponding email addresses.

      Usage Example (Groovy Script):

      
 // Get membership references from parameters
 String[] refMemberships = EmailRecipientsHelper.extractMembershipRefs(pbActionContent.parameters)

 // Query user lists
 def userLists = pBUserListDAO.findByProcessIdAndRefMemberships(
     processId, refMemberships, 0, Integer.MAX_VALUE
 )

 // Process and get all emails in one call
 Set<String> emails = EmailRecipientsHelper.processMembershipBasedRecipients(
     identityAPI, userLists, { it.userId }
 )
      Type Parameters:
      T - the type of elements in the user lists collection
      Parameters:
      identityAPI - the Bonita Identity API for email lookup
      userLists - the collection of user list objects from a DAO query
      userIdExtractor - a function that extracts the user ID from each user list object
      Returns:
      a set of email addresses for all valid users in the membership results