Notification Configuration

Configure the Base URL

You must configure the base URL before attempting to configure notifications for your team. IQ Server uses the base URL value to construct links for outgoing notifications.

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. Refer to the documentation of your reverse proxy server to correctly configure it to set these headers.

Configure Email Notifications

The IQ Server can be configured to send email notifications for events such as policy violation notifications. This functionality requires an SMTP server. The SMTP connection details must specify hostname and port and optionally may also specify username, password, TLS/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 email server is configured by a system Administrator using the Email option in the System Preferences menu.

Configure Notifications through JIRA Cloud

Note

IQ Server Notifications are compatible with Jira Cloud, Server, and Data Center. Jira Server and Jira Data Center users are recommended to use the Sonatype for Jira integration.

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

JIRA integration requires:

Base URL must be configured.
Basic JIRA connection information (url, username, password)
Default field values if selecting a JIRA project issue type that has custom required fields without default values defined in JIRA

Warning

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 the 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.

Example Enabled Basic JIRA information in config.yml

# Notification JIRA settings.
# Note that any user of the IQ Server will have access to see all projects and applicable issue types available
# to the configured JIRA account. More details available in the 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 these 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 initial 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.

Example curl request for retrieving all JIRA create issue metadata

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 .

Example JIRA required system field with no default value

            "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_##### .

Example JIRA required custom field with no default value

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

Example logging statements for JIRA

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