Package com.polarion.alm.tracker.model

Interface IWorkItem

All Superinterfaces:
IAdaptable, IChangeListener, IHasCustomValues, IHasValues, IPObject, IUniqueObject, IWithAttachments<IAttachment>, IWithLinkedOslcResources, IWorkflowObject
public interface IWorkItem extends IWorkflowObject, IWithAttachments<IAttachment>, IWithLinkedOslcResources
The typed interface for Work Items.
Author:
POLARION SOFTWARE

  • Field Details

  • Method Details

    • getProjectId

      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

      String getOutlineNumber()
      Since:
      3.4

    • getId

      String getId()
      Specified by:
      getId in interface IUniqueObject

    • getTitle

      String getTitle()

    • setTitle

      void setTitle(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)

    • getResolution

      IResolutionOpt getResolution()

    • setResolution

      void setResolution(IResolutionOpt newResolution)

    • getCategories

      IPObjectList getCategories()

    • 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.

    • getTimePoint

      ITimePoint getTimePoint()

    • setTimePoint

      void setTimePoint(ITimePoint newTimePoint)

    • getApprovals

      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 -

    • addApprovalFor

      @NotNull IApprovalBuilder addApprovalFor(@NotNull IUser approvee)
      Returns a builder that allows for the addition of a user to the collection of approvals, with a status selected by IApprovalBuilder.withStatus(String).
      Parameters:
      approvee -
      Since:
      3.18.2

    • 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 -

    • getLinkedRevisions

      @NotNull IPObjectList<IRevision> getLinkedRevisions()
      Returns:
      The immutable IRevision collection that are either referenced by this item or reference this item.

      The resulting collection is the union of the results of getLinkedRevisionsDirect() and getLinkedRevisionsDerived().

    • 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(String repositoryName, 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(String repositoryName, 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.

    • getComments

      @NotNull IPObjectList<IComment> getComments()
      Shortcut for getComments(true).

    • getComments

      @NotNull IPObjectList<IComment> getComments(boolean includeResolved)
      Optionally also includes resolved comments. Sorts comments by creation time.
      Since:
      3.7.1
      See Also:

    • getComments

      @NotNull IPObjectList<IComment> getComments(boolean includeResolved, @NotNull ICommentBase.SortBy sortBy)
      Optionally also includes resolved comments. Sorts comments according to a parameter.
      Since:
      3.7.3
      See Also:

    • getRootComments

      @NotNull IPObjectList<IComment> getRootComments()
      Shortcut for getRootComments(true).
      Since:
      3.1.1
      See Also:

    • getRootComments

      @NotNull IPObjectList<IComment> getRootComments(boolean includeResolved)
      Returns the root comments of this Work Item. Optionally includes resolved comments.
      Returns:
      root IComments (not null)
      Since:
      3.7.1
      See Also:

    • 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 String title, @Nullable 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, 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 -

    • getAttachments

      @NotNull IPObjectList getAttachments()
      Description copied from interface: IWithAttachments
      Returns all attachments of this object.
      Specified by:
      getAttachments in interface IWithAttachments<IAttachment>
      Returns:
      attachments (never null)

    • createAttachment

      @NotNull IAttachment createAttachment(@NotNull String fileName, @Nullable String title, @Nullable 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 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(String fileName)

    • getAttachmentsContainedByDescription

      @NotNull IPObjectList<IAttachmentBase> getAttachmentsContainedByDescription()
      Returns the attachments of this Work Item that are referenced by the description; this includes images and diagram data attachments.
      Returns:
      list of IAttachmentBase
      Since:
      3.3.1
      See Also:

    • getAttachmentsContainedByText

      @NotNull IPObjectList<IAttachmentBase> getAttachmentsContainedByText(@Nullable 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

    • getAllAttachmentsContainedByDescription

      @NotNull IPObjectList<IAttachmentBase> getAllAttachmentsContainedByDescription()
      Returns all attachments that are referenced by the description; this includes images and diagram data attachments. These attachments can be owned by the containing document.
      Returns:
      list of IAttachmentBase
      Since:
      3.7.0
      See Also:

    • getLinkedWorkItemsStructsDirect

      @NotNull Collection<ILinkedWorkItemStruct> getLinkedWorkItemsStructsDirect()
      Returns the collection of ILinkedWorkItemStruct structures contained in this item.

    • getLinkedWorkItemsStructsBack

      @NotNull Collection<ILinkedWorkItemStruct> 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

      @NotNull List<ILinkedWorkItemStruct> getLinkedWorkItemsStructsDirect(@Nullable 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.

    • getLinkedWorkItemsStructsBack

      @NotNull List<ILinkedWorkItemStruct> getLinkedWorkItemsStructsBack(@Nullable String sort)
      The same as getLinkedWorkItemsStructsBack() but with possibility to have the links sorted by Work Item a sort string.

    • getExternallyLinkedWorkItemsStructs

      List<IExternallyLinkedWorkItemStruct> getExternallyLinkedWorkItemsStructs()
      All external links.

      Returns data even if ITrackerService.isExternalLinkingEnabled(com.polarion.subterra.base.data.identification.IContextId) is false.

      Returns:
      Externally linked Work Items (not null).
      Since:
      3.5.0
      See Also:

    • getExternallyLinkedWorkItemsStructsDirect

      List<IExternallyLinkedWorkItemStruct> getExternallyLinkedWorkItemsStructsDirect()
      All direct external links.

      Returns data even if ITrackerService.isExternalLinkingEnabled(com.polarion.subterra.base.data.identification.IContextId) is false.

      Returns:
      Externally linked Work Items (not null).
      Since:
      3.5.0

    • addExternallyLinkedItem

      boolean addExternallyLinkedItem(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(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, 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

      @NotNull IPObjectList<IWorkItem> 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.

    • getLinkedWorkItemsDirect

      @NotNull IPObjectList<IWorkItem> getLinkedWorkItemsDirect()
      Returns:
      The immutable IWorkItem collection contained in the object, no querying is required.
      See Also:

    • getLinkedWorkItemsBack

      @NotNull IPObjectList<IWorkItem> getLinkedWorkItemsBack()
      Returns:
      The immutable IWorkItem collection that reference this item. The result is obtained by querying.

    • traverseLinkedWorkitems

      boolean traverseLinkedWorkitems(Set treeLinked, Set linkTypes, 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

      Collection getHyperlinks()
      Returns:
      Collection of IHyperlinkStruct.

    • addHyperlink

      boolean addHyperlink(String url, IEnumOption role)

    • removeHyperlink

      boolean removeHyperlink(String url)

    • getPlanningConstraints

      ITypedList getPlanningConstraints()

    • addPlanningConstraint

      boolean addPlanningConstraint(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(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

      Date getPlaningConstraintDate(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

      Date getCreated()
      Returns:
      The date the Work Item was created.

    • getUpdated

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

    • getPlannedStart

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

    • setPlannedStart

      void setPlannedStart(Date plannedStart)
      Sets the date of the planned start of an activity for this Work Item.

    • getPlannedEnd

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

    • setPlannedEnd

      void setPlannedEnd(Date plannedEnd)
      Sets the date of the planned end of an activity for this Work Item.

    • getPlannedIn

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

    • getResolvedOn

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

    • isVotingEnabled

      boolean isVotingEnabled()
      Shortcut for IVotingManager.isVotingEnabled(IWorkItem)

    • getVotesCount

      int getVotesCount()
      Shortcut for IVotingManager.getVotesCount(IWorkItem)

    • getVotes

      IPObjectList getVotes()
      Shortcut for IVotingManager.getVotes(IWorkItem)

    • getWatchingUsers

      IPObjectList getWatchingUsers()

    • getPriority

      IPriorityOpt getPriority()

    • setPriority

      void setPriority(IPriorityOpt option)

    • 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:

    • 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:

    • getSeverity

      ISeverityOpt getSeverity()

    • setSeverity

      void setSeverity(ISeverityOpt option)

    • 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

      String getLocalizedTitle(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:

    • getLocalizedDescription

      Text getLocalizedDescription(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:

    • setLocalizedTitle

      void setLocalizedTitle(String language, 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:
      IllegalArgumentException - if the language is not defined.
      Since:
      3.6.1
      See Also:

    • setLocalizedDescription

      void setLocalizedDescription(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:
      IllegalArgumentException - if a language is not defined.
      Since:
      3.6.1
      See Also:

    • 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.

    • can

      @NotNull IWorkItemPermissions can()
      Specified by:
      can in interface IPObject
      Specified by:
      can in interface IWorkflowObject
      Since:
      3.8.2

    • getTestCase

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