Package com.bonitasoft.processbuilder.extension

Class IdentityUtils

java.lang.Object
com.bonitasoft.processbuilder.extension.IdentityUtils
public final class IdentityUtils extends Object
Utility class for common operations with Bonita Identity API.

Provides methods to retrieve user information, managers, and users by memberships without depending on BDM objects, ensuring functional independence and portability.

Since:
1.0
Version:
2.0.0 - Fixed membership handling for group-only or role-only memberships
Author:
Bonitasoft

  • Method Details

    • getUser

      public static org.bonitasoft.engine.identity.User getUser(Long userId, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Retrieves a Bonita User object by its ID.
      Parameters:
      userId - The ID of the user to retrieve
      identityAPI - The Bonita Identity API instance
      Returns:
      The User object, or null if not found, invalid ID, or on error

    • getUserRecord

      public static UserRecord getUserRecord(Long userId, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Retrieves a UserRecord by user ID.

      Converts the Bonita User object into a lightweight UserRecord containing the essential fields: id, userName, fullName, firstName, lastName, and email. The email is retrieved from the user's professional contact data.

      Parameters:
      userId - The ID of the user to retrieve
      identityAPI - The Bonita Identity API instance
      Returns:
      A UserRecord with user data, or null if user not found or on error

    • getUserManager

      public static Long getUserManager(Long userId, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Gets the manager ID of a given user.
      Parameters:
      userId - The ID of the user whose manager is to be retrieved
      identityAPI - The Bonita Identity API instance
      Returns:
      The manager's user ID, or null if not found or on error

    • getUsersByMemberships

      public static Set<Long> getUsersByMemberships(List<?> membershipList, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Gets all users matching the given memberships (groups/roles).

      This method accepts a list of objects that contain group and role information. Each object must have getGroupId() and getRoleId() methods.

      IMPORTANT: This method correctly handles memberships that have:

      • Both groupId AND roleId defined
      • Only groupId defined (roleId is null or 0)
      • Only roleId defined (groupId is null or 0)
      Parameters:
      membershipList - List of objects containing group and role IDs
      identityAPI - The Bonita Identity API instance
      Returns:
      Set of user IDs matching the memberships, empty set if no users found

    • getUserIdFromObject

      public static Long getUserIdFromObject(Object bdmObject, String methodName)
      Extracts a user ID from a BDM object using reflection.

      This method attempts to call a getter method on the provided object to extract a user ID. It supports various method names commonly used in BDM objects such as getUserId(), getStepUser(), or any custom getter name.

      The method handles null objects, null return values, and invalid ID values (0 or negative).

      Parameters:
      bdmObject - The BDM object from which to extract the user ID (can be null)
      methodName - The name of the getter method to invoke (e.g., "getUserId", "getStepUser")
      Returns:
      The user ID if valid (greater than 0), or null if object is null, method not found, or ID is invalid

    • buildCandidateUsers

      public static Set<Long> buildCandidateUsers(Long stepUserId, boolean includeManager, List<?> membershipList, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Builds a set of candidate user IDs for task assignation based on step user, manager, and memberships.

      This method implements the common actor filter logic:

      1. If stepUserId is valid, add it to the candidates
      2. If includeManager is true and stepUserId has a manager, add the manager ID
      3. If membershipList is provided, add all users from those memberships

      This method is designed to be used by Groovy scripts to reduce code duplication when implementing actor filters.

      Parameters:
      stepUserId - The user ID from a previous step (can be null)
      includeManager - Whether to include the step user's manager
      membershipList - List of membership objects with getGroupId/getRoleId methods (can be null)
      identityAPI - The Bonita Identity API instance
      Returns:
      A set of candidate user IDs (never null, may be empty)

    • filterAssignableUsers

      public static Set<Long> filterAssignableUsers(Set<Long> candidateUserIds, Collection<Long> assignableUserIds)
      Filters assignable users based on candidate user IDs.

      This method takes a set of candidate user IDs and returns only those that are present in the provided collection of assignable user IDs. This is the final step in actor filter logic where candidates are intersected with users who are actually assignable to the task.

      Parameters:
      candidateUserIds - Set of candidate user IDs to filter
      assignableUserIds - Collection of user IDs that are assignable to the task
      Returns:
      A set containing only the user IDs that are both candidates AND assignable

    • getFilteredAssignableUsers

      public static Set<Long> getFilteredAssignableUsers(Long stepUserId, boolean includeManager, List<?> membershipList, Collection<Long> assignableUserIds, org.bonitasoft.engine.api.IdentityAPI identityAPI)
      Convenience method that combines building candidate users and filtering in one call.

      This method performs the complete actor filter logic:

      1. Builds the candidate user set from step user, manager, and memberships
      2. Filters the candidates against the assignable users

      Example usage in Groovy: 

      
 Set<Long> filteredUsers = IdentityUtils.getFilteredAssignableUsers(
     stepUserId,
     true,  // include manager
     membershipList,
     assignableUserIds,
     identityAPI
 )
 return filteredUsers.toList()
      Parameters:
      stepUserId - The user ID from a previous step (can be null)
      includeManager - Whether to include the step user's manager
      membershipList - List of membership objects with getGroupId/getRoleId methods (can be null)
      assignableUserIds - Collection of user IDs that are assignable to the task
      identityAPI - The Bonita Identity API instance
      Returns:
      A set of user IDs that are both candidates AND assignable (never null)

    • extractUserIdsFromObjects

      public static Set<Long> extractUserIdsFromObjects(List<?> userObjects, String userIdMethodName)
      Extracts user IDs from a list of BDM user objects.

      This method iterates over a list of BDM objects and extracts user IDs using the specified getter method. It filters out null and invalid IDs (0 or negative).

      This is useful for extracting user IDs from BDM objects like PBUserList where each object has a user ID field.

      Parameters:
      userObjects - List of BDM objects containing user IDs
      userIdMethodName - The getter method name to extract user ID (e.g., "getUserId")
      Returns:
      A set of valid user IDs extracted from the objects (never null)

    • parseJson

      public static Optional<com.fasterxml.jackson.databind.JsonNode> parseJson(String jsonContent, org.slf4j.Logger logger)
      Parses a JSON string and returns the root JsonNode.
      Parameters:
      jsonContent - JSON string to parse
      logger - Logger for error reporting (nullable)
      Returns:
      Optional containing the root JsonNode, or empty if parsing fails

    • parseJsonAndGetNode

      public static Optional<com.fasterxml.jackson.databind.JsonNode> parseJsonAndGetNode(String jsonContent, String nodeKey, org.slf4j.Logger logger)
      Parses JSON and extracts a specific node by key.
      Parameters:
      jsonContent - JSON string to parse
      nodeKey - Key of the node to extract
      logger - Logger for error reporting (nullable)
      Returns:
      Optional containing the extracted JsonNode, or empty if not found

    • getJsonNode

      public static Optional<com.fasterxml.jackson.databind.JsonNode> getJsonNode(com.fasterxml.jackson.databind.JsonNode parentNode, String nodeKey, org.slf4j.Logger logger)
      Extracts a child node from a parent JsonNode.
      Parameters:
      parentNode - Parent node to search in
      nodeKey - Key of the child node
      logger - Logger for error reporting (nullable)
      Returns:
      Optional containing the child JsonNode, or empty if not found

    • getNodeText

      public static Optional<String> getNodeText(com.fasterxml.jackson.databind.JsonNode node, org.slf4j.Logger logger)
      Extracts a non-empty text value from a JsonNode.
      Parameters:
      node - JsonNode to extract text from
      logger - Logger for debug reporting (nullable)
      Returns:
      Optional containing the trimmed text, or empty if null/blank

    • getNodeArrayAsStringList

      public static List<String> getNodeArrayAsStringList(com.fasterxml.jackson.databind.JsonNode arrayNode, org.slf4j.Logger logger)
      Extracts a list of strings from a JsonNode array.
      Parameters:
      arrayNode - JsonNode that should be an array
      logger - Logger for error reporting (nullable)
      Returns:
      List of strings (empty if node is not an array or is empty)

    • getUsersByMemberships

      public static <T> Set<Long> getUsersByMemberships(Supplier<List<T>> membershipDataSupplier, Function<T,Long> groupIdExtractor, Function<T,Long> roleIdExtractor, org.bonitasoft.engine.api.IdentityAPI identityAPI, org.slf4j.Logger logger)
      Gets user IDs from memberships using a supplier for data access. The supplier should return a collection of objects that have group/role information.
      Type Parameters:
      T - Type of membership data object
      Parameters:
      membershipDataSupplier - Supplier that provides membership data objects
      groupIdExtractor - Function to extract group ID from membership object
      roleIdExtractor - Function to extract role ID from membership object
      identityAPI - Bonita Identity API
      logger - Logger for reporting (nullable)
      Returns:
      Set of user IDs (empty if none found)

    • getUsersForMembership

      public static Set<Long> getUsersForMembership(Long groupId, Long roleId, org.bonitasoft.engine.api.IdentityAPI identityAPI, org.slf4j.Logger logger)
      Gets user IDs for a specific group/role combination. Handles three cases: group+role, group-only, role-only.
      Parameters:
      groupId - Group ID (nullable)
      roleId - Role ID (nullable)
      identityAPI - Bonita Identity API
      logger - Logger for reporting (nullable)
      Returns:
      Set of user IDs matching the membership criteria

    • findMostRecentInstance

      public static <T> T findMostRecentInstance(Supplier<List<T>> instanceSupplier, String typeName, org.slf4j.Logger logger)
      Finds the most recent instance from a supplier result. Generic method that works with any step instance type.
      Type Parameters:
      T - Type of the step instance
      Parameters:
      instanceSupplier - Supplier that executes the DAO query and returns a list
      typeName - Name of the type for logging purposes
      logger - Logger for reporting (nullable)
      Returns:
      The first (most recent) instance, or null if none found

    • extractFieldFromJson

      public static Optional<String> extractFieldFromJson(String jsonString, String fieldName, org.slf4j.Logger logger)
      Extracts a field value from a JSON string.
      Parameters:
      jsonString - JSON string to parse
      fieldName - Field name to extract
      logger - Logger for reporting (nullable)
      Returns:
      Optional containing the field value as string, or empty if not found