Notification Configuration

Base URL

The Base URL is the web address used when navigating to the server user interface or using the REST API. 

When the Base URL is not set, notifications and alerts which create links back to IQ Server will not function correctly.

The IQ Server uses the Base URL value to construct absolute URLs back to IQ server in cases such as:

  • application policy alert emails (ie. to build a link to the Application report )
  • repository policy alert emails (ie. to build a link to the Repository report )
  • JIRA policy alert notifications ( ie. to build a link to the Application report )
  • IQ for SCM pull request and status checks ( ie. to build a link to the Application Report )

To configure the baseUrl parameter, uncomment the baseUrl setting in config.yml

baseUrl: http://nexus-iq-server.example.com/

IQ Server uses the X-Forwarded-Proto and X-Forwarded-Host headers to resolve user-facing URLs when a HTTP request comes through a reverse proxy server. Please refer to the documentation of your reverse proxy server to correctly configure it to set these headers.

Email Server

The IQ Server can be configured to send email notifications for events such as policy violation notifications. This functionality requires an SMTP server.

The connection details must specify hostname and port and optionally may also specify usernamepasswordTLS/STARTTLS and SSL. The system email is also required and will be used as the sender email for any emails the IQ Server sends.

Once configured, make sure you have also set the Base URL, otherwise sending of notification emails may fail.

Starting in version 83, the mail server configuration is stored in IQ Server's database. If a mail server configuration already exists in the config.yml file, then IQ Server version 83 will attempt to migrate it on first startup in a one-off operation, after which it will be obsolete.

IQ Server 83 and newer

NEW IN RELEASE 83

The mail server is configured by a System Administrator using the Mail REST API or through IQ Server's UI via the Email option in the System Preferences menu.

IQ Server 82 and older

The mail server is configured along with a number of other options in the mail section of the config.yml file displayed in Mail Configuration in config.yml.

mail:
    hostname: mail.example.com
    port: 465
    username: user@example.com
    password: password
    tls: true
    ssl: true
    systemEmail: "system@localhost"

Atlassian JIRA 

Nexus IQ Notifications are compatible with Jira Cloud, Server, and Data Center. Jira Server and Jira Data Center users are encouraged to use the IQ for Jira integration for advanced feature set.


The IQ Server can be configured to create Atlassian JIRA issues in response to policy violations.

JIRA integration requires:

  • Base URL must be configured. If not, even valid JIRA configurations will fail to create issues
  • basic JIRA connection information defined in config.yml ( url, username, password )
  • default field values defined in config.yml for any JIRA project issue type custom required fields without default values defined in JIRA


JIRA Project Access Control

A JIRA system user should be configured for integration with IQ Server. Any authenticated user of the IQ Server will be able to view the projects and applicable issue types available to the user configured in the config.yml. IQ Server users who can create and edit policy will be able to set up automated ticket creation for any project over which the configured JIRA user has authority to create tickets.


The default config.yml contains a commented example JIRA configuration section which can be edited to be read by the server on startup.

# Notification JIRA settings.
# Note that any user of the Nexus IQ Server will have access to see all projects and applicable issue types available
# to the configured JIRA account. More details available in the Nexus IQ Server documentation. If enabled, ensure that
# the baseUrl configuration setting is also enabled and correct, because generated tickets contain links to the server.
jira:
  # The JIRA server address
  url: "https://jira.example.org"

  # The username used to connect to the JIRA server
  username: "exampleuser"

  # The password used to connect to the JIRA server
  password: "examplepassword"

  # Any JIRA project issue type required fields without default values defined in JIRA must have their initial
  # field values defined here in order for that project and issue type to be available for policy notifications 
  #customFields:
    # Example 'user' type system field
    #reporter:
    #  name: "username"

    # Example 'array' type system field
    #labels:
    #  - test
    #  - bug

    # Example 'version' type custom field    
    #customfield_12001:
    #  name: "Example"

    # Example 'option' type custom field   
    #customfield_10050:
    #  value: "P1"

    # Example 'number' type custom field
    #customfield_13001: 10
    
    # Example 'datetime' type custom field
    #customfield_14000: "2016-11-01"

