Bulk import issues if you need to avoid time-consuming manual data entry or migrate data from another system.
You can also update multiple issues at once using sessions in Bulk Importer. For more information, see Update existing issues in bulk.
How it works
You open a new Bulk Importer session and download the Excel template from the Bulk Importer page in the Launchpad. You prepare data in the template and then you upload the template in the Bulk Importer page.
Where are the uploaded issues?
Once you upload issues, the data is available in:
- the Issues tab
- Issue Tracker app
- OrganizationName Project Report (the final audit report)
- all of the downloadable Issues reports
Before you start
Before you begin to import issues, you must create a project through the Bulk Importer by filling in the Projects worksheet or from the user interface.
Note
Using the Bulk Importer, you can create many Diligent One resources in a single import. You can fill in the worksheets of all the resources required and import them all, in one go.
Workflow
Permissions
Only System Admins can bulk upload Diligent One resources from Bulk Importer.
Upload new issues in bulk
Note
- Interface terms are customizable, and fields and tabs are configurable. In your instance of Diligent One, some terms, fields, and tabs may be different.
- If a required field is left blank, you will see a warning message: This field is required. Some custom fields may have default values.
Open a new Bulk Importer session and download the Excel template
-
Note
If your company uses more than one instance in Launchpad, make sure the appropriate instance is active.
- Select Platform Settings > Organization.
If you do not see Organization as an option, the account you used to sign in does not have Admin privileges.
- Under Bulk Importer, click Manage bulk resources.
A new Bulk Importer session begins, with the session ID appended to the URL.
CautionAlways begin a new session to add new resources, else you may lose previously uploaded data.
NoteYou can use previous sessions to update previously uploaded data. For more information, see Update functionality in the Bulk Importer.
-
Under Select resource, in the Resource type, select All resources.
- Click Download .xlsx Template.
The Excel template saves to your local machine.
Prepare data in the template
- Open the downloaded template (HighBond_Template.xlsx) and go to the Issues worksheet.
- Copy and paste or enter your data into the template.
For help with entering data, see Tips for preparing content.
Note
- If you use Add-In for Excel, ensure the ACL Add-In option is disabled before modifying the Excel template. To learn how to do it, see Configuring Add-In for Excel.
- Do not change the name of the worksheet or the fields. These are case sensitive and must not be modified.
- The maximum number of rows that can be uploaded at once is 2000 (including all the worksheets).
Field Description mandatory
Specifies a unique ID for the resource. This must be unique for each row in the worksheet.
It can contain a combination of text and numbers, and the maximum length is 255 characters.
This field is the primary key for each row in the template. You will need this key if you want to update this resource again.
Important
You can use reference IDs to associate resources to one another, on the fly. For example, you can create a new project and a new objective associated to that project in the same upload. You can do this by creating a link between the project and the objective by providing referenceId in the required field.
To learn more about associating Diligent One resources in Bulk Importer, see Using reference IDs to link resources in Bulk Importer.
Note
Reference IDs are required when you add or update resources using the Bulk Importer. They are not available when you add / update resources from the user interface of Diligent One.
projectId
mandatory
Specifies ID of the project where this issue needs to be placed.
For example:
https://stark.projects.highbond.com/audits
/90305/dashboard, where 90305 is the project ID.Alternatively, in this field, you can provide reference ID of a new project that you have added in the current template. This will associate the issue with the project when you upload the template.
To learn more about associating Diligent One resources in Bulk Importer, see Using reference IDs to link resources in Bulk Importer.
description
mandatory
Specifies detailed description of the issue.
TipUse HTML tags to format text. For example: <b>, <i>, <ol>, <ul>.
For information about issues, see Managing issues and remediation
owner
conditionally mandatory
Specifies name or email ID of the person responsible for the issue.
This field is best suited to add non-Diligent One users.
This field becomes mandatory if ownerUser is left blank.
ownerUser
conditionally mandatory
Specifies user ID (UID) or email ID of the person responsible for the issue.
Learn how to get the UID of a user.
You cannot add non-Diligent One users to this field.
This field becomes mandatory if owner is left blank.
Note that specifying an ownerUser overrides any value provided in the owner field.
NoteEnsure the user you want to add to this field has already been assigned to the respective project / framework.
To learn about assigning user roles, see Assigning user roles in projects and frameworks
deficiencyType
mandatory
Specifies classification of the issue, such as Management Recommendation, Significant Deficiency, Material Weakness.
The options available depend on the project type.
recommendation
Specifies detailed description of the recommended actions to be taken based on the issue.
title
Specifies title of the issue.
severity
Specifies intensity of the issue.
The options available depend on the project type.
published
Specifies visibility of the issue:
- True: Visible to all users.
- False: Hidden from users assigned the Contributor Tester, Contributor User, Oversight Executive, and Oversight Reviewer roles.
The default is false.
identifiedAt
Specifies timestamp when the issue was identified.
The default is the current date and time.
reference
Specifies ID of the issue. risk
specifies detailed description of the risk or the impact the issue will have. escalation
Specifies the person, department, or organizational body that the issue should be brought to.
The options available depend on the project type.
cause
Specifies detailed description of what caused the issue to issue. effect
Specifies detailed description of the effect the issue will have on the organization. costImpact
Specifies the estimated or actual monetary cost associated with the issue. scope
Specifies the extent to which the issue affects the organization.
The options available depend on the project type.
executiveSummary
Specifies overview of the issue that typically summarizes information from other related fields, such as risk/impact, cause, and effect. executiveOwner
Specifies executive owner of the issue. projectOwner
Specifies project owner of the issue. closed
Specifies overall status of the issue:
- True: Closed.
- False: Open.
The default is false.
remediationStatus
Specifies remediation status of the issue.
The options available depend on the project type.
remediationPlan
Specifies detailed description of the remediation plan. remediationDate
Specifies deadline for the issue to be remediated by.
Date must be in YYYY-MM-DD format.
actualRemediationDate
Specifies the date the issue was actually remediated.
Date must be in YYYY-MM-DD format.
retestDeadlineDate
Specifies deadline for the issue to be retested by.
Date must be in YYYY-MM-DD format.
actualRetestDate
Specifies the actual date when the issue was retested.
Date must be in YYYY-MM-DD format.
retestingResultsOverview
Specifies detailed description that specifies whether or not the issue has truly been remediated. position
Specifies value that determines the order in which the issue is displayed.
TipFill in the values in sequential order, so that the resources appear in the same order after the import.
entities
Specifies entity IDs of the entities tagged to the issue.
You can find entity ID in the URL when you navigate to an entity.
For example:
https://stark.projects.highbond.com/
auditable_entities/33055, where 33055 is the entity ID.You can provide multiple IDs separated by commas.
Alternatively, in this field, you can provide reference ID of a new entity that you have added in the current template. This will associate the issue with the entity when you upload the template.
To learn more about associating Diligent One resources in Bulk Importer, see Using reference IDs to link resources in Bulk Importer.
For more information about entities, see Setting up entity tagging.
targetType
Specifies component type where this issue must be placed.
The target type must be one of the following:
projects
project_files
objectives
narratives
risks
controls
walkthroughs
control_test_plans
control_tests
walkthrough_summaries
project_plannings
project_results
risk_control_matrices
testing_rounds
The default is projects.
ImportantUse the exact terminology as mentioned above.
Note
Use only English default values for this field. Custom English values and localized (non-English) values are not yet supported in Bulk Importer.
For information about which target ID to use for which component, see Target type and ID for project components
targetId
mandatory
Specifies ID of the resource where this issue must be placed. You can find the resource ID in the URL.
For example:
https://stark.projects.highbond.com/audits
/90305/objectives/94778, where 90305 is the project ID and 94778 is the objective ID.In the targetId field, you can do one of the following:
specify the project ID if you want to place the issue under the project (this would be the same ID as mentioned in the projectId field).
specify the component ID (objective ID in the above example) if you want to place the issue under the component of a project. Note that the project ID must be mentioned in the projectId field.
For information about which target ID to use for which component, see Target type and ID for project components
customAttributes_1_term - customAttributes_n_term
Specifies custom attribute fields 1 through n.
By default, the template will have one pair of custom attribute term and value in the template. You can manually add nine more, making it a total of ten pairs.
To add, follow the same naming convention with a counter, for example: customAttributes_2_term, customAttributes_2_value, etc.
The custom attributes of a project, framework, and their components are defined in the project type. For more information about custom attributes, see Customizing terms, fields, and notifications.
customAttributes_1_value - customAttributes_n_value
Specifies custom attribute values 1 through n.
By default, the template will have one pair of custom attribute term and value in the template. You can manually add nine more, making it a total of ten pairs.
To add, follow the same naming convention with a counter, for example: customAttributes_2_term, customAttributes_2_value, etc.
The custom attributes of a project, framework, and their components are defined in the project type. For more information about custom attributes, see Customizing terms, fields, and notifications.
Note- If a value begins with a square bracket or contains a comma, semicolon, or a line break, enclose the value in double quotation marks (" ").
For example: "[2021]", "First, second asset", "This is important; this too". - For a multiple choice field, you can add multiple values by separating each value with a comma.
- For a dropdown list or a multiple choice field, ensure the values are exactly the same as provided in the options.
- Save and close the template.
Tips for preparing content
Preparing content involves:
- copying and pasting your source data into the Excel template
- entering data, where applicable, in the Excel template
- saving the template in preparation for bulk upload
Using reference IDs to link resources in Bulk Importer
Reference ID is a field in the Bulk Importer Excel template. It is the first field in all the worksheets and is available for all the resources. It is a unique identifier for each record in the worksheet.
Using reference IDs, you can associate Diligent One resources to each other, on the fly. For example, you can create a project and an objective that is associated to the project in the same import. You can do this by providing referenceId in the required field.
Target type and ID for project components
The following section shows the target type and ID for the respective project component.
Based on the component where you want to place the issue, use the relevant target type and ID in the Excel template.
Upload data
Do one of the following:
Result A success or failure message appears depending on the outcome of the process, and the latest session is updated in the Sessions table.
Sessions in Bulk Importer
A session in the Bulk Importer is a series of user interactions to import Diligent One resources. Each user session is recorded in the Sessions table.
The Sessions table contains the following information.
Field Name |
Description |
---|---|
Web Sessions |
Shows the list of web sessions. A web session refers to a session completed using the Bulk Importer user interface. A new session begins each time you open the Bulk Importer page. |
API Sessions |
Shows the list of API sessions. An API session refers to a session completed using an API platform such as Postman, etc. |
Refresh |
Reloads the Sessions table. |
Session ID |
Session identifier. In Web Sessions, you can click on the session ID to go to a particular session, and the session ID is appended to the URL. For example: https://stark.bulkimporter.highbond.com/import/bcc1e04e-4cd3-46d2-a8be-0b9083baccdc, where Note
Session IDs of both the web and API sessions look similar, ensure not to interchange the IDs to avoid any errors. |
Date |
Shows the date and time of the session. You can sort the date in ascending or descending order. |
Uploaded By |
Shows the name of the user. |
Status |
Shows the status of the upload, if it was successful or not. You can click on the status to view the complete import details. |
File Name |
Shows the name of the uploaded template / error log. For example: HighBond_Template.xlsx, ErrorLog.xlsx. Template You can click and download the template to correct any previously uploaded data. Error log An error log is generated when an upload fails. You can check the error log to rectify the errors and re-upload the template. Note
|
Update existing issues in bulk
You can update multiple items at once in Bulk Importer using sessions.
Note
You can only update resources that you have uploaded using Bulk Importer.
Troubleshooting
You can download and check the error log from the Sessions table. Understand common bulk upload errors and learn how to fix errors.
The following table provides a list of possible errors that may occur when uploading the template.
Error | Solution(s) |
---|---|
There may be more than 2000 rows in the uploaded file (including all the worksheets). | Remove the extra rows from the template and re-upload. |
Mandatory fields may be blank or missing in the uploaded file. | Ensure that all mandatory fields (marked with red and orange column names in the template) are completed. Note If you do not provide data in the mandatory fields, the row is not processed. |
Data format may be incorrect. |
Ensure that data in text fields is valid and does not exceed the maximum field length: 255 characters. Rich text fields do not have a character limit. |
Data values may be invalid or may not match the dropdown values. |
For example: The value for received and sendRecurrentNotifications fields in the Requests sheet must be True or False. |
Invalid fields in the template. |
|
Template may not be in expected format. |
Ensure the file format is .xlsx. |
Invalid worksheet names. |
Do not change the name of the worksheet. |
Session may have expired. |
Refresh the page and try uploading again. |
Session ID may be invalid. | Ensure you are using a web session ID. |