5. Integration Tool
Read this section to learn how to upload diamond data to Tracr using the Integration Tool.
Overview
Use the Integration Tool to manually upload your data files to your instance of the Tracr Platform. To begin, you need to create a new session. Then, you provide a prepared CSV file containing your diamond data.
There are templates to help you prepare the CSV file and a Data Dictionary, which describes the information that you must include in your CSV file for rough, split, or polished diamond data.
Do not mix different types of data in your CSV file and it is recommended that you use a text editor to edit the file.
Create a new session
You need to create a new session to upload diamond data to Tracr.
Provide your CSV file
Either drag and drop your prepared CSV file onto the page or select Or, select from device to browse for and select the file that you want to upload.
Tracr validates your CSV file and then, if the file is valid, asks you to confirm the integration type. It is important that the type you select matches the type defined in your CSV file. If not, you will get an error.
Select integration type and continue
Select your integration type, and then select Continue.
If validation is successful, Tracr displays the Required files page with the Session overview tab selected. You must then upload the files declared in the CSV file (ensuring that the filenames match) before you can complete the upload.
If validation fails, Tracr displays the Upload failed page. You should review the error text and make the appropriate changes to your CSV file. Select Quit and create a new session to upload the changed file.
Typical reasons for failing validation include:
Incorrect integration type selected during upload — the integration type is not correct for the template that you are trying to upload.
Incorrect columns in the CSV file that do not match the CSV template.
Incorrect entries in the CSV file that do not match the accepted values defined in the Data Dictionary.
Session overview
The Session overview tab provides a summary of the files that are associated with each diamond that you are uploading to Tracr. Before you can submit the session, you need to upload the data files referenced in the CSV file. If you are unsure, Tracr lists the names of these files on the Missing files tab.
To upload the required files:
Either drag and drop the files onto the page or select the Or, select from device button to browse for and select the files that you want to upload. As Tracr accepts the files, you will see a green tick appear under the appropriate file type on the Session overview tab. An orange exclamation mark indicates a file is missing. You will not be able to complete your session if there are any files missing.
Tip: To only display diamonds with missing files on the Session overview tab, move the Hide complete diamonds toggle to the ‘on’ position.
Exclude diamonds from upload
If you decide that you do not want to upload certain diamonds listed in your CSV file to Tracr, you can manually exclude those diamonds from the upload process. When you exclude a diamond, it is not submitted to Tracr.
Note: To identify an excluded diamond, look for 'You have excluded this diamond, by doing so it will not be submitted with this session' next to the Participant ID.
To exclude a diamond from the upload:
Point to a Participant ID on the Session overview tab, and then select the Exclude diamond icon.
To include an excluded diamond and submit it to Tracr:
Point to a Participant ID on the Session overview tab, and then select the Include diamond icon.
Missing files
The Missing files tab lists any files that Tracr is expecting you to provide. You will not be able to complete your session if there are any files missing.
Note: Your CSV file specifies the names and types of files, so if any of these are not to be provided, you need to edit your CSV file and start a new session.
Tracr displays a number in an orange circle on the Missing files tab to tell you that there are missing files.
To upload missing files:
Either drag and drop the files onto the Missing files tab or select the Or, select from device button to browse for and select the files that you want to upload. As Tracr accepts the files, you will see a green tick appear under the appropriate file type on the Session overview tab. An orange exclamation mark indicates a file is missing. You will not be able to complete your session if there are any files missing. When all files are uploaded, look for this message in the top right corner: ‘Ready to submit. All required files have been accepted and uploaded for this session, submit to continue.’
Download a missing files report
You can download a report which details the missing files for the session. The report lists the participant ID, file name, and file type.
To download a report:
On the Missing files tab, select download as .xlsx. Tracr generates the report which is downloaded and saved in your default downloads folder. View example report
Failed files
Tracr validates each file as it is uploaded and lists any files that fail validation on the Failed files page. You will not be able to complete your session if any files fail validation. The validation checks include:
CSV files
Is the header present?
Does the header match the template?
Are the values in the columns in each row valid according to the template and data dictionary?
Is the participant_id and participant_parent_id distinct from each other?
Are the filenames in each row unique from one another (for declared files, i.e., images, videos, scans, etc)?
Any type (for example, scan, plan, and image files)
Is the file > 0 bytes in length?
HTML, XML and PDF files
Is the file valid according to its declared file type (i.e., is a .xml file a valid XML file, is a .pdf a valid PDF file)?
HTML files
Does the file contain one or more of the HTML anchor tags expected in the HTML accepted by Tracr?
PDF files
Is the file greater than 100 kb in size?
Tracr displays a number in a red circle on the Failed files tab to tell you that there are failed files.
Download a failed files report
You can download a report which details the failed files for the session. The report lists the participant ID, file name, file type, and details.
To download a report:
On the Failed files tab, select download as .xlsx. Tracr generates the report which is downloaded and saved in your default downloads folder. View example report
Unexpected files
Tracr lists any unexpected files that you have uploaded on the Unexpected files page. While these files will not affect the upload, you should check the names and types of any files shown on the Unexpected files page to see whether these should have been included in your CSV file. To help you do this, you can download a file containing the names and types of any unexpected files.
Note: If you selected all the files in a folder to upload, you may have uploaded the CSV file again. If so, this appears on the Unexpected files page.
Tracr displays a number in a white circle on the Unexpected files tab to tell you that there are unexpected files.
Download an unexpected files report
You can download a report which details the unexpected files for the session. The report lists the file name and file type.
To download a report:
On the Unexpected files tab, select download as .xlsx. Tracr generates the report which is downloaded and saved in your default downloads folder. View example report
Submit a session
When all files are uploaded, look for the message ‘Ready to submit. All required files have been accepted and uploaded for this session, submit to continue.’ in the top right corner. You can now select the Submit session button.
Tracr provides you with a summary of your session: the number of diamonds to submit and the number excluded. Select the Submit button to submit the session for matching and verification.
You then have the option to download a session report or view the session on the Session history page.
Quit a session
You can quit a session without submitting it for matching and verification. To do this, select the Quit button at any time.
Tracr provides you with two options:
Save and quit – Tracr saves your session which appears on the Session history page with a status of ‘In progress’. Select Continue session to resume the session.
Abandon and quit (all progress will be lost) – When you abandon a session, it is no longer accessible, and Tracr deletes all progress.
Update a diamond after integration
Provided you have not uploaded the next processing step, you can update diamonds which you have already integrated.
Allowed update operations
Data for rough diamonds - split or polished not yet uploaded:
Update carat, add images, add videos, add optional data.
Data for split diamonds - split or polished version not yet uploaded:
Update carat, add images, add videos, add optional data.
Data for polished diamonds, which you can update at any time (unless sold and transferred out):
Update carat, add images, add videos, add grading certificate, add optional data.
Add an additional grading certificate for the same diamond.
Update procedure
To update a diamond that you have already integrated, you can:
Upload the same CSV file containing the diamonds you want to update. Only change the fields that you want to update. -or-
Create a new CSV file (using the appropriate Tracr template) with the diamonds you want to update and provide the updated values.
Important: Every time you update a diamond, you must provide the fields marked in the Data Dictionary as 'required'.
Updates to grading certificates
You can upload grading certificates multiple times to reflect diamond changes. For example:
Incorrect certificate provided.
Re-cut of the diamond.
Re-certification of the diamond.
Updates to other grading fields (inscription number, grading report number, and so on).
After a certificate is uploaded to Tracr, every next upload of grading information will be considered as an update and depending on what must be updated, it can be actioned in one of two ways:
If the grading certificate must be updated
Re-upload polished diamond data on your Tracr Portal (mandatory and updated fields only) and provide a new grading certificate and corresponding inscription number.
Upload of a new grading certificate (different file) will create a new grading record for the diamond.
Your Tracr Portal instance and Tracr Search will display:
The latest grading certificate.
The current and previous inscription numbers.
If the inscription number or other grading data other than the grading certificate has to be added or updated
Re-upload polished diamond data on your Tracr Portal and provide the previously uploaded grading certificate with updated or new grading information.
Your Tracr Portal instance and Tracr Search will display:
The latest (the same) grading certificate.
Updated grading information.
Tracr stores all grading certificates uploaded for a polished diamond and this data can be retrieved using the Tracr Search API.
Last updated