Insight cloud onboarding guide
This guide is for anyone getting started on setting up Insight in Jira Service Management Cloud Premium or Enterprise editions. With Insight, teams can track their assets, configuration items, and resources to gain visibility into critical relationships between applications, services, the underlying infrastructure, and other key assets. Insight is built on Jira, giving teams a simple and quick way to tie assets and configuration items to service requests, incidents, problems, changes, and other issues to gain valuable context.
Step 1 - Access Insight
Whether you are on a licensed or trial version of Jira Service Management Premium or Enterprise, you can access Insight by selecting it from the top menu.
Step 2 - Understand how Insight is structured
This section will give an overview of how the Insight database is structured.
An object is anything that is singular and unique - a laptop, a server, a piece of equipment, a contract, or even a vehicle. Objects are your actual assets/configuration items (CIs).
Objects can be linked to your Jira issues so whenever an issue comes in, the issue immediately has more context. Objects can also be linked with each other using object references to show how objects depend on each other.
Similar objects are grouped into object types. Object types act as containers for your actual objects. Object types go within a schema and define the objects that schema contains. You can define these yourself or you can use an object schema template that will come pre-populated with certain object types that you can customize. Common object types include:
- Business services
But they don’t have to be IT assets. For example, many people add other useful information such as:
- Business Priority
You can organize object types in the hierarchy tree in a way that makes sense. This tree is mainly for navigation and readability and you can have empty object types to aid this, but it can be set up to offer inheritance of attributes to make creating object types easier.
An object schema is the actual configuration management database (CMDB) that contains your object types and objects. You can create multiple object schemas in Insight, which is useful for a number of reasons:
- Breaking data into smaller chunks helps with auditing the data and keeping it accurate.
- If you have sensitive data, e.g., employee information, it may be simpler to keep all that data together in one object schema with restricted access permissions.
When deciding how to put data into Insight, consider the uses of the data and who will update it so the data can be grouped into logical object schemas. You can easily use multiple object schemas for one use case and create links between objects in different object schemas.
Insight automatically syncs with the Services feature within Jira Service Management and creates a read-only object schema within the Insight database with objects entered for each service documented within your service registry. This means you can link your Jira Service Management services to various assets and CIs to build up a service map to support changes, incidents, and problems.
An attribute represents a specific piece of information that is attached to an object, such as a description of that object, its model number, another associated object, or a user assigned as the object’s owner.
Each object type will have its own set of attributes. For example, the object type “laptops” might have the attributes: model, serial number, user, warranty expiry date, etc.
Entering actual values for the attribute will define an object. This can be done manually or automatically (see Step 4).
All object types will have four mandatory attributes:
- Created Date
- Last Updated Date
The last three are set automatically. Every other attribute can be defined by the admin. And because there’s a unique key attribute, the name of each object does not need to be unique.
A reference is a connection between two different objects in Insight. Each object can be connected to many other objects, not directly, but through attributes containing references to other objects.
For example, if location is its own object type, then each location object can be one of your business' office locations. This allows you to quickly set the location for every laptop by selecting “Stockholm” for example.
Object references don’t have to be set manually. They can be added automatically from network scanners, importers, automation rules, etc.
References between objects have two main benefits:
- You can map dependencies between your objects. For example, you can map your ITSM application to business services and the different hosts, operating systems, and files they depend on. This map can be incredibly useful for understanding the downstream effects of changes (if I change this OS, what might be impacted?), as well as finding the causes of incidents and problems. And because each object can be linked to a Jira issue, over time you build up a comprehensive history of your infrastructure or other business assets which further helps with solving issues and problems.
- It is easier to manage. For example, if an office moves from Montreal to Toronto, you only need to update the object Montreal rather than go through each laptop changing Montreal to Toronto.
There are two types of object references:
- Outbound references are references from the current object to another object.
- Inbound references point from another object toward the current object.
References between objects can be viewed using the graphical viewer. You can decide what reference types you have (e.g. installed on, owned by, vendor) and you can color-code these in the object schema settings.
Insight has two types of permissions:
- Object schema permissions - In object schema settings, you can define who has administrative permissions for a particular object schema, who can update object schema data, and who can just view the data.
- Object type permissions - Sometimes you might want Jira Service Management customers to only see certain information in an object schema but you don’t want to give them access to view all the data within the entire object schema. You can use object type permissions here.
Step 3 - Choose what data to include
Every instance of Insight will be unique as every company requires different information to be tracked. Insight can store any piece of information that is useful for you and your business to know and understand. What specific assets or configuration items you should include will depend on what you are trying to do. This section includes our advice for deciding what data should be included.
Define your problem
Most tools are implemented to solve a problem, and Insight is no exception. It could be that your incident resolution time is not as fast as you’d like, or perhaps changes to a specific service often cause unexpected outcomes because you can’t easily see service dependencies.
Find your problem and use that to define everything else, from who you involve to what assets and information you include in your database. Look at the problem and understand what extra information is needed to help overcome it. This information will define your object types.
Adding too much information at once can make it tough to check accuracy so try to focus on one problem at a time. Once your first problem is solved, Insight can grow to solve other problems.
Start with your services
If you plan to use Insight for configuration management, our advice would be to use a top-down approach by starting with your services. Then map what those services depend on (e.g., applications and hosts). Then map what those dependencies depend on and so on. This way you will quickly build up a service map that can be used when incidents and change requests come in. You can expand to documenting other areas as needed.
Think beyond physical items
As Insight lets you define the objects you need, you aren’t limited to traditional or even physical assets. Business services, for example, are not physical assets but are often critical for people to understand in detail. You can link all of a service’s physical and non-physical dependencies to it so just by looking at a business service object, you can get a full understanding of how it’s running.
You can go as abstract as you’d like. Common examples include objects of business importance, environment types, departments/teams, locations, etc.
Example: categorizing business services
Let’s say all your business services are added to Insight under the object type “Business Services”. You may want to categorize those business services into “Finance,” “Logistics,” “Sales,” “Infrastructure,” etc. You can do this with an attribute in the Business Service object type or you can make these categories their own object type called “Service Category”.
The benefit of this is that you can add details (attributes) specific to the business service category. Maybe there’s someone responsible for all finance business services. You don’t want to add that person directly to every finance “Business Service” object as it will become harder to maintain. Instead, you just add it once to the “Finance” object in the “Service Category” object type and now you only need to update it in one place and don't have to duplicate data.
You can also have rules that take the operation status of each individual finance business service and roll them up into an overall status for the finance category. This way you can quickly see if there are any service problems with each category of service by viewing the category objects.
You don’t need to add these types of objects to Insight but it’s important to know that you’re not limited by traditional assets/configuration items. It all depends on what you want to do which is why understanding your goals and the information you need to achieve them is so key.
Look ahead and grow gradually
Keep in mind any extensions you may want to include in the future. This will both shape what data you choose to include, as well as how you structure your data.
While it’s good to keep your desired end-state in mind, we recommend building Insight up in a gradual way. Trying to do one huge big release with 100% accurate data for 1000s of objects is very tough. Building small and adding new attributes, objects, and object schemas as you go is going to be significantly simpler.
Our recommendation is to find a problem, build up Insight to fix it, then move on to the next problem, growing Insight as you go.
Set realistic expectations for accuracy
100% accuracy at all times should be the goal but in reality, that may not be possible. As long as the data is sufficiently accurate to offer more business value than not having it in the first place, then you’re still coming out ahead. Many CMDB projects can be delayed or even fail as they’re waiting to be ‘perfect’ before go-live.
Step 4 - Get your data into Insight
Entering everything manually could be a life’s work in a large organization. So that’s why there are a few tools to help.
Insight Discovery (available on the Atlassian Marketplace at no cost) is an agentless scanner that picks up network assets. You can choose which assets and attributes you pull into your Insight object schemas as well as create your own scanning patterns to find more niche assets. If you run it on a schedule, it will pick up changes and keep data updated. With automation rules, you can even trigger Jira issues, email notifications, and more based on detected changes.
You can use Insight imports to bring in data from other sources. These import rules can be synchronized on a schedule so you can update your data when required. For each import type, you need to define where the data is stored and where it needs to go in Insight.
If you're using a spreadsheet like Excel or Sheets that contains all your assets, you can use the CSV import to bring your data in Insight. This will ensure that you have an integrated and transparent system where you can link your assets to issues and analyze impact.
You can import objects into Insight with a JSON file that holds the data to import.
Tips and tricks
We recommend running Insight Discovery and importers as often as you can during quiet times. Take a look at how often you think data will change and the importance of that data to determine how often you need to schedule it to run. You want to stay just ahead of how fast the data is changing.
With Insight Discovery, you can have different scanning patterns run at different frequencies to lower the resources required to keep Insight as up-to-date as possible.
Step 5 - Decide how to structure your data
Split data into logical object schemas
We recommend having multiple object schemas based on the use of the data or the owner(s) of the data.
Breaking your data down into different object schemas is both more user-friendly and easier to maintain than one large schema. Teams such as finance or HR departments who may need some information from Insight, don’t need to be bombarded with information they don’t care about. It’s also easier to ask one team to do a regular check of data quality on one object schema than it is to ask them to check only certain parts of one large object schema.
Federate your data
If you have a perfectly usable database or source of information somewhere and there are processes already in place to keep it updated, the data doesn’t need to be moved into Insight. Instead, it’s likely better to create a copy of the relevant data using integrations and have those integrations run on a schedule to update the Insight information.
Insight comes with a number of importers (see the previous section). With these importers, the information you need to make decisions can be made available in a Jira issue/Insight itself, but you’re not maintaining two separate copies.
Sometimes people will create separate object schemas for this imported data, other times people integrate them into bigger object schemas. If the data is going to be used for different uses (e.g., IT support and HR), then it makes more sense to have it as a separate object schema rather than to tie it directly to your IT object schema and then having to give HR access to that schema too.
If it’s not possible to use an importer, you could create an object and give it a URL attribute that links to the other database where more information can be found. This option is good if you just want agents to be able to view the information and don’t want to search or report based on it.
Avoid reusing the same attributes everywhere
If an attribute is used in many places and has the same repeated values, it oftentimes makes more sense to make it its own object type. For example, you could have an attribute called Vendor for the object types laptop, phone, printer, monitor, etc. And for each object, you would need to type (or import) the vendor name for that particular laptop or phone.
This is fine, but it’s more efficient to have an object type called “Vendors” and set each vendor as an object for a number of reasons:
- You may want more than just the vendor name. Maybe you want other information related to the vendor such as a support contact number or links to contracts. You don’t want to have to repeat this for every laptop and every phone. Just have it once and link it to the vendor object. This also helps if you want to do elements of vendor management within Jira Service Management.
- The vendor will be standardized this way, meaning reports are easier to run. If you wanted to report on the number of support requests per vendor, you can be confident you’re not missing something because someone wrote Micrsoft or Aple somewhere.
- If the vendor rebrands or needs to be changed in some way, then you only need to update it in one place.
Vendor is just one example but others include business importance levels, deployment environments, departments, and locations.
Step 6 - Configure Insight custom fields for your Jira issues
This section explains how you can configure Jira issues to link them with Insight objects. This could be adding the affected business service to your incident issues, adding a computer to a hardware request issue, or adding a set of potentially affected hosts to a change request issue.
Insight gives you access to a new, specific Insight custom field. This custom field needs to be configured to point at a particular set of objects.
Step 7 - Set up automation
Insight introduces a new set of object-related automation triggers and actions that can be used to automate various tasks.
- Updating the owner or status of a laptop during the workflow of a service request
- Updating the status of parts of your infrastructure to ‘incident in progress’ when an incident issue comes in
- Auto-routing Jira issues to certain staff based on the attached object(s)
- Notifying key people when licenses, contracts, or warranties are due to expire
Step 8 - Decide how to keep your data accurate
Keeping your data up to date is critical, otherwise, teams are going to be working under false assumptions which might delay incident resolutions or lead to the wrong outcome after a service request.
There are a number of ways to keep your data up to date in Insight, many relying on automation to do the heavy lifting.
- Perform regular audits of your data.
Insight automation rules can be set up to notify people to perform a data audit on a schedule. This gives them the reminder to do a quick sanity check to make sure key assets are up to date.
- Synchronize Insight Discovery, and relevant importers and integrations regularly.
A big cause of out-of-date data is not synchronizing Insight often enough with external sources of data. Think about how often data in your external source changes and how often it is used in Jira Service Management to get the balance correct. If something changes often and is linked to issues regularly, it may need to be synchronized every 24 hours. Other integrations may be able to wait weeks or even months.
- Use automation rules.
When decisions are made in Jira issues that change asset/configuration data, it’s important to capture that in Insight.
For example, if an agent decides to give a user a new laptop because the one they have is broken, there is information that needs to be captured in Insight:
- The new laptop needs its owner updated to the requestor and its status updated to “in service”.
- The old laptop needs its owner removed and its status updated to “broken”.
As the agent communicates this to the requestor, you can use transition screens and Insight post functions to capture this type of information and set the new statuses and owners in Insight using automation.
This is just one example, but as you build Insight into your Jira workflows, consider what information from the issue may need to be relayed back into Insight. Ideally, you want as little manual updating of Insight as possible as that’s something that is easy to forget to do.
Insight Query Language- IQL
Insight query language (IQL) is the language used to query Insight. IQL comes in handy when you want to build search views, automation rules, advanced references between assets, or even instruct imports.
Tips and tricks