Package mks.ci.server.engine

Class LocalTriggerManager.ScriptIssueDeltaBean

  • All Implemented Interfaces:
    mks.ci.server.engine.IScriptIssueDeltaBean, mks.ci.server.engine.IssueProxy, mks.frame.triggers.ScriptExposableBean
    Enclosing class:
    LocalTriggerManager
    public static class LocalTriggerManager.ScriptIssueDeltaBean
extends LocalTriggerManager.ScriptIssueBean
implements mks.frame.triggers.ScriptExposableBean, mks.ci.server.engine.IScriptIssueDeltaBean, mks.ci.server.engine.IssueProxy
    The main bean created for an issue changed event trigger. Retrieve it via: bsf.lookupBean("imIssueDeltaBean"). This bean will allow you to examine the issue as is was before the change, and as it will be after the change. In the pre-trigger you may also update the set of changes to be performed. Changes made will not be committed to the database until your and all other issue-changed pre-event triggers have run and completed successfully. Changes indicated may not have been made by the user, but by previous triggers that have run. Further, we may indicate a field has changed, when a previous trigger has actually restored it to its original value.

    This trigger is actually invoked in two cases: when an issue is editted, or when an issue is being created. Note that an issue being branched, or copied via the CopyTree methodology does not fire this trigger.

    Permissions: Your trigger runs on the server, it runs without any permissions checking.

    Your trigger runs after the system has validated the user's changes to conform to field visibility, and mandatory fields. These are not re-validated after your trigger completes: you have the ability to bypass these checks in your trigger.

    This bean is available both on pre and post triggers. However, for the post trigger, it is in readonly mode. In other words, you can examine the delta, but at that point you are not permitted to modify the delta.

    This bean is a subclass of the imIssueBean, all calls on that superclass return the values of the issue prior to the set of changes that caused this trigger to fire; even in the post event trigger.

    The transactionality of an issue modification should be understood. When the client requests to update an issue, it presents a set of issue deltas to the server. The server starts a transaction, which runs in the following order:

    • Transaction
    • PRE-Trigger
    • Commit-Transaction
    • POST-Trigger
    In other words, we make the commitment that the PRE-trigger will run, and it will run before any modifications have been made to the database. If an error occurs (or a trigger veto) in the PRE-trigger, no changes will be made, the transaction will be rolled back. This applies along the chain of rules, and multiple scripts and assignments that might run. Since any changes being made will be discarded, the exception that stopped a script stops all scripts and triggers and assignments.

    However, we make the committment that the POST-trigger will run only after all data has been committed to disk. Exceptions in a given script will be logged to the server log, but will only stop the current set of scripts. All other rules will be evaluated and run scripts as required. Each trigger rule is associated with zero or more scripts to run (the scripts is a comma-delimited list), and there can be multiple rules. The exception stops running any further script in the comma- delimited list, but not the other rules.

    If you are trying to modify other issues, you can only do it thru the pre-event trigger. The order above needs to be expanded upon in that case:

    • Transaction
    • PRE-Trigger Chain
    • Commit-Transaction
    • POST-Trigger Chain
    Note that the triggers become chains of triggers. If a PRE-Trigger attempts to modify another issue (via the LocalTriggerManager.ScriptServerBean.getIssueDeltaBean(int) method) or create another issue (via the LocalTriggerManager.ScriptServerBean.postNewIssue(java.lang.String) method) (called the secondary issue) the secondary issue is added to a list of issues that become part of the current transaction. At this point, either all of the modifications made to all of the issues must succeed, or none of them. This means that any PRE-triggers for the secondary issue must also run, and are subject to the same rules as the triggers running for the primary issue. If a secondary issue PRE-trigger attempts to access another secondary issue, we try to find the issue on the chain and return the same issue already operated on. However, it is possible that the PRE-trigger for a secondary issue has already completed! If we were to allow the script to modify that issue again, we would be in the position of violating the contract: that is, the PRE script would be running twice, without having run the post trigger. Therefore it is considered illegal to perform this operation: once the PRE trigger has completed, other secondary triggers will not be permitted to obtain that issue again.

    For similar reasons, the POST trigger is never allowed to make any modifications at all. Any modification would put us in the position of having to build a new transaction; potentially acting on issues which have not yet run their POST triggers.

    Permissions. Secondary issues bypass permission checking. While the history records all changes as having been performed by the actual end user, the trigger need not conform to the permissions for that end user. There are several cases here:

    • Field editability. This is a permission, triggers ignore it, they can modify any field.
    • State transition. This is a permission, triggers ignore it, they can move any issue into any state.
    • Change packages closed. This is considered a constraint. If you are in state X, then there will be no open change packages. Therefore this is enforced. In other words, if you change the state of an issue (either the primary or a secondary issue), the change package constraint will be validated at the end of the the trigger. Since validation occurs outside of the trigger, it cannot be intercepted.
    • Mandatory field filled in. This is considered a constraint. If you are in state X, then all the mandatory fields should be filled in. Therefore this is enforced. In other words, if you change the state of an issue (either the primary or a secondary issue), the mandatory field constraint will be validated at the end of the trigger, with the final set of issue deltas. Since validation occurs outside of the trigger, it cannot be intercepted.

      However, this is relaxed in one particular manner. There may be a pre-existing constraint violation. In other words, the administrator added a mandatory constraint, and existing issues may not have that mandatory field filled in. An end user is not allowed to modify that violating issue; they must fix it up. However, a trigger is probably trying to maintain a single field perhaps, and doesn't care about the violation. So a trigger modification is allowed, as long as it isn't causing new mandatory constraint violations. This falls into two cases: If the trigger nulls out a mandatory constraint, it is creating a new violation; or if a trigger changes the state. If it decides to change the state then it is responsible for fulfilling all mandatory constraints in the new state.

    In the event that the user is modifying a field-value-attribute(FVA) then the values will be found in the delta here. They can be manipulated here like any other field. After completion of this trigger, the delta will then be split into parent/children deltas. The child issue's PRE-trigger will then run as part of the PRE-trigger chain. Thus, the editable FVA values being changed will be seen twice, once on the parent issue, and once in the context of the real issue.

    Caution

    Use Extreme Caution when accessing the database where there are any delta beans. Different databases do locking differently. For example, any create or edit operation that caused this bean will have an exclusive row lock. Under Oracle, a read operation will not get any locks, and will ignore the newly created/modified rows. However, under MS/SQL Server, the read operation will attempt to get a shared lock on the exclusively locked rows if the query might potentially match the row. Therefore it is highly recommended that no access be made to the database from any PRE trigger, outside of the methods made available through these beans. Failure to follow this guideline may cause the server to deadlock. See also ScriptAPISessionBean.

    • Method Detail

      • getDelta

        public mks.ci.server.engine.IssueDelta getDelta()
        Called only from engine to share deltas
        Specified by:
        getDelta in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • getFieldDeltas

        public java.util.Map<java.lang.Integer,​java.lang.Object> getFieldDeltas()

      • isSecondaryIssueChange

        public boolean isSecondaryIssueChange()
        Check if this issue delta was initially created due to a secondary cause: another trigger either fetched or created this delta; or this issue is the target of a relationship field modification.

        Note: This indicates the *initial* cause. A batch edit can in theory have multiple causes; e.g. a batch edit of two issues A and B where A's pre-trigger fetches and modifies B; issue B has now been changed both due to user-interaction, and due to secondary causes.

        For an issue which is modified due to an editable FVA (i.e. the end user updated a field which was an FVA, causing modification to the issue underlying it); the secondary issue change flag is false. This is because the change is really coming from the end-user.

        For a node operation, the parent item, if updated, is considered to be a secondary change. However, both the Node itself and the Shared Item are considered to be primary changes.

        Returns:
        true if this delta was created due to a secondary cause; false if the delta was caused by an end user gesture.

      • isEditableFVA

        public boolean isEditableFVA()
        Check if this issue delta was created due to an editable FVA edit. In a batch edit, this may be set, while there are still end-user modifications in the delta; since the delta may be modified both as part of the end-user gesture, as well as another issue via an editable FVA.

      • isDocumentModelCreate

        public boolean isDocumentModelCreate()
        Was this issue created during this transaction by the document model?

      • isEditSignificant

        public boolean isEditSignificant()
                          throws mks.frame.triggers.TriggerException
        Is this issue delta considered a Significant edit in the document model? A significant edit is one which causes the revision date to be modified. In the case of a Node/Shared Item, an edit on the Node which is actually a significant edit field on the Shared Item, would cause the Shared Item to be considered for potentially branching.

        The list of significant edit fields is configured on the type. An edit of the standard Attachment field is always considered significant.

        Returns:
        true, if the edit is significant.
        Throws:
        mks.frame.triggers.TriggerException - if the significant edit fields are incorrectly configured. If this call is made against an item which is not part of the document mode, i.e. isDocumentItem() would return false.

      • setRevisionRequest

        public void setRevisionRequest​(mks.ci.common.RevisionRequest rr)
        Specified by:
        setRevisionRequest in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • getRevisionRequest

        public mks.ci.common.RevisionRequest getRevisionRequest()
        Specified by:
        getRevisionRequest in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • incrementMajor

        public void incrementMajor()
                    throws mks.frame.triggers.TriggerException
        If the item's type is enabled for revisioning, cause this edit to increment the major number in the revision.

        The revision rule is not evaluated when this method is invoked from a trigger, it is the trigger's responsibility to ensure appropriate business logic has been enforced.

        When invoked by a trigger, incrementMajor will always create a new revision, even if the delta is empty; triggers do not have the same concept of checkin unchanged as the client does.

        Throws:
        mks.frame.triggers.TriggerException - if the current item's type is not enabled for revisioning.

      • incrementMinor

        public void incrementMinor()
                    throws mks.frame.triggers.TriggerException
        If the item's type is enabled for revisioning, cause this edit to increment the minor number in the revision.

        The revision rule is not evaluated when this method is invoked from a trigger, it is the trigger's responsibility to ensure appropriate business logic has been enforced.

        When invoked by a trigger, incrementMinor will always create a new revision, even if the delta is empty; triggers do not have the same concept of checkin unchanged as the client does.

        Throws:
        mks.frame.triggers.TriggerException - if the current item's type is not enabled for revisioning.

      • isIncrementMajor

        public boolean isIncrementMajor()
        Is this edit flagged to increment the major revision?
        Returns:
        true if so indicated.

      • isIncrementMinor

        public boolean isIncrementMinor()
        Is this edit flagged to increment the minor revision?
        Returns:
        true if so indicated.

      • isStateChanged

        public boolean isStateChanged()
        Does this issue delta modify the state of the issue?
        Returns:
        true if this issue delta contains a change to the state field.

      • getOldState

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

      • getNewState

        public java.lang.String getNewState()
        Retrieve the state of the issue, after this issue change. If there are no changes to the state, the old state will be returned.
        Returns:
        The state, as a string. For the unspecified state, returns the string "Unspecified".

      • isNewlyPosted

        public boolean isNewlyPosted()
        Is this a newly posted issue? This could be newly posted either because the end user just posted it, or because another trigger created it via imServerBean.postNewIssue
        Specified by:
        isNewlyPosted in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • isCreatedByEventTrigger

        public boolean isCreatedByEventTrigger()
        Was this issue created by an event trigger? i.e. by imServerBean.postNewIssue This means as part of the current transaction.
        Specified by:
        isCreatedByEventTrigger in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • isNewMeaningful

        public boolean isNewMeaningful()
                        throws mks.frame.triggers.TriggerException
        Is the category of the shared item that this node is referencing "meaningful", using the new value of the Category field.
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node.

      • isOldMeaningful

        public boolean isOldMeaningful()
                        throws mks.frame.triggers.TriggerException
        Is the category of the shared item that this node is referencing "meaningful", using the old value of the Category field, i.e was this node meaningful prior to the current operation.
        Throws:
        mks.frame.triggers.TriggerException - if this item is not a node.

      • isOldSubSegmentReference

        public boolean isOldSubSegmentReference()
                                 throws mks.frame.triggers.TriggerException
        Does this node reference (as opposed to include) a subsegment? This uses the old value of the follow flag, i.e. did we reference a subsegment prior to the current operation.
        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:
        LocalTriggerManager.ScriptIssueBean.isSubSegmentInclude(), LocalTriggerManager.ScriptIssueBean.isSubSegment()

      • getNewRelatedIssues

        public int[] getNewRelatedIssues()
                          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. If the Outward Relationship field has been modified in the current delta, return that new value; otherwise return the current value.

        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.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewRelatedIssues

        public int[] getNewRelatedIssues​(java.lang.String fieldName)
                          throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that the named relationship field points at. If the named relationship field has been modified in the current delta, return that new value; otherwise return the current value.
        Returns:
        an array of ints which are the IDs of related issues.
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not a relationship field.

      • getNewContains

        public int[] getNewContains()
                     throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that are pointed at by the Contains field. The Contains field points at all the child issues in the document model.
        Returns:
        an array of issue numbers.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewContainedBy

        public int getNewContainedBy()
                      throws mks.frame.triggers.TriggerException
        Retrieve the ID of the new container for this document model node. If this node has been disconnected from its document then this method returns -1.
        Returns:
        the ID of the item that contains this node.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewReferences

        public int getNewReferences()
                     throws mks.frame.triggers.TriggerException
        Retrieve the ID of the new shared item or segment being referenced by this document model node. The document model requires that a node reference one and only one data, but if for some reason the node has been disconnected from its referrant then this methd returns -1.
        Returns:
        the ID of the shared item or segment referenced by this node.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewReferencedBy

        public int[] getNewReferencedBy()
                         throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that are pointed at by the Referenced By field. The Referenced By field points back from the shared content, at one or more nodes.
        Returns:
        an array of either zero or more issue numbers.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldRelatedIssues

        public int[] getOldRelatedIssues()
                          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. Return the value prior to the current issue edit.

        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.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldRelatedIssues

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

      • getOldContains

        public int[] getOldContains()
                     throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that are pointed at by the Contains field. The Contains field points at all the child issues in the document model.
        Returns:
        an array of issue numbers.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldContainedBy

        public int getOldContainedBy()
                      throws mks.frame.triggers.TriggerException
        Retrieve the ID of the old container for this document model node. If this node has been disconnected from its document then this method returns -1.
        Returns:
        the ID of the item that contains this node.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldReferences

        public int getOldReferences()
                     throws mks.frame.triggers.TriggerException
        Retrieve the ID of the old shared item or segment being referenced by this document model node. The document model requires that a node reference one and only one data, but if for some reason the node has been disconnected from its referrant then this methd returns -1.
        Returns:
        the ID of the shared item or segment referenced by this node.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldReferencedBy

        public int[] getOldReferencedBy()
                         throws mks.frame.triggers.TriggerException
        Retrieve the list of issue numbers that are pointed at by the Referenced By field. The Referenced By field points back from the shared content, at one or more nodes.
        Returns:
        an array of either zero or more issue numbers.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewAttachments

        public java.lang.String[] getNewAttachments​(java.lang.String fieldName)
                                     throws mks.frame.triggers.TriggerException
        Retrieve all the attachments from the new field value taking into account any added or removed attachments (if modified). If the attachment field hasn't been modified then return all the attachments from the existing field value.
        Parameters:
        fieldName - The name of the attachment field
        Returns:
        an array of Strings which are the names of the attachments.
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not an attachment field.

      • getNewAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getNewAttachmentBeans​(java.lang.String fieldName)
                                                                 throws mks.frame.triggers.TriggerException
        Retrieve all the attachments from the new field value taking into account any added or removed attachments (if modified). If the attachment field hasn't been modified then return all the attachments from the existing field value.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getOldAttachmentBeans​(java.lang.String fieldName)
                                                                 throws mks.frame.triggers.TriggerException
        Retrieve the values of an attachment field, by field name. Retrieve the values from the issue prior to the current edit. The return is an array of ScriptAttachmentBean objects.
        Parameters:
        fieldName - The name of the attachment field
        Returns:
        an array of ScriptAttachmentBeans
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not an attachment field.

      • getOldAttachments

        public java.lang.String[] getOldAttachments​(java.lang.String fieldName)
                                     throws mks.frame.triggers.TriggerException
        Retrieve the list of attachment names that the attachment field points at. Return the value prior to the current issue edit.
        Parameters:
        fieldName - The name of the attachment field
        Returns:
        an array of Strings which are the names of the attachments.
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not an attachment field.

      • getOldSourceTraceBeans

        public LocalTriggerManager.ScriptSourceTraceBean[] getOldSourceTraceBeans​(java.lang.String fieldName)
                                                                   throws mks.frame.triggers.TriggerException
        Retrieve the old values of a source trace field, by field name. Retrieve the values from the issue prior to the current edit. The return is an array of ScriptSourceTraceBean objects.
        Parameters:
        fieldName - The name of the source trace field
        Returns:
        an array of imSourceTraceBeans
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not a source trace field.

      • getNewSourceTraceBeans

        public LocalTriggerManager.ScriptSourceTraceBean[] getNewSourceTraceBeans​(java.lang.String fieldName)
                                                                   throws mks.frame.triggers.TriggerException
        Retrieve the new values of a source trace field, by field name. These are the new source trace values, as modified by any existing delta.
        Returns:
        an array of imSourceTraceBean objects.
        Throws:
        mks.frame.triggers.TriggerException - if the named field does not exist, or is not a source trace field.

      • getOldFieldValue

        public java.lang.Object getOldFieldValue​(java.lang.String fieldName)
                                  throws mks.frame.triggers.TriggerException
        Retrieve the old value of the field. That is the current value as stored with the issue as any other user would see it, without the changes made by the current edit, or any modifications made by this or any other trigger.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldFieldValueWithSub

        public java.lang.Object getOldFieldValueWithSub​(java.lang.String fieldName)
                                         throws mks.frame.triggers.TriggerException
        Retrieve the old value of the field, with parameter substitution enabled. @see getFieldValueWithSub(String) That is the current value as stored with the issue as any other user would see it, without the changes made by the current edit, or any modifications made by this or any other trigger.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldFieldValueWithSubForSession

        public java.lang.Object getOldFieldValueWithSubForSession​(java.lang.String fieldName,
                                                          int sessionId)
                                                   throws mks.frame.triggers.TriggerException
        Retrieve the old value of the field, with parameter substitution enabled. @see getFieldValueWithSubForSession(String, int) That is the current value as stored with the issue as any other user would see it, without the changes made by the current edit, or any modifications made by this or any other trigger.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldFieldDisplayString

        public java.lang.String getOldFieldDisplayString​(java.lang.String fieldName)
                                          throws mks.frame.triggers.TriggerException
        Retrieve the old 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

      • getNewFieldValue

        public java.lang.Object getNewFieldValue​(java.lang.String fieldName)
                                  throws mks.frame.triggers.TriggerException
        Retrieve the value of a field, by name. If the value is unchanged, the old value of the field is retrieved.

        For the builtin fields Modified Date and Modified By, they will never show up as a new value, since they are only set at final commit time.

        Throws:
        mks.frame.triggers.TriggerException

      • getNewFieldValueWithSubForSession

        public java.lang.Object getNewFieldValueWithSubForSession​(java.lang.String fieldName,
                                                          int sessionId)
                                                   throws mks.frame.triggers.TriggerException
        Retrieve the value of a field, by name. Substitution with parameter values is performed. @see getFieldValueWithSubForSession(String, int). If the value is unchanged, the old value of the field is retrieved.

        For the builtin fields Modified Date and Modified By, they will never show up as a new value, since they are only set at final commit time.

        Throws:
        mks.frame.triggers.TriggerException

      • getNewFieldValueWithSub

        public java.lang.Object getNewFieldValueWithSub​(java.lang.String fieldName)
                                         throws mks.frame.triggers.TriggerException
        Retrieve the value of a field, by name. Substitution with parameter values is performed. @see getFieldValueWithSub(String). If the value is unchanged, the old value of the field is retrieved.

        For the builtin fields Modified Date and Modified By, they will never show up as a new value, since they are only set at final commit time.

        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. The new field value is used if available, else the current field value is used. 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".
        Overrides:
        substituteFields in class LocalTriggerManager.ScriptIssueBean
        Parameters:
        str - The string containing substitution directives.
        Returns:
        String with all the field values replaced
        Throws:
        mks.frame.triggers.TriggerException

      • getNewFieldDisplayString

        public java.lang.String getNewFieldDisplayString​(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

      • getNewFieldValueRaw

        public java.lang.Object getNewFieldValueRaw​(java.lang.Integer f)
                                     throws mks.ci.exception.CIException,
                                            java.sql.SQLException
        Specified by:
        getNewFieldValueRaw in interface mks.ci.server.engine.IScriptIssueDeltaBean
        Throws:
        mks.ci.exception.CIException
        java.sql.SQLException

      • getNewSIProjectFieldServer

        public java.lang.String getNewSIProjectFieldServer​(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

      • getNewSIProjectFieldProject

        public java.lang.String getNewSIProjectFieldProject​(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

      • getNewSIProjectFieldConfigPath

        public java.lang.String getNewSIProjectFieldConfigPath​(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

      • getNewSIProjectFieldRevision

        public java.lang.String getNewSIProjectFieldRevision​(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

      • getNewSIProjectFieldDevpath

        public java.lang.String getNewSIProjectFieldDevpath​(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

      • getOldSIProjectFieldServer

        public java.lang.String getOldSIProjectFieldServer​(java.lang.String fieldName)
                                            throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the server component, prior to the current issue edit.
        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

      • getOldSIProjectFieldProject

        public java.lang.String getOldSIProjectFieldProject​(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

      • getOldSIProjectFieldConfigPath

        public java.lang.String getOldSIProjectFieldConfigPath​(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 if the field contains a legacy flat path.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldSIProjectFieldRevision

        public java.lang.String getOldSIProjectFieldRevision​(java.lang.String fieldName)
                                              throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the checkpoint component, prior to the current issue edit.
        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

      • getOldSIProjectFieldDevpath

        public java.lang.String getOldSIProjectFieldDevpath​(java.lang.String fieldName)
                                             throws mks.frame.triggers.TriggerException
        For a field of type siproject, return the devpath component, prior to the current issue edit.
        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

      • getNewSummary

        public java.lang.String getNewSummary()
                               throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Summary" field. If the value is unchanged, the old summary value is retrieved.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldSummary

        public java.lang.String getOldSummary()
                               throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Summary" field prior to the issue change.
        Returns:
        The summary of the issue.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewAssignedUser

        public java.lang.String getNewAssignedUser()
                                    throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Assigned User" field. If the value is unchanged, the old assigned user value is retrieved.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldAssignedUser

        public java.lang.String getOldAssignedUser()
                                    throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Assigned User" field prior to the issue change.
        Returns:
        the assigned users, as String
        Throws:
        mks.frame.triggers.TriggerException

      • getNewAssignedGroup

        public java.lang.String getNewAssignedGroup()
                                     throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Assigned Group" field. If the value is unchanged, the old assigned group value is retrieved.
        Throws:
        mks.frame.triggers.TriggerException

      • getOldAssignedGroup

        public java.lang.String getOldAssignedGroup()
                                     throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Assigned Group" field prior to the issue change.
        Returns:
        the assigned groups as String
        Throws:
        mks.frame.triggers.TriggerException

      • getNewProject

        public java.lang.String getNewProject()
                               throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Project" field. If the value is unchanged, the old project value is retrieved.
        Returns:
        The project, as a string. For unspecified project, returns null.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewProjectIssue

        public int getNewProjectIssue()
                       throws mks.frame.triggers.TriggerException
        Retrieves the issue that backs the new project for this issue. If the project is unchanged then the issue that backs the old project is returned.
        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

      • getOldProjectIssue

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

      • getOldProject

        public java.lang.String getOldProject()
                               throws mks.frame.triggers.TriggerException
        Retrieve the value of the "Project" field prior to the issue change.
        Returns:
        The project, as a string. For unspecified project, returns null.
        Throws:
        mks.frame.triggers.TriggerException

      • getNewRelationshipFieldBeans

        public LocalTriggerManager.ScriptRelationshipBean[] getNewRelationshipFieldBeans​(java.lang.String fieldName)
                                                                          throws mks.frame.triggers.TriggerException
        Retrieve the values of a field relationship, by field name. These are the new values, as modified by any existing delta. The return is an array of ScriptRelationshipBean objects. This is an ordered list of all relationships on that field for this issue.

        Note that you get a copy of the actual list; if you invoke the set methods on these ScriptRelationshipBeans it will not have any effect unless you call setRelationshipFieldValue with the changed array.

        Throws:
        mks.frame.triggers.TriggerException

      • getOldRelationshipFieldBeans

        public LocalTriggerManager.ScriptRelationshipBean[] getOldRelationshipFieldBeans​(java.lang.String fieldName)
                                                                          throws mks.frame.triggers.TriggerException
        Retrieve the values of a field relationship, by field name. Retrieve the values from the issue prior to the current edit. The return is an array of ScriptRelationshipBean objects. This is an ordered list of all relationships on that field for this issue.

        Note that you get a copy of the actual list; if you invoke the set methods on these ScriptRelationshipBeans it will not have any effect unless you call setRelationshipFieldValue with the changed array.

        Throws:
        mks.frame.triggers.TriggerException

      • getNewIBPLFieldIssueID

        public int getNewIBPLFieldIssueID​(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 from the delta. If the value is unchanged, the old value of the field is retrieved.
        Parameters:
        fieldName - the name of a field of type ibpl
        Returns:
        the id of the backing issue as an integer. 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.

      • getOldIBPLFieldIssueID

        public int getOldIBPLFieldIssueID​(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 prior to the current issue edit.
        Parameters:
        fieldName - the name of a field of type ibpl
        Returns:
        the id of the backing issue as an integer. 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.

      • getNewIBPLFieldIssueIDs

        public java.util.Set<java.lang.Integer> getNewIBPLFieldIssueIDs​(java.lang.String fieldName)
                                                         throws mks.frame.triggers.TriggerException
        For an issue backed pick list, retrieve the set of backing issue ids from the delta. If the value is unchanged, the old value of the field is retrieved.
        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.

      • getOldIBPLFieldIssueIDs

        public java.util.Set<java.lang.Integer> getOldIBPLFieldIssueIDs​(java.lang.String fieldName)
                                                         throws mks.frame.triggers.TriggerException
        For an issue backed pick list, retrieve the set of backing issue ids from the issue prior to the current issue edit.
        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.

      • isFieldChanged

        public boolean isFieldChanged​(java.lang.String fieldName)
                       throws mks.frame.triggers.TriggerException
        Has the field changed? Note this is a remembered value: once set, it remains set. In other words, if a field is changed by the user, but then any trigger code changes it back, it will still appear changed. Further, if it was unchanged by the user, and trigger code changes it, then it will appear changed.
        If the field is an FVA, then it will only indicate a change if there was an edit against the FVA, not if the relationship to the target item is changed.
        Throws:
        mks.frame.triggers.TriggerException

      • isFieldReallyChanged

        public boolean isFieldReallyChanged​(java.lang.String fieldName)
                             throws mks.frame.triggers.TriggerException
        Has the field really changed? Note that this is the value now, if some code in a trigger changes the value back to the old value, this will now indicate false.
        If the field is an FVA, then it will only indicate a change if there was an edit against the FVA, not if the relationship to the target item is changed.
        Throws:
        mks.frame.triggers.TriggerException

      • clearFieldChange

        public void clearFieldChange​(java.lang.String fieldName)
                      throws mks.frame.triggers.TriggerException
        Remove any change to a field from the delta. Rather than setting a field to the same value as the base edit, you can completely remove the edit by removing the change.
        Throws:
        mks.frame.triggers.TriggerException

      • setFieldValue

        public void setFieldValue​(java.lang.String fieldName,
                          double value)
                   throws mks.frame.triggers.TriggerException
        Change the value of a field by name. The field type must be of type float, integer, or date. In the case of a date, the value must be a numeric time value, such as that returned by new Date().valueOf() which returns the current time.
        Throws:
        mks.frame.triggers.TriggerException -
        • If the field is a computed field
        • If the field is not a floating point, integer, or date field.
        See Also:
        for comments on updating FVAs.

      • setFieldValue

        public void setFieldValue​(java.lang.String fieldName,
                          boolean value)
                   throws mks.frame.triggers.TriggerException
        Change the value of a field by name. The field type must be of type boolean.
        Throws:
        mks.frame.triggers.TriggerException -
        • If the field is a computed field
        • If the field is not a boolean field
        See Also:
        for comments on updating FVAs.

      • setSetFieldValue

        public void setSetFieldValue​(java.lang.String fieldName,
                             java.util.Set<java.lang.String> value)
                      throws mks.frame.triggers.TriggerException
        Change the value of a field by name. The field must be a multi-valued field. The value must be a Set of Strings and not null.
        Parameters:
        fieldName - the name of the field to set
        value - the Set of values
        Throws:
        mks.frame.triggers.TriggerException
        See Also:
        for further comments

      • setFieldValue

        public void setFieldValue​(java.lang.String fieldName,
                          java.lang.String value)
                   throws mks.frame.triggers.TriggerException
        Change the value of a field by name. The value must be representable by a string. e.g. for an integer field, the string must be parsable as an integer, for a user field, the string must be a user name.
        • The value may be null. This unsets the field.

          For "State" or "Project" field, "" (empty string) also unsets the field.

        • If "State" field is unset, it is the same as setting the state to "Unspecified"; "Unspecified" is an acceptable value for the field.
        • For a date field, the format is always mm/dd/yyyy.
        • For a logging text field, this is the new string value to get appended to/prefixed to the existing string value.
        • For a picklist, the string must be a valid the pick string, or a pick number. If the pick list allows multiple values, then the string may consist of multiple values separated by commas.
        • An issue backed pick list (ibpl) is the same as a picklist: you can either specify the pick string, or the pick number. In this case, the pick number is actually the issue id.
        • For a relationship field, the value is a comma-separated list of issue values; each value optionally followed by one or more link flag characters.
        • Attachment fields cannot be set using this method. Use the addAttachment or removeAttachment method instead.
        • If the field is an FVA, you will be able to update only if the target issue has not already fired its issue changed pre-trigger. This is required in order to ensure that all trigger contracts are honoured. In general permissions are bypassed by triggers, however, if the editability rule on the field is set to simply (false), the assumption is that the field is not intended for update, and an exception will be thrown. Note that other exceptions dependent on the actual issue data will not be thrown until the actual assignment is attempted: for example, if the relationship field used by the FVA is empty.
        Throws:
        mks.frame.triggers.TriggerException - An appropriate error message is returned in a TriggerException in the following cases:
        • The field name isn't known
        • If the field is of user type, the value is an unknown user
        • If the field is of pick type, the value isn't a valid pick value string, or if a number isn't a valid pick value.
        • Various field constraints are violated. For example, for an integer field if the value is out of the valid min/max range specified for the field.
        • If the field is a computed field
        • If the field is an FVA which has a false editability rule
        • If the field is an FVA to a field which cannot be updated, for example Type or State.
        • If the field is a source trace field. Modifications of source traces are not supported.
        • If the new Rich Text field value contains an item link "AsOf" an unparseable date. For example:
          ...a href=mks:///item?itemid=50&asof=date...
        • Any attempt to perform a significant edit on a Document Node which is referenced in Share mode

      • setPickFieldValue

        public void setPickFieldValue​(java.lang.String fieldName,
                              java.util.Set<?> value)
                       throws mks.frame.triggers.TriggerException
        Assignment of a set to a multi-valued pick field. Each member of the set must be a String, which is a valid string for this picklist field.

        Example: 

         var values = new java.util.HashSet();
 values.add("pick-value1");
 values.add("pick-value15");
 values.add("pick-value25");
 issueBean.setPickFieldValue("MyPickField", values);
        If any value is invalid, an exception will be thrown.
        Throws:
        mks.frame.triggers.TriggerException

      • setRelationshipFieldValue

        public void setRelationshipFieldValue​(java.lang.String fieldName,
                                      java.util.Collection<?> c)
                               throws mks.frame.triggers.TriggerException
        Assign to a relationship field.
        Parameters:
        fieldName - A relationship field name
        c - A java Collection object containing potentially a mixture of various objects:
        Strings, in which case they should have a comma-delimited list of issue numbers; each possibly followed by its link flag characters;
        ScriptRelationshipBean
        a javascript number, being the target issue number
        null is ignored
        Throws:
        mks.frame.triggers.TriggerException - if the field is not a relationship field, or if any object in the Collection is not of one of the specified types.

      • setRelationshipFieldValue

        public void setRelationshipFieldValue​(java.lang.String fieldName,
                                      int[] value)
                               throws mks.frame.triggers.TriggerException
        Set a relationship field to an array of integers. Each integer is an issue id number to create a relationship to.
        Parameters:
        fieldName - A relationship field name
        value - An integer array of issue numbers. If any issue is invalid you will not receive an error from this method, rather it will occur after the trigger has run.
        Throws:
        mks.frame.triggers.TriggerException - if the field is not a relationship field.

      • setRelationshipFieldValue

        public void setRelationshipFieldValue​(java.lang.String fieldName,
                                      java.lang.Object[] values)
                               throws mks.frame.triggers.TriggerException
        Assign to a relationship field.
        Parameters:
        fieldName - A relationship field name
        values - An array containing potentially a mixture of various objects:
        Strings, in which case they should have a comma-delimited list of issue numbers; each possibly followed by its link flag characters;
        ScriptRelationshipBean
        a javascript number, being the target issue number
        null is ignored
        Throws:
        mks.frame.triggers.TriggerException - if the field is not a relationship field, or if any object in the Collection is not of one of the specified types.

      • setDateFieldValue

        public void setDateFieldValue​(java.lang.String fieldName,
                              java.util.Date value)
                       throws mks.frame.triggers.TriggerException
        Set a date field value. Note that you should use this method to make an assignment to a date field, if you are using a java Date object. If you have a string in the format mm/dd/yyyy then you should use setFieldValue; if you have a number in seconds since the epoch you should also use setFieldValue
        Throws:
        mks.frame.triggers.TriggerException - if the field name doesn't exist, is readonly, is not a date field, or the date is out of range.

      • setAssignedGroup

        public void setAssignedGroup​(java.lang.String value)
                      throws mks.frame.triggers.TriggerException
        Change the value of the "Assigned Group" field.
        Parameters:
        value - a group name as the new value for the field "Assigned Group"; null unsets the field
        Throws:
        mks.frame.triggers.TriggerException - if the group does not exist

      • setAssignedUser

        public void setAssignedUser​(java.lang.String value)
                     throws mks.frame.triggers.TriggerException
        Change the value of the "Assigned User" field.
        Parameters:
        value - a user name as the new value for the field "Assigned User"; null unsets the field
        Throws:
        mks.frame.triggers.TriggerException - if the user does not exist

      • setProject

        public void setProject​(java.lang.String value)
                throws mks.frame.triggers.TriggerException
        Change the value of the "Project" field.
        Parameters:
        value - a project name as the new value for the field "Project"; both null and "" unset the field
        Throws:
        mks.frame.triggers.TriggerException - if the project does not exist

      • setState

        public void setState​(java.lang.String value)
              throws mks.frame.triggers.TriggerException
        Change the value of the "State" field.
        Parameters:
        value - a state name as the new value for the field "State"; null, "", and "Unspecified" all set the issue state to "Unspecified"
        Throws:
        mks.frame.triggers.TriggerException - if the state does not exist

      • setSummary

        public void setSummary​(java.lang.String value)
                throws mks.frame.triggers.TriggerException
        Change the value of the "Summary" field.
        Parameters:
        value - summary text as the new value for the field "Summary"; null unsets the field
        Throws:
        mks.frame.triggers.TriggerException - if there is a problem

      • setSignatureComment

        public void setSignatureComment​(java.lang.String value)
                         throws mks.frame.triggers.TriggerException
        Change the value of the "Signature Comment" field.
        Throws:
        mks.frame.triggers.TriggerException

      • addRelatedIssue

        public void addRelatedIssue​(int issueID)
                     throws mks.frame.triggers.TriggerException
        Add the specified issue to the default relationship field.

        This version of addRelatedIssue will always operate against the historic relationships; i.e. the field now normally named Forward Relationships.

        Throws:
        mks.frame.triggers.TriggerException
        See Also:
        addRelatedIssue(String fieldName, int issueID)

      • addRelatedIssue

        public void addRelatedIssue​(java.lang.String fieldName,
                            int issueID)
                     throws mks.frame.triggers.TriggerException
        Add a related issue to the specified field of this issue. If the issue is already scheduled to be added in the current delta, do nothing. If the issue is already scheduled to be removed in the current delta, remove it from the remove list; i.e. it will not be removed.

        You cannot manipulate pointers to this issue from this bean. You must obtain the bean for the other issue, and add this issue to its relationships.

        If the issue to be added is already linked to this issue, or already added to the link list, the request is ignored.

        Parameters:
        fieldName - The name of the relationship field
        issueID - The issue number to add to the current relationships in that field.
        Throws:
        mks.frame.triggers.TriggerException -
        • If the issue number is invalid.
        • If the link is to this issue
        Other exceptions may occur during the commiting of the issue.

      • getAddedRelatedIssues

        public int[] getAddedRelatedIssues()
                            throws mks.frame.triggers.TriggerException
        Fetch the list of newly added issue relationships, on the default Outward Relationship field.
        Returns:
        an array of integers, one for each newly added relationship. Returns a null if there are none.
        Throws:
        mks.frame.triggers.TriggerException

      • getAddedRelatedIssues

        public int[] getAddedRelatedIssues​(java.lang.String fieldName)
                            throws mks.frame.triggers.TriggerException
        Fetch the list of newly added issue relationships, on the specified relationship field.
        Returns:
        an array of integers, one for each newly added relationship. Returns a null if there are none.
        Throws:
        mks.frame.triggers.TriggerException -
        • The specified field does not exist
        • The specified field is not a relationship field

      • removeRelatedIssue

        public void removeRelatedIssue​(int issueID)
                        throws mks.frame.triggers.TriggerException
        Remove the specified issue from the default Outward Relationship field.

        This version of removeRelatedIssue will always operate against the historic relationships; i.e. the field now normally named Forward Relationships.

        Throws:
        mks.frame.triggers.TriggerException
        See Also:
        removeRelatedIssue(String fieldName, int issueID)

      • removeRelatedIssue

        public void removeRelatedIssue​(java.lang.String fieldName,
                               int issueID)
                        throws mks.frame.triggers.TriggerException
        Remove a related issue from the specified field of this issue. If the issue is not in the current list of links, remove it.

        To manipulate pointers to this issue, you either need to obtain the bean for the pointed at issue and manipulate that one thru this field; or you must know the paired field name and manipulate that field instead.

        Throws:
        mks.frame.triggers.TriggerException -
        • If the issue to be removed is not related to this issue.
        • If the issue number is invalid.
        • The specified field does not exist
        • The specified field is not a relationship field

      • getRemovedRelatedIssues

        public int[] getRemovedRelatedIssues()
                              throws mks.frame.triggers.TriggerException
        Fetch the list of newly removed issue relationships, on the default Forward Relationships fields.
        Returns:
        an array of integers, one for each newly removed relationship. Returns a null if there are none.
        Throws:
        mks.frame.triggers.TriggerException

      • getRemovedRelatedIssues

        public int[] getRemovedRelatedIssues​(java.lang.String fieldName)
                              throws mks.frame.triggers.TriggerException
        Fetch the list of newly removed issue relationships, on the specified relationship field.
        Returns:
        an array of integers, one for each newly removed relationship. Returns a null if there are none.
        Throws:
        mks.frame.triggers.TriggerException -
        • The specified field does not exist
        • The specified field is not a relationship field

      • 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
        Overrides:
        getExposedName in class LocalTriggerManager.ScriptIssueBean
        Returns:
        the bean name: imIssueDeltaBean.

      • getFieldDeltaCount

        public int getFieldDeltaCount()
        How many fields have been modified as part of this issue changed event? This is the full, accumulated count of all fields which have changed, both by the user, and any prior event triggers which have run, including this trigger itself.

      • isDeltaEmpty

        public boolean isDeltaEmpty()
        Are there any modifications made as part of this issue changed event? This will be true even if the original user didn't modify the issue, but one of the event triggers has done so, including this event trigger itself.

      • getDeltaFieldNames

        public java.lang.String[] getDeltaFieldNames()
        Return the full list of modified field names. This is the full, accumulated list of all fields which have changed, both by the user, and any prior event triggers which have run, including this trigger itself.
        This list will include FVAs which have been modified by the delta. It will not include FVAs which changed because their target item changed.

      • getAddedAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getAddedAttachmentBeans​(java.lang.String fieldName)
                                                                   throws mks.frame.triggers.TriggerException
        Fetch a list of added attachment beans for this issue.
        Parameters:
        fieldName - the name of the field to get added attachments from
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getAddedAttachmentBeans

        @Deprecated
public LocalTriggerManager.ScriptAttachmentBean[] getAddedAttachmentBeans​(int fieldID)
                                                                   throws mks.frame.triggers.TriggerException
        Deprecated.
        Fetch a list of added attachment beans for this issue.
        Parameters:
        fieldID - the ID of the field to get added attachments from
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getAddedAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getAddedAttachmentBeans()
                                                                   throws mks.frame.triggers.TriggerException
        Fetch a list of attachment beans that were added to the default Attachments field
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getRemovedAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getRemovedAttachmentBeans()
                                                                     throws mks.frame.triggers.TriggerException
        Fetch a list of attachment beans that were removed from the default Attachments field
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getRemovedAttachmentBeans

        public LocalTriggerManager.ScriptAttachmentBean[] getRemovedAttachmentBeans​(java.lang.String fieldName)
                                                                     throws mks.frame.triggers.TriggerException
        Fetch a list of removed attachment beans for this issue.
        Parameters:
        fieldName - the name of the field to get removed attachments from
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • getRemovedAttachmentBeans

        @Deprecated
public LocalTriggerManager.ScriptAttachmentBean[] getRemovedAttachmentBeans​(int fieldID)
                                                                     throws mks.frame.triggers.TriggerException
        Deprecated.
        Fetch a list of removed attachment beans for this issue.
        Parameters:
        fieldID - the ID of the field to get removed attachments from
        Returns:
        an array of imAttachmentBean objects.
        Throws:
        mks.frame.triggers.TriggerException

      • addAttachment

        public LocalTriggerManager.ScriptAttachmentBean addAttachment​(java.lang.String filename)
                                                       throws mks.frame.triggers.TriggerException
        Add an attachment to the issue. Assumes no mimetype.
        Parameters:
        filename - the absolute path of the attachment
        Returns:
        the ScriptAttachmentBean for the attachment
        Throws:
        mks.frame.triggers.TriggerException - if the attachment already exists, Engine errors creating the attachment

      • addAttachment

        public LocalTriggerManager.ScriptAttachmentBean addAttachment​(java.lang.String filename,
                                                              java.lang.String mimeType)
                                                       throws mks.frame.triggers.TriggerException
        Add an attachment to the issue. Assumes no mimetype.
        Parameters:
        filename - the absolute path of the attachment
        Returns:
        the ScriptAttachmentBean for the attachment
        Throws:
        mks.frame.triggers.TriggerException - if the attachment already exists, Engine errors creating the attachment

      • addAttachment

        public LocalTriggerManager.ScriptAttachmentBean addAttachment​(java.lang.String filename,
                                                              java.lang.String mimeType,
                                                              java.lang.String fieldName)
                                                       throws mks.frame.triggers.TriggerException
        Add an attachment to the issue
        Parameters:
        filename - the absolute path of the attachment
        mimeType - the mime-type of the attachment. Its is the caller's responsibility to ensure that this type is valid.
        fieldName - the name of the field to add the attachment to
        Returns:
        the ScriptAttachmentBean for the attachment
        Throws:
        mks.frame.triggers.TriggerException - if the attachment already exists, Engine errors creating the attachment

      • addAttachment

        @Deprecated
public LocalTriggerManager.ScriptAttachmentBean addAttachment​(java.lang.String filename,
                                                              java.lang.String mimeType,
                                                              int fieldID)
                                                       throws mks.frame.triggers.TriggerException
        Deprecated.
        Add an attachment to the issue
        Parameters:
        filename - the absolute path of the attachment
        mimeType - the mime-type of the attachment. Its is the caller's responsibility to ensure that this type is valid.
        fieldID - the ID of the field to add the attachment to
        Returns:
        the ScriptAttachmentBean for the attachment
        Throws:
        mks.frame.triggers.TriggerException - if the attachment already exists, Engine errors creating the attachment

      • removeAttachment

        public void removeAttachment​(java.lang.String filename)
                      throws mks.frame.triggers.TriggerException
        Remove an attachment from the issue
        Parameters:
        filename - the filename to remove
        Throws:
        mks.frame.triggers.TriggerException - if the attachment doesn't exist already

      • removeAttachment

        public void removeAttachment​(java.lang.String filename,
                             java.lang.String fieldName)
                      throws mks.frame.triggers.TriggerException
        Remove an attachment from the issue
        Parameters:
        filename - the filename to remove
        fieldName - the name of the field to remove the attachment from
        Throws:
        mks.frame.triggers.TriggerException - if the attachment doesn't exist already

      • removeAttachment

        @Deprecated
public void removeAttachment​(java.lang.String filename,
                             int fieldID)
                      throws mks.frame.triggers.TriggerException
        Deprecated.
        Remove an attachment from the issue
        Parameters:
        filename - the filename to remove
        fieldID - the ID of the field to remove the attachment from
        Throws:
        mks.frame.triggers.TriggerException - if the attachment doesn't exist already

      • createSegment

        public LocalTriggerManager.ScriptIssueDeltaBean createSegment​(java.lang.String typeName,
                                                              java.lang.String category,
                                                              java.lang.String position,
                                                              boolean isReference)
                                                       throws mks.frame.triggers.TriggerException
        Create a document model segment. It will be placed under the current item, which must be either a document segment, or a document node.
        Parameters:
        typeName - The name of the type. The type must be a document model segment, and must be a legal type for for heterogeneous support for the parent document.
        category - The value of the Category field. A null value indicates to use the default.
        position - A string indicating at what position to insert the new content. Valid values are:
        1. first the first child
        2. last the last child
        3. before:number before the specified position
        4. after:number after the specified position
        5. number at exactly the specified position
        isReference - if true, the new document is referenced otherwise it is included.
        Returns:
        The IssueDeltaBean for the newly created segment. Additional fields can be set on the returned bean. Any mandatory fields must be set on the returned bean, or an exception will be thrown when the created segment is saved.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item is not a node or a segment
        2. If the position string is null or not valid
        3. If the category is not a legal value for this document
        4. If the category is not of type segment
        5. If the current item is in a group document
        6. Various errors if the document types are not correctly configured

      • insertSegment

        public void insertSegment​(LocalTriggerManager.ScriptIssueDeltaBean parentIDB,
                          java.lang.String position,
                          boolean isReference)
                   throws mks.frame.triggers.TriggerException
        Insert a document model segment, under a specified parent. The current item must be a segment.
        Parameters:
        parentIDB - The Issue Delta Bean for a parent item. The parent must be document segment or node.
        position - A string indicating at what position to insert the new content. Valid values are:
        1. first the first child
        2. last the last child
        3. before:number before the specified position
        4. after:number after the specified position
        5. number at exactly the specified position
        isReference - if true, the document is referenced otherwise it is included.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item is not a segment
        2. If the parent is not a segment or a node
        3. If the position string is null or not valid
        4. If the current item is in a group document
        5. Various errors if the document types are not correctly configured

      • createContent

        public LocalTriggerManager.ScriptIssueDeltaBean createContent​(java.lang.String category,
                                                              java.lang.String position)
                                                       throws mks.frame.triggers.TriggerException
        Create a document model node/shared item pair. They will be placed under the current item, which must be either a document segment, or a document node.
        Parameters:
        category - The value of the Category field. A null value indicates to use the default.
        position - A string indicating at what position to insert the new content. Valid values are:
        1. first the first child
        2. last the last child
        3. before:number before the specified position
        4. after:number after the specified position
        5. number at exactly the specified position
        Returns:
        The IssueDeltaBean for the newly created node. Additional fields can be set on the returned bean.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item is not a node or a segment
        2. If the position string is null or not valid
        3. If the category is not a legal value for this document
        4. If this document is a group document and the category is meaningful.
        5. If the category is of type segment
        6. Various errors if the document types are not correctly configured

      • removeContent

        public void removeContent()
                   throws mks.frame.triggers.TriggerException
        Remove the current node from it's parent node or segment. This issue must be a node or a segment.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item does not have a parent
        2. If this item is not a node or subsegment.

      • changeSegmentProject

        public void changeSegmentProject​(java.lang.String project)
                          throws mks.frame.triggers.TriggerException
        Change the project for a document. The project is recursively changed for the current segment.
        Parameters:
        project - The new project name.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item is not a segment
        2. If the project is not valid.

      • revision

        public void revision​(boolean incrementMajor,
                     boolean conditionalModified,
                     boolean conditionalSignificantEdit,
                     boolean recurse,
                     boolean recurseInclude,
                     boolean recurseReference)
              throws mks.frame.triggers.TriggerException
        Version document content. The current delta must be either a segment, or a node. The actual list of items which will be revisioned is the current item, plus any items reached subject to the recursion parameters; subject to the conditional arguments. Each such item must not have already run their pre-triggers; this operation is equivalent to an item edit. As such, an item edit trigger will run for each such item (except this one, since this one is in progress). You can test to see if a particular item was revisioned by invoking the isIncrementMajor()/isIncrementMinor() methods on those deltas. However, items for which the condition causes them not to be revisioned, will not have an item edit trigger unless there is some other modification -- triggers are not fired when a delta is empty.

        As we are running in a trigger, permissions are bypassed. This call will succeed if the end-user does not have project or type visibility.

        This operation is transactional, in other words, all will succeed, or all will fail. All revision timestamps, and all modified dates will end up identical.

        Parameters:
        incrementMajor - If set to true, then the revision operation will increment the major part of the revision; otherwise it will increment the minor.
        conditionalModified - This options is now ignored and always internally set to false Conditional revisioning. Only revision a given item if its Modified Date is larger than its Revision Date.
        conditionalSignificantEdit - This options is now ignored and always internally set to true Conditional revisioning. Only revision a given item if the field Significant Change Since Item Revision is true. In other words, revision a node if there has been a significant edit since the last revision operation.
        recurse - Recurse into any children in the document structure of this item. If this is a Segment or a node that points to a Segment, the options is ignored and always internally set to true. If this is a node with children, then recurse through the children.
        recurseReference - This options is now ignored and always internally set to true Recurse into any children which are referenced subdocuments.
        recurseInclude - This options is now ignored and always internally set to true Recurse into any children which are included subdocuments.
        Throws:
        mks.frame.triggers.TriggerException -
        1. If this item is not a node or a segment

      • createCustomField

        public LocalTriggerManager.ScriptCustomFieldBean createCustomField​(java.lang.String name,
                                                                   java.lang.String dataType,
                                                                   java.lang.String description,
                                                                   java.lang.Object defaultValue)
                                                            throws mks.frame.triggers.TriggerException
        Create a new custom field definition. Note that this will add a new custom field definition only if the field with the name provided does not exist. If a field with the name already exist Exception will be thrown.
        Parameters:
        name - custom field name.
        dataType - the datatype of the custom field. either: integer, float, shorttext, logical, date
        description - description of the custom field.
        defaultValue - default value of the custom field. The default value will be a java object according to the data type of the custom field definition.
        • Integer: Java 'Integer' object
        • Boolean: Java 'Boolean' object
        • Float: Java 'Double' object
        • Date: Java 'Date' object
        • Text: Java 'String' object.
        Returns:
        newly created custom field definition.
        Throws:
        mks.frame.triggers.TriggerException

      • createCustomField

        public LocalTriggerManager.ScriptCustomFieldBean createCustomField​(java.lang.String name,
                                                                   java.lang.String dataType,
                                                                   java.lang.String description,
                                                                   java.lang.Object defaultValue,
                                                                   java.util.Map<java.lang.String,​java.lang.Integer> allowedPicks)
                                                            throws mks.frame.triggers.TriggerException
        Create a new custom field definition. Note that this will add a new custom field definition only if the field with the name provided does not exist. If a field with the name already exist Exception will be thrown.
        Parameters:
        name - custom field name.
        dataType - the datatype of the custom field. either: integer, float, shorttext, logical, date, pick.
        description - description of the custom field.
        defaultValue - default value of the custom field. The default value will be a java object according to the data type of the custom field definition.
        • Integer: Java 'Integer' object
        • Boolean: Java 'Boolean' object
        • Float: Java 'Double' object
        • Pick: Java 'String' representing the pick name must be one of the key in the allowed picks.
        • Date: Java 'Date' object
        • Text: Java 'String' object.
        allowedPicks - the allowed picks. This is a map of String to Integer values.
        Returns:
        newly created custom field definition.
        Throws:
        mks.frame.triggers.TriggerException

      • removeCustomField

        public LocalTriggerManager.ScriptCustomFieldBean removeCustomField​(java.lang.String name)
                                                            throws mks.frame.triggers.TriggerException,
                                                                   mks.ci.exception.CIException
        Remove the custom field definition. If a field with the name does not exist Exception will be thrown.
        Parameters:
        name - name of custom field to remove.
        Returns:
        removed custom field bean.
        Throws:
        mks.frame.triggers.TriggerException
        mks.ci.exception.CIException

      • setCustomField

        public LocalTriggerManager.ScriptCustomFieldBean setCustomField​(java.lang.String name,
                                                                java.lang.String newName,
                                                                java.lang.String description,
                                                                java.lang.Object defaultValue)
                                                         throws mks.frame.triggers.TriggerException
        Updates the custom field definition. Updates only if the custom field already exist, if not found throws exception.
        Parameters:
        name - name of the existing custom field definition.
        newName - new name of the custom field.
        description - derscription of the custom field.
        defaultValue - default value of the custom field. The default value will be a java object according to the data type of the custom field definition.
        • Integer: Java 'Integer' object
        • Boolean: Java 'Boolean' object
        • Float: Java 'Double' object
        • Pick: Java 'String' representing the pick name must be one of the valid picks in the field.
        • Date: Java 'Date' object
        • Text: Java 'String' object.
        Returns:
        updated instance of the custom field bean.
        Throws:
        mks.frame.triggers.TriggerException

      • setCustomField

        public LocalTriggerManager.ScriptCustomFieldBean setCustomField​(java.lang.String name,
                                                                java.lang.String newName,
                                                                java.lang.String description,
                                                                java.lang.Object defaultValue,
                                                                java.util.Map<java.lang.String,​java.lang.Integer> allowedPicks)
                                                         throws mks.frame.triggers.TriggerException
        Updates the custom field definition. Updates only if the custom field already exist, if not found throws exception.
        Parameters:
        name - name of the existing custom field definition.
        newName - new name of the custom field.
        description - derscription of the custom field.
        defaultValue - default value of the custom field. The default value will be a java object according to the data type of the custom field definition.
        • Integer: Java 'Integer' object
        • Boolean: Java 'Boolean' object
        • Float: Java 'Double' object
        • Pick: Java 'String' representing the pick name must be one of the key in the allowed picks.
        • Date: Java 'Date' object
        • Text: Java 'String' object.
        allowedPicks - the allowed pick values of the custom field. Note: The allowedPicks replaces the existing allowed picks for the field.
        Returns:
        updated instance of the custom field bean.
        Throws:
        mks.frame.triggers.TriggerException

      • setCustomFieldValue

        public LocalTriggerManager.ScriptCustomFieldValueBean setCustomFieldValue​(java.lang.String name,
                                                                          java.lang.Object value)
                                                                   throws mks.frame.triggers.TriggerException
        Sets a custom field value for a custom field. Throws exception if a field with name does not exist.
        Parameters:
        name - custom field name.
        value - value of the custom field. The default value will be a java object according to the data type of the custom field definition.
        • Integer: Java 'Integer' object
        • Boolean: Java 'Boolean' object
        • Float: Java 'Double' object
        • Pick: Java 'String' representing the pick name must be one of the key in the allowed picks.
        • Date: Java 'Date' object
        • Text: Java 'String' object.
        Returns:
        returns the created custom field value bean instance.
        Throws:
        mks.frame.triggers.TriggerException

      • setOperation

        public void setOperation​(java.lang.String operation)

      • getVersionDescription

        public java.lang.String getVersionDescription()
        Specified by:
        getVersionDescription in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • setVersionDescription

        public void setVersionDescription​(java.lang.String versionDescription)
        Specified by:
        setVersionDescription in interface mks.ci.server.engine.IScriptIssueDeltaBean

      • copyDateFieldValue

        public void copyDateFieldValue​(java.lang.String sourceField,
                               java.lang.String targetField)
                        throws mks.frame.triggers.TriggerException
        Copy the original value of a date-only field to another date-only field preserving time zone.
        Parameters:
        sourceField - the name of the source field
        targetField - the name of the target field
        Throws:
        mks.frame.triggers.TriggerException - if the source or target fields are not date-only fields or the source/target fields don't exist

      • copyDateFieldValue

        public void copyDateFieldValue​(LocalTriggerManager.ScriptIssueBean sourceItem,
                               java.lang.String sourceField,
                               java.lang.String targetField)
                        throws mks.frame.triggers.TriggerException
        Copy the original value of a date-only field of another item to another date-only field preserving time zone.
        Parameters:
        sourceItem - the bean corresponding to the item containing the source field
        sourceField - the name of the source field
        targetField - the name of the target field
        Throws:
        mks.frame.triggers.TriggerException - if the source or target fields are not date-only fields or the source/target fields don't exist

      • copyNewDateFieldValue

        public void copyNewDateFieldValue​(java.lang.String sourceField,
                                  java.lang.String targetField)
                           throws mks.frame.triggers.TriggerException
        Copy the new value of a date-only field to another date-only field preserving time zone.
        Parameters:
        sourceField - the name of the source field
        targetField - the name of the target field
        Throws:
        mks.frame.triggers.TriggerException - if the source or target fields are not date-only fields or the source/target fields don't exist

      • copyNewDateFieldValue

        public void copyNewDateFieldValue​(LocalTriggerManager.ScriptIssueDeltaBean sourceItem,
                                  java.lang.String sourceField,
                                  java.lang.String targetField)
                           throws mks.frame.triggers.TriggerException
        Copy the original value of a date-only field of another item to another date-only field preserving time zone.
        Parameters:
        sourceItem - the bean corresponding to the item containing the source field
        sourceField - the name of the source field
        targetField - the name of the target field
        Throws:
        mks.frame.triggers.TriggerException - if the source or target fields are not date-only fields or the source/target fields don't exist

      • markSuspectOnOSLCLinks

        public void markSuspectOnOSLCLinks​(java.lang.String ServerID)
                            throws mks.frame.triggers.TriggerException
        This method will run on all the outgoing OSLC link of issue. If the OSLC resource is modified then this will update the suspect flag on Windchill RV&S server. Also if the Title of the OSLC resource is modified then the title will also get updated.
        Parameters:
        ServerID - Trigger should run against links created from this server
        Throws:
        mks.frame.triggers.TriggerException

      • requiresSignature

        public boolean requiresSignature()
        This method will return if signature is required for the item. It also determines whether to store the signature information against this delta in the database.
        -For batch edit, the default value for this flag is false.
        -For single item edit, the default value for this flag is true.
        Returns:
        true if requires signature, else false.
        See Also:
        setRequiresSignature(boolean)

      • setRequiresSignature

        public void setRequiresSignature​(boolean isSignatureRequired)
        Use this method to enable storing of signature in the item delta. Change in this flag is recommended for batch edit only. In the user-selected list of items, this flag must be set to true for the items that require signature.
        By default:
        -For batch edit, this flag is false for all the items in the user-selected list.
        -For single item edit, this flag is true.
        Parameters:
        isSignatureRequired - true if the item being edited requires signature.