How to bulk create Tags?

You will learn how to create tags in bulk by either uploading a file, using the UI, or using the API.

Last Updated: 02/09/2024

Overview

You may need to create tags for targets in bulk when you can't add a tag at the source scanner with a file upload -- think of Tenable Nessus -- or if you don't have a CMDB and need to manage tags in bulk. 

You can do this in the platform three ways; file upload in UI, via Prioritize Page, or API.

As of 02/09/24 we only support a self-service File Upload via the UI. We will update this page when the other methods become available.

Business Logic

As a user with the Tags write permission, which we believe will normally be an Admin type role, you can now view a new Sub-Navigation item within the Settings page named File Uploads.

You can use this page to upload and view the status of your uploads. 

• Every upload for Tags must follow the following CSV template using these specific column names.
  • target_id
  • tag_key
  • tag_value
  • action
  • new_value
• The actions supported are:
  • add = Creates a new tag if the target id is found and the tag key + tag value doesn't already exist
  • remove = Finds target by ID, if the tag_key + tag_value exist for that target it deletes it. If it doesn't find the tag_key + tag_value it skips.
  • modify = Finds target by ID, if the tag_key + tag value exist for that target, it replaces the tag_value with the value placed in the new_value column. If the tag does not exist, no new tags will be created this row is skipped.
  • NOTE: if you wish to edit the Tag Key, you will have to delete the original key and create a new one.

• Each tag_key and tag_value is case sensitive. The platform will attempt to find the target by using its ID, and then attempt to see if the tag_key and tag_value exists for this source type (in this case User input). If it exists it skips the row.
  • Quick context, Tags created from your scanner receive a source of that scanner. This means you could have a tag with a source from Qualys and CMDB and User Input. 
  • We attempt to de-duplicate User Input tags before creating them, but we will not restrict you from creating a tag that already exists in another source. This means you can have 3 identical tags, one for each source. If needed, you can use the following queries to be specific in your reports:
    • tags.source_type
    • tags.source_name
• Case sensitivity means that the following tags are unique:
  • Tag Key = Department, Tag Value = Product
  • Tag Key = department, Tag Value = product
  • Tag Key = dePartment, Tag Value = prOduct
• If the target is not found using the target id you provided the row is skipped.
  
  

Finding your Target IDs

To find your target IDs, you can download all targets or load a report or filter your report to the specific assets you're interested in.

1. Select one, several, or all items in the report table and click Download CSV.
2. Select how many of the items you want to download in your CSV.
3. Click Download CSV.
4. In your CSV you will find a column named Target ID, use this column as your target_id.

CSV File Template

The CSV file you upload must use the following column names. We've provided an example file with example values.

Self-Service File Upload via the UI

1. Go to Settings
2. Click on File Uploads Sub-Navigation Tab
3. Click on Attach File (located on top right of Tag Uploads card)
4. Select the file you'd like to upload.
5. Click Save Changes at the top right of the page (blue button).
6. Refresh page, your new task should populate in the table at the bottom of the screen. 
   1. Task ID is the unique ID for this specific task.
   2. Status =
      1. Finished = means the file was parsed successfully without errors. It does not mean any tags were created (this may happen if you upload the same file twice with no changes).
      2. Parsing Error = this means a column is missing or spelled incorrectly, or a format issue with your data occurred. Attempt to address the issue and try again. If it continues reach out to your CS Team.
      3. Generic Error = this means the error is in our code or processing and not something you can change. If this continues please submit a help ticket and provide your CS Team with a copy of the file.