Package com.flowable.engage.conversation.api

Interface ConversationService

  • All Known Implementing Classes:
    ConversationServiceImpl
    public interface ConversationService
    The conversation service is the main API for the conversation and messaging functionality.
    Author:
    Micha Kiener, Filip Hrisafov, Anatolii Balakiriev

    • Method Detail

      • createConversationQuery

        ConversationQuery createConversationQuery()
        Creates a new conversation query as a builder where you can add predicates in order to query for conversations. If you search by the conversation id only you should better use findById(String) because it takes the cache into account.
        Returns:
        the conversation query builder

      • createConversationBuilder

        ConversationBuilder createConversationBuilder()
        Returns a conversation builder used to start new Conversation objects. Make sure to always explicitly set the sub type of the conversation as it is a mandatory information.
        Returns:
        the conversation builder

      • createConversationParticipantBuilder

        ConversationParticipantBuilder createConversationParticipantBuilder​(String conversationId)
        Creates a new participant builder to add or remove participants to / from a conversation with various extended options mainly on message visibility.
        Parameters:
        conversationId - the id of the conversation to manage participants through the builder
        Returns:
        a conversation participant builder

      • createConversationUserQuery

        ConversationUserQuery createConversationUserQuery()
        Creates a new user query to request user ids involved in a specific conversation (e.g. participants or all involved users, etc).
        Returns:
        the conversation query builder

      • createConversationStatusQuery

        ConversationStatusQuery createConversationStatusQuery()
        Creates a new conversation status query, that can be used to get the different unread statuses for a conversation.
        Returns:
        the conversation status query builder

      • exists

        boolean exists​(String conversationId)
        Returns:
        Checks if the given conversation exists.

      • unreadMessagesCount

        long unreadMessagesCount​(String userId,
                         String conversationId)
        The unread data count for the user with id userId in the conversation with id conversationId
        Parameters:
        userId - the id of the user for which the unread data count is needed
        conversationId - the id of the conversation for which the count is needed
        Returns:
        the number of unread messages for the given user in the given conversation

      • setReference

        Conversation setReference​(String conversationId,
                          String referenceId,
                          String referenceType,
                          String referenceDefinitionId)
        Set the optional reference for a conversation like a case or process where the conversation is liked to.
        Parameters:
        conversationId - the id of the conversation to set its reference
        referenceId - the id of the referenced work item
        referenceType - the type of the referenced work item
        referenceDefinitionId - the optional definition id of the referenced work item
        Returns:
        the modified conversation retrieved from the database

      • updateName

        Conversation updateName​(String conversationId,
                        String name)
        Updates the conversation name (title) for the given conversation.
        Parameters:
        conversationId - the id of the conversation to change its name
        name - title of the conversation, it can be also be null or empty
        Returns:
        modified conversation retrieved from database

      • updateDescription

        Conversation updateDescription​(String conversationId,
                               String description)
        Updates the conversation description for the given conversation.
        Parameters:
        conversationId - the id of the conversation to change its description
        description - the description of the conversation, it can be also be null or empty
        Returns:
        modified conversation retrieved from database

      • updateAvatarId

        Conversation updateAvatarId​(String conversationId,
                            String avatarId)
        Updates the conversation avatar id for the given conversation.
        Parameters:
        conversationId - the id of the conversation to change its description
        avatarId - the avatar id of the conversation, it can be also be null or empty
        Returns:
        modified conversation retrieved from database

      • archive

        void archive​(String conversationId)
        Archives the conversation with the given id. You can't post anything to an archived conversation, the only thing left to do is re-opening it.
        Parameters:
        conversationId - the id of the conversation to be archived

      • reopen

        void reopen​(String conversationId)
        Reopens the archived conversation with the given id.
        Parameters:
        conversationId - the id of the conversation to be reopened

      • addParticipants

        void addParticipants​(String conversationId,
                     Collection<String> participants)
        Adds the given participants to the conversation with the given id
        Parameters:
        conversationId - the id of the conversation to which the participants needs to be added
        participants - the ids of the participants that need to be added

      • removeParticipants

        void removeParticipants​(String conversationId,
                        Collection<String> participants)
        Removes the given participants to the conversation with the given id
        Parameters:
        conversationId - the id of the conversation from which the participants need to be removed
        participants - the ids of the participants that need to be removed

      • assignToGroup

        void assignToGroup​(String conversationId,
                   String assignedGroupId)
        Assigns the conversation to a group of users (set the assignedGroupId property).
        Parameters:
        conversationId - the id of the conversation to be assigned to a group
        assignedGroupId - the id of the group to assign the conversation to

      • removeAssignedGroup

        void removeAssignedGroup​(String conversationId)
        Removes an assigned group from a conversation (sets the assignedGroupId proeprty to null).
        Parameters:
        conversationId - the id of the conversation to remove the assgined group from

      • assignToUser

        void assignToUser​(String conversationId,
                  String assignedUserId)
        Assigns the conversation to a user (set the assigneeId property).
        Parameters:
        conversationId - the id of the conversation to be assigned to a user
        assignedUserId - the id of the user to assign the conversation to

      • removeAssignedUser

        void removeAssignedUser​(String conversationId)
        Removes an assigned user from a conversation.
        Parameters:
        conversationId - the id of the conversatoin to remove the assigned user (set the assigneeId ot null).

      • changeOwner

        void changeOwner​(String conversationId,
                 String ownerUserId)
        Changes an owner of the conversation.
        Parameters:
        conversationId - the id of the conversation to change an owner in
        ownerUserId - the id of the user to become a new owner of this conversation

      • userTyping

        void userTyping​(String conversationId,
                String userId)
        Information that a user with id userId is typing in the conversation with id conversationId
        Parameters:
        conversationId - the id of the conversation in which the user is typing
        userId - the id of the user that is doing the typing

      • deleteConversation

        void deleteConversation​(String conversationId)
        Deletes a conversation and all related data (messages, unread counts, etc.).
        Parameters:
        conversationId - the id of the conversation which needs to be deleted.

      • addTags

        void addTags​(String conversationId,
             Collection<String> tags)
        Tag the conversation with provided tags
        Parameters:
        conversationId - the id of the conversation to which the tags need to be added
        tags - the tags that should be added to the conversation

      • addTag

        void addTag​(String conversationId,
            String tag)
        Adds the provided tag to the specified conversation.
        Parameters:
        conversationId - the id of the conversation where the tag should be added
        tag - the tag to be added, must not be null or empty

      • removeTags

        void removeTags​(String conversationId,
                Collection<String> tags)
        Remove the provided tags from the conversation
        Parameters:
        conversationId - the id of the conversation from which tags need to be removed
        tags - the tags that need to be removed from the conversation

      • removeTag

        void removeTag​(String conversationId,
               String tag)
        Removes the provided tag from the specified conversation, if it exists.
        Parameters:
        conversationId - the id of the conversatoin to remove the provided tag from
        tag - the tag to be removed

      • countConversationsWithLastMessageBetween

        long countConversationsWithLastMessageBetween​(Date from,
                                              Date until,
                                              boolean includePrivateMessages,
                                              boolean includeStickMessages)
        TODO: this might be not the right service Number of conversations which received new messages within a given time frame. If you are only interested in general messages (neither private nor sticky messages) it's better to use ConversationQuery and build a query with ConversationQuery.lastMessageAfter(Date) or ConversationQuery.lastMessageBefore(Date) This method is needed if private or sticky messages are also to be taken account, because Conversation.getLastMessageTime() will not be updated for private or sticky messages.
        Parameters:
        from - start of the time frame (optional)
        until - end of the time frame (optional)
        includePrivateMessages - true if private messages should also be considered
        includeStickMessages - true if sticky messages should also be considered
        Returns:
        count of conversations with new messages within given time frame

      • findConversationsWithLastMessageBetween

        List<Conversation> findConversationsWithLastMessageBetween​(Date from,
                                                           Date until,
                                                           boolean includePrivateMessages,
                                                           boolean includeStickMessages)
        TODO: this might be not the right service Finds conversations which received new messages within a given time frame. If you are only interested in general messages (neither private nor sticky messages) it's better to use ConversationQuery and build a query with ConversationQuery.lastMessageAfter(Date) or ConversationQuery.lastMessageBefore(Date) This method is needed if private or sticky messages are also to be taken account, because Conversation.getLastMessageTime() will not be updated for private or sticky messages.
        Parameters:
        from - start of the time frame (optional)
        until - end of the time frame (optional)
        includePrivateMessages - true if private messages should also be considered
        includeStickMessages - true if sticky messages should also be considered
        Returns:
        list of conversations with new messages withing given time frame

      • findByIdWithIdentityLinks

        Conversation findByIdWithIdentityLinks​(String conversationId)
        Finds the conversation with the given id, with the identity links already prefetched.

      • findByIdWithIdentityLinksAndVariables

        Conversation findByIdWithIdentityLinksAndVariables​(String conversationId)
        Finds the conversation with the given id, with the identity links and variables already prefetched.

      • findById

        Conversation findById​(String conversationId)
        Finds the conversation with the given id. If you are interested in the conversation owner, participants etc. you must call findByIdWithIdentityLinks(String).
        Parameters:
        conversationId - the conversation id
        Returns:
        the conversation without any identity links

      • linkConversationWithUserAccount

        void linkConversationWithUserAccount​(String conversationId,
                                     String userAccountId)
        Set the id of the user account that is linked with this conversation. If a conversation is already linked with a user account then this operation will fail. If a conversation needs to have it's user account changed then call removeUserAccountFromConversation(String) first.
        Parameters:
        conversationId - the id of the conversation that should be updated
        userAccountId - the id of the user account that should be linked with the conversation

      • removeUserAccountFromConversation

        void removeUserAccountFromConversation​(String conversationId)
        Remove the id of the user account from this conversation. If the conversation is not linked with a user already then this method does nothing.
        Parameters:
        conversationId - the id of the conversation that should be updated

      • getVariables

        Map<String,​Object> getVariables​(String conversationId)
        All variables visible from the given conversation.
        Parameters:
        conversationId - id of the conversation, cannot be null.
        Returns:
        the variables or an empty map if no such variables are found.
        Throws:
        FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

      • getVariable

        Object getVariable​(String conversationId,
                   String variableName)
        The variable value. Returns null when no variable value is found with the given name or when the value is set to null.
        Parameters:
        conversationId - id of conversation, cannot be null.
        variableName - name of variable, cannot be null.
        Returns:
        the variable value or null if the variable is undefined or the value of the variable is null.
        Throws:
        FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

      • setVariable

        void setVariable​(String conversationId,
                 String variableName,
                 Object value)
        Update or create a variable for a conversation.
        Parameters:
        conversationId - id of conversation to set variable in, cannot be null.
        variableName - name of variable to set, cannot be null.
        value - value to set. When null is passed, the variable is not removed, only it's value will be set to null.
        Throws:
        FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

      • setVariables

        void setVariables​(String conversationId,
                  Map<String,​Object> variables)
        Update or create given variables for a conversation.
        Parameters:
        conversationId - id of the conversation, cannot be null.
        variables - map containing name (key) and value of variables, can be null.
        Throws:
        FlowableObjectNotFoundException - when no conversation is found for the given conversationId.

      • removeVariable

        void removeVariable​(String conversationId,
                    String variableName)
        Removes a variable for a conversation.
        Parameters:
        conversationId - id of conversation to remove variable in.
        variableName - name of variable to remove.

      • removeVariables

        void removeVariables​(String conversationId,
                     Collection<String> variableNames)
        Removes variables for a conversation.
        Parameters:
        conversationId - id of conversation to remove variable in.
        variableNames - collection containing name of variables to remove.