Debugging Missing JIRA Projects and Issue Types 

If there is a problem seeing the expected JIRA projects and issues types when configuring JIRA type policy notifications a common cause is JIRA issue fields not meeting selection criteria.

A JIRA project is considered valid for policy notifications when it contains at least one issue type that is not a sub-task and the issue type has all fields satisfying this criteria:

  • field is not required OR
  • field is required AND
    • field name is one of project, summary, issuetype, description OR
    • field has default value defined in JIRA  OR
    • field is defined in IQ Server config.yml customFields section with an inittial value

Determining Required JIRA Project Fields

IQ Server uses the JIRA Get create issue meta REST API to look up projects and issue types fields. You may examine this data yourself to confirm the names of required custom fields for your JIRA projects. Atlassian has additional example resources.

curl -v -u exampleusername "http://localhost:8080/rest/api/2/issue/createmeta" > createmeta-all.json

In the response, locate the JIRA project of concern, then examine its issue types, then examine all the fields that have "required" : true  and "hasDefaultValue": false .

            "reporter": {
              "required": true,
              "schema": {
                "type": "user",
                "system": "reporter"
              },
              "name": "Reporter",
              "autoCompleteUrl": "https://jira.example.org/rest/api/latest/user/search?username=",
              "hasDefaultValue": false,
              "operations": [
                "set"
              ]
            },


In JIRA 7, the reporter field of an issue is required by default. In order to create JIRA notifications, you must either turn off the required setting, assign a default value for the issue type, or configure it using the custom fields section in the config.yml.

JIRA has system fields and custom fields - any custom field name will have a name format of customfield_##### .

            "customfield_10050": {
              "required": true,
              "schema": {
                "type": "option",
                "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
                "customId": 10050
              },
              "name": "Support Priority",
              "hasDefaultValue": false,
              "operations": [
                "set"
              ],
              "allowedValues": [
                {
                  "self": "https://jira.example.org/rest/api/2/customFieldOption/10010",
                  "value": "P1",
                  "id": "10010"
                },
                {
                  "self": "https://jira.example.org/rest/api/2/customFieldOption/10011",
                  "value": "P2",
                  "id": "10011"
                },
                {
                  "self": "https://jira.example.org/rest/api/2/customFieldOption/10012",
                  "value": "P3",
                  "id": "10012"
                },
                {
                  "self": "https://jira.example.org/rest/api/2/customFieldOption/10013",
                  "value": "P4",
                  "id": "10013"
                },
                {
                  "self": "https://jira.example.org/rest/api/2/customFieldOption/10014",
                  "value": "unassigned",
                  "id": "10014"
                }
              ]
            }

In config.yml, you must refer to JIRA fields by its field key, not its display name.

There are alternative ways to determine Jira field keys to specify in the config.yml.

Server Logging For JIRA Integration

Additional IQ Server logging can be enabled which reports excluded JIRA projects and issue types.

Find the loggers section of config.yml and insert a trace logger:

"com.sonatype.insight.brain.jira": TRACE

Restart IQ Server.

When JIRA type policy notifications are being configured, the clm-server.log should have logging statements indicating what projects and issues types are excluded:

2019-02-01 17:44:34,444-0500 TRACE [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Omitting unacceptable issue-type: Task for project: AC
2019-02-01 17:44:34,444-0500 TRACE [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Omitting unacceptable issue-type: Sub-task for project: AC
2019-02-01 17:44:34,444-0500 TRACE [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Omitting unacceptable issue-type: Story for project: AC
2019-02-01 17:44:34,444-0500 TRACE [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Omitting unacceptable issue-type: Bug for project: AC
2019-02-01 17:44:34,444-0500 TRACE [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Omitting unacceptable issue-type: Epic for project: AC
2019-02-01 17:44:34,444-0500 DEBUG [dw-35 - GET /rest/jira/project?timestamp=1549061067133] admin com.sonatype.insight.brain.jira.JiraService - Ignoring project AC; which has no acceptable issue-types