Package com.atlassian.jira.issue

Interface IssueInputParameters

All Known Implementing Classes:
IssueInputParametersImpl
@PublicApi public interface IssueInputParameters
This represents an issue builder and can be used to provide parameters that can be used to create and update an issue through the IssueService.

Any fields that are set on this object will have the values used for validation and population of the issue object created via the validate methods on the IssueService. This object is forgiving as possible so if you try to set a null value for a field no exceptions will be thrown, the value will just be ignored.

Some users might want to provide a FieldValuesHolder to the validation calls with some pre-populated data, if this is the case then you can set the field values holder on this object and the IssueService will clone the contents and pass them along to any field invocations it might make.

If you wish to indicate to the IssueService that you do not want to validate against all fields configured for the create screen then you can set the setProvidedFields(java.util.Collection) with the field id's that you want to have validated. All other fields that exist on the screen will be populated with the system default.

To construct a new IssueInputParameters object you can call IssueService.newIssueInputParameters().

NOTE: this object is not thread-safe and is only meant to be used as a transport object.

Since:
v4.1
See Also:

  • Method Details

    • retainExistingValuesWhenParameterNotProvided

      boolean retainExistingValuesWhenParameterNotProvided()
      Returns:
      true if the issues value should be retained when a parameter has not been provided, false if the missing parameter should be treated as an update.

    • setRetainExistingValuesWhenParameterNotProvided

      void setRetainExistingValuesWhenParameterNotProvided(boolean retain)
      Flag to designate whether existing values should be retained when no parameter is provided.

      Note: setting this flag here will assume that validation of fields should still occur, even if they were not specified. To change this, please use setRetainExistingValuesWhenParameterNotProvided(boolean, boolean) instead.

      Parameters:
      retain - true if non-provided parameters should have the values retained, false otherwise.
      See Also:

    • setRetainExistingValuesWhenParameterNotProvided

      void setRetainExistingValuesWhenParameterNotProvided(boolean retainExistingValues, boolean onlyValidatePresentFields)
      Set flags retainExistingValuesWhenParameterNotProvided() and onlyValidatePresentFieldsWhenRetainingExistingValues().

      The latter is only relevant when the former is true.

      Parameters:
      retainExistingValues - true if non-provided parameters should have the values retained, false otherwise.
      onlyValidatePresentFields - whether or not to only validate present fields
      Since:
      v5.0.2
      See Also:

    • onlyValidatePresentFieldsWhenRetainingExistingValues

      boolean onlyValidatePresentFieldsWhenRetainingExistingValues()
      Get the flag to designate which fields are to be validated when the retainExistingValuesWhenParameterNotProvided() flag is set to true.

      If this flag is true, only fields which are "present" will take part in validation (and subsequently update) on the issue. This allows single-field edits to ignore the validation of other fields on the issue.

      If this flag is false, or if retainExistingValuesWhenParameterNotProvided() is false, then all fields on the screen of the current operation will partake in the "validation-update" step.

      Returns:
      whether or not to only validate present fields
      Since:
      v5.0.2
      See Also:

    • applyDefaultValuesWhenParameterNotProvided

      boolean applyDefaultValuesWhenParameterNotProvided()
      Returns:
      true if default value should be supplied when a parameter has not been provided. false if the default value should not be applied.

    • setApplyDefaultValuesWhenParameterNotProvided

      void setApplyDefaultValuesWhenParameterNotProvided(boolean applyDefaults)
      Parameters:
      applyDefaults - true if default value should be supplied when a parameter has not been provided. false if the default value should not be applied.

    • skipScreenCheck

      boolean skipScreenCheck()
      Get the flag to skip screen checks during create, update or transition.

      By default, the Issue Service only allows setting values to fields which appear on the screen of the operation which you are performing (e.g. the Edit screen). By enabling this flag, the Issue Service will skip this check.

      Returns:
      whether or not we are skipping screen check
      Since:
      v5.0 for editing, v6.3 for creating
      See Also:

    • setSkipScreenCheck

      void setSkipScreenCheck(boolean skipScreenCheck)
      Set the flag to skip screen checks during create, update or transition.

      By default, the Issue Service only allows setting values to fields which appear on the screen of the operation which you are performing (e.g. the Edit screen). By enabling this flag, the Issue Service will skip this check.

      Parameters:
      skipScreenCheck - whether or not we are skipping screen check
      Since:
      v5.0 supports for editing, v6.3 for creating
      See Also:

    • skipLicenceCheck

      boolean skipLicenceCheck()
      Returns true if the skipLicenceCheck flag is set.
      Returns:
      the value of the skipLicenceCheck flag.
      Since:
      v7.1

    • setSkipLicenceCheck

      void setSkipLicenceCheck(boolean skipLicenceCheck)
      Set the flag to skip licence checks during create.

      By default, the Issue Service will check the user is licensed to an application role. By enabling this flag, the Issue Service will skip this check.

      Parameters:
      skipLicenceCheck - whether or not we are skipping the licence check
      Since:
      v7.1

    • getCustomFieldValue

      String[] getCustomFieldValue(Long customFieldId)
      Parameters:
      customFieldId - uniquely identifies the custom field value you are looking for.
      Returns:
      the values for the provided custom field if they exist, null otherwise.

    • getCustomFieldValue

      String[] getCustomFieldValue(String fullCustomFieldKey)
      Parameters:
      fullCustomFieldKey - identifies the custom field values you are looking for.
      Returns:
      the values for the provided custom field if they exist, null otherwise.

    • addCustomFieldValue

      IssueInputParameters addCustomFieldValue(Long customFieldId, String... values)
      Adds a value for a custom field with the specified id. This will put a value in the web-style parameters with a key of the form "customfield_PROVIDED_ID". If you want to specify the key then use the method addCustomFieldValue(String, String...).
      Parameters:
      customFieldId - the unique identifier of the custom field.
      values - the custom field values, must be in the format the field expects.
      Returns:
      this object.

    • addCustomFieldValue

      IssueInputParameters addCustomFieldValue(String fullCustomFieldKey, String... values)
      Adds a value for a custom field with the specified full key. This will put a value in the web-style parameters with a key as provided.
      Parameters:
      fullCustomFieldKey - used in the "web-style" parameters as the key, the custom field should expect this value as the key in its populate from parameters method.
      values - the custom field values, must be in the format the field expects.
      Returns:
      this object.

    • getCommentValue

      String getCommentValue()
      Returns:
      the comment string value if it has been set, null otherwise.

    • setComment

      IssueInputParameters setComment(String comment)
      Set a comment value with no visibility restrictions.
      Parameters:
      comment - the comment value.
      Returns:
      this object.

    • setComment

      IssueInputParameters setComment(String comment, Long projectRoleId)
      Set a comment value with a project role restriction.
      Parameters:
      comment - the comment value.
      projectRoleId - the id of the project role the comment must be restricted by.
      Returns:
      this object.

    • setComment

      IssueInputParameters setComment(String comment, String groupId)
      Set a comment value with a group restriction.
      Parameters:
      comment - the comment value.
      groupId - the group name that the comment must be restricted by.
      Returns:
      this object.

    • getActionParameters

      Map<String,String[]> getActionParameters()
      This provides the "web-style" parameters that JIRA fields expect to perform their functions.
      Returns:
      this is a raw map of "web" style input parameters. These parameters are used to allow the fields to attain the user inputted values. This map is of the style: <field_name> <String [] {value}>.

    • setFieldValuesHolder

      void setFieldValuesHolder(Map<String,Object> fieldValuesHolder)
      If set the validation will use the seed values from this field values holder.
      Parameters:
      fieldValuesHolder - provides the seed values for the field values holder.

    • getFieldValuesHolder

      Map<String,Object> getFieldValuesHolder()
      Returns:
      the provided field values holder or an empty map, never null.

    • getProvidedFields

      Collection<String> getProvidedFields()
      Returns:
      the field id's that should be validated, null if not specified.

    • setProvidedFields

      void setProvidedFields(Collection<String> providedFields)
      Use this to indicate which fields validation should be performed on, if left alone then the systems configured fields for either create/update will be used.
      Parameters:
      providedFields - a collection of Field.getId()'s which identify the fields.

    • isFieldSet

      boolean isFieldSet(String fieldId)
      Parameters:
      fieldId - identifies the field in question, this will be the Field.getId().
      Returns:
      true if a non-null, non-empty value has been set for the field, false if not.

    • isFieldPresent

      boolean isFieldPresent(String fieldId)
      Parameters:
      fieldId - identifies the field in question, this will be the Field.getId().
      Returns:
      true if the field has been set, even with an empty value, false if not.

    • addFieldToForcePresent

      void addFieldToForcePresent(String fieldId)
      Extra fields to consider present, even if they are not in the actionParams. When "setRetainExisitingValuesWhenParameterNotProvided" is true, a field is not considered for update if its parameter is not provided. You can force a field to be considered even if its parameter is not providfed by forcing it to be considered by this setter.

      The action post params can also contain an array of fieldIds under the "fieldsToForcePresent" param.

      This may be useful if you want to clear a field's value in a single field edit.

      Parameters:
      fieldId - the id of the field to force to be present
      Since:
      5.0.2

    • setProjectId

      IssueInputParameters setProjectId(Long projectId)
      Parameters:
      projectId - sets the project id for the issue.
      Returns:
      this object.

    • getProjectId

      Long getProjectId()
      Returns:
      the set project id, null if one does not exist or if it is not a valid number.

    • setIssueTypeId

      IssueInputParameters setIssueTypeId(String issueTypeId)
      Parameters:
      issueTypeId - sets the issue type for the issue.
      Returns:
      this object.

    • getIssueTypeId

      String getIssueTypeId()
      Returns:
      the set issue type id, null if one does not exist.

    • setPriorityId

      IssueInputParameters setPriorityId(String priorityId)
      Parameters:
      priorityId - sets the priority for the issue.
      Returns:
      this object.

    • getPriorityId

      String getPriorityId()
      Returns:
      the set priority id, null if one does not exist.

    • setResolutionId

      IssueInputParameters setResolutionId(String resolutionId)
      Parameters:
      resolutionId - sets the resolution for the issue.
      Returns:
      this object.

    • getResolutionId

      String getResolutionId()
      Returns:
      the set resolution id, null if one does not exist.

    • setStatusId

      IssueInputParameters setStatusId(String statusId)
      Parameters:
      statusId - sets the status of the issue.
      Returns:
      this object.

    • getStatusId

      String getStatusId()
      Returns:
      the set status id, null if one does not exist.

    • setSummary

      IssueInputParameters setSummary(String summary)
      Parameters:
      summary - sets the summary for the issue.
      Returns:
      this object.

    • getSummary

      String getSummary()
      Returns:
      the set summary, null if one does not exist.

    • setDescription

      IssueInputParameters setDescription(String description)
      Parameters:
      description - sets the description for the issue.
      Returns:
      this object.

    • getDescription

      String getDescription()
      Returns:
      the set description, null if one does not exist.

    • setEnvironment

      IssueInputParameters setEnvironment(String environment)
      Parameters:
      environment - sets the environment of the issue.
      Returns:
      this object.

    • getEnvironment

      String getEnvironment()
      Returns:
      the set environment, null if one does not exist.

    • setAssigneeId

      IssueInputParameters setAssigneeId(String assigneeId)
      Parameters:
      assigneeId - sets the assignee id for the issue.
      Returns:
      this object.

    • getAssigneeId

      String getAssigneeId()
      Returns:
      the set assginee, null if one does not exist.

    • setReporterId

      IssueInputParameters setReporterId(String reporterId)
      Parameters:
      reporterId - sets the reporter id for the issue.
      Returns:
      this object.

    • getReporterId

      String getReporterId()
      Returns:
      the set reporter, null if one does not exist.

    • setComponentIds

      IssueInputParameters setComponentIds(Long... componentIds)
      Parameters:
      componentIds - sets the components id's on the issue.
      Returns:
      this object.

    • getComponentIds

      Long[] getComponentIds()
      Returns:
      the set component id's, null if they do not exist or if they are not valid numbers.

    • setFixVersionIds

      IssueInputParameters setFixVersionIds(Long... fixVersionIds)
      Parameters:
      fixVersionIds - sets the fix version id's on the issue.
      Returns:
      this object.

    • getFixVersionIds

      Long[] getFixVersionIds()
      Returns:
      the set fix version id's, null if they do not exist or if they are not valid numbers.

    • setAffectedVersionIds

      IssueInputParameters setAffectedVersionIds(Long... affectedVersionIds)
      Parameters:
      affectedVersionIds - sets the affected version id's= on the issue.
      Returns:
      this object.

    • getAffectedVersionIds

      Long[] getAffectedVersionIds()
      Returns:
      the set affected version id's, null if they do not exist or if they are not valid numbers.

    • setDueDate

      IssueInputParameters setDueDate(String dueDate)
      Parameters:
      dueDate - the formatted string that JIRA will accept as a date that will be set on the issue.
      Returns:
      this object.

    • getDueDate

      String getDueDate()
      Returns:
      the set due date, null if one does not exist.

    • setResolutionDate

      IssueInputParameters setResolutionDate(String resolutionDate)
      Parameters:
      resolutionDate - the formatted string that JIRA will accept as a date that will be set on the issue.
      Returns:
      this object.

    • getResolutionDate

      String getResolutionDate()
      Returns:
      the set resolution date, null if one does not exist.

    • setSecurityLevelId

      IssueInputParameters setSecurityLevelId(Long securityLevelId)
      Parameters:
      securityLevelId - sets the security level id on the issue.
      Returns:
      this object.

    • getSecurityLevelId

      Long getSecurityLevelId()
      Returns:
      the set security level id, null if one does not exist or it is not a valid number.

    • setOriginalEstimate

      IssueInputParameters setOriginalEstimate(Long originalEstimate)
      Sets the original estimate on the issue.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      originalEstimate - the new original estimate on the issue. The units used are determined by APKeys.JIRA_TIMETRACKING_DEFAULT_UNIT.
      Returns:
      this object.

    • setOriginalEstimate

      IssueInputParameters setOriginalEstimate(String originalEstimate)
      Sets the original estimate on the issue.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      originalEstimate - the new original estimate on the issue, e.g. "1d 5h" for 1 day and 5 hours
      Returns:
      this object.

    • setRemainingEstimate

      IssueInputParameters setRemainingEstimate(String remainingEstimate)
      Sets the remaining estimate on the issue

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      remainingEstimate - the remaining estimate on the issue, e.g. "1d 5h" for 1 day and 5 hours
      Returns:
      this object

    • setRemainingEstimate

      IssueInputParameters setRemainingEstimate(Long remainingEstimate)
      Sets the remaining estimate on the issue

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method behaves differently.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      remainingEstimate - the remaining estimate on the issue. The units used are determined by APKeys.JIRA_TIMETRACKING_DEFAULT_UNIT.
      Returns:
      this object

    • setOriginalAndRemainingEstimate

      IssueInputParameters setOriginalAndRemainingEstimate(String originalEstimate, String remainingEstimate)
      Sets both the original and remaining estimate on the issue.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method has no effect.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      originalEstimate - the new original estimate, e.g. "1d 5h" for 1 day and 5 hours
      remainingEstimate - the new remaining estimate, e.g. "1d 5h" for 1 day and 5 hours
      Returns:
      this object

    • setOriginalAndRemainingEstimate

      IssueInputParameters setOriginalAndRemainingEstimate(Long originalEstimate, Long remainingEstimate)
      Sets both the original and remaining estimate on the issue.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this method has no effect.

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Parameters:
      originalEstimate - the new original estimate. The units used are determined by APKeys.JIRA_TIMETRACKING_DEFAULT_UNIT.
      remainingEstimate - the new remaining estimate.The units used are determined by APKeys.JIRA_TIMETRACKING_DEFAULT_UNIT.
      Returns:
      this object

    • getOriginalEstimate

      Long getOriginalEstimate()
      Gets the original estimate set.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getRemainingEstimate().

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Returns:
      the set original estimate, null if one does not exist or it is not a valid number.

    • getRemainingEstimate

      Long getRemainingEstimate()
      Gets the remaining estimate set.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getOriginalEstimate() .

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Returns:
      the set remaining estimate, null if one does not exist or it is not a valid number.

    • getOriginalEstimateAsDurationString

      String getOriginalEstimateAsDurationString()
      Gets the original estimate set.

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getRemainingEstimateAsDurationString().

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Returns:
      the set original estimate, null if one does not exist.

    • getRemainingEstimateAsDurationString

      String getRemainingEstimateAsDurationString()
      Gets the remaining estimate provided

      If (APKeys.JIRA_OPTION_TIMETRACKING_ESTIMATES_LEGACY_BEHAVIOUR is set, we are in legacy time tracking mode and this will return the same as getOriginalEstimateAsDurationString().

      See http://confluence.atlassian.com/display/JIRA044/Configuring+Time+Tracking#ConfiguringTimeTracking-legacymode for more information on legacy mode.

      Returns:
      the set remaining estimate, null if one does not exist.

    • setTimeSpent

      IssueInputParameters setTimeSpent(Long timeSpent)
      Parameters:
      timeSpent - sets the time spent on the issue.
      Returns:
      this object.

    • getTimeSpent

      Long getTimeSpent()
      Returns:
      the set time spent, null if one does not exist or it is not a valid number.

    • setHistoryMetadata

      IssueInputParameters setHistoryMetadata(HistoryMetadata historyMetadata)
      Allows defining history metadata related to the issue update. This is only relevant for changes that generate history entries (transitions and updates).
      Parameters:
      historyMetadata - the metadata to save with the history change
      Returns:
      this object
      Since:
      JIRA 6.3

    • getHistoryMetadata

      @Nullable HistoryMetadata getHistoryMetadata()
      Returns:
      the current history metadata for the update, null if not defined
      Since:
      JIRA 6.3

    • getFormToken

      String getFormToken()
      Return form token if it is present in input parameters
      Returns:
      the form token

    • addProperty

      IssueInputParameters addProperty(String propertyKey, String propertyValue)
      Allows properties to be set on issues during create or update
      Parameters:
      propertyKey - the key to the property
      propertyValue - the JSON property value
      Returns:
      this object
      Since:
      7.1.0

    • properties

      Map<String,String> properties()
      Returns:
      JSON issue properties
      Since:
      7.1.0