Field Detail

• protected java.util.Map fields

• protected final Issue originalIssue

• protected boolean skipScreenCheck

• protected java.util.Map update

Constructor Detail

• AbstractIssuesDelegate(Issue originalIssue)

Method Detail

• @java.lang.Override
  void clearCustomField(java.lang.Long fieldId)

  Clears the value of a custom field identified by its ID.

  This method sets the value of the specified custom field to null, effectively clearing its content. The custom field must be configured and available in the issue's field configuration. Clearing a custom field can be useful in scenarios where the field's value needs to be reset or removed.

  Usage Example:

  // Clear the value of a custom field identified by its ID
   Issues.getByKey("JRA-1").update {
       clearCustomField(12345L)
   
   }

  Notes:

  • The custom field ID must correspond to a valid field configured in Jira.
  • If the field ID is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to modify the custom field.
  • Clearing a field may have workflow or reporting implications, depending on the Jira configuration.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  IllegalArgumentException if the provided field ID is null or invalid

  Parameters:

  fieldId - the ID of the custom field to clear; must correspond to a valid field in Jira

• @java.lang.Override
  void clearCustomField(java.lang.String fieldName)

  Clears the value of a custom field identified by its name.

  This method sets the value of the specified custom field to null, effectively removing its content. The custom field must be configured and available in the issue's field configuration. Clearing a custom field is useful when the field's value needs to be reset or explicitly removed.

  Usage Example:

  // Clear the value of a custom field identified by its name
   Issues.getByKey("JRA-1").update {
       clearCustomField("Custom Field Name")
   
   }

  Notes:

  • The custom field name must exactly match the configured field name in Jira.
  • If the field name is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to modify the custom field.
  • Clearing a field may have workflow or reporting implications, depending on your Jira configuration.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  DuplicateCustomFieldException if multiple fields match the provided name

  throws:

  IllegalArgumentException if the provided field name is null or empty

  Parameters:

  fieldName - the name of the custom field to clear; must match the configured field name in Jira

• protected java.lang.Object getCustomFieldTransportValue(java.lang.String type, java.lang.String value)

• abstract T getMetaDatas(boolean overrideScreenSecurity)

• void setAffectedVersions(java.lang.String[] versionNames)

  Sets the affected versions for the issue using version names.

  This method updates the issue's affected versions field with the specified version names. The versions must exist in the project's version list; otherwise, an error will occur when the issue is updated.

  Usage Examples:

  // Set a single affected version
   Issues.create("JRA", "Task") {
            setSummary("Setting a version")
            setAffectedVersions("1.0")
        
   }
  
   // Set multiple affected versions
   Issues.create("JRA", "Task") {
            setSummary("Setting a version")
            setAffectedVersions("1.0", "2.0", "3.0")
        }
   }
  
   // Using an array of version names
   String[] versions = {"1.0", "2.0"};
   Issues.create("JRA", "Task") {
            setSummary("Setting a version")
            setAffectedVersions(versions)
        }
   }
   

  Note: The version names must exactly match the versions defined in the project. If a version name does not exist, the operation will fail when the issue is updated.

  Parameters:

  versionNames - one or more version names to set as affected versions

• @java.lang.Override
  void setAffectedVersions(@groovy.lang.DelegatesTo(value: MultiOptionNameUpdater)
  groovy.lang.Closure<?> specification)

  Configures the affected versions for the issue using a closure-based specification.

  This method allows you to dynamically manage the issue's affectedVersions field by specifying add, remove, set, or clear operations through a closure. The closure operates on a MultiOptionNameUpdater delegate, which provides methods to manipulate version names or IDs.

  Available Operations:

  • add(String... items): Add versions by their names.
  • add(Long... items): Add versions by their IDs.
  • remove(String... items): Remove versions by their names.
  • remove(Long... items): Remove versions by their IDs.
  • set(String... items): Replace all existing versions with specified names.
  • set(Long... items): Replace all existing versions with specified IDs.
  • clear(): Clear all versions from the field.

  Usage Example:

  issue.update {
       setAffectedVersions {
           add("1.0", "2.0")       // Add versions by name
           remove("1.0")           // Remove a version by name
           set("3.0", "4.0")       // Replace all affected versions with specified names
           clear()                 // Clear all affected versions
       
   }
   }

  Advanced Usage: Use version IDs instead of names:

  issue.update {
       setAffectedVersions {
           add(10001L, 10002L)    // Add versions by ID
           remove(10001L)         // Remove a version by ID
           set(10003L, 10004L)    // Replace all affected versions with IDs
       
   }
   }

  Notes:

  • The specified version names or IDs must exist in the project's configuration.
  • If invalid version names or IDs are provided, Jira will return an error during the update.
  • Using set() or clear() will overwrite all existing values in the field.
  • Ensure that the user executing the script has the necessary permissions to update the affected versions field.

  Parameters:

  specification - a closure that specifies the affected versions to update; operates on a MultiOptionNameUpdater instance

• void setAssignee(User user)

  Sets the assignee of the issue to the user represented by a User object.

  This method updates the issue's assignee field using the account ID of the provided User. The User object must contain a valid account ID, which is required by Jira Cloud's user privacy standards.

  Notes:

  • Direct user lookups by username are not supported due to Jira Cloud's guidance.
  • You must use account IDs to identify users. These can be obtained through the Jira UI or API.
  • Providing a null User object will cause a runtime error.
  • If the account ID is invalid or not assignable, Jira will reject the update.

  To look up user account IDs in Jira, navigate to: https://<your-domain>.atlassian.net/people.

  Usage Example:

  // Retrieve a User object by account ID
   def user = Users.getByAccountId("5b10a2844c20165700ede21g");
  
   // Set the assignee for an existing issue
   Issues.getByKey("JRA-1").update {
       setAssignee(user)
   
   }

  For more details on obtaining a User object, see: Users.getByAccountId

  Parameters:

  user - the User object representing the assignee; must contain a valid accountId

