Package mks.ci.server.engine

Class LocalTriggerManager.ScriptIssueBean

  • All Implemented Interfaces:
    mks.frame.triggers.ScriptExposableBean
    Direct Known Subclasses:
    LocalTriggerManager.ScriptIssueDeltaBean
    Enclosing class:
    LocalTriggerManager
    public static class LocalTriggerManager.ScriptIssueBean
extends LocalTriggerManager.ScriptIdentifiedBean
implements mks.frame.triggers.ScriptExposableBean
    The issue bean. This allows readonly access to the information in an issue.

    The imIssueDeltaBean extends this class -- in that case, the calls against this superclass always reflect the values prior to the deltas being applied to the issue. This is also true in the post event trigger, even though the issue has now been committed to the database, methods against this superclass will still reflect the values prior to the set of deltas.

    • Constructor Detail

      • ScriptIssueBean

        public ScriptIssueBean​(int userId,
                       int issueId,
                       mks.ci.server.engine.Issue issue,
                       java.sql.Connection c,
                       mks.ci.server.engine.IssueComponents ic)

    • Method Detail

      • getIssue

        public mks.ci.server.engine.Issue getIssue()

      • getID

        public int getID()
        Retrieve the issue id.

      • getIssueIDString

        public java.lang.String getIssueIDString()
        Provides the caller with a text representation of the item's unique identifier. In the case where this item represents a versioned item of another (live) item, the display string will return a String in the following format: 
         {LIVE_ITEM_ID}-{MAJOR_REVISION}.{MINOR_REVISION}
        where {LIVE_ITEM_ID} is the unique item identifier of the live item from which this versioned item was created. In the case where the supplied item is not versioned, we will simply return a String representation of its unique identifier.
        Returns:
        a suitable display of the item's unique identifier taking into account any item revisions

      • toString

        public java.lang.String toString()
        Returns a summary of this object.
        Overrides:
        toString in class java.lang.Object

      • isDocumentItem

        public boolean isDocumentItem()
        Is this issue part of the Document Model? In other words, is it a Segment, Node, or Shared Item?

      • isSegment

        public boolean isSegment()
        Is this issue a Segment in the Document Model?

      • isNode

        public boolean isNode()
        Is this issue a Node in the Document Model?

      • isSharedItem

        public boolean isSharedItem()
        Is this issue a Shared Item in the Document Model?

      • isGroupDocument

        public boolean isGroupDocument()
        Is this issue a Group Segment in the Document Model?

      • isLive

        public boolean isLive()
        Is this issue Live?

      • isVersioned

        public boolean isVersioned()
        Is this issue Versioned?

      • isMeaningful

        public boolean isMeaningful()
                     throws mks.frame.triggers.TriggerException
        Is the category of the shared item that this node is referencing "meaningful"?
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node.

      • isSubSegment

        public boolean isSubSegment()
                     throws mks.frame.triggers.TriggerException
        Is the item that this node is referencing a Segment in the Document Model?
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node.

      • isSubSegmentReference

        public boolean isSubSegmentReference()
                              throws mks.frame.triggers.TriggerException
        Does this node reference (as opposed to include) a subsegment?
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node or if it references a shared item instead of a segment.
        See Also:
        isSubSegmentInclude(), isSubSegment()

      • isSubSegmentInclude

        public boolean isSubSegmentInclude()
                            throws mks.frame.triggers.TriggerException
        Does this node include (as opposed to referece) a subsegment?
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node or if it references a shared item instead of a segment.
        See Also:
        isSubSegmentReference(), isSubSegment()

      • isContent

        public boolean isContent()
                  throws mks.frame.triggers.TriggerException
        Is the item that this node is referencing a Shared Item in the Document Model?
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node.

      • isTestItem

        public boolean isTestItem()
        Is this type part of the Test model? In other words, is it a Test Case, Test Step or Test Session?

      • isTestCase

        public boolean isTestCase()
        Is this type a Test Case in the Test model?

      • isTestStep

        public boolean isTestStep()
        Is this type a Test Step in the Test model?

      • isTestSession

        public boolean isTestSession()
        Is this type a Test Session in the Test model?

      • isTestSuite

        public boolean isTestSuite()
        Is this type a Test Suite in the Test model?

      • getState

        public java.lang.String getState()
        Retrieve the state of the issue.
        Returns:
        The state, as a string. For the unspecified state, returns the string "Unspecified".

      • getSummary

        public java.lang.String getSummary()
                            throws mks.frame.triggers.TriggerException
        Retrieve the summary of the issue.
        Returns:
        The summary of the issue.
        Throws:
        mks.frame.triggers.TriggerException

      • getType

        public java.lang.String getType()
                         throws mks.frame.triggers.TriggerException
        Retrieve the type of the issue.
        Returns:
        The type as a string.
        Throws:
        mks.frame.triggers.TriggerException

      • getAssignedUser

        public java.lang.String getAssignedUser()
                                 throws mks.frame.triggers.TriggerException
        Retrieve the assigned users for this issue.
        Returns:
        The assigned users, as String
        Throws:
        mks.frame.triggers.TriggerException

      • getAssignedGroup

        public java.lang.String getAssignedGroup()
                                  throws mks.frame.triggers.TriggerException
        Retrieve the assigned groups for this issue.
        Returns:
        The assigned groups, as String
        Throws:
        mks.frame.triggers.TriggerException

      • getDocumentID

        public int getDocumentID()
                  throws mks.frame.triggers.TriggerException
        Retrieve the Document ID for this issue. The document ID is the issue number for the root segment for this document. The result is undefined for any item which is not a document model node.
        Returns:
        The issue number of the document ID item. The value 0 is returned if the node has been removed from its document.
        Throws:
        mks.frame.triggers.TriggerException

      • getRootID

        public int getRootID()
              throws mks.frame.triggers.TriggerException
        Retrieve the Root ID for this issue. The root ID is the issue number from which this item was originally derived, i.e. branched from originally. The result is undefined for any item that is a) not a document model item, or b) a document model item that was copied with the --nobranch option.
        Returns:
        The issue number of the root item.
        Throws:
        mks.frame.triggers.TriggerException

      • getProject

        public java.lang.String getProject()
        Retrieve the project that this issue is associated with.
        Returns:
        The project, as a string. For unspecified project, returns null.

      • getProjectIssue

        public int getProjectIssue()
                    throws mks.frame.triggers.TriggerException
        Retrieves the issue that backs the project.
        Returns:
        The id of the issue that backs the project or -1 if there is no issue backing the project
        Throws:
        mks.frame.triggers.TriggerException - if the project cannot be found

      • getParametersBean

        public LocalTriggerManager.ScriptParametersFieldBean getParametersBean()
                                                                throws mks.frame.triggers.TriggerException
        Retrieve the value of a parameters field, by the "default" field. The return value is a ScriptParametersFieldBean object.
        Returns:
        a ScriptParametersFieldBean object. If the field is empty, the ScriptParametersFieldBean object will have no parameters defined.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getParametersFieldBean

        public LocalTriggerManager.ScriptParametersFieldBean getParametersFieldBean​(java.lang.String fieldName)
                                                                     throws mks.frame.triggers.TriggerException
        Retrieve the value of a parameters field, by field name. The return value is a ScriptParametersFieldBean object.
        Parameters:
        fieldName - the name of a field that is a "Parameters" field or is an fva to a field that is a "Parameters" field.
        Returns:
        a ScriptParametersFieldBean object. If the field is empty, the ScriptParametersFieldBean object will have no parameters defined.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getResolvedParametersBean

        public LocalTriggerManager.ScriptParametersFieldBean getResolvedParametersBean()
                                                                        throws mks.frame.triggers.TriggerException
        Returns a ScriptParametersFieldBean object that represents the resolved set of parameters for this issue. All of the levels (project, session, document, and local) will have been merged together to create the resolved set of parameters. The session context will remain unchanged from the last time it was explicitly set.
        Returns:
        a ScriptParametersFieldBean representing the resolved set of parameters for this issue.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while resolving the parameters.
        See Also:
        getResolvedParametersBeanForSession(int)

      • getResolvedParametersBeanForSession

        public LocalTriggerManager.ScriptParametersFieldBean getResolvedParametersBeanForSession​(int sessionId)
                                                                                  throws mks.frame.triggers.TriggerException
        Returns a ScriptParametersFieldBean object that represents the resolved set of parameters for this issue. All of the levels (project, session, document, and local) will have been merged together to create the resolved set of parameters. If sessionId >= 0, then the session context will be changed for all other calls involving parameter substitution or resolution.
        Parameters:
        sessionId - The session item id to use for resolving. If 0, then no session context will be used. If < 0, then the previous session context will be used again. Otherwise, we will replace the session context with the new session item id provided.
        Returns:
        a ScriptParametersFieldBean representing the resolved set of parameters for this issue.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while resolving the parameters.

      • getResolvedParameterValuesBean

        public LocalTriggerManager.ScriptParameterValuesBean getResolvedParameterValuesBean()
                                                                             throws mks.frame.triggers.TriggerException
        Returns a ScriptParameterValuesBean object that represents the resolved set of parameter values for this issue. All of the levels (project, session, document, and local) will have been merged together to create the resolved set of parameter values. The session context will remain unchanged from the last time it was explicitly set.
        Returns:
        a ScriptParameterValuesBean representing the resolved set of parameter values for this issue.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while resolving the parameter values.
        See Also:
        getResolvedParameterValuesBeanForSession(int)

      • getResolvedParameterValuesBeanForSession

        public LocalTriggerManager.ScriptParameterValuesBean getResolvedParameterValuesBeanForSession​(int sessionId)
                                                                                       throws mks.frame.triggers.TriggerException
        Returns a ScriptParameterValuesBean object that represents the resolved set of parameter values for this issue. All of the levels (project, session, document, and local) will have been merged together to create the resolved set of parameter values. If sessionId >= 0, then the session context will be changed for all other calls involving parameter substitution or resolution.
        Parameters:
        sessionId - The session item id to use for resolving. If 0, then no session context will be used. If < 0, then the previous session context will be used again. Otherwise, we will replace the session context with the new session item id provided.
        Returns:
        a ScriptParameterValuesBean representing the resolved set of parameter values for this issue.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while resolving the parameter values.

      • setParameterResolutionSession

        public void setParameterResolutionSession​(int sessionId)
                                   throws mks.frame.triggers.TriggerException
        Sets the current session context when doing parameter substitution and viewing resolved parameters or parameter values. If sessionId >= 0, then the session context will be changed for all other calls involving parameter substitution or resolution.
        Parameters:
        sessionId - The session item id to use for resolving. If 0, then no session context will be used. If < 0, then the previous session context will be used again. Otherwise, we will replace the session context with the new session item id provided.
        Throws:
        mks.frame.triggers.TriggerException - if any error occurs while replacing the session context.

      • getParameterValuesBean

        public LocalTriggerManager.ScriptParameterValuesBean getParameterValuesBean()
                                                                     throws mks.frame.triggers.TriggerException
        Retrieve the value of a parameter values field, by the "default" field. The return value is a ScriptParameterValuesBean object.
        Returns:
        a ScriptParameterValuesBean object. If the field is empty, the ScriptParameterValuesBean object will have no parameters defined.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getParameterValuesFieldBean

        public LocalTriggerManager.ScriptParameterValuesBean getParameterValuesFieldBean​(java.lang.String fieldName)
                                                                          throws mks.frame.triggers.TriggerException
        Retrieve the value of a parameter values field, by field name. The return value is a ScriptParameterValuesBean object.
        Parameters:
        fieldName - the name of a field that is a "Parameter Values" field or is an fva to a field that is a "Parameter Values" field.
        Returns:
        a ScriptParameterValuesBean object. If the field is empty, the ScriptParameterValuesBean object will have no parameters defined.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getRelationshipFieldBeans

        public LocalTriggerManager.ScriptRelationshipBean[] getRelationshipFieldBeans​(java.lang.String fieldName)
                                                                       throws mks.frame.triggers.TriggerException
        Retrieve the values of a field relationship, by field name. The return is an array of ScriptRelationshipBean objects. This is an ordered list of all relationships on that field for this issue.
        Parameters:
        fieldName - the name of a field of type relationship, qbr or ibpl.
        Returns:
        an array of imRelationshipBeans. If the field is empty, then an array is still returned, but it has zero entries.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getIBPLFieldIssueID

        public int getIBPLFieldIssueID​(java.lang.String fieldName)
                        throws mks.frame.triggers.TriggerException
        For a single valued issue backed pick list, retrieve the integer value of the target issue.
        Parameters:
        fieldName - the name of a field of type ibpl
        Returns:
        the integer value of the backing issue. If this field is empty, then the value returned is zero.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, is not an issue backed pick list, or points at multiple issues.

      • getIBPLFieldIssueIDs

        public java.util.Set<java.lang.Integer> getIBPLFieldIssueIDs​(java.lang.String fieldName)
                                                      throws mks.frame.triggers.TriggerException
        For an issue backed pick list, retrieve the set of backing issue ids.
        Parameters:
        fieldName - the name of a field of type ibpl.
        Returns:
        a Set, each entry in the set is an Integer representing an issue id which backs the value of this field. A value of null is returned if the field is empty.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, is not an issue backed pick list.

      • getFieldValue

        public java.lang.Object getFieldValue​(java.lang.String fieldName)
                               throws mks.frame.triggers.TriggerException
        Retrieve the value of the field. The actual value returned is always a java object:
        • User: String name of the user For multi-valued fields, this may be a java Set object, each set value is the String name of a user.
        • Group: String name of the group For multi-valued fields, this may be a java Set object, each set value is the String name of a group.
        • State: String name of the state For the unspecified state, the string "Unspecified" is returned.
        • Integer: Java `Integer' object
        • Boolean: Java `Boolean' object
        • Double: Java `Double' object
        • PickList: String name of the picked entry If the pick list has multiple values, the list may be returned as a java Set object, each set value is the String name of a picked entry. For a multiple value pick list, where there is only one value set, you may receive either the single value, or a set of the single value.
        • Date: Java `Date' object
        • Text: String
        • Relationship: A java `List' object, each list value is the string value of the individual link: i.e. the issue number followed by it's link flags. For more detailed control, use the getRelationshipFieldBeans method to return individual link beans.
        Note that in javascript, you can mostly use all these values without converting, javascript will for example extract the int value out of the Integer if you try to use it for arithmetic. If you want to assign a date back to another field, you must use setDateFieldValue not setFieldValue, since the .toString method for the java Date object doesn't agree with the format required for our date field.

        Note that this method is also available using the imIssueDeltaBean. In this case, this method is always identical to that returned by the getOldFieldValue, the old field value, in both the pre and post triggers.

        For a logging field, the value returned is the entire value of the field, including all users and timestamps.

        Returns:
        Various, if the field has not been set, the null value.
        Throws:
        mks.frame.triggers.TriggerException

      • isFieldValueAmbiguous

        public boolean isFieldValueAmbiguous​(java.lang.String fieldName)
                              throws mks.frame.triggers.TriggerException
        Return true if the value for the specified field is ambiguous on a versioned item. If the field value for the supplied field cannot be computed in a versioned item because it is ambiguous, the field value will be null. Use this method to differentiate between an actual null value and null return because the field value is ambiguous.

        Because the trigger framework does not have the same access to the document context as other interfaces, there will be more cases in which field values will be ambiguous

        Parameters:
        fieldName - the name of the field to be inspected for ambiguity
        Returns:
        true if the field value is ambiguous on a versioned item.
        Throws:
        mks.frame.triggers.TriggerException

      • getFieldDisplayString

        public java.lang.String getFieldDisplayString​(java.lang.String fieldName)
                                       throws mks.frame.triggers.TriggerException
        Retrieve the value of a field as a printable string.
        Parameters:
        fieldName - the name of the field whose value we return.
        Returns:
        a string representing the display value of the field
        Throws:
        mks.frame.triggers.TriggerException

      • substituteFields

        public java.lang.String substituteFields​(java.lang.String str)
                                  throws mks.frame.triggers.TriggerException
        Substitutes the string representation of the field value for field xxx, for all occurrences of {xxx} in the argument. Eg., str = "The ID is {ID} and summary is \"{Summary}\"." will return something like this "The ID is 20930 and summary is "This is a summary".
        Parameters:
        str - The string containing substitution directives.
        Returns:
        String with all the field values replaced
        Throws:
        mks.frame.triggers.TriggerException

      • getSIProjectFieldServer

        public java.lang.String getSIProjectFieldServer​(java.lang.String fieldName)
                                         throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the server component.
        Returns:
        the server name, in the format server:port as a string. If the field is not set, null is returned. If the field is set, the server is always returned
        Throws:
        mks.frame.triggers.TriggerException

      • getSIProjectFieldProject

        public java.lang.String getSIProjectFieldProject​(java.lang.String fieldName)
                                          throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the project component.
        Returns:
        the project name as a string If the field is not set, null is returned. If the field contains a legacy flat path, that value is returned. If the field contains a canonical location configuration path (e.g. #location=/root/project.pj#b=1.1), the location portion is returned.
        Throws:
        mks.frame.triggers.TriggerException

      • getSIProjectFieldConfigPath

        public java.lang.String getSIProjectFieldConfigPath​(java.lang.String fieldName)
                                             throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the configuration path when available.
        Returns:
        the configuration path stored in the field, or null when the field is not set or contains a legacy flat path.
        Throws:
        mks.frame.triggers.TriggerException

      • getSIProjectFieldRevision

        public java.lang.String getSIProjectFieldRevision​(java.lang.String fieldName)
                                           throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the checkpoint component.
        Returns:
        the checkpoint revision as a string If the field is not set, null is returned. If the field is set, the revision may or may not be set; null is returned if it is not set.
        Throws:
        mks.frame.triggers.TriggerException

      • getSIProjectFieldDevpath

        public java.lang.String getSIProjectFieldDevpath​(java.lang.String fieldName)
                                          throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the devpath component.
        Returns:
        the devpath name as a string If the field is not set, null is returned. If the field is set, the devpath name may or may not be set; null is returned if it is not set.
        Throws:
        mks.frame.triggers.TriggerException

      • getRelatedIssues

        public int[] getRelatedIssues()
                       throws mks.frame.triggers.TriggerException
        Retrieve all the issues that our Outward Relationship field points at. This does not include all the issues that point at us thru the reverse field, i.e. thru the Inward Relationship field.

        The value returned is an integer, not a bean. To retrieve the imIssueBean, use the getIssueBean() on the imServerBean.

        This call works on the standard relationship field normally called Forward Relationships.

        Returns:
        an array of ints which are the IDs of related issues. The order of the array is the same as that of the related issues.
        Throws:
        mks.frame.triggers.TriggerException

      • getReverseRelatedIssues

        public int[] getReverseRelatedIssues()
                              throws mks.frame.triggers.TriggerException
        Retrieve all the issues that our Inward Relationship field points at. This does not include all the issues that we point at thru the reverse field, i.e. thru the Outward Relationship field.

        The value returned is an integer, not a bean. To retrieve the imIssueBean, use the getIssueBean() on the imServerBean.

        This call works on the standard relationship field normally called Backward Relationships.

        Returns:
        an array of ints which are the IDs of related issues. The order of the array is the same as that of the related issues.
        Throws:
        mks.frame.triggers.TriggerException

      • getRelatedIssues

        public int[] getRelatedIssues​(java.lang.String fieldName)
                       throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that the named relationship field points at.
        Returns:
        an array of ints which are the IDs of related issues. The order of the array is the same as that of the related issues.
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not a relationship field.

      • verifyFieldLoaded

        public void verifyFieldLoaded​(int fieldID)
                       throws mks.ci.exception.CIException,
                              java.sql.SQLException
        Verify that an individual field has been loaed. Convenience method for calling verifyFieldLoaded when we only have the field id.
        Parameters:
        fieldID - the id of the field to load
        Throws:
        mks.ci.exception.CIException
        java.sql.SQLException

      • getAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getAttachmentBeans()
                                                              throws mks.frame.triggers.TriggerException
        Fetch a list of attachment beans from the default Attachments field
        Returns:
        an array of imAttachmentBean objects. An empty array is returned if there are no attachments in the default attachments.
        Throws:
        mks.frame.triggers.TriggerException

      • getAttachments

        public java.lang.String[] getAttachments​(java.lang.String fieldName)
                                  throws mks.frame.triggers.TriggerException
        Retrieve the values (by name) of an attachment field, by field name. The return is an array of the String names of the attachment objects.
        Parameters:
        fieldName - the name of a field of type attachment
        Returns:
        an array of String objects. If the field is empty, then an array is still returned, but it has zero entries.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getAttachmentBeans​(java.lang.String fieldName)
                                                              throws mks.frame.triggers.TriggerException
        Retrieve the values of an attachment field, by field name. The return is an array of ScriptAttachmentBean objects.
        Parameters:
        fieldName - the name of a field of type attachment
        Returns:
        an array of imAttachmentBeans. If the field is empty, then an array is still returned, but it has zero entries.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getSourceTraceBeans

        public LocalTriggerManager.ScriptSourceTraceBean[] getSourceTraceBeans​(java.lang.String fieldName)
                                                                throws mks.frame.triggers.TriggerException
        Retrieve the values of a source trace field, by field name. The return is an array of imSourceTraceBean objects.
        Parameters:
        fieldName - the name of a field of type source trace
        Returns:
        an array of imSourceTraceBean objects. If the field is empty, then an array is still returned, but it has zero entries.
        Throws:
        mks.frame.triggers.TriggerException - if the field does not exist, or is not of an appropriate type.

      • getTimeEntryBeans

        public LocalTriggerManager.ScriptTimeEntryBean[] getTimeEntryBeans()
                                                            throws mks.frame.triggers.TriggerException
        Fetch a list of time entry beans for this issue.
        Returns:
        an array of imTimeEntryBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getChangePackageBeans

        public LocalTriggerManager.ScriptChangePackageBean[] getChangePackageBeans()
                                                                    throws mks.frame.triggers.TriggerException
        Fetch a list of Source Code Management related change package beans for this issue.
        Returns:
        An array of imChangePackageBean objects for the Source Code Management change packages.
        Throws:
        mks.frame.triggers.TriggerException

      • getAllChangePackageBeans

        public LocalTriggerManager.ScriptGenericChangePackageBean[] getAllChangePackageBeans()
                                                                              throws mks.frame.triggers.TriggerException
        Fetch a list of change package beans for all change package types, including SI and Implementer.
        Returns:
        An array of imChangePackageBean objects for SI change packages and imGenericChangePackageBean objects for the other change package types.
        Throws:
        mks.frame.triggers.TriggerException

      • getGenericChangePackageBeans

        public LocalTriggerManager.ScriptGenericChangePackageBean[] getGenericChangePackageBeans​(java.lang.String cpType)
                                                                                  throws mks.frame.triggers.TriggerException
        Fetch a list of change package beans for change packages of the specified change package type.
        Parameters:
        cpType - The real name of the change package type.
        Returns:
        An array of imChangePackageBean objects for SI change packages and imGenericChangePackageBean objects for the other change package types.
        Throws:
        mks.frame.triggers.TriggerException

      • getGenericChangePackageBeans

        public LocalTriggerManager.ScriptGenericChangePackageBean[] getGenericChangePackageBeans​(java.lang.String[] cpTypes)
                                                                                  throws mks.frame.triggers.TriggerException
        Fetch a list of change package beans for change packages of the specified change package types.
        Parameters:
        cpTypes - The array of String change package type real names. If this value is null then all change package types are fetched.
        Returns:
        An array of imChangePackageBean objects for SI change packages and imGenericChangePackageBean objects for the other change package types.
        Throws:
        mks.frame.triggers.TriggerException

      • getSIChangePackageBeans

        public LocalTriggerManager.ScriptChangePackageBean[] getSIChangePackageBeans()
                                                                      throws mks.frame.triggers.TriggerException
        Fetch a list of change package beans corresponding to the Source Code Management change packages for this issue.
        Returns:
        An array of imChangePackageBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getImplementerChangePackageBeans

        public LocalTriggerManager.ScriptGenericChangePackageBean[] getImplementerChangePackageBeans()
                                                                                      throws mks.frame.triggers.TriggerException
        Fetch a list of change package beans corresponding to the Implementer change packages for this issue.
        Returns:
        An array of imGenericChangePackageBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getExposedName

        public java.lang.String getExposedName()
        Returns the name of this bean that is exposed to the scripting language.
        Specified by:
        getExposedName in interface mks.frame.triggers.ScriptExposableBean
        Specified by:
        getExposedName in class ScriptBaseBean
        Returns:
        the bean name: imIssueBean.

      • getIssueID

        public int getIssueID()
        Return the issue number for this issue.

      • getDisplayString

        public java.lang.String getDisplayString()
        For debugging, a displayable version of the issue.

      • getLabels

        public LocalTriggerManager.ScriptLabelBean[] getLabels()
                                                throws mks.frame.triggers.TriggerException
        Retrieve all the labels associated with this issue.
        Returns:
        An array of imLabelBeans. If there are no labels, the array is still returned, but it is zero length.
        Throws:
        mks.frame.triggers.TriggerException

      • walkHierarchy

        public int[] walkHierarchy​(java.lang.String field)
                    throws mks.frame.triggers.TriggerException
        Perform a walk from this issue thru a particular field.
        Throws:
        mks.frame.triggers.TriggerException

      • walkHierarchyIncludingFirst

        public int[] walkHierarchyIncludingFirst​(java.lang.Object[] fields)
                                  throws mks.frame.triggers.TriggerException
        Perform a walk from this issue thru a list of fields and return this issue with those coming back from the walk.
        Parameters:
        fields - An array of fields. Each entry can either be a string, i.e. the field name; or a field bean.
        Returns:
        an integer array of issue ids visited while walking thru those fields. If there are any loops, each issue is only visited once. If there are no relationships thru any of the given fields from this issue, then an array of size one is returned. This is ordered by level: the issues one level from this issue through all fields; followed by the issues two levels, ... Within each level, the issues are ordered within each relationship field by their relationship order. However, if multiple fields are specified, the order of the sets of issues is not defined.

        Be cautious in the use of this function, a significant sized hierarchy could cause a performance problem.

        Throws:
        mks.frame.triggers.TriggerException - if any of the fields specified are not normal relationship fields.
        See Also:
        walkHierarchy(Object[])

      • walkHierarchy

        public int[] walkHierarchy​(java.lang.Object[] fields)
                    throws mks.frame.triggers.TriggerException
        Perform a walk from this issue thru a list of fields.
        Parameters:
        fields - An array of fields. Each entry can either be a string, i.e. the field name; or a field bean.
        Returns:
        an integer array of issue ids visited while walking thru those fields. If there are any loops, each issue is only visited once. If there are no relationships thru any of the given fields from this issue, then an empty array is returned. This is ordered by level: the issues one level from this issue through all fields; followed by the issues two levels, ... Within each level, the issues are ordered within each relationship field by their relationship order. However, if multiple fields are specified, the order of the sets of issues is not defined.

        Be cautious in the use of this function, a significant sized hierarchy could cause a performance problem.

        Throws:
        mks.frame.triggers.TriggerException - if any of the fields specified are not normal relationship fields.
        See Also:
        walkHierarchyIncludingFirst(Object[])

      • getRootIssueID

        public int getRootIssueID​(java.lang.String field)
                   throws mks.frame.triggers.TriggerException
        Walk up the specified relationship field until reaching an issue which has no relationships using that field.
        Returns:
        the root issue id, i.e. the issue which does not have any more relationships. Zero is returned if there is a loop, or if the starting issue does not have any relationships.
        Throws:
        mks.frame.triggers.TriggerException - if the field specified is not a normal relationship field.

      • getParent

        public LocalTriggerManager.ScriptBranchBean getParent()
                                               throws mks.frame.triggers.TriggerException
        If this issue was created as a result of a branch operation, retrieve the information about the parent branch.
        Returns:
        an imBranchBean which can be used to retrieve both the parent issue id, and the point in time that the branch was created against. Null is returned if this issue was not created by a branch operation.
        Throws:
        mks.frame.triggers.TriggerException

      • getBranches

        public LocalTriggerManager.ScriptBranchBean[] getBranches()
                                                   throws mks.frame.triggers.TriggerException
        If this issue has been branched, then retrieve the information about all the child issue branches.
        Returns:
        an array of imBranchBeans which can be used to retrieve both the child issue id, and the point in time that the branch was created against. Null is returned if there are no branches.
        Throws:
        mks.frame.triggers.TriggerException

      • computeHistoryNow

        public void computeHistoryNow​(java.lang.String fieldname)
                       throws mks.frame.triggers.TriggerException
        Compute a computed field now, and store its new value to history. The value is computed only for the current issue, i.e. the issue represented by this bean. If it is a statically computed field, update the issue record for the field as well. Note that this computation uses its own transaction. If this method does not throw an exception then the values have been successfully computed, stored, and committed. This method is therefore not permitted in a PRE trigger. It may be used either in a scheduled trigger, or in a POST trigger.
        Parameters:
        fieldname - The string name of the field to compute.
        Throws:
        mks.frame.triggers.TriggerException - If the field is not a computed field or on error computing the history for the field.

      • getRelatedTestResultBeans

        public LocalTriggerManager.ScriptTestResultBean[] getRelatedTestResultBeans()
                                                                     throws mks.frame.triggers.TriggerException
        Retrieve any test results that are related to this issue.
        Returns:
        An array of LocalTriggerManager.ScriptTestResultBean, or null if there are no test results related to this issue.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while retrieving test results from the database.

      • getAssociatedSessionTestResultBeans

        public LocalTriggerManager.ScriptTestResultBean[] getAssociatedSessionTestResultBeans()
                                                                               throws mks.frame.triggers.TriggerException
        Retrieve any test results that use this item as a test session.
        Returns:
        An array of LocalTriggerManager.ScriptTestResultBean, or null if there are no test results that use this item as a test session.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while retrieving test results from the database.

      • getTestCaseAssociatedTestResultBeans

        public LocalTriggerManager.ScriptTestResultBean[] getTestCaseAssociatedTestResultBeans()
                                                                                throws mks.frame.triggers.TriggerException
        Retrieve any test results that use this item as a test case. This essentially returns all test results for this test case in any test session.
        Returns:
        An array of LocalTriggerManager.ScriptTestResultBean, or null if there are no test results that use this item as a test case, or if the item does not play test case role.
        Throws:
        mks.frame.triggers.TriggerException - if an error occurs while retrieving test results from the database.

      • getChangedContent

        public int[] getChangedContent​(boolean recurseInclude,
                               boolean recurseReference)
                        throws mks.frame.triggers.TriggerException
        Find all content under this node or segment which has been changed since it was last revisioned. This walks the document from the specified starting item, checking the state of the field Significant Change Since Item Revision. Any items for which that field evaluates true are returned. The starting item, this item, may be included in the result list, but will depend on the change state prior to the current edit.

        As this is a trigger, all permissions are bypassed. Returned items may or may not be visible to the end user.

        If this item is not a node or a segment, the results are undefined.

        Examples:

        To block on an issue edit, say a state change on the segment, install an appropriate trigger rule on an edit item pre-trigger: 

         var idb = bsf.lookupBean("imIssueDeltaBean");
 var eb = bsf.lookupBean("siEnvironmentBean");
 var changes = idb.getChangedContent(false, false);
 if (changes.length > 0)
     eb.abortScript(reason, true);

        To block on a baseline gesture. This is actually a label, so you need to install a label pre-trigger, and fetch the item bean for the item being labeled: 

         var labelBean = bsf.lookupBean("imLabelArgsBean");
 var eb = bsf.lookupBean("siEnvironmentBean");
 var toLabel = labelBean.getIssueID();
 var labelIssue = ssb.getIssueBean(toLabel, []);
 var changes = labelIssue.getChangedContent(false, false);
 if (changes.length > 0)
     eb.abortScript(reason, true);

        To block on a branch segment gesture. You must install a branch pre-trigger. However, the branch of the root of the document is not necessarily the first trigger, so you must obtain the document id from the first item being branched, and retrieve its item bean. 

         var branchBean = bsf.lookupBean("imBranchArgsBean");
 var ssb = bsf.lookupBean("imServerBean");
 var eb = bsf.lookupBean("siEnvironmentBean");
 var toBranch = branchBean.getIssueID();
 var branchIssue = ssb.getIssueBean(toBranch, [ ssb.getDocumentIDFieldBean() ]);
 var rootID = branchIssue.getDocumentID();
 var rootBranchIssue = ssb.getIssueBean(rootID, []);
 var changes = rootBranchIssue.getChangedContent(false, false);
 if (changes.length > 0)
     eb.abortScript(reason, true);
        Parameters:
        recurseReference - Recurse into any children which are referenced subdocuments.
        recurseInclude - Recurse into any children which are included subdocuments.
        Returns:
        An integer array containing the ids of all the items which have changed. The order of the results is not defined. If there are no changed items, an array will still be returned, but it will have zero items.
        Throws:
        mks.frame.triggers.TriggerException

      • isLocked

        public boolean isLocked()
        Check to see if this issue is currently locked, either by a group or a user.
        Returns:
        true if the issue is locked and false otherwise

      • isGroupLock

        public boolean isGroupLock()
        Check to see if this issue is locked by a group
        Returns:
        true if the lock issue is locked by a group, false otherwise

      • getLockPrincipalBean

        public LocalTriggerManager.ScriptPrincipalBean getLockPrincipalBean()
                                                             throws mks.frame.triggers.TriggerException
        Get a ScriptPrincipalBean for the group or user that has this issue locked
        Returns:
        a ScriptPrincipalBean containing the locker's information, can be group, dynamic group, or user. Returns null if the issue is not locked
        Throws:
        mks.frame.triggers.TriggerException - If the issue is locked but the group or user is not found