Package com.bonitasoft.processbuilder.extension

Class ProcessUtils

java.lang.Object
com.bonitasoft.processbuilder.extension.ProcessUtils
public final class ProcessUtils extends Object
Utility class providing common process and BDM (Business Data Model) operations. This includes retrieving the process initiator and utility methods for BDM validation and deletion handling, specifically tailored for Bonita API interaction.

This class is non-instantiable and all methods are static.

Since:
1.0
Author:
Bonitasoft

  • Method Details

    • getProcessInitiator

      public static UserRecord getProcessInitiator(org.bonitasoft.engine.api.APIAccessor apiAccessor, long processInstanceId)
      Retrieves the user who started a specific process instance. This method accesses the Bonita process and identity APIs to find the initiator's details. If the initiator is not found, or an unexpected error occurs, a default 'unknown_user' is returned.
      Parameters:
      apiAccessor - An instance of APIAccessor to get the Bonita APIs.
      processInstanceId - The unique identifier of the process instance.
      Returns:
      A UserRecord record containing the initiator's ID, username, and full name, etc.

    • getTaskExecutor

      public static UserRecord getTaskExecutor(org.bonitasoft.engine.api.APIAccessor apiAccessor, long activityInstanceId)
      Retrieves the user who executed a specific human task instance. This method accesses the Bonita Process and Identity APIs to find the executor's details. If the executor is not found, or an unexpected error occurs, a default 'unknown_user' is returned.
      Parameters:
      apiAccessor - An instance of APIAccessor to get the Bonita APIs.
      activityInstanceId - The unique identifier of the human task instance (activityId).
      Returns:
      A UserRecord record containing the executor's ID, username, and full name.

    • searchAndValidateId

      public static <T> T searchAndValidateId(String persistenceIdString, Function<Long,T> searchFunction, String objectType) throws RuntimeException
      Searches for a BDM object by its persistence ID, handling the ID conversion from String to Long. Validates that the object exists if the persistence ID is present.
      Type Parameters:
      T - The generic type of the BDM object (e.g., PBProcess, PBCategory).
      Parameters:
      persistenceIdString - The persistence ID as a String (can be null or empty).
      searchFunction - The function (e.g., DAO method) to perform the search: (Long ID -> T Object).
      objectType - The name of the BDM object class (e.g., "PBProcess" or "PBCategory").
      Returns:
      The found BDM object of type T, or null if the persistence ID is null or empty.
      Throws:
      RuntimeException - if the String cannot be converted to Long, or if the object is not found (and ID was present).

    • validateActionAndDelete

      public static <T> T validateActionAndDelete(T bdmObject, String actionTypeInput, Long persistenceId, String objectType)
      Combines the check for a DELETE action with the validation that the BDM object exists. If the actionTypeInput is "DELETE", it delegates to validateForDelete. For any other action type (or null), it returns null, assuming the caller will handle creation or update logic on the bdmObject.
      Type Parameters:
      T - The generic type of the BDM object.
      Parameters:
      bdmObject - The BDM object retrieved from the search (may be null).
      actionTypeInput - The action type (e.g., "DELETE", "INSERT", "UPDATE").
      persistenceId - The ID used for logging.
      objectType - The name of the BDM object class.
      Returns:
      The existing BDM object (T) if the action is DELETE and the object exists; otherwise, returns null.
      Throws:
      RuntimeException - if the action is DELETE but the object is null (not found).

    • searchById

      public static <T> T searchById(Long persistenceId, Function<Long,T> searchFunction, String objectType)
      Searches for a BDM object using a provided search function (closure/lambda). This method is a generic wrapper that accepts a search function and applies it to retrieve the object. It does not perform any validation; use searchAndValidateId for validated searches.

      This method is useful when you want to defer the actual search logic to the caller, allowing the same retrieval method to work with different BDM types through their respective DAOs.

      Type Parameters:
      T - The generic type of the BDM object to be retrieved.
      Parameters:
      persistenceId - The ID (Long) used to search for the object.
      searchFunction - The function that performs the search. Must accept a Long ID and return the BDM object (or null if not found).
      objectType - The name of the BDM object class (e.g., "PBProcess"). Used for logging purposes only.
      Returns:
      The BDM object found by the search function, or null if the search function returns null.

    • searchBDM

      public static <T> T searchBDM(String persistenceIdInput, Function<Long,T> searchFunction, String objectType)
      Searches for a BDM object by its persistence ID string, handling conversion and validation. This is a convenience method that combines ID parsing and object search in a single call.

      This method is particularly useful for Bonita scripts where the persistence ID comes as a String and you want to retrieve any BDM object type without writing multiple lines of boilerplate code.

      Type Parameters:
      T - The generic type of the BDM object to be retrieved.
      Parameters:
      persistenceIdInput - The persistence ID as a String (can be null or empty).
      searchFunction - The function that performs the search. Must accept a Long ID and return the BDM object (or null if not found).
      objectType - The name of the BDM object class (e.g., "PBProcess" or "PBCategory"). Used for logging purposes.
      Returns:
      The BDM object if found, or null if the persistence ID is null/empty, invalid format, or object not found.

    • searchByStringKey

      public static <T> T searchByStringKey(String searchKeyInput, Function<String,T> searchFunction, String objectType)
      Searches for a BDM object by a string key or reference, handling validation and error handling. This is a convenience method for queries that use string-based identifiers (like stepActionRef) instead of numeric persistence IDs.

      This method is particularly useful for Bonita scripts where you need to find BDM objects by their business reference strings rather than their persistence IDs.

      Example usage: 

      
 PBAction pbAction = ProcessUtils.searchByStringKey(
     stepActionRefInput,
     stepActionRef -> pBActionDAO.findByStepActionRef(stepActionRef),
     "PBAction"
 );
      Type Parameters:
      T - The generic type of the BDM object to be retrieved.
      Parameters:
      searchKeyInput - The string key/reference used to search for the object (can be null or empty).
      searchFunction - The function that performs the search. Must accept a String key and return the BDM object (or null if not found).
      objectType - The name of the BDM object class (e.g., "PBAction"). Used for logging purposes.
      Returns:
      The BDM object if found, or null if the search key is null/empty or object not found.

    • searchBDMList

      public static <T> List<T> searchBDMList(Long persistenceIdInput, Function<Long,List<T>> searchFunction, String objectType)
      Searches for a list of BDM objects by a persistence ID, handling validation and error handling. This is a convenience method for queries that return collections based on a parent entity ID.

      This method is particularly useful for Bonita scripts where you need to retrieve related BDM objects (e.g., all PBActionContent for a given PBAction).

      Type Parameters:
      T - The generic type of the BDM objects in the returned list.
      Parameters:
      persistenceIdInput - The persistence ID of the parent entity (can be null or not positive).
      searchFunction - The function that performs the search. Must accept a Long ID and return a List of BDM objects.
      objectType - The name of the BDM object class (e.g., "PBActionContent"). Used for logging purposes.
      Returns:
      A list of BDM objects if found, or an empty list if the persistence ID is invalid or no results found.

    • findMostRecentStepInstance

      public static <T> T findMostRecentStepInstance(Supplier<List<T>> searchFunction, String objectType)
      Finds the most recent step process instance using a search function.

      This method accepts a search function that returns a list of step instances ordered by recency (most recent first). It returns the first element from the list, which represents the most recent instance.

      The search function should be provided by the caller as a lambda or method reference that encapsulates the specific DAO call and its parameters, maintaining independence from BDM classes.

      Example usage: 
      
 PBStepProcessInstance mostRecent = ProcessUtils.findMostRecentStepInstance(
     () -> pBStepProcessInstanceDAO.findMostRecentByProcessInstanceAndRefStepAndStatus(
         processInstancePersistenceId,
         refStep,
         StepProcessInstanceStateType.ENDED.getKey(),
         0,
         1
     ),
     "PBStepProcessInstance"
 );
      Type Parameters:
      T - The generic type of the step process instance object
      Parameters:
      searchFunction - A supplier that performs the search and returns a list of instances
      objectType - The name of the object type for logging purposes (e.g., "PBStepProcessInstance")
      Returns:
      The most recent step instance (first element in the list), or null if no instances found or on error

    • getUserIdsInProfile

      public List<Long> getUserIdsInProfile(org.bonitasoft.engine.api.APIAccessor apiAccessor, String profileName)
      Retrieves the list of user IDs associated with a specific profile.

      This method searches for all users assigned to the specified profile, including users assigned directly, through roles, through groups, or through memberships (role + group).

      Parameters:
      apiAccessor - An instance of APIAccessor to access Bonita APIs.
      profileName - The name of the profile to search for user assignments.
      Returns:
      A list of user IDs associated with the profile, or an empty list if an error occurs.