• @java.lang.Override
  void setAssignee(java.lang.String accountId)

  Sets the assignee of the issue to the user identified by the given account ID.

  This method updates the issue's assignee field with the specified account ID. The account ID must be a valid identifier for a user in Jira, and the user must have the necessary permissions to be assigned to the issue.

  Notes:

  • Account IDs are required due to Jira Cloud's privacy updates; usernames and user keys are no longer supported.
  • If the account ID is invalid or refers to a user who cannot be assigned to the issue, Jira will reject the update.
  • You can look up account IDs in Jira via the People directory or the REST API.

  To look up account IDs in Jira, navigate to: https://<your-domain>.atlassian.net/people.

  Usage Example:

  // Assign an issue to a user by their account ID
   Issues.getByKey("JRA-1").update {
       setAssignee("5b10a2844c20165700ede21g");
   
   }

  For more information about Jira's account IDs, see the official documentation: Jira API User Privacy Migration Guide.

  Parameters:

  accountId - the account ID of the user to be set as the assignee; must be a valid account ID

• void setComponents(java.lang.String[] components)

  Sets the components for the issue.

  This method updates the issue's components field with the specified component names. Components are used in Jira to categorize issues into specific areas or modules of a project. The component names provided must exist in the project's configuration; otherwise, an error will occur when the issue is updated.

  Usage Examples:

  // Update the issue to set its components
   issue.update {
       setComponents("Backend", "API")
   
  
   // Set components during issue creation
   Issues.create("PROJECT", "Bug") {
       setSummary("API response inconsistency")
       setDescription("Details about the issue")
       setComponents("Backend", "API")
   }
   }

  Notes:

  • The component names must exist in the project configuration; invalid names will result in an error when updating or creating the issue.
  • Components can be used to filter and organize issues in Jira reports and boards.
  • If no components are provided, the issue's components field will be cleared.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's components.

  Parameters:

  components - the names of the components to set for the issue; each name must match a component configured in the project

• @java.lang.Override
  void setComponents(@groovy.lang.DelegatesTo(value: MultiOptionNameUpdater)
  groovy.lang.Closure<?> specification)

  Configures the fix versions for the issue using a closure-based specification.

  This method dynamically manages the issue's fixVersions field by allowing add, remove, set, or clear operations through a closure. The closure operates on a MultiOptionNameUpdater delegate, which provides methods to manipulate version names or IDs.

  Available Operations:

  • add(String... items): Add versions by their names.
  • add(Long... items): Add versions by their IDs.
  • remove(String... items): Remove versions by their names.
  • remove(Long... items): Remove versions by their IDs.
  • set(String... items): Replace all existing versions with specified names.
  • set(Long... items): Replace all existing versions with specified IDs.
  • clear(): Clear all fix versions from the field.

  Usage Examples:

  Adding and Removing Versions by Name:

  Issues.getByKey("JRA-1").update {
       setFixVersions {
           add("1.0", "2.0")       // Add versions by name
           remove("1.0")           // Remove a version by name
       
   }
   }

  Replacing Versions by ID:

  Issues.getByKey("JRA-1").update {
       setFixVersions {
           set(10001L, 10002L)    // Replace all fix versions with specified IDs
       
   }
   }

  Clearing Fix Versions:

  Issues.getByKey("JRA-1").update {
       setFixVersions {
           clear()                 // Clear all fix versions
       
   }
   }

  Notes:

  • The specified version names or IDs must exist in the project's version configuration.
  • If invalid names or IDs are provided, Jira will reject the update during API submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's fix versions field.
  • Using set() or clear() will overwrite all existing values in the field.

  Parameters:

  specification - a closure that specifies the fix versions to update;

  See Also:

  for available operations on version fields

