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 or alerts will not function correctly.

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

  • 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 )

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, which 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"

The connection details are established with hostname and port and optionally with the addition of usernamepasswordtls and ssl. The systemEmail parameter will be used as the sender email for any emails the IQ Server sends. All fields are required.

Finally, when setting email configuration, make sure you have also set the Base URL, otherwise sending of notification emails may fail.

Atlassian JIRA

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