Bulk importing requests
Bulk import requests to a project if you need to avoid time-consuming manual data entry or migrate data from another system.
You can also update multiple requests at once using sessions in Bulk Importer. For more information, see Update existing requests 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.
You can bulk upload requests to projects or to a component within a project such as an objective, narrative, etc.
Where are the uploaded requests?
Once you upload requests, the data is available in:
- the Requests tab
- Task Tracker app
- the component within the project such as objective, narrative, etc (if targetType and targetId are mentioned in the template). For more information, see Prepare data in the template.
Before you start
Before you can begin to import requests, 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 requests 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.
Learn moreFor example: You want to import 200 entities in two batches (100 +100). If you upload the batches one after the other in the same session, then after you upload the second batch, the data uploaded in the first batch will get replaced with data in the second batch. To avoid this data loss, always upload the first batch in one session and begin a new session for the next batch. Likewise, begin new session to add more new resources.
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 Requests 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.
ccContacts
Specifies email IDs of users responsible for fulfilling the request.
TipYou can add multiple email IDs separated by a comma.
description
mandatory
Describes the requested information, such as the document name, version number, or department where you might expect to find the information.
TipUse HTML tags to format text. For example: <b>, <i>, <ol>, <ul>.
For information about requests, see Requesting documentation.
dueDate
Specifies by when the request should be fulfilled.
Date must be in YYYY-MM-DD format.
emailMessage
Provides the ability to customize the body of the email. emailSubject
Provides the ability to customize the email subject line.
owner
conditionally mandatory
Specifies name of the person responsible for fulfilling the request.
It is best suited to add non-Diligent One users to this field.
This field becomes mandatory if ownerUser is left blank.
ownerEmail
conditionally mandatory
Specifies email ID of the person responsible for fulfilling the request.
It is best suited to add non-Diligent One users to this field.
ownerUser
conditionally mandatory
Specifies user ID (UID) or email ID of the person responsible for fulfilling the request.
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 values provided in the owner and ownerEmail fields.
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
position
Specifies the order in which the request is displayed.
projectId
mandatory
Specifies ID of the project where this request needs to be placed.
For example:
https://stark.projects.highbond.com/audits/
90305/dashboard, where 90305 is the project ID.NoteAlternatively, in this field, you can provide reference ID of a new project that you have added in the current template. This will associate the request 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.
received
Specifies status of the request:
- True: Received.
- False: Open.
The default is false.
requestorUser
mandatory
Specifies user ID (UID) or email ID of the person requesting the documentation.
sendRecurrentNotifications
Specifies whether to send an email to the request owner and CC'ed persons on a specified recurring schedule.
- True: Sends the email on a recurrent schedule.
- False: Turns off the email schedule.
For more information about recurring reminders, see Sending recurring request reminders.
ccUsers
Specifies user ID (UID) or email ID of internal users who are part of the organization responsible for fulfilling the request.
Specifies component type where this request 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
issues
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 request 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
- 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
The table below provides a variety of tips you can use to quickly and efficiently prepare your content in the Excel templates.
Task | Steps |
---|---|
View both the template and your source document on one screen
|
Windows users: Press Windows key + right or left arrow. Mac users: Drag the window to fill one half of the screen. |
Copy/paste data from multiple cells in the template |
|
Treat a number or formula as text | In Excel, insert an apostrophe before the number in the formula. |
Change the column width or row height to automatically fit your data |
In Excel, do any of the following:
|
Enter sequential numeric data |
|
Use formulas to calculate data |
|
Sort or filter data in a single column |
|
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.
Example 1
Scenario
Using the Bulk Importer, you want to accomplish the following in a single upload:
- Create a new project.
- Create a new objective and associate it to the new project.
Process
You download and open the Excel template. You go to the Projects worksheet and fill in the required fields including the referenceId. You copy the referenceId of the new project.
Then, you go to the Objectives worksheet, add the new objective details, and in the parentResourceId field, you paste the referenceId that you copied from the Projects worksheet. By doing this, you are associating the new objective to the new project.
Result
When you upload the template, the following things happen:
- A new project is created.
- A new objective is created, and the new objective is associated to the new project.
Example 2
Scenario
Using the Bulk Importer, you want to accomplish the following in a single upload:
- Create 1 new project.
- Create 1 new objective and associate it to the new project.
- Create 2 new risks and 2 new controls and associate them to the new objective.
Process
You download and open the Excel template, go to the Projects worksheet and add in details of the new project such as the referenceId and other required fields. You copy the referenceId of the new project.
Then, you go to the Objectives worksheet and add in the new objective, and in the parentResourceId field of the objective, you paste the referenceId of the new project that you copied from the Projects worksheet. You now copy the referenceId of the new objective.
Then, you go to the Risks worksheet, add in the new risks, and in the objectiveId field of each risk, you paste the referenceId of the new objective that you copied from the Objectives worksheet.
Finally, you go to the Controls worksheet, add in the new controls, and in the objectiveId field of each control, you paste the referenceId of the new objective that you copied from the Objectives worksheet.
Result
When you upload the template, the following things happen:
- 1 new project is created.
- 1 new objective is created, and it is associated to the new project.
- 2 new risks and 2 new controls are created, and they are associated to the new objective.
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 request, use the relevant target type and ID in the Excel template.
Component: Project
Target type: projects
Target ID: Provide project ID.
For example: https://stark.projects.highbond.com/audits/13360/dashboard, where 13360 is the project ID.
Component: Project > Planning > Planning Files OR Project > Results > Results Files
Target type: project_files
Target ID: Provide planning file ID or results file ID.
For example: https://stark.projects.highbond.com/audits/13360/planning/56292, where 56292 is the planning file ID.
https://stark.projects.highbond.com/audits/13360/results/56293, where 56293 is the results file ID.
Component: Project > Fieldwork > Overview
Target type: objectives
Target ID: Provide objective ID.
For example: https://stark.projects.highbond.com/audits/13360/objectives/55979, where 55979 is the objective ID.
Component: Project > Fieldwork > Narratives > Narrative
Target type: narratives
Target ID: Provide narrative ID.
For example: https://stark.projects.highbond.com/audits/13360/objectives/55979/narratives/22422, where 22422 is the narrative ID.
Component: Project > Fieldwork > Risk Control Matrix > Risk
Target type: risks
Target ID: Provide risk ID.
For example: https://stark.projects.highbond.com/audits/13360/objectives/55979/risks/168393, where 168393 is the risk ID.
Component: Project > Fieldwork > Risk Control Matrix > Control
Target type: controls
Target ID: Provide control ID.
For example: https://stark.projects.highbond.com/audits/13360/objectives/55979/controls/1571107, where 1571107 is the control ID.
Component: Project > Fieldwork > Walkthroughs > Walkthrough
Target type: walkthroughs
Target ID: Provide walkthrough ID.
For example: https://stark.projects.highbond.com/audits/13360/objectives/55979/walkthroughs/1538197, where 1538197 is the walkthrough ID.
Component: Project > Fieldwork > Test Plan > Test plan
Target type: control_test_plans
Target ID: Provide control test plan ID.
For example: https://stark.projects.highbond.com/audits/39215/objectives/72348/control_test_plans/1657599, where 1657599 is the control test plan ID.
Component: Project > Fieldwork > Testing > Control test
Target type: control_tests
Target ID: Provide control test ID.
For example: https://stark.projects.highbond.com/audits/39215/objectives/72348/round_one_testing/5102879, where 5102879 is the control test ID.
Component: Project > Issues > Issue
Target type: issues
Target ID: Provide issue ID.
For example: https://stark.projects.highbond.com/audits/39215/findings/249870, where 249870 is the issue ID.
Component: Project > Fieldwork > Walkthroughs
Target type: walkthrough_summaries
Target ID: Not available in the user interface, please contact Support for assistance.
Component: Project > Planning
Target type: project_plannings
Target ID: Not available in the user interface, please contact Support for assistance.
Component: Project > Results
Target type: project_results
Target ID: Not available in the user interface, please contact Support for assistance.
Component: Project > Fieldwork > Risk Control Matrix
Target type: risk_control_matrices
Target ID: Not available in the user interface, please contact Support for assistance.
Component: Project > Fieldwork > Testing
Target type: testing_rounds
Target ID: Not available in the user interface, please contact Support for assistance.
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 requests 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.
How it works
You open a previous session from the Bulk Importer page. You open the template uploaded in the previous session and make the required changes. Then, you upload the template in the Bulk Importer page.
Important
- Use previous sessions to make changes or correct previously uploaded data.
- Begin a new session to upload new resources, even when they are related to previously uploaded data.
For example: You have uploaded a project and a few objectives in a previous session. Open the same session to update those resources. Begin a new session if you want to upload risks, controls, or any other resource related to that project or objectives.
Requirements before you update
Before you can update, you must do the following:
-
Decide which session to select. This is required as the uploaded data is linked to a session. Therefore, you have to open the session linked to the data you want to update. For information about sessions, see Sessions in Bulk Importer.
-
Ensure you have access to the Excel template uploaded in the session that you want to select. The template contains reference IDs, which are unique identifiers for each row in the template. These are required to update the data. For more information about reference IDs, see Prepare data in the template.
CautionData is updated based on the corresponding session and reference IDs. Mismatch between the session and the reference IDs may create duplicates or result in an error.
Steps to update
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 previous session
No previous sessions will be available when you open the Bulk Importer page for the first time. You must upload at least once to see the session details.
For more information about sessions, see Sessions in Bulk Importer.
-
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.
-
Scroll down to the Sessions section and click on the Session ID of your choice.
Result The session loads with the selected session id appended to the URL.
NoteEnsure you select the appropriate session, in which you want to update the previously uploaded data. Mismatch between the session and the reference IDs may create duplicates or result in an error. For more information, see Requirements before you update.
Update data in the template
-
Open the Excel template uploaded in the session that you selected in the previous step. This file contains the previously uploaded data along with the reference IDs. For more information, see Requirements before you update.
NoteEnsure the ACL Add-In option is disabled before you modify the Excel template, else the upload will fail. For more information about ACL Add-Ins, see Configuring Add-In for Excel.
-
Go to the corresponding worksheet and update the data based on the reference IDs. For more information about the fields, see Prepare data in the template
NoteEnsure you update the values corresponding to the reference IDs, based on which the previously uploaded data will be updated. Mismatch may create duplicates or result in an error.
-
Save and close the file.
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.
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. |