• void setCustomFieldValue(java.lang.String customFieldName, @groovy.lang.DelegatesTo(value: MultiOptionUpdater)
  groovy.lang.Closure<?> specification)

  Sets the value of a custom field using its name and a closure-based specification.

  This method allows you to dynamically add, remove, or set options for custom fields that support multiple options, such as multi-select lists, checkboxes, cascading select fields, or user/group pickers. By providing a closure, you can specify the exact changes you want to make to the custom field's value. The closure operates on a MultiOptionUpdater delegate, which provides methods to manipulate the options.

  Applicable Custom Field Types:

  • Multi-select lists
  • Checkboxes
  • Cascading select fields
  • User picker (multiple users)
  • Group picker (multiple groups)

  Available Operations:

  • add(String... items): Add options by their values.
  • remove(String... items): Remove options by their values.
  • set(String... items): Replace all existing options with the specified values.

  Usage Examples:

  // Example 1: Add options to a multi-select custom field by option values
   Issues.getByKey("JRA-1").update {
        setCustomFieldValue("My Multi-Select Field") {
            add("Option A", "Option B")
   
  
   // Example 2: Remove options from a multi-select custom field by option values
   Issues.getByKey("JRA-1").update {
        setCustomFieldValue("My Multi-Select Field") {
            remove("Option A", "Option B")
   }
  
   // Example 3: Set options for a multi-select custom field
   Issues.getByKey("JRA-1").update {
        setCustomFieldValue("My Multi-Select Field") {
            set("Option C", "Option D")
   }
  
   }

  Notes:

  • The customFieldName must correspond to a custom field that exists in the issue's context.
  • If the custom field does not exist or is not applicable to the issue, an exception will be thrown when the issue is updated.
  • Option values must be valid for the custom field; invalid values will cause errors upon update.
  • For cascading select fields, use nested closures to specify parent and child options.
  • When working with user or group pickers, use account IDs or group names respectively.

  Parameters:

  customFieldName - the name of the custom field to set

  specification - a closure that specifies how to update the custom field's value; operates on a MultiOptionUpdater instance

  See Also:

  for available operations on custom field options

• void setCustomFieldValue(java.lang.String customFieldName, java.lang.String[] values)

  Sets the value of a custom field identified by its name.

  This method updates the specified custom field with the provided values. Custom fields must be configured and available in the issue's field configuration. The values must adhere to the field's expected format, which varies depending on the custom field type (e.g., text, select list, user picker).

  Usage Example:

  // Set a single value for a custom field
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Custom Field Name", "Custom Value")
   
  
   // Set multiple values for a custom field (e.g., multi-select field)
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Custom Field Name", "Value 1", "Value 2", "Value 3")
   }
  
   // Set values on a Cascading Select
   Issues.getByKey("JRA-1").update {
        setCustomFieldValue("Custom Field Name", "Cascade level 1", "Cascade level 2")
       }
   }

  Notes:

  • The custom field name must exactly match the field's name configured in Jira.
  • If the field name is invalid or the field is not available in the issue's context, an error will occur.
  • The provided values must conform to the field's expected type and configuration.
  • Ensure that the user executing the script has the necessary permissions to update the custom field.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  DuplicateCustomFieldException if multiple fields match the provided name

  Parameters:

  customFieldName - the name of the custom field to update; must match the configured field name in Jira

  values - one or more values to set for the custom field; must adhere to the field's expected format

• @java.lang.Override
  void setCustomFieldValue(java.lang.Long fieldId, @groovy.lang.DelegatesTo(value: MultiOptionUpdater)
  groovy.lang.Closure<?> specification)

  Sets the value of a custom field using its field ID and a closure-based specification.

  This method allows you to dynamically add, remove, set, or clear options for custom fields that support multiple options, such as multi-select lists, checkboxes, or cascading select fields. By providing a closure, you can specify the exact changes you want to make to the custom field's value. The closure operates on a MultiOptionUpdater delegate, which provides methods to manipulate the options.

  Applicable Custom Field Types:

  • Multi-select lists
  • Checkboxes
  • Cascading select fields
  • User picker (multiple users)
  • Group picker (multiple groups)

  Available Operations:

  • add(String... items): Add options by their values.
  • add(Long... ids): Add options by their IDs.
  • remove(String... items): Remove options by their values.
  • remove(Long... ids): Remove options by their IDs.
  • set(String... items): Replace all existing options with the specified values.
  • set(Long... ids): Replace all existing options with the specified IDs.

  Usage Examples:

  // Example 1: Add options to a multi-select custom field by option values
   def issue = Issues.getByKey("JRA-1").update {
        setCustomFieldValue(10001L) {
        add("Option A", "Option B")
   
  
   // Example 2: Remove options from a multi-select custom field by option IDs
   def issue = Issues.getByKey("JRA-1").update {
        setCustomFieldValue(10001L) {
            remove(20001L, 20002L)
   }
   }

  Notes:

  • The fieldId must correspond to a custom field that exists in the issue's context.
  • If the custom field does not exist or is not applicable to the issue, an exception will be thrown when the issue is updated.
  • Option values and IDs must be valid for the custom field; invalid values will cause errors upon update.
  • For cascading select fields, use nested closures to specify parent and child options.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  DuplicateCustomFieldException if multiple fields match the provided name

  Parameters:

  fieldId - the ID of the custom field to set

  specification - a closure that specifies how to update the custom field's value;

• @java.lang.Override
  void setCustomFieldValue(java.lang.String customFieldName, java.lang.Long[] longs)

  Sets the value of a custom field identified by its name, using numeric values.

  This method updates the specified custom field with one or more numeric values. The custom field must be configured and available in the issue's field configuration. The values must adhere to the field's expected format, which varies depending on the custom field type (e.g., number fields, select lists with numeric IDs, or cascading fields).

  Usage Examples:

  Setting a Single Value:

  // Set a single numeric value for a custom field
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Numeric Custom Field", 12345L)
   
   }

  Setting Multiple Values:

  // Set multiple numeric values for a custom field (e.g., multi-select or cascading field)
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Multi-Select Numeric Field", 10001L, 10002L, 10003L)
   
   }

  Notes:

  • The custom field name must exactly match the field's name configured in Jira.
  • The provided numeric values must conform to the custom field's expected type and configuration.
  • If the field name is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to update the custom field.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  DuplicateCustomFieldException if multiple fields match the provided name

  Parameters:

  customFieldName - the name of the custom field to update; must match the configured field name in Jira

  longs - one or more numeric values to set for the custom field; must adhere to the field's expected format

• @java.lang.Override
  void setCustomFieldValue(java.lang.String fieldName, java.lang.Object[] objects)

  Sets the value of a custom field identified by its name, with flexibility for different data types.

  This method updates the specified custom field with one or more values, supporting various data types. The custom field must be configured and available in the issue's field configuration. If the custom field is an array type and a single collection is provided, the collection's elements will be expanded and set as individual values for the field.

  Usage Examples:

  Single Value:

  // Set a single value for a custom field
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Custom Text Field", "Custom Value")
   
   }

  Multiple Values:

  // Set multiple values for a custom field
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Custom Multi-Select Field", "Value 1", "Value 2", "Value 3")
   
   }

  Using a Collection:

  // Set multiple values for an array-type custom field using a collection
   def values = ["Value 1", "Value 2", "Value 3"]
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue("Custom Multi-Select Field", values)
   
   }

  Notes:

  • The custom field name must exactly match the field's name configured in Jira.
  • The provided values must conform to the custom field's expected type and configuration.
  • If the custom field is an array type and a single collection is passed, the collection will be expanded into individual values.
  • If the field name is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to update the custom field.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  DuplicateCustomFieldException if multiple fields match the provided name

  Parameters:

  fieldName - the name of the custom field to update; must match the configured field name in Jira

  objects - one or more values to set for the custom field; supports various data types, including collections

