Plugin methods and method calls

requiresAuthentication

This method is expected to return true if it requires the framework to request credentials from the user for any bug-tracking operation.

This returns true, except when the plugin gets its credentials using a different mechanism, such as from the credential store or if the plugin interacts with the bug-tracking system asynchronously and not in real time. If the method returns false, the system passes null for all the UserAuthenticationStore parameters of the plugin methods.

Used by the plugin framework to get the list of bug parameters the plugin needs to submit batch bugs. Provides default or null values. The BugTrackerPlugin.setConfiguration(java.util.Map) method is called on the plugin instance before this method is invoked. Parameter choice lists and defaults can be made dynamic by having the implementation go to the bug tracking system to determine the list of valid choices.

getConfiguration

The plugin framework uses this method to get metadata about the questions to be presented to the user during plugin configuration. The return value is a list of BugTrackerConfig objects that provide required information about the configuration item. Each item corresponds to a text box in the user interface. The value field of each item specifies the default value for the text box.

setConfiguration (call)

After you select the bug-tracking system for the application version and save the configuration to the database, all future interactions with the plugin are preceded by the setConfiguration call, which sets the configuration for the plugin using which operations are to be carried out.

testConfiguration (call)

The plugin framework uses the testConfiguration call to test the configuration previously set using the setConfiguration call. This method is expected to hit the bug‑tracking system using the configuration details set and validate them to the fullest extent possible. The user credentials are fetched from the user if this plugin declared that it requires authentication.

getShortDisplayName

The getShortDisplayName method returns a short display name for the plugin. This string populates the list of available bug tracker plugins.

getLongDisplayName

The getLongDisplayName method returns a value that includes additional identification of the bug tracking system obtained from the configuration. This method is used, for example, when the user is prompted to provide credentials for a bug‑tracking system.

getBugParameters

The getBugParameters method returns metadata about the bug parameters to present to users. Application Security supports the following three bug parameter types:

• BugParamText translates to a text box.
• BugParamTextArea translates to a multiple‑line text box and is typically used for bug descriptions.
• BugParamChoice translates to a list.
• The issueDetail object encompasses the details of the issue for which the user is attempting to log a bug. This defaults to several bug parameters such as the description and summary, which can be extracted from this object. The pluginHelper protected member has a helper method to build a suggested default bug description. (See Plugin Helper.)

If a user changes the value of a parameter in the user interface, this method fetches the updated choice list for other batch bug parameters. The BugTrackerPlugin.setConfiguration(Map) method is called on the plugin instance before this method is invoked. If the BugParamChoice.getHasDependentParams() attribute for a plugin bug parameter is set to true, then this method is called whenever the parameter value changes in the user interface layer.

Recommendations:

• Act on each bug parameter that has dependent parameters.
• Do not forget to handle the case in which a parameter value changes to null (no selection made).
• Do not forget to set the parameter value in return list to null when its choices change.
• Before you add a new parameter, ensure that it is not already in the return list.
• Return null if there is no change

• Use either of the following strategies:

  • Modify the currentValues parameter and return it.
  • Construct the return value from the raw parameters maintained. Set the values and choice lists before returning.

onParameterChange

The plugin framework calls the onParameterChange method whenever the value for a bug parameter marked as hasDependentParams (see BugParamChoice class javadoc) changes. This method can take action and return a new list of bug parameters to display.

Keep the following guidelines in mind:

• Act on each bug parameter that has dependent parameters.
• Do not forget handling case when parameter value changes to null (no selection made).
• Do not forget to set the parameter value in a return list to null when its selections change.
• Before you add a new parameter, check the return list to ensure that it does not already include the parameter.
• Return null if there is no change.

• Use one of the following strategies:

  • Modify the currentValues parameter and return it.
  • Construct the return value from raw parameters maintained. Set values and choice lists before returning.

fileBug

This method files a bug on the external bug‑tracking system. The BugSubmission object passed encompasses all bug details.

Ensure that you correctly differentiate between the bug.getIssueDetail() object and the bug.getParams()object. The bug.getIssueDetail() object returns details of the issue, whereas the bug.getParams() object returns the bug parameter values that the user provides.

If you added Bug Description as a user‑editable bug parameter, then fetch the bug description from the bug.getParams() object instead of from the bug.getIssueDetail()object. The return value of the fileBug object must be a bugId, which can be used to fetch the bug with the fetchBug method and formulate the deep link with the getBugDeepLink method.

Use fields in BugSubmission.getIssueDetail(), namely getLastBuildWithoutIssue(), getDetectedInBuild(), and getFileName() to perform changeset discovery if you have access to your repository.

File bugs that contain multiple issues on the bug tracking system. The BugTrackerPlugin.setConfiguration(Map) method is called on the plugin instance before this method is invoked.

Recommendations:

• Application Security provides the summary and description obtained using MultiIssueBugSubmission.getIssueDetails(). The user does not supply these values. If you added the summary and description as bug parameters, use bug.getParams() to retrieve the user-supplied values.

• If you have access to your repository, use the getLastBuildWithoutIssue(), getDetectedInBuild(), and getFileName()fields in MultiIssueBugSubmission.getIssueDetails() to perform changeset discovery.

fetchBug

This method fetches the current bug status.

getBugDeepLink

This method formulates a deep link to the bug. If the bug tracker does not support a deep link, return null.