> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/tracr-user-guide/5.-integration-tool.md). # 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. {% stepper %} {% step %} ### Start a new session From the Tracr menu, select **Integration > Integration Tool** to display the **Session history** page, then select **New session**. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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. {% endstep %} {% endstepper %} {% hint style="warning" %} 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. {% endhint %} ## 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. {% hint style="info" %} Tip: To only display diamonds with missing files on the **Session overview** tab, move the **Hide complete diamonds** toggle to the ‘on’ position. {% endhint %} ### 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. {% hint style="info" %} 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. {% endhint %} To exclude a diamond from the upload: * Point to a **Participant ID** on the **Session overview** tab, and then select the **Exclude diamond** icon.

Excluding a diamond.

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.

Including an excluded diamond.

## 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. {% hint style="info" %} 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. {% endhint %} Tracr displays a number in an orange circle on the **Missing files** tab to tell you that there are missing files.

A session with 15 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**](broken://pages/c648ce1e22de29247b407f1387b749fb5c45b8a6#integration-tool-missing-files-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.

A session with one failed file.

### 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**](broken://pages/c648ce1e22de29247b407f1387b749fb5c45b8a6#integration-tool-failed-files-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. {% hint style="info" %} 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. {% endhint %} Tracr displays a number in a white circle on the **Unexpected files** tab to tell you that there are unexpected files.

A session with one unexpected file.

### 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**](broken://pages/c648ce1e22de29247b407f1387b749fb5c45b8a6#integration-tool-unexpected-files-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. {% hint style="warning" %} Important: Every time you update a diamond, you must provide the fields marked in the Data Dictionary as 'required'. {% endhint %} ## 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](https://search.tracr.com/) 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](https://search.tracr.com/) 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.](https://docs.tracr.com/docs/cross-participant-search-xps/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tracr.com/tracr-user-guide/5.-integration-tool.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.