• @java.lang.Override
  void setCustomFieldValue(java.lang.Long fieldId, java.lang.String[] strings)

  Sets the value of a custom field identified by its ID, using string values.

  This method updates the specified custom field with one or more string values. The custom field must be configured and available in the issue's field configuration. The provided values must conform to the custom field's expected type and format.

  Usage Examples:

  Single Value:

  // Set a single string value for a custom field by its ID
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue(12345L, "Custom Value")
   
   }

  Multiple Values:

  // Set multiple string values for a custom field (e.g., multi-select or cascading field) by its ID
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue(12345L, "Value 1", "Value 2", "Value 3")
   
   }

  Notes:

  • The custom field ID must correspond to a valid field configured in Jira.
  • The provided values must conform to the field's expected type and configuration (e.g., text, multi-select).
  • If the field ID is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to update the custom field.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  IllegalArgumentException if the provided field ID is null or invalid

  Parameters:

  fieldId - the ID of the custom field to update; must correspond to a valid field in Jira

  strings - one or more string values to set for the custom field; must adhere to the field's expected format

• @java.lang.Override
  void setCustomFieldValue(java.lang.Long fieldId, java.lang.Long[] longs)

• @java.lang.Override
  void setCustomFieldValue(java.lang.Long fieldId, java.lang.Object[] objects)

  Sets the value of a custom field identified by its ID, using a flexible range of data types.

  This method updates the specified custom field with one or more values, which can be of various types. The custom field must be configured and available in the issue's field configuration. The provided values must adhere to the field's expected type and format, depending on the field's configuration in Jira.

  Usage Examples:

  Setting a Single Value:

  // Set a single value for a custom field identified by its ID
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue(12345L, "Custom Value")
   
   }

  Setting Multiple Values:

  // Set multiple values for a multi-select custom field identified by its ID
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue(12345L, "Value 1", "Value 2", "Value 3")
   
   }

  Using Different Data Types:

  // Set various types of values for a custom field identified by its ID
   Issues.getByKey("JRA-1").update {
       setCustomFieldValue(12345L, 42, "Text Value", true)
   
   }

  Notes:

  • The custom field ID must correspond to a valid field configured in Jira.
  • The provided values must conform to the field's expected type and configuration (e.g., string, number, boolean).
  • If the field ID is invalid or the field is not available in the issue's context, an error will occur.
  • Ensure that the user executing the script has the necessary permissions to update the custom field.

  throws:

  NoSuchCustomFieldInContextException if the custom field is not found in the issue's context

  throws:

  IllegalArgumentException if the provided field ID is null or invalid

  Parameters:

  fieldId - the ID of the custom field to update; must correspond to a valid field in Jira

  objects - one or more values of various types to set for the custom field; must adhere to the field's expected format

• @java.lang.Override
  void setCustomFieldValueById(java.lang.String fieldName, java.lang.Long[] longs)

• void setDescription(java.lang.String description)

  Sets the description for the issue being configured.

  The description field supports basic Markdown formatting, allowing you to add elements such as headings, lists, links, code blocks, and inline formatting to enrich the issue's content. Use this method to provide detailed and well-structured information about the issue.

  Note: This method does not support ADF (Atlassian Document Format). Advanced formatting options available through ADF, such as tables and certain styling features, are available when using the map-based version of this method.

  Usage Examples:

  // Using plain text
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("Hello, HAPI");
    
  
   // Using bullet points with triple quotes
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("""
            - Item 1
            - Item 2
            - Item 3
            """);
    }
  
   // Adding a numbered list
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("""
            1. First step
            2. Second step
            3. Third step
        """);
   }
  
   // Including a link
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("[Visit Jira documentation](https://developer.atlassian.com/)")
   }
  
   // Using bold and italics
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription(" *This text is italicized* and **bold**.");
   }
  
   // Including a code block
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("""
            ```
            System.out.println("Hello, World!");
            ```
        """);
   }
  
   // Adding a table
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("""
            || *Column 1* || *Column 2* ||
            | Data 1   | Data 2   |
        """);
   }
  
   // Adding a blockquote
   Issues.create("JRA", "Task") {
            setSummary("Setting a description")
            setDescription("""
                > This is a blockquote.
                >
                > It can span multiple lines.
            """);
   }
  
   // Combining multiple formatting options
   Issues.create("JRA", "Task") {
        setSummary("Setting a description")
        setDescription("""
            ## Issue Details
  
            **Summary:** This is a **bold** summary.
  
            **Steps to Reproduce:**
            1. Step one
            2. Step two
            3. Step three
  
            **Expected Result:** The application should behave *as expected*.
  
            **Actual Result:** The application crashes.
  
            ```
            Error stack trace goes here.
            ```
        """);
   }
   }

  Please note that not all Markdown features are fully supported in Jira Cloud issue descriptions. For example, tables and some advanced formatting options may not render as expected.

  Some of Jira Cloud's support for Markdown is documented at: Markdown and keyboard shortcuts. You can find out more details by researching their support pages and the developer community.

  Parameters:

  description - the text content to set as the issue's description; can include basic Markdown syntax

