Notification Configuration

Configure the Base URL

You must configure the Base URL before attempting to configure notifications for your team. If your Base URL is not set, links that direct back to the IQ Server will not work.

IQ Server uses the Base URL value to construct links inside the notifications it sends. For example, if IQ Server sends an email as part of an application policy alert, it will use the Base URL to construct a link that leads direclty to the Application Report.

IQ Server also 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.

If you have set the applicationContextPath to a custom value, that value is not automatically appended to the baseUrl value when constructing links. Be sure to explicitly include a custom application context path as part of the baseUrl value if one is needed to access IQ Server.

To configure the baseUrl parameter:

In IQ Server Release 138 and later

Use the configuration REST API.

In IQ Server Release 137 and prior

Uncomment the baseUrl setting in config.yml

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

Configure Notifications through Email

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. Make sure you have also set the Base URL.

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.

Test the mail server is configured correctly using the UI Send Test Email option.

Clicking Send Test Email will use the whatever values are entered on the form or existing saved values if nothing has been edited. If there are problems sending mail, examine the application log for detailed messages.

Configure Notifications through JIRA Cloud

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 (url, username, password)
  • Default field values if selecting a JIRA project issue type which has 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 configured user. 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.

In IQ Server Release 139 and later

This can be configured using the JIRA configuration REST API.

In IQ Server Release 138 and prior

This can be configured in your config.yml file.

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"
              ]
            },


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"
                }
              ]
            }

Note: 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