Interface CaseService

  • All Known Implementing Classes:
    CaseServiceImpl

    public interface CaseService
    Provides case management operations.
    • Method Detail

      • startCase

        String startCase​(String deploymentId,
                         String caseDefinitionId)
        Starts a new case for given definition with empty case file.
        Case id is generated based on case id prefix (defined on case definition) and generated value.
        CASE-XXXXXXXXX where XXXXXXX is generated value for the prefix
        Examples:
        • CASE-0000000123
        • HR-0000000321
        • LOAN-0000000099
        Parameters:
        deploymentId - deployment id of project that case definition belongs to
        caseDefinitionId - id of case definition
        Returns:
        returns unique case id in the format PREFIX-GENERATED_ID as described above
      • startCase

        String startCase​(String deploymentId,
                         String caseDefinitionId,
                         CaseFileInstance caseFile)
        Starts a new case for given definition with given case file.
        Case id is generated based on case id prefix (defined on case definition) and generated value.
        CASE-XXXXXXXXX where XXXXXXX is generated value for the prefix
        Examples:
        • CASE-0000000123
        • HR-0000000321
        • LOAN-0000000099
        Parameters:
        deploymentId - deployment id of project that case definition belongs to
        caseDefinitionId - id of case definition
        caseFile - initial case file to be used for this case
        Returns:
        returns unique case id in the format PREFIX-GENERATED_ID as described above
      • getCaseFileInstance

        CaseFileInstance getCaseFileInstance​(String caseId)
                                      throws CaseNotFoundException
        Returns Case file for give case id
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        Returns:
        returns current snapshot of CaseFileInstance
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • getCaseInstance

        CaseInstance getCaseInstance​(String caseId,
                                     boolean withData,
                                     boolean withRoles,
                                     boolean withMilestones,
                                     boolean withStages)
                              throws CaseNotFoundException
        Returns case instance (only if it's active) identified by given case id with options on what should be fetched
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        withData - determines if case file should be loaded
        withRoles - determines if role assignments should be loaded
        withMilestones - determines if milestones should be loaded
        withStages - determines with stages should be loaded
        Returns:
        returns current snapshot of CaseInstance
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • closeCase

        void closeCase​(String caseId,
                       String comment)
                throws CaseNotFoundException
        Closes case with given case id (including all attached process instances if any). Does not affect case file so in case it can still be used to reopen the case by starting new instances.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        optional - comment to be added when closing the case instance
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • cancelCase

        void cancelCase​(String caseId)
                 throws CaseNotFoundException
        Cancels case with given case id (including all attached process instances if any). Does not affect case file so in case it can still be used to reopen the case by starting new instances.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • destroyCase

        void destroyCase​(String caseId)
                  throws CaseNotFoundException
        Permanently destroys case identified by given case id. It performs the same operation as abortCase and destroys the case file and other attached information.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • reopenCase

        void reopenCase​(String caseId,
                        String deploymentId,
                        String caseDefinitionId)
                 throws CaseNotFoundException
        Reopens case given by case id by starting another instance of case definition. It will inherit all data from case file that was available in before case was closed/canceled.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        deploymentId - deployment id of project that case definition belongs to
        caseDefinitionId - id of case definition
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
        CaseActiveException - thrown when case is still active
      • reopenCase

        void reopenCase​(String caseId,
                        String deploymentId,
                        String caseDefinitionId,
                        Map<String,​Object> data)
                 throws CaseNotFoundException
        Reopens case given by case id by starting another instance of case definition. It will inherit all data from case file that was available in before case was closed/canceled.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        deploymentId - deployment id of project that case definition belongs to
        caseDefinitionId - id of case definition
        data - additional data to be set on case file
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
        CaseActiveException - thrown when case is still active
      • addDynamicTask

        void addDynamicTask​(String caseId,
                            TaskSpecification taskSpecification)
                     throws CaseNotFoundException
        Adds new user task to specified case. Should be used when user task should be added to the main process instance of the case. If there are more process instances for given case and user task should be added to specific process instance addDynamicTask(Long, TaskSpecification) should be used
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        taskSpecification - complete specification that defines the type of a task to be added
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDynamicTaskToStage

        void addDynamicTaskToStage​(String caseId,
                                   String stage,
                                   TaskSpecification taskSpecification)
                            throws CaseNotFoundException,
                                   StageNotFoundException
        Adds new user task to specified case and stage. Should be used when user task should be added to the main process instance of the case. If there are more process instances for given case and user task should be added to specific process instance addDynamicTaskToStage(Long, String, TaskSpecification) should be used
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        stage - id or name of the stage there the task should be added
        taskSpecification - complete specification that defines the type of a task to be added
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
        StageNotFoundException - thrown in case stage does not exist
      • addDynamicTaskToStage

        void addDynamicTaskToStage​(Long processInstanceId,
                                   String stage,
                                   TaskSpecification taskSpecification)
                            throws CaseNotFoundException,
                                   StageNotFoundException
        Adds new user task to specified case and stage on given process instance.
        Parameters:
        processInstanceId - unique process instance id
        stage - id or name of the stage there the task should be added
        taskSpecification - complete specification that defines the type of a task to be added
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
        StageNotFoundException - thrown in case stage does not exist
      • addDynamicSubprocess

        Long addDynamicSubprocess​(String caseId,
                                  String processId,
                                  Map<String,​Object> parameters)
                           throws CaseNotFoundException
        Adds new subprocess (identified by process id) to given process instance. Should be used when subprocess should be added to the main process instance of the case. If there are more process instances for given case and subprocess should be added to specific process instance
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        processId - identifier of the process to be added
        parameters - optional parameters for the subprocess
        Returns:
        returns process instance id of the subprocess
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDynamicSubprocess

        Long addDynamicSubprocess​(Long processInstanceId,
                                  String processId,
                                  Map<String,​Object> parameters)
                           throws CaseNotFoundException
        Adds new subprocess (identified by process id) to case.
        Parameters:
        processInstanceId - unique process instance id
        processId - identifier of the process to be added
        parameters - optional parameters for the subprocess
        Returns:
        returns process instance id of the subprocess
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDynamicSubprocessToStage

        Long addDynamicSubprocessToStage​(String caseId,
                                         String stage,
                                         String processId,
                                         Map<String,​Object> parameters)
                                  throws CaseNotFoundException
        Adds new subprocess (identified by process id) to given process instance. Should be used when subprocess should be added to the main process instance of the case. If there are more process instances for given case and subprocess should be added to specific process instance
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method addDynamicSubprocess(Long, String, Map) method should be used instead.
        stage - id or name of the stage there the task should be added
        processId - identifier of the process to be added
        parameters - optional parameters for the subprocess
        Returns:
        returns process instance id of the subprocess
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDynamicSubprocessToStage

        Long addDynamicSubprocessToStage​(Long processInstanceId,
                                         String stage,
                                         String processId,
                                         Map<String,​Object> parameters)
                                  throws CaseNotFoundException
        Adds new subprocess (identified by process id) to case.
        Parameters:
        processInstanceId - unique process instance id
        stage - id or name of the stage there the task should be added
        processId - identifier of the process to be added
        parameters - optional parameters for the subprocess
        Returns:
        returns process instance id of the subprocess
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • triggerAdHocFragment

        void triggerAdHocFragment​(String caseId,
                                  String fragmentName,
                                  Object data)
                           throws CaseNotFoundException
        Triggers given by fragmentName adhoc element (such as task, milestone) within given case. Should be used when fragment should be triggered on the main process instance of the case. If there are more process instances for given case and fragment should be triggered on specific process instance triggerAdHocFragment(Long, String, Object) method should be used instead
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        fragmentName - name of the element that can be triggered
        data - optional data to be given when triggering the node
        Throws:
        CaseNotFoundException
      • triggerAdHocFragment

        void triggerAdHocFragment​(Long processInstanceId,
                                  String fragmentName,
                                  Object data)
                           throws CaseNotFoundException
        Triggers given by fragmentName adhoc element (such as task, milestone) within given process instance
        Parameters:
        processInstanceId - unique process instance id
        fragmentName - name of the element that can be triggered
        data - optional data to be given when triggering the node
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • triggerAdHocFragment

        void triggerAdHocFragment​(String caseId,
                                  String stage,
                                  String fragmentName,
                                  Object data)
                           throws CaseNotFoundException
        Triggers given by fragmentName adhoc element (such as task, milestone) within given case and stage. Should be used when fragment should be triggered on the main process instance of the case. If there are more process instances for given case and fragment should be triggered on specific process instance triggerAdHocFragment(Long, String, String, Object) method should be used instead
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        stage - id or name of the stage there the task should be added
        fragmentName - name of the element that can be triggered
        data - optional data to be given when triggering the node
        Throws:
        CaseNotFoundException
      • triggerAdHocFragment

        void triggerAdHocFragment​(Long processInstanceId,
                                  String stage,
                                  String fragmentName,
                                  Object data)
                           throws CaseNotFoundException
        Triggers given by fragmentName adhoc element (such as task, milestone) within given process instance and stage
        Parameters:
        processInstanceId - unique process instance id
        stage - id or name of the stage there the task should be added
        fragmentName - name of the element that can be triggered
        data - optional data to be given when triggering the node
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDataToCaseFile

        void addDataToCaseFile​(String caseId,
                               String name,
                               Object value,
                               String... restrictedTo)
                        throws CaseNotFoundException
        Adds given named value into case file of given case.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        name - unique name for given value to be put into case file
        value - actual value to be added to case file
        restrictedTo - optional case roles that this data should be restricted to
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addDataToCaseFile

        void addDataToCaseFile​(String caseId,
                               Map<String,​Object> data,
                               String... restrictedTo)
                        throws CaseNotFoundException
        Adds complete map to case file of given case. Replaces any existing value that is registered under same name.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        data - key value representing data to be added to case file
        restrictedTo - optional case roles that this data should be restricted to
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • removeDataFromCaseFile

        void removeDataFromCaseFile​(String caseId,
                                    String name)
                             throws CaseNotFoundException
        Removes given variable (stored under name) from case file of given case.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        name - variable name that should be removed from case file
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • removeDataFromCaseFile

        void removeDataFromCaseFile​(String caseId,
                                    List<String> variableNames)
                             throws CaseNotFoundException
        Removes given variables (stored under variableNames) from case file of given case.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        variableNames - list of variables to be removed from the case file
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • assignToCaseRole

        void assignToCaseRole​(String caseId,
                              String role,
                              org.kie.api.task.model.OrganizationalEntity entity)
                       throws CaseNotFoundException
        Assigns given entity (user or group) to case role for a given case. Case roles can be used for user task assignments.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        role - name of the role entity should be assigned to
        entity - user or group to be assigned to given role
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
        IllegalArgumentException - thrown in case there no role found with given name or cardinality was exceeded
      • removeFromCaseRole

        void removeFromCaseRole​(String caseId,
                                String role,
                                org.kie.api.task.model.OrganizationalEntity entity)
                         throws CaseNotFoundException
        Removes given entity (user or group) from the case role for a given case.
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        role - name of the role entity should be assigned to
        entity - entity user or group to be assigned to given role
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • getCaseRoleAssignments

        Collection<CaseRoleInstance> getCaseRoleAssignments​(String caseId)
                                                     throws CaseNotFoundException
        Returns role assignments for given case
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        Returns:
        returns collection of all currently defined role assignments of the given case
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • getCaseComments

        Collection<CommentInstance> getCaseComments​(String caseId,
                                                    org.kie.api.runtime.query.QueryContext queryContext)
                                             throws CaseNotFoundException
        Returns all case comments sorted by date
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        Returns:
        returns all comments added to given case
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • getCaseComments

        Collection<CommentInstance> getCaseComments​(String caseId,
                                                    CommentSortBy sortBy,
                                                    org.kie.api.runtime.query.QueryContext queryContext)
                                             throws CaseNotFoundException
        Returns all case comments sorted with given sortBy
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        sortBy - defines how to sort comments
        Returns:
        sorted comments
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • addCaseComment

        String addCaseComment​(String caseId,
                              String author,
                              String comment,
                              String... restrictedTo)
                       throws CaseNotFoundException
        Adds new comment to the case
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        author - author of the comment
        comment - actual comment (text)
        restrictedTo - optional case roles that this data should be restricted to
        Returns:
        unique id of the comment that has been added
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • updateCaseComment

        void updateCaseComment​(String caseId,
                               String commentId,
                               String author,
                               String text,
                               String... restrictedTo)
                        throws CaseNotFoundException
        Updated given comment with entire text provided
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        commentId - unique id of the comment
        author - author of the comment
        text - updated text of the comment
        restrictedTo - optional case roles that this data should be restricted to
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • removeCaseComment

        void removeCaseComment​(String caseId,
                               String commentId)
                        throws CaseNotFoundException
        Removes given comment from the case comments list
        Parameters:
        caseId - unique case id in the format PREFIX-GENERATED_ID as described on startCase method
        commentId - unique id of the comment
        Throws:
        CaseNotFoundException - thrown in case case was not found with given id
      • newCaseFileInstance

        CaseFileInstance newCaseFileInstance​(String deploymentId,
                                             String caseDefinition,
                                             Map<String,​Object> data)
        Builds and returns new CaseFileInstance with given data. Not yet associated with any case
        Parameters:
        deploymentId - deployment that case belongs to
        caseDefinition - id of the case definition to be able to properly setup case file
        data - initial data for case file
        Returns:
        returns new instance (not associated with case) of CaseFileInstance populated with given data
      • newCaseFileInstanceWithRestrictions

        CaseFileInstance newCaseFileInstanceWithRestrictions​(String deploymentId,
                                                             String caseDefinition,
                                                             Map<String,​Object> data,
                                                             Map<String,​List<String>> accessRestrictions)
        Builds and returns new CaseFileInstance with given data. Not yet associated with any case
        Parameters:
        deploymentId - deployment that case belongs to
        caseDefinition - id of the case definition to be able to properly setup case file
        data - initial data for case file
        accessRestrictions - access restrictions to data that defines what case roles are allowed to add and manipulate given data
        Returns:
        returns new instance (not associated with case) of CaseFileInstance populated with given data
      • newCaseFileInstance

        CaseFileInstance newCaseFileInstance​(String deploymentId,
                                             String caseDefinition,
                                             Map<String,​Object> data,
                                             Map<String,​org.kie.api.task.model.OrganizationalEntity> rolesAssignment)
        Builds and returns new CaseFileInstance with given data and roles assignments. Not yet associated with any case
        Parameters:
        deploymentId - deployment that case belongs to
        caseDefinition - id of the case definition to be able to properly setup case file
        data - initial data for case file
        rolesAssignment - initial role assignment
        Returns:
        returns new instance (not associated with case) of CaseFileInstance populated with given data
      • newCaseFileInstanceWithRestrictions

        CaseFileInstance newCaseFileInstanceWithRestrictions​(String deploymentId,
                                                             String caseDefinition,
                                                             Map<String,​Object> data,
                                                             Map<String,​org.kie.api.task.model.OrganizationalEntity> rolesAssignment,
                                                             Map<String,​List<String>> accessRestrictions)
        Builds and returns new CaseFileInstance with given data and roles assignments. Not yet associated with any case
        Parameters:
        deploymentId - deployment that case belongs to
        caseDefinition - id of the case definition to be able to properly setup case file
        data - initial data for case file
        rolesAssignment - initial role assignment
        accessRestrictions - access restrictions to data that defines what case roles are allowed to add and manipulate given data
        Returns:
        returns new instance (not associated with case) of CaseFileInstance populated with given data
      • newHumanTaskSpec

        TaskSpecification newHumanTaskSpec​(String taskName,
                                           String description,
                                           String actorIds,
                                           String groupIds,
                                           Map<String,​Object> parameters)
        Returns new TaskSpecification describing user task so it can be created as dynamic task. All string based attributes support variable expressions (#{variable-name})
        Parameters:
        taskName - - mandatory name of the task
        description - - optional description of the task
        actorIds - - optional list (comma separated) of actors to be assigned
        groupIds - - optional list (comma separated) of groups to be assigned
        parameters - - optional parameters (task inputs)
        Returns:
      • newTaskSpec

        TaskSpecification newTaskSpec​(String nodeType,
                                      String nodeName,
                                      Map<String,​Object> parameters)
        Returns new TaskSpecification describing generic (work item based) task so it can be added as dynamic task.
        Parameters:
        nodeType - - type of a node (same as used for registering work item handler)
        nodeName - - name of the node to be assigned on task
        parameters - - optional parameters (task inputs)
        Returns:
      • newUser

        org.kie.api.task.model.User newUser​(String userId)
        Creates new user with given id;
        Parameters:
        userId - user id to be used when creating User instance
        Returns:
        new instance for userId
      • newGroup

        org.kie.api.task.model.Group newGroup​(String groupId)
        Creates new group with given id;
        Parameters:
        groupId - group id to be used when creating Group instance
        Returns:
        new instance for groupId