• void setDescription(java.util.Map description)

  Sets the description for the issue being configured using Atlassian Document Format (ADF).

  This method allows you to set the issue description using ADF, which provides rich text formatting capabilities beyond basic Markdown. ADF supports advanced features such as tables, panels, and more complex styling options.

  Note: This method expects a Map representation of ADF. If you have a JSON string, you can parse it into a Map using Groovy's JsonSlurper before passing it to this method.

  Usage Examples:

  1. Simple paragraph with bold text:

  Issues.create("JRA", "Task") {
       setSummary("Simple ADF Example")
       setDescription([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "paragraph",
                   content: [
                       [type: "text", text: "This is "],
                       [type: "text", text: "bold", marks: [[type: "strong"]]],
                       [type: "text", text: " text in ADF."]
                   ]
               ]
           ]
       ])
   
   }

  2. Bullet list:

  Issues.create("JRA", "Task") {
       setSummary("ADF Bullet List")
       setDescription([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "bulletList",
                   content: [
                       [type: "listItem", content: [[type: "paragraph", content: [[type: "text", text: "Item 1"]]]]],
                       [type: "listItem", content: [[type: "paragraph", content: [[type: "text", text: "Item 2"]]]]]
                   ]
               ]
           ]
       ])
   
   }

  3. Table with two columns:

  Issues.create("JRA", "Task") {
       setSummary("ADF Table Example")
       setDescription([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "table",
                   attrs: [isNumberColumnEnabled: false, layout: "default"],
                   content: [
                       [
                           type: "tableRow",
                           content: [
                               [type: "tableHeader", content: [[type: "paragraph", content: [[type: "text", text: "Header 1"]]]]],
                               [type: "tableHeader", content: [[type: "paragraph", content: [[type: "text", text: "Header 2"]]]]]
                           ]
                       ],
                       [
                           type: "tableRow",
                           content: [
                               [type: "tableCell", content: [[type: "paragraph", content: [[type: "text", text: "Cell 1"]]]]],
                               [type: "tableCell", content: [[type: "paragraph", content: [[type: "text", text: "Cell 2"]]]]]
                           ]
                       ]
                   ]
               ]
           ]
       ])
   
   }

  *

  4. Using JsonSlurper to parse a JSON string:

  import groovy.json.JsonSlurper
  
   def jsonString = '''
   {
       "version": 1,
       "type": "doc",
       "content": [
           {
               "type": "paragraph",
               "content": [
                   {
                       "type": "text",
                       "text": "This is a paragraph parsed from JSON."
                   
               ]
           }
       ]
   }
   '''
  
   Issues.create("JRA", "Task") {
       setSummary("ADF from JSON Example")
       def jsonSlurper = new JsonSlurper()
       def adfMap = jsonSlurper.parseText(jsonString)
       setDescription(adfMap)
   }
   }

  For more information on ADF structure and capabilities, refer to the Atlassian Developer documentation: ADF Structure

  While ADF provides more formatting options than Markdown, it's also more complex to construct manually. Consider using the string-based setDescription method for simpler formatting needs.

  Parameters:

  description - a Map representing the ADF structure for the issue's description

• void setDueDate(java.time.LocalDate date)

  Sets the due date for the issue using a java.time.LocalDate object.

  This method updates the issue's duedate field with the provided date, formatted as yyyy-MM-dd. The due date represents the deadline for completing the issue and must be a valid calendar date.

  Usage Example:

  // Set the due date for an issue to December 31, 2023
   issue.update {
       setDueDate(LocalDate.of(2023, 12, 31))
   
   }

  Notes:

  • The due date must be in the future or a valid date based on your Jira configuration.
  • If the provided date is null, the due date will not be updated, and no changes will be made to the field.
  • Ensure that the user executing the script has the necessary permissions to set the due date.
  • The duedate field must be available in the issue's configuration for the update to succeed.

  Parameters:

  date - the java.time.LocalDate object representing the due date; must be non-null and formatted as yyyy-MM-dd

• @java.lang.Override
  void setDueDate(java.lang.String date)

  Sets the due date for the issue using a string representation of the date.

  This method updates the issue's duedate field with the provided date in string format. The string must represent a valid date in Jira's expected format, typically yyyy-MM-dd.

  Usage Example:

  // Set the due date for an issue to December 31, 2023
   issue.update {
       setDueDate("2023-12-31")
   
   }

  Creating an Issue:

  // Set the due date while creating a new issue
   Issues.create("PROJECT", "Task") {
       setSummary("Complete project documentation")
       setDueDate("2023-12-31")
   
   }

  Notes:

  • The string must represent a valid calendar date in the format yyyy-MM-dd.
  • If the provided date is null or improperly formatted, Jira may reject the update during API submission.
  • Ensure that the user executing the script has the necessary permissions to set the due date.
  • The duedate field must be available in the issue's configuration for the update to succeed.

  Parameters:

  date - the string representation of the due date; must be in yyyy-MM-dd format and non-null

• void setEnvironment(java.lang.String environment)

  Sets the environment for the issue.

  This method updates the issue's environment field with the specified value. The environment field is often used to describe the context in which an issue was observed, such as a specific software version, hardware setup, or deployment environment.

  Usage Example:

  // Update the issue to set its environment
   issue.update {
       setEnvironment("Production - v1.2.3")
   
  
   // Set environment during issue creation
   Issues.create("PROJECT", "Bug") {
       setSummary("Critical bug in production")
       setEnvironment("Production - v1.2.3")
   }
   }

  Notes:

  • The environment field must be configured in your Jira instance and available on the issue type for it to be updated successfully.
  • If the environment field is not configured or is absent from the issue's context, Jira will reject the update.
  • The value of the environment field should provide clear and meaningful information to aid issue resolution.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's environment field.

  Parameters:

  environment - the environment value to set for the issue (e.g., "Production", "Staging", "Local Development")

