Interface IWorkItem

    • Method Detail

      • getProjectId

        java.lang.String getProjectId()
        Specified by:
        getProjectId in interface IUniqueObject
        Returns:
        The project id without resolving the Work Item.
        Since:
        3.5.3
      • getModule

        IModule getModule()
        Since:
        3.2
      • getExternalLinkingModules

        IPObjectList getExternalLinkingModules()
        Returns the list of Documents that this Work Item is referenced in. The list of results is sorted by modification time. (The most recently modified is first.)
        Since:
        3.5.3
      • getOutlineNumber

        java.lang.String getOutlineNumber()
        Since:
        3.4
      • getTitle

        java.lang.String getTitle()
      • setTitle

        void setTitle​(java.lang.String title)
      • getDescription

        Text getDescription()
      • renderDescription

        @Deprecated
        Text renderDescription​(Text description,
                               IWorkItem.RenderingOptions options)
        Deprecated.
        use e.g. WorkItemFields.description(). It is not rendered the same way. Use other functionality from the Rendering API to render as required.
        Renders Text as the Description. Doesn't convert \n characters to <br>
        Parameters:
        description -
        options - or null to use defaults.
        Returns:
        Rendered Description content.
        Since:
        3.5.0
      • transformDescriptionForUI

        @Deprecated
        Text transformDescriptionForUI​(Text description)
        Deprecated.
        use e.g. WorkItemFields.description(). It is not rendered the same way. Use other functionality from the Rendering API to render as required.
        Since:
        3.2
      • setDescription

        void setDescription​(Text description)
      • addCategory

        boolean addCategory​(ICategory category)
        Parameters:
        category -
        Returns:
        true, if the categories were changed (false if it already had this category).
      • removeCategory

        boolean removeCategory​(ICategory category)
        Parameters:
        category -
        Returns:
        true if category was removed, false if did not contain this category.
      • setTimePoint

        void setTimePoint​(ITimePoint newTimePoint)
      • getApprovals

        java.util.Collection getApprovals()
        Returns:
        A Collection of IApprovalStruct, containing all approvals.
      • removeApprovee

        void removeApprovee​(IUser approvee)
        Removes the user from the approvees collection. It has no effect if the user is not there.
        Parameters:
        approvee -
      • addAprovee

        void addAprovee​(IUser approvee)
        Adds the user to the approval collection with the default status. Has no effect, if the user is already there.
        Parameters:
        approvee -
      • setApprovalStatus

        void setApprovalStatus​(IUser approvee,
                               IApprovalStatusOpt status)
        Sets the approval status for the given user. The user is added if they are not yet in the approvees collection.
        Parameters:
        approvee -
        status -
      • getLinkedRevisionsDirect

        @NotNull
        IPObjectList<IRevision> getLinkedRevisionsDirect()
        Returns:
        The immutable IRevision collection linked from this Work Item. No querying is required. Use addLinkedRevision
      • getLinkedRevisionsDerived

        @NotNull
        IPObjectList<IRevision> getLinkedRevisionsDerived()
        Returns:
        The immutable IRevision collection that reference this work item. Obtained using a query.
      • addLinkedRevision

        boolean addLinkedRevision​(java.lang.String repositoryName,
                                  java.lang.String revision)
        Adds the given revision to revisions that are directly linked. Does nothing if the revision is already in the linked revisions set.
        Parameters:
        repositoryName - if null then the default repository will be used.
        revision -
        Returns:
        true if the revision was added, false if it was already there.
        Since:
        3.5.1
      • removeLinkedRevision

        boolean removeLinkedRevision​(java.lang.String repositoryName,
                                     java.lang.String revision)
        Removes the given revision from the link set. Does nothing if the revision is not in the set.
        Parameters:
        repositoryName - if null then the default repository will be used.
        revision -
        Returns:
        true if the revision was removed, false if not present in the set.
        Since:
        3.5.1
      • addLinkedRevision

        boolean addLinkedRevision​(IRevision revision)
        Adds the revision to revisions that are directly linked. Does nothing if the revision is already in the linked revisions set.
        Parameters:
        revision -
        Returns:
        true if the revision was added, false if it was already there.
      • removeLinkedRevision

        boolean removeLinkedRevision​(IRevision revision)
        Removes the given revision from the link set. Does nothing if the revision is not in the set.
        Parameters:
        revision -
        Returns:
        true if the revision was removed, false if not present in the set.
      • getAssignees

        @NotNull
        IPObjectList getAssignees()
        Returns:
        The list of users, that are assignees of this Work Item.
      • addAssignee

        boolean addAssignee​(@NotNull
                            IUser participant)
        Adds a user to the list of assignees.
        Parameters:
        participant - the IUser to add to the list of assignees.
        Returns:
        true, if the assignee was added (false if Work Item already has an assignee).
      • removeAssignee

        boolean removeAssignee​(@NotNull
                               IUser participant)
        Removes a user from the list of assignees.
        Parameters:
        participant - the IUser to remove from the list of assignees
        Returns:
        true if assignee was removed, false if Work Item doesn't contain a participant.
      • getAllowedAssignees

        @NotNull
        IPObjectList getAllowedAssignees()
        Allowed assignees.

        Allowed assignee is a user with the global "assignable" role or the context "project_assignable" role .

        Returns:
        IPObjectList of IUsers sorted according to IUser.getName() (not null)
      • getAllowedApprovers

        @NotNull
        IPObjectList getAllowedApprovers()
        Allowed approvers.

        Allowed approver is a user with the global "approver" role or the context "project_approver" role .

        Returns:
        IPObjectList of IUsers sorted according to IUser.getName() (not null)
        Since:
        3.5.3
      • doAutoAssign

        void doAutoAssign()
        Performs the auto-assignment of this item, based on the relevant configuration. The changes are not automatically saved.
      • doAutoSuspect

        void doAutoSuspect()
        Performs an autosuspect of this item.
      • doSuspectDerivedItems

        void doSuspectDerivedItems()
        Set suspect=true to links from derived items.
        Since:
        3.3
      • getAuthor

        @Nullable
        IUser getAuthor()
        Returns this Work Item author. The author field can not be changed, therefore there is no set method for this field.
      • createComment

        @NotNull
        IComment createComment​(Text text)
        Creates a (temporary) comment object, that can be manipulated by the client. However, the comment is not persisted until it's explicitly saved.

        The fields workItem, project, author, date are pre-filled with their values.

        Parameters:
        text - The text, can not be null.
        Returns:
        The Comment object with the necessary fields filled in.
      • createComment

        @NotNull
        IComment createComment​(@NotNull
                               Text text,
                               @Nullable
                               java.lang.String title,
                               @Nullable
                               java.util.List visibleTo)
        Creates a (temporary) comment object, that can be manipulated by the client. However, the comment is not persisted until it's explicitly saved.

        The fields workItem, project, author, date are pre-filled with their values.

        Parameters:
        text - Text, can not be null.
        title - Title, can be null.
        visibleTo - VisibleTo, can be null.
        Returns:
        the Comment object, with the necessary fields filled in.
        Since:
        3.1.1
      • createWorkRecord

        IWorkRecord createWorkRecord​(IUser user,
                                     DateOnly date,
                                     DurationTime timeSpent)
        Creates a (temporary) work record object, that can be manipulated by the client. However, the work record is not persisted until it's explicitly saved.

        The fields workItem and project are pre-filled.

        Returns:
        The temporary IWorkRecode created.
      • createWorkRecord

        IWorkRecord createWorkRecord​(IUser user,
                                     DateOnly date,
                                     IWorkRecordTypeOpt type,
                                     DurationTime timeSpent,
                                     java.lang.String comment)
        Creates a (temporary) work record object, that can be manipulated by the client. However, the work record is not persisted until it's explicitly saved.

        The fields workItem and project are pre-filled.

        Returns:
        The temporary IWorkRecode created.
        Since:
        3.3
      • deleteWorkRecord

        void deleteWorkRecord​(IWorkRecord workRecord)
        Removes and deletes the work record from this Work Item.
        Parameters:
        workRecord -
      • createAttachment

        @NotNull
        IAttachment createAttachment​(@NotNull
                                     java.lang.String fileName,
                                     @Nullable
                                     java.lang.String title,
                                     @Nullable
                                     java.io.InputStream data)
        Creates a (temporary) attachment object, that can be manipulated by the client. However, the attachment is not persisted until it's explicitly saved.

        The author field is automatically pre-filled with the current user.

        Specified by:
        createAttachment in interface IWithAttachments<IAttachment>
        Parameters:
        fileName - The file name, can not be null.
        title - The title can be null. If so, the file name is used instead.
        data - The content input stream, can not be null
        Returns:
        The temporary IAttachement created.
      • getAttachment

        IAttachment getAttachment​(@NotNull
                                  java.lang.String id)
        Returns the attachment with the given Id for this Work Item.
        Specified by:
        getAttachment in interface IWithAttachments<IAttachment>
        Parameters:
        Id - The Id of the attachment to get.
        Returns:
        The IAttachement with the specified Id.
      • getAttachmentByFileName

        IAttachment getAttachmentByFileName​(java.lang.String fileName)
      • getAttachmentsContainedByText

        IPObjectList<IAttachmentBase> getAttachmentsContainedByText​(Text text,
                                                                    boolean includeDocumentAttachments)
        Returns the attachments of this Work Item that are referenced by a certain field; this includes images and diagram data attachments.
        Since:
        3.7.2
      • getLinkedWorkItemsStructsBack

        java.util.Collection getLinkedWorkItemsStructsBack()
        Returns the collection of ILinkedWorkItemStruct structures that reference this item. The result is obtained by querying and involves resolving all items that link to this item.
      • getLinkedWorkItemsStructsDirect

        java.util.List getLinkedWorkItemsStructsDirect​(java.lang.String sort)
        The same as getLinkedWorkItemsStructsDirect() but with possibility to have the links sorted by a Work Item sort string. If a sort string is specified, the result is obtained by querying.
        Parameters:
        sort -
      • getLinkedWorkItemsStructsBack

        java.util.List getLinkedWorkItemsStructsBack​(java.lang.String sort)
        The same as getLinkedWorkItemsStructsBack() but with possibility to have the links sorted by Work Item a sort string.
        Parameters:
        sort -
      • addExternallyLinkedItem

        boolean addExternallyLinkedItem​(java.net.URI workItemURI,
                                        IEnumOption role)
        Adds a given link. Does nothing if such a link already exists.
        Parameters:
        workItemURI - The external link (not null).
        role - The link's role (not null).
        Returns:
        true if a link was added.
        Since:
        3.5.0
      • removeExternallyLinkedItem

        boolean removeExternallyLinkedItem​(java.net.URI workItemURI,
                                           IEnumOption role)
        Removes a given link. Does nothing if such a link does not exist.
        Parameters:
        workItemURI - The external link (not null).
        role - The link's role (not null).
        Returns:
        true if a link was removed.
        Since:
        3.5.0
      • isAutoSuspectOn

        boolean isAutoSuspectOn()
        Returns true, if modifications of this item should, by default, result in setting the suspect flag. This is a hint for the UI, that renders the default value.
      • hasSuspectLinks

        boolean hasSuspectLinks()
      • addLinkedItem

        boolean addLinkedItem​(IWorkItem item,
                              ILinkRoleOpt role,
                              java.lang.String revision,
                              boolean suspect)
        Adds the link. If the link already exists, it will NOT add another one. Links are the same, when target item and link role are equal. The link is also not created when the given item is same as this item.
        Parameters:
        item - target of the link; the eventual revision of the object will be ignored.
        role -
        revision - null to point to the HEAD.
        suspect -
        Returns:
        true if a link was added.
      • removeLinkedItem

        boolean removeLinkedItem​(IWorkItem item,
                                 IEnumOption role)
        Removes the link. Does nothing, if there is no such link.
        Parameters:
        item -
        role -
        Returns:
        true if the link was removed.
      • getLinkedWorkItems

        IPObjectList getLinkedWorkItems()
        Returns all Work Items linked with and that link this Work Item. The returned collection is a union of collections returned from the getLinkedWorkItemsDirect() and getLinkedWorkItemsBack() methods.
        Returns:
        An immutable List of IWorkItem linked with this item in both directions.
      • getLinkedWorkItemsBack

        IPObjectList getLinkedWorkItemsBack()
        Returns:
        The immutable IWorkItem collection that reference this item. The result is obtained by querying.
      • traverseLinkedWorkitems

        boolean traverseLinkedWorkitems​(java.util.Set treeLinked,
                                        java.util.Set linkTypes,
                                        java.util.Set backLinkTypes,
                                        IWorkItem.ITerminalCondition condition)
        Traverses, depth first, the tree of items linked (both backward and forward) with this item then adds all touched items to the treeLinked return parameter and terminates either by traversing all of them or on a given condition.
        Parameters:
        treeLinked - The set that contains the result. Either a new HashSet() can be passed in, or the existing modifiable set with Work Items to ignore in the traversal. If the caller is not interested in this result, then passing a null value will result in the set's auto creation.
        linkTypes - String Ids of forward link roles for traversal. Passing in null means to traverse all roles.
        backLinkTypes - String Ids of backward link roles for traversal. Passing in null means to traverse all roles.
        condition - The termination condition to be evaluated on every item. Can be null and constant false will be used in such a case. Returning true for some Work Item means that the traversal will not continue through this item. However, it will terminate just a given tree branch, not the complete traversal.
        Returns:
        true if the traversal was stopped by the condition, false if the whole tree was processed.
      • getHyperlinks

        java.util.Collection getHyperlinks()
        Returns:
        Collection of IHyperlinkStruct.
      • addHyperlink

        boolean addHyperlink​(java.lang.String url,
                             IEnumOption role)
      • removeHyperlink

        boolean removeHyperlink​(java.lang.String url)
      • getPlanningConstraints

        ITypedList getPlanningConstraints()
      • addPlanningConstraint

        boolean addPlanningConstraint​(java.util.Date date,
                                      IPlanningConstraintOpt constraint)
        Adds the new planning constraint. Does nothing if such a constraint already exists or would conflict with another one.
        Parameters:
        date -
        constraint -
        Returns:
        true if modification was done, false otherwise.
      • removePlanningConstraint

        boolean removePlanningConstraint​(java.util.Date date,
                                         IPlanningConstraintOpt constraint)
        Removes the given planning constraint. Does nothing, if no such constraint exists.
        Parameters:
        date -
        constraint -
        Returns:
        true if modification was done. Otherwise false.
      • getPlaningConstraintDate

        java.util.Date getPlaningConstraintDate​(java.lang.String constraintId)
        Returns the Date of a planning constraint.
        Parameters:
        constraintId - The Id of the constraint to return.
        Returns:
        Date of the given planning constraint, null if the constraint does not exist.
      • getDueDate

        DateOnly getDueDate()
        Returns the due date of this Work Item.
        Returns:
        The due date for this Work Item.
      • setDueDate

        void setDueDate​(DateOnly dueDate)
        Sets the due data for this Work Item.
        Parameters:
        dueDate - The Date to set as the due date.
      • getInitialEstimate

        DurationTime getInitialEstimate()
        Returns the initial estimate of this Work Item.
        Returns:
        The initial estimate for this Work Item.
      • setInitialEstimate

        void setInitialEstimate​(DurationTime initialEstimate)
        Sets the initial estimate for this Work Item.
      • getTimeSpent

        DurationTime getTimeSpent()
        Returns:
        The time spent on this Work Item.
      • setTimeSpent

        void setTimeSpent​(DurationTime timeSpent)
        Sets The time spent on this Work Item.
      • getRemainingEstimate

        DurationTime getRemainingEstimate()
        Returns:
        The remaining estimate to complete this Work Item.
      • setRemainingEstimate

        void setRemainingEstimate​(DurationTime remainingEstimate)
        Sets the new estimate to complete this Work Item
      • getCreated

        java.util.Date getCreated()
        Returns:
        The date the Work Item was created.
      • getUpdated

        java.util.Date getUpdated()
        Returns:
        The date of the last update to this Work Item.
      • getPlannedStart

        java.util.Date getPlannedStart()
        Returns:
        The date of the planned start of an activity for this Work Item.
      • setPlannedStart

        void setPlannedStart​(java.util.Date plannedStart)
        Sets the date of the planned start of an activity for this Work Item.
      • getPlannedEnd

        java.util.Date getPlannedEnd()
        Returns:
        the date of the planned end of an activity for this Work Item.
      • setPlannedEnd

        void setPlannedEnd​(java.util.Date plannedEnd)
        Sets the date of the planned end of an activity for this Work Item.
      • getPlannedIn

        @NotNull
        java.util.List<IPlan> getPlannedIn()
        Returns:
        The list of Plans that contain this Work Item.
        Since:
        3.8.0
      • getResolvedOn

        java.util.Date getResolvedOn()
        Returns:
        The date that the Work Item was resolved on.
      • createPriorityOpt

        IPriorityOpt createPriorityOpt​(float value)
        Creates a new Priority Option for the given value. Just a short form of getProject().getPriorityEnum().wrapOption(value).
        Parameters:
        value - - priority level
        Returns:
        The IPriorityOpt with the given value.
        See Also:
        IEnumeration.wrapOption(String)
      • getClosestStandardOpt

        IPriorityOpt getClosestStandardOpt​(IPriorityOpt option)
        Returns the closest standard option for the given option. The shortcut for this.getProject().getPriorityEnum().getClosestStandardOpt(option.getFloat()).
        Parameters:
        option - the IPriorityOpt to find the closest standard option for
        Returns:
        the standard IPriorityOpt
        See Also:
        IPriorityEnumeration.getClosestStandardOpt(float)
      • getWorkRecords

        IPObjectList getWorkRecords()
        Returns the list of work records for this Work Item.
        Returns:
        The List of IWorkRecords for this Work Item.
      • getLocation

        ILocation getLocation()
        Returns the location of this Work Item in the repository.
        Returns:
        The ILocation in the repository that this item came from.
      • delete

        void delete()
        Deletes this Work Item (including comments, work records and attachments) and removes all its files from the repository.
        Since:
        3.2.0
      • getLocalizedTitle

        java.lang.String getLocalizedTitle​(java.lang.String language)
        Returns the localized title or the normal title if the localized title is not defined or empty.
        Parameters:
        language - The language Id or null for the default language. (In which case this method acts as getTitle()).
        Returns:
        localized title (can be null).
        Since:
        3.6.1
        See Also:
        ILanguageDefinition
      • getLocalizedDescription

        Text getLocalizedDescription​(java.lang.String language)
        Returns the localized description or the normal description if the localized description is not defined or empty.
        Parameters:
        language - The language Id or null for default language (in which case this method acts as getDescription()).
        Returns:
        localized description (can be null).
        Since:
        3.6.1
        See Also:
        ILanguageDefinition
      • setLocalizedTitle

        void setLocalizedTitle​(java.lang.String language,
                               java.lang.String title)
        Sets the localized title.
        Parameters:
        language - The language Id or null for the default language (in which case this method acts as setTitle(String)).
        title - The title (can be null).
        Throws:
        java.lang.IllegalArgumentException - if the language is not defined.
        Since:
        3.6.1
        See Also:
        ILanguageDefinition
      • setLocalizedDescription

        void setLocalizedDescription​(java.lang.String language,
                                     Text description)
        Sets the localized description.
        Parameters:
        language - The language Id or null for the default language (in which case this method acts as setDescription(Text))
        description - The description (can be null).
        Throws:
        java.lang.IllegalArgumentException - if a language is not defined.
        Since:
        3.6.1
        See Also:
        ILanguageDefinition
      • getPreviousStatus

        @Nullable
        @Deprecated
        IStatusOpt getPreviousStatus()
        Deprecated.
        The previous status is not used internally anymore and should not be used.
        Returns:
        The previous status of the Work Item.
      • getTestCase

        @NotNull
        ITestCase getTestCase()
        Returns The test case specific view of this Work Item.
        Since:
        3.9.2