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 for outgoing notifications.
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.
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 Mail REST API or through IQ Server's UI via the Email option in the System Preferences menu.
You can test the email server configuration using the Send Test Email option. For troubleshooting, check the application log.
Configure Notifications through JIRA Cloud
IQ Server Notifications are compatible with Jira Cloud, Server, and Data Center. Jira Server and Jira Data Center users are encouraged to use the Lifecycle 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 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 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 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. 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