• void setEnvironment(java.util.Map environment)

  Sets the environment for the issue being configured using Atlassian Document Format (ADF).

  This method allows you to set the issue environment using ADF, which provides rich text formatting capabilities beyond basic Markdown. ADF supports advanced features such as tables, panels, and more complex styling options.

  Note: This method expects a Map representation of ADF. If you have a JSON string, you can parse it into a Map using Groovy's JsonSlurper before passing it to this method.

  Usage Examples:

  1. Simple paragraph with bold text:

  Issues.create("JRA", "Task") {
       setSummary("Simple ADF Example")
       setEnvironment([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "paragraph",
                   content: [
                       [type: "text", text: "This is "],
                       [type: "text", text: "bold", marks: [[type: "strong"]]],
                       [type: "text", text: " text in ADF."]
                   ]
               ]
           ]
       ])
   
   }

  2. Bullet list:

  Issues.create("JRA", "Task") {
       setSummary("ADF Bullet List")
       setEnvironment([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "bulletList",
                   content: [
                       [type: "listItem", content: [[type: "paragraph", content: [[type: "text", text: "Item 1"]]]]],
                       [type: "listItem", content: [[type: "paragraph", content: [[type: "text", text: "Item 2"]]]]]
                   ]
               ]
           ]
       ])
   
   }

  3. Table with two columns:

  Issues.create("JRA", "Task") {
       setSummary("ADF Table Example")
       setEnvironment([
           version: 1,
           type: "doc",
           content: [
               [
                   type: "table",
                   attrs: [isNumberColumnEnabled: false, layout: "default"],
                   content: [
                       [
                           type: "tableRow",
                           content: [
                               [type: "tableHeader", content: [[type: "paragraph", content: [[type: "text", text: "Header 1"]]]]],
                               [type: "tableHeader", content: [[type: "paragraph", content: [[type: "text", text: "Header 2"]]]]]
                           ]
                       ],
                       [
                           type: "tableRow",
                           content: [
                               [type: "tableCell", content: [[type: "paragraph", content: [[type: "text", text: "Cell 1"]]]]],
                               [type: "tableCell", content: [[type: "paragraph", content: [[type: "text", text: "Cell 2"]]]]]
                           ]
                       ]
                   ]
               ]
           ]
       ])
   
   }

  *

  4. Using JsonSlurper to parse a JSON string:

  import groovy.json.JsonSlurper
  
   def jsonString = '''
   {
       "version": 1,
       "type": "doc",
       "content": [
           {
               "type": "paragraph",
               "content": [
                   {
                       "type": "text",
                       "text": "This is a paragraph parsed from JSON."
                   
               ]
           }
       ]
   }
   '''
  
   Issues.create("JRA", "Task") {
       setSummary("ADF from JSON Example")
       def jsonSlurper = new JsonSlurper()
       def adfMap = jsonSlurper.parseText(jsonString)
       setEnvironment(adfMap)
   }
   }

  For more information on ADF structure and capabilities, refer to the Atlassian Developer documentation: ADF Structure

  While ADF provides more formatting options than Markdown, it's also more complex to construct manually. Consider using the string-based setDescription method for simpler formatting needs.

  Parameters:

  environment - a Map representing the ADF structure for the issue's environment

• @java.lang.Override
  void setFixVersions(java.lang.String[] versionNames)

  Sets the fix versions for the issue using their names.

  This method updates the issue's fixVersions field with the specified version names. The provided version names must exist in the project's version configuration.

  Usage Examples:

  Setting a Single Fix Version:

  // Set a single fix version for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions("1.0")
   
   }

  Setting Multiple Fix Versions:

  // Set multiple fix versions for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions("1.0", "2.0", "3.0")
   
   }

  Notes:

  • The version names must match existing versions in the project's configuration.
  • If invalid or non-existent version names are provided, Jira will reject the update during submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's fix versions field.
  • Fix versions are typically used for release planning and reporting in Jira.

  Parameters:

  versionNames - one or more version names to set for the issue; must correspond to existing versions in the project

• @java.lang.Override
  void setFixVersions(@groovy.lang.DelegatesTo(value: MultiOptionNameUpdater)
  groovy.lang.Closure<?> specification)

  Sets the fix versions field for the issue using the specific version names.

  This method sets the issue's fixVersions field to the specified version names. The provided version names must exist in the project's version configuration. This method overwrites any existing value(s).

  Usage Examples:

  Setting a Single Fix Version:

  // Set a single fix version for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions {
           set("1.0")
       
   }
   }

  Setting Multiple Fix Versions:

  // Set multiple fix versions for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions {
           set("1.0", "2.0", "3.0")
       
   }
   }

  Notes:

  • The version names must match existing versions in the project's configuration.
  • If invalid or non-existent version names are provided, Jira will reject the update during submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's fix versions field.
  • Fix versions are typically used for release planning and reporting in Jira.

  Parameters:

  specification - a closure that specifies version name (or names) to set for the issue; operates on a MultiStringUpdater instance

• @java.lang.Override
  void setFixVersions(java.lang.Long[] ids)

  Sets the fix versions for the issue using their ids.

  This method updates the issue's fixVersions field with the specified version id. The provided version ids must exist in the project's version configuration. This method overwrites any existing value(s).

  Usage Examples:

  Setting a Single Fix Version:

  // Set a single fix version for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions(10000)
   
   }

  Setting Multiple Fix Versions:

  // Set multiple fix versions for an issue
   Issues.getByKey("JRA-1").update {
       setFixVersions(10000, 10001, 10002)
   
   }

  Notes:

  • The version ids must match existing versions in the project's configuration.
  • If invalid or non-existent version names are provided, Jira will reject the update during submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's fix versions field.
  • Fix versions are typically used for release planning and reporting in Jira.

  Parameters:

  ids - one or more version ids to set for the issue; must correspond to existing versions in the project

• void setLabels(java.lang.String[] labels)

  Sets one or more labels on the issue.

  Usage Examples:

  // Add labels to the issue
   Issues.getByKey("JRA-1").update {
       setLabels("urgent", "backend")
   
  
   // Remove a label from the issue
   Issues.getByKey("JRA-1").update {
       remove("obsolete")
   }
  
   // Set the labels to a specific issue
   Issues.getByKey("JRA-1").update {
        setLabels {
            set("new-feature", "api")
        }
   }
   }

  Labels are case-insensitive and can contain up to 255 characters. If a label does not exist, it will be created when added.

  Note: Be cautious when setting labels, as this operation can overwrite existing labels on the issue.

  Parameters:

  labels - a list of labels that will be set on the issue

• void setLabels(@groovy.lang.DelegatesTo(value: MultiStringLabelUpdater)
  groovy.lang.Closure<?> specification)

  Updates the issue's labels using a closure to specify the modifications.

  This method allows you to dynamically add, remove, set, or clear labels on an issue. By providing a closure, you can specify the exact changes you want to make to the labels. The closure operates on a MultiStringUpdater delegate, which provides methods to manipulate the labels.

  Available Operations:

  • add(String... labels): Add one or more labels to the issue.
  • remove(String... labels): Remove one or more labels from the issue.
  • set(String... labels): Replace all existing labels with the specified labels.

  Usage Examples:

  // Add labels to the issue
   Issues.getByKey("JRA-1").update {
       add("urgent", "backend")
   
  
   // Remove a label from the issue
   Issues.getByKey("JRA-1").update {
       remove("obsolete")
   }
  
   // Set the labels to a specific issue
   Issues.getByKey("JRA-1").update {
        setLabels {
            set("new-feature", "api")
        }
   }
   }

  Labels are case-insensitive and can contain up to 255 characters. If a label does not exist, it will be created when added.

  Note: Be cautious when setting or clearing labels, as these operations can overwrite existing labels on the issue. Use add or remove to modify labels incrementally.

  Parameters:

  specification - a closure that specifies how to update the labels; operates on a MultiStringUpdater instance

• @java.lang.Override
  void setOriginalAndRemainingEstimate(java.lang.String originalEstimate, java.lang.String remainingEstimate)

  Sets both the original and remaining time estimates for the issue.

  This method updates the issue's timetracking field with the specified original and remaining estimates. The values should be provided in Jira's time tracking format, which supports combinations of weeks, days, hours, and minutes. Examples of valid formats include:

  • 2w 4d: 2 weeks and 4 days
  • 3d 5h: 3 days and 5 hours
  • 2h: 2 hours
  • 45m: 45 minutes

  Usage Examples:

  Updating an Issue:

  // Set both original and remaining estimates for an existing issue
   Issues.getByKey("JRA-1").update {
       setOriginalAndRemainingEstimate("3d", "2d 4h")
   
   }

  Creating an Issue:

  // Set both original and remaining estimates while creating a new issue
   Issues.create("PROJECT", "Task") {
       setSummary("Document API updates")
       setOriginalAndRemainingEstimate("1w", "3d 5h")
   
   }

  Notes:

  • Both estimates must be provided in Jira's time tracking format.
  • The timetracking field must be present in the issue's configuration for the operation to succeed.
  • If either format is invalid or the field is not configured, Jira will reject the update during API submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's time tracking fields.
  • Passing null for either estimate will leave the respective field unset.

  Parameters:

  originalEstimate - the original time estimate in Jira's time tracking format (e.g., "1w", "3d"); can be null to leave it unset

  remainingEstimate - the remaining time estimate in Jira's time tracking format (e.g., "2d 4h"); can be null to leave it unset

• @java.lang.Override
  void setOriginalEstimate(java.lang.String estimate)

  Sets the original time estimate for the issue.

  This method updates the issue's timetracking field with the specified original estimate. The value should be provided in Jira's time tracking format, which supports combinations of weeks, days, hours, and minutes. Examples of valid formats include:

  • 2w 4d: 2 weeks and 4 days
  • 3d 5h: 3 days and 5 hours
  • 2h: 2 hours
  • 45m: 45 minutes

  Usage Examples:

  Updating an Issue:

  // Set the original estimate for an existing issue
   Issues.getByKey("JRA-1").update {
       setOriginalEstimate("3d 4h")
   
   }

  Creating an Issue:

  // Set the original estimate while creating a new issue
   Issues.create("PROJECT", "Bug") {
       setSummary("Fix critical bug")
       setOriginalEstimate("1w 2d")
   
   }

  Notes:

  • The estimate must be provided in Jira's time tracking format.
  • The timetracking field must be present in the issue's configuration for the operation to succeed.
  • If the format is invalid or the field is not configured, Jira will reject the update during API submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's time tracking fields.

  Parameters:

  estimate - the original time estimate in Jira's time tracking format (e.g., "1w", "3d 5h"); must be a valid string

• void setParent(java.lang.String parentKey)

• void setPriority(java.lang.String priority)

  Sets the priority of the issue using the given priority name.

  This method updates the issue's priority field with the specified priority name. The priority must exist in your Jira instance; otherwise, an error will occur when the issue is updated.

  Usage Example:

  // Update the issue to set its priority to "High"
   issue.update {
       setPriority("High")
   
  
   // Set the priority when creating a new issue
   Issues.create("PROJECT", "Task") {
       setSummary("New Task")
       setPriority("Highest")
   }
   }

  Note:

  • The priority names are case-sensitive and must exactly match the names defined in your Jira instance.
  • Common priority names include "Highest", "High", "Medium", "Low", and "Lowest", but they may vary based on your Jira configuration.
  • If an invalid priority name is provided, Jira will return an error when the issue is updated or created.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's priority.

  Parameters:

  priority - the name of the priority to set for the issue

• void setRemainingEstimate(java.lang.String remainingEstimate)

  Sets the remaining time estimate for the issue.

  This method updates the issue's timetracking field with the specified remaining estimate. The value should be provided in Jira's time tracking format, which supports combinations of weeks, days, hours, and minutes. Examples of valid formats include:

  • 2w 4d: 2 weeks and 4 days
  • 3d 5h: 3 days and 5 hours
  • 2h: 2 hours
  • 45m: 45 minutes

  Usage Examples:

  Updating an Issue:

  // Set the remaining estimate for an existing issue
   Issues.getByKey("JRA-1").update {
       setRemainingEstimate("2d 3h")
   
   }

  Creating an Issue:

  // Set the remaining estimate while creating a new issue
   Issues.create("PROJECT", "Task") {
       setSummary("Complete project documentation")
       setRemainingEstimate("1w")
   
   }

  Notes:

  • The estimate must be provided in Jira's time tracking format.
  • The timetracking field must be present in the issue's configuration for the operation to succeed.
  • If the format is invalid or the field is not configured, Jira will reject the update during API submission.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's time tracking fields.

  throws:

  IllegalArgumentException if the provided remainingEstimate is null or empty

  Parameters:

  remainingEstimate - the remaining time estimate in Jira's time tracking format (e.g., "1w", "2d 3h"); must be a valid string

• @java.lang.Override
  void setReporter(java.lang.String accountId)

  Sets the reporter of the issue to the user identified by the given account ID.

  Note: In alignment with secure coding best practices, this library does not provide functionality to perform user lookups by name. Instead, use account IDs to identify users.

  You can look up account IDs of users in Jira by visiting: https://<your-domain>.atlassian.net/people

  This method updates the issue's reporter field with the specified user's account ID.

  Usage Example:

  // Set the reporter using an account ID
   issue.setReporter("5b10a2844c20165700ede21g");
   

  Parameters:

  accountId - the account ID of the user to be set as the reporter

• void setReporter(User user)

  Sets the reporter of the issue to the specified user.

  This method updates the issue's reporter field using the account ID from the provided User object. Ensure that the User object contains a valid accountId.

  Note: In alignment with secure coding best practices, this library does not provide functionality to perform user lookups by name. Instead, use account IDs to identify users.

  
  You can look up account IDs of users in Jira by visiting:
  https://<your-domain>.atlassian.net/people

  
  Usage Example:

  // Set the reporter using a User object
   def reporter = Users.getByAccountId("5b10a2844c20165700ede21g");
   Issues.getByKey("JRA-1).update {
     setReporter(reporter)
   
   }

  See Also:

  Users.getByAccountId

  Parameters:

  user - the User object representing the reporter; must include a valid accountId

• void setResolution(java.lang.String resolution)

  Sets the resolution of the issue using the given resolution name.

  This method updates the issue's resolution field with the specified resolution name. The resolution must exist in your Jira instance; otherwise, an error will occur when the issue is updated.

  Usage Example:

  // Update the issue to set its resolution to "Fixed"
   issue.update {
       setResolution("Fixed")
   
  
   // Note: Resolutions are typically set during transitions that resolve an issue.
   // Ensure that setting the resolution directly aligns with your workflow.
   }

  Important Notes:

  • The resolution names are case-sensitive and must exactly match the names defined in your Jira instance.
  • Common resolution names include "Fixed", "Won't Fix", "Duplicate", "Incomplete", "Cannot Reproduce"; however, they may vary based on your Jira configuration.
  • If an invalid resolution name is provided, Jira will return an error when the issue is updated.
  • If you want to clear resolution, use null as parameter value setResolution(null)
  • Setting the resolution field typically signifies that an issue has been resolved. Be cautious when setting this field directly, as it may affect issue statuses, workflows, and reports.
  • Ensure that the user executing the script has the necessary permissions to modify the issue's resolution.

  Parameters:

  resolution - the name of the resolution to set for the issue

• @java.lang.Override
  void setSecurityLevel(java.lang.String issueSecurityLevelName)

  Sets the security level for the issue using the specified security level name.

  This method updates the issue's security level, which controls who can view the issue based on the project's security scheme. The provided security level name must match an existing security level configured in the project.

  Usage Example:

  // Set the security level to "Internal"
   issue.setSecurityLevel("Internal");
   

  Important: Ensure that the security level name is valid and exists in the project's security scheme. If the security level does not exist or the user does not have permission to set it, the operation will fail when the issue is submitted.

  Parameters:

  issueSecurityLevelName - the name of the security level to set for the issue

  See Also:

  Jira Security Level Documentation

• @java.lang.Override
  void setSkipScreenCheck(boolean skip)

  Whether to check if the field is present on the screen

  Parameters:

  skip - true to allow a field to be set when it is not on the screen, false to prevent the operation

• void setSummary(java.lang.String summary)

  Sets the summary (title) for the issue.

  Required field when creating an issue. Provides a concise description of the issue's purpose. If the summary is not set, the issue creation request will fail with a validation error.

  Example Usage in Groovy:

  Issues.create("TEST", "Bug") {
       setSummary("Fix login button alignment")
   
   }

  Parameters:

  summary - the summary (title) of the issue