Creating an Integration Profile

RealTheory uses Integration Profiles to store a specific set of configuration options so users do not have to enter the third-party ticketing system configuration details each time they want to open a ticket against a RealTheory recommendation. These profiles define the connection between RealTheory and a specific third-party ticketing system, including the authentication credentials, the project (Jira only), and the default ticket type settings.

Note: RealTheory currently supports Jira Cloud, Jira Data Center, and ServiceNow.

Prerequisites

Before you create an integration profile, review the configuration article for your ticketing system to ensure it has been set up correctly:
- Configuring Jira for RealTheory Ticketing Integration
- Configuring ServiceNow for RealTheory Ticketing Integration
To manage Integration Profiles, you must have one of the following roles assigned to your RealTheory user account:
- sys_admin
- jira_admin - for Jira profiles
- servicenow_admin - for ServiceNow profiles

Procedure

As a user with the sys_admin, jira_admin, or servicenow_admin role, navigate to Settings > Ticketing Systems.
Click Add Integration.
Provide a unique, meaningful name for the profile.
Note: When creating a ticket, the user must select the correct profile using only the profile name. Meaningful names will help the user.
Add a Description that will help you remember the purpose and scope of the new profile.
Select the Provider. Currently supported third-party ticketing systems are:
- Jira Cloud
- Jira Data Center
- ServiceNow
The fields in the rest of the form change to match the selected provider.
Select the authentication method:
- Jira Cloud - Basic Authentication
- Jira Data Center - Basic Authentication or Personal Access Token (PAT)
- ServiceNow - Basic Authentication. This is pre-selected because it is the only supported method.
Provide the authentication credentials:
- Jira Cloud - the Basic Authentication supports a Username + Secret authentication model where Username is the email address, and Secret is the API token associated with the account
- Jira Data Center:
  - Basic Authentication supports a Username + Secret authentication model where Username is the Jira username, and Secret is the password associated with the account
  - Personal Access Token (PAT) supports a token authentication model
- ServiceNow - Basic Authentication supports a Username + Secret authentication model where Username is the ServiceNow User ID, and Secret is the password associated with the account
Enter the API URL for the third-party ticketing system. For ServiceNow, this field is labeled Instance URL.
The API URL is used for machine-to-machine communication. This field is required.
Jira Cloud Example: https://<your-domain>.atlassian.net
Jira Data Center Example: https://jira.<your-company>.internal
ServiceNow Example: https://<instance>.service-now.com
Enter the Console URL for the third-party ticketing system.
The Console URL is used to build a clickable link for human users to access the ticketing system console. This field is required.
Jira Cloud Example: https://<your-domain>.atlassian.net
Jira Data Center Example: https://jira.<your-company>.internal
ServiceNow Example: https://<instance>.service-now.com
(Jira only) Enter the Default Project Key to identify the project where RealTheory will add tickets. This field is required.
Note: The integration account must have the required permissions for this project. ServiceNow does not use a project key, so this field is not shown when ServiceNow is selected.
Enter the Default Issue Type to specify the issue type RealTheory will create by default when adding tickets. This field is required.
- Jira - the Default Issue Type must be valid in the specified project. For example, Task, Bug, or Story.
- ServiceNow - the Default Issue Type is the ServiceNow record type. Supported record types are Incident and Problem.
Note: Users can override the Default Issue Type during ticket creation if the default does not meet their needs.
(Optional) If your ticketing system uses custom statuses, expand the More options section and use the Status Mapping table to map external ticket statuses (for example, To Do, Open, Done) to RealTheory statuses so RealTheory can consistently track and report ticket progress.
Note: The table is pre-populated with default mappings for the selected provider.
Click Validate Configuration to confirm that the information you provided is valid and that RealTheory can connect to the third-party ticketing system.
The Validate Configuration dialog opens and runs a series of checks, showing the result of each one.

When the checks are complete, click Close. If a check fails, address the related issue, then validate again.
Click Add Integration.
The new profile will be added to the list, which is sorted alphabetically by default.