Assets Discovery step by step
Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
This article explains how Assets Discovery work. Looking for Discovery Agent usage? Read more about Discovery Agent
This tutorial will guide you through the most important aspects of Asset Discovery, from setting up the Discovery tool to importing its data into Jira.
On this page:
- Before you begin
- Extracting Discovery
- Configuring Assets Discovery
- Running a scan
- Importing data into Jira
- Automating the import process
Before you begin
Make sure to check the system requirements.
Assets Discovery requires Jira Service Management to function:
You can download Assets Discovery for both Cloud and Data Center products from the Atlassian Marketplace.
If you're using Jira Service Management Data Center, Assets Discovery has two parts: Assets Discovery Jira app and Assets Discovery tools (desktop app for network scans).
You must have Jira Admin permissions as well as administrator permissions on your Windows (as a member of the admin group) or Linux system to install Assets Discovery:
For Jira Data Center only, once you install the app, you can download the Discovery tool. Go to Manage Apps, then Assets Discovery, and then Discovery Download, and download the tool from the link on the page. For Jira Cloud, Assets Discovery Cloud is already a part of Cloud Assets.
Extracting Discovery
Assets Discovery is available in the form of a package that contains MSI (Microsoft Installer) installers for the Discovery Tools (Assets Discovery and the Assets Discovery collector) and the Assets Discovery Agent. Before you run Assets Discovery, you must unpack the package and install the application into a directory on your local system.
After downloading Discovery:
Create a directory to hold the tool. Assets Discovery Tool must be able to both read and write data within this directory.
For Windows users, we recommend creating a new directory in
C:\Program Files
. Or, you can use the default folderC:\Program Files\Atlassian\Discovery Tools
, which is automatically selected when you run the installer.For Unix users, we recommend creating a new directory in
/opt/
.
Unpack the files from the Assets Discovery package into your directory and install Discovery.
If you’re using a Windows machine, run
Discovery_Tools_Setup.msi
installer package. If you’re installing the agent, use theDiscovery_Agent_Setup.msi
package.If you’re using a Linux machine, you'll need an additional package to unpack MSI.
Configuring Assets Discovery
This process refers to Assets Discovery configuration, but you can configure Assets Discovery Collector export in a similar way. Explore Assets Discovery Collector
To configure Assets Discovery:
Set up credentials to scan network devices.
These credentials on target devices are a prerequisite, as the Discovery will connect to target devices using WMI, WinRM, SSH, or SNMP. For every credential, you have a test button to test the connectivity and credential on a target device.Set the target device IP addresses for scanning. You can add individual IPs, IP ranges, or networks in CIDR notation. Explore how to configure scan settings
In this example, we’re also adding the localhost loopback IP:
127.0.0.1
. As an initial test, we recommend adding at least this to gather data from the computer running the Discovery. Note that credentials are required also for localhost.Select the export type as FileCopy and append a single dot
.
to the export path.
This will ensure that the zip file containing the scan data is saved in the Discovery main directory. Alternatively, you can set the export to None to store the file in the scans directory. Later on, you can automate this process and upload the file directly to your Jira. However, for the initial setup, you’ll need the zip file to facilitate the Jira importSelect Test Export Path to confirm the export path is writable.
When the initial configuration is done, you can now the Discovery configuration window and run your first scan.
Running a scan
To run a Discovery scan, open your command-line program and execute discovery.exe without any parameter.
After the scan completes successfully, a zip file will be created in the Discovery installation directory.
Storing the scan file in Jira Service Management Data Center
This section applies only to Jira Data Center. In Jira Cloud, you can upload the scan file directly from the Jira user interface when creating the import.
For Jira Service Management Data Center, you need to copy the zip file to a location that Jira can access, either in your local-home folder or the shared-home folder if you’re using a clustered Jira. For a single node without a shared-home, create a new folder inside your jira-home
folder. For a clustered Jira with a shared-home folder, place the file in a new folder created at the root of the shared-home.
Here are some requirements for storing the scan file:
Place the file in a new folder created at the root of your Jira. Don’t place it inside other existing folders like
import
orexport
, otherwise your Jira won’t read the import data.Avoid using spaces and special characters in the folder names. Restrict to alphanumeric characters, hyphens, and underscores. For example
: /discovery-scan
,/discoveryscan
, or/discovery_scan
.Grant full permissions to the Jira user. If you’re using a clustered Jira, ensure the permissions are granted on each node.
This folder should be exclusive to Discovery and Jira Assets. Do not place any other files or folders inside this dedicated scan, export, or import folder. Only include those generated automatically by the Discovery and Assets processes.
When the initial import is finished, you’ll be able to automate this process.
Importing data into Jira
Depending on what Jira Service Management product you use, you can import your Discovery data into:
Import data into Jira Service Management Cloud
To import your Discovery data into Jira Service Management Cloud:
Create an object schema in your Jira.
We recommend using the ITSM template as it contains all the common object types used by Discovery. Explore how to create an object schemaIn your object schema, create a new import configuration:
In the Import type configuration, select Discovery Import.
In the Define structure field, select the file created by Assets Discovery.
The import connection should automatically create a structure and configuration for the data it receives from Assets Discovery. If the import connection fails to create a structure and configuration automatically, you might need to create both manually.
Return to your Import configuration.
In the upper-right corner of the your import configuration, go to Setting
and select Generate token.
Copy the token created by Assets.
Open your Assets Discovery configuration and go to the Export tab.
In the Export Type field, change the setting to Cloud.
In the Auth token field, paste the token you copied from Assets. Is your token validation failing? Explore how to troubleshoot your export to cloud
Exit Assets Discovery configuration and review your results in Jira.
Your object schema should now contain object types, objects, and attributes imported from Assets Discovery. Now that Assets Discovery is configured to export directly to Assets, the results of any Assets Discovery scans, either manual or scheduled, will automatically upload, import, and synchronize with Assets.
Is your token validation failing? Explore how to troubleshoot your export to cloud
Import data into Jira Service Management Data Center
To import your Discovery data into Jira Service Management Data Center:
Create the object schema if you haven’t done it yet. Read how to create an object schema
In the upper-right corner of your object schema, go to Object Schema and select Configure.
In the Schema configuration view, open the Import tab:
- If there’s no import structure, you’ll see the message “You don't have any import connections yet”. Select Create Import configuration to create a new import structure.
If an import structure has already been created, select Create Configuration.
In the window that appears, select Discovery import.
If Discovery import isn’t available, it means Assets Discovery isn’t installed on your instance. If this happens, go to Marketplace and download Assets Discovery.Fill in the Name field and select Next.
In the Directory field, indicate the directory of your Discovery scan file and select Next.
Select the user to perform the automatic sync and select Save Import configuration. You can also set up the interval for automatic data syncs, if needed.
Create the predefined structure and configuration. You can do this manually or Assets can create them automatically. To make this process automatic, select:
Create predefined structure – this will create object types with attributes and relationships in the schema
Create predefined configuration – this will create type mappings in the import configuration
Once the data import is complete, you’ll see the import configuration and object mappings.
Once finished, you will see the import configuration and object mappings.
Then, go to your import configuration, enable your mappings and configuration, and then sync them.
If everything went smoothly, your data should be imported to your object types. If you're missing something, go back to your configuration and edit the fields or the mappings.
Automating the import process
When the initial configuration and import are complete, you can automate the import process:
In your Discovery tool, open the Export tab.
In the Export type, select one of the following options:
- Use SFTP to automatically copy the zip file to the Jira local-home or shared-home location.
- Use FileCopy to transfer the zip file to a mounted remote path on Windows.
- Use Cloud to automatically upload the file to a Jira Service Management Cloud instance. This requires a token that you can generate when you import your Discovery data for the first time.
After you set up your export type, select Install Service. This action will configure a Windows service, and the scans will run according to the Scan schedule settings. Once each scan completes, Discovery will automatically send the scan file to your Jira.