> 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/4.-integration.md). # 4. Integration Read this section to learn more about the preparation of diamond data to upload to Tracr and how to monitor an integration session. ## Overview Tracr provides two ways of integrating diamond data: * **Integration Tool** available on the Tracr Management Portal. Use the [Integration Tool](/tracr-user-guide/5.-integration-tool.md) to manually upload your diamond data files. * **Tracr Loader** available for Windows-based operating systems. Use [Tracr Loader](/tracr-user-guide/11.-tracr-loader.md) to automate the file upload process. You can download the Tracr Loader application and user guide from the **Integration toolkit**. ### Key concepts Before you integrate your diamond data, it is important that you understand the following key concepts: * A participant must claim the provenance of a diamond. Therefore, to register a diamond on Tracr, you must provide information about each diamond from a box so that Tracr can match the box information. If a diamond scan or video is provided, Tracr will also try to identify that single diamond individually. * To register a rough diamond 'family' (all splits and polished), Tracr must be aware of all the diamonds and how they are linked. Tracr therefore requires each diamond to have a unique participant\_id. Each split part of the diamond must have a unique ID. Each polished diamond must also have a unique ID so that Tracr knows which diamond is being polished and the new name of its polished version. * Tracr keeps information about each step from rough to polished. To link diamonds, you must always register the parent diamond first. To register a split diamond, Tracr must know the rough diamond (or the split, if it is a 'split of a split'). To register a polished diamond, Tracr must know which diamond is being polished.

How diamonds are linked by Parent ID. Not that diamonds IDs are for example only.

## Prepare your diamond data for an integration To register diamonds on Tracr, you must upload the required data through the Tracr Management Portal or the Tracr Loader whenever the diamond changes form and/or is passed from one process to another. This includes windowing and when unexpected incidents happen during the manufacturing process. You can also upload optional files like images and videos to enhance the Diamond Experience. {% hint style="info" %} Provided you have all the required data, you can upload multiple diamonds at once provided all diamonds in the upload are at the same stage. You cannot upload rough, all split, and polished diamonds in the same CSV file as Tracr requires different templates for different manufacturing steps. {% endhint %} ### Prepare a rough diamond dataset To integrate rough diamonds, you will need to provide basic information about the diamonds, including the carat, and some information about the sight box, including the year, sight number, and sight box ID. Tracr uses this information to check: * If the box exists and has been assigned to you. * That you are uploading the correct number of carats (total) in the box. Please note: * Tracr does not require the scan and the plan to be provided for rough diamonds. * Providing the images and videos is optional, however, this will greatly improve the Diamond Experience. {% stepper %} {% step %} ### Prepare the rough CSV * Download the rough CSV file template (**Integration Tool > Integration toolkit > CSV Templates**). {% endstep %} {% step %} ### Populate the rough CSV * Populate the CSV file - one row per diamond. {% endstep %} {% step %} ### Use the Data Dictionary * It is recommended that you download and use the Data Dictionary (**Integration Tool > Integration toolkit > Data dictionary**) to help you to populate the CSV file. Filter the Data Dictionary by "Stone State = Rough". Ensure that you populate fields with the column "Required = true". {% endstep %} {% endstepper %} #### Additional data fields to upload a scan file Tracr requires two additional data fields when uploading a scan file: * scan\_device\_manufacturer * scan\_device\_model **Supported technologies** | Technology | Comments | Data field values | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Lexus Helium |

The Cutwise platform offers a service to convert 3D Scans to STL files.

Please contact Lexus India for more details.

|

Values for the additional fields are:
scan\_device\_manufacturer : "Lexus SoftMac"
scan\_device\_model : "Model name of your device"

| | Diabot | InnovSeed Diabot generates an open STL file which can be uploaded into Tracr. |

Values for the additional fields are:
scan\_device\_manufacturer : "InnovSeed"
scan\_device\_model : "Diabot" or "Diabot NX"

| | Sarine | If you require to use a Sarine device to upload a 3D scan to Tracr, please contact our [Support Team](mailto:support@tracr.com) for more details. | | ### Prepare a split diamond dataset This procedure applies to every modification to the diamond after the rough session and before the diamond is polished. If the rough diamond is split during the manufacturing process, every part that was split has to be declared using a new participant ID and linked to the parent diamond. Please note: * Tracr does not require the scan and the plan to be provided for the split diamonds. * Ensure that the parent diamond is always registered before submitting the split diamond - the parent needs to be declared first. * Providing the images and videos is optional, however, this will greatly improve the Diamond Experience. * Every time you split a rough diamond, each split will receive a new unique Tracr ID. {% stepper %} {% step %} ### Download the split CSV template * Download the split CSV file template (**Integration Tool > Integration toolkit > CSV Templates**). {% endstep %} {% step %} ### Populate the split CSV * Populate the CSV file - one row per diamond. {% endstep %} {% step %} ### Use the Data Dictionary * It is recommended that you download and use the Data Dictionary (**Integration Tool > Integration toolkit > Data dictionary**) to help you to populate the CSV file. Filter the Data Dictionary by "Stone State = Split". Ensure that you populate fields with the column "Required = true". {% endstep %} {% endstepper %} ### Prepare a polished diamond dataset #### Sarine Instructor If you are using **Sarine Instructor** to provide a scan for polished diamonds, you need to generate an XML report and an STL export. Use the template provided by Tracr to export the report for each diamond. To extract data for polished diamonds using Sarine Instructor, refer to [Sarine Instructor: Extracting data for polished diamonds](#sarine-instructor-extracting-data-for-polished-diamonds) In the CSV file, Tracr needs the STL file in the column **scan**, and the XML report in the column **scan\_report**. [Download Sarine export templates](https://jcpackages.tracr.network/integration/Polished_Diamond_Sarine_Instructor_Export_Template.zip) #### Helium software If you are using **Helium software** to provide a scan for polished diamonds, you need to generate an HTM report and an STL export. Use the template provided by Tracr to export the report for each diamond. There are two types of Helium template: * Specific shape, only for a handful of shapes with additional information. * Generic, less information but you can use this template for all shapes. In the CSV file, Tracr needs the STL file in the column **scan**, and the HTM report in the column **scan\_report**. For more information about exporting using a Helium Polish Scanner, please refer to the [Helium Polish Scanner - Settings for Export (PDF)](https://www.lexusindia.in/download/download-files/HELIUMPOLISH_SETTINGS_FOR_EXPORTS.pdf). [Download Helium templates](https://jcpackages.tracr.network/integration/helium_templates.zip) Please note: * Before uploading polished diamond data, please make sure that you register the parent diamond on Tracr. * To verify the polished diamond, a 3D scan and the report of the scan of the diamond are crucial. * Providing the images and videos is optional, however, this will greatly improve the Diamond Experience. * Add the grading document to complete the polished digital asset. {% stepper %} {% step %} ### Download the polished CSV template * Download the polished CSV file template (**Integration Tool > Integration toolkit > CSV Templates**). {% endstep %} {% step %} ### Populate the polished CSV * Populate the CSV file - one row per diamond. {% endstep %} {% step %} ### Use the Data Dictionary * It is recommended that you download and use the Data Dictionary (**Integration Tool > Integration toolkit > Data dictionary**) to help you to populate the CSV file. Filter the Data Dictionary by "Stone State = Polished". Ensure that you populate fields with the column "Required = true". {% endstep %} {% endstepper %} ### Sarine Instructor: Extracting data for polished diamonds Extracting the required traceability data for polished diamonds using Sarine Instructor software is compatible with the following hardware: * DiaMension * DiaMension HD * DiaMark HD * DiaMark™ HD Once a polished diamond is scanned and the file loaded onto the Instructor software, you can extract the following data points: * Diamond Measurements (using a provided template) * Diamond 3D Model The following instructions describe how to extract the required data. {% stepper %} {% step %} ### 1. Install the Tracr templates for polished diamonds * Place the Tracr template file, e.g. ‘TracrPolishedTemplate.txt’, within the Sarine Instructor Export folder:\ Sarine Technologies/Instructor/Export/ {% endstep %} {% step %} ### 2. Export diamond measurements * Open the stone .srn file in Sarine Instructor. * Point to the **Export** icon, and select the corresponding Tracr template, for example, ‘TracrPolishedTemplate.txt’. * In the **Save As** dialog box, save the measurements as ‘YourStoneName.xml’. {% endstep %} {% step %} ### 3. Export the mesh * Open the stone .srn file. * Point to the **Save** icon, and select **Save as**. * In the **Save As** dialog box, select ‘\*.stl’ as the file type and save the mesh with the stone's name. {% endstep %} {% endstepper %} ## Required fields for diamond integration The following are the required fields for diamond integration. Refer to the Data Dictionary for more information, including the allowed values. Rough * participant\_id – Your unique identifier for the diamond. This can be your ERP ID or any other ID which will help you to identify the diamond in your system. * participant\_timestamp – A date and time of your choosing. For example, this may be when you added the diamond into to your system or when it was processed. * box\_id – The parcel identification number. This is the ID of the parcel you receive from the producer. * sight\_year – The sight year. * sight\_no – The sight number. * carats – The weight of the rough diamond. Tracr requires a precision of three digits. {% hint style="info" %} **Note** Producers are no longer required to provide a colour for diamonds registered via DIT at rough. Colour can be omitted by leaving the colour cell for that diamond in the upload CSV blank. {% endhint %} Split * participant\_id – Your unique identifier for the diamond. This can be your ERP ID or any other ID which will help you to identify the diamond in your system. * participant\_parent\_id – Your identifier for the parent rough diamond. * participant\_timestamp – A date and time of your choosing. For example, this may be when you added the diamond into to your system or when it was processed. * carats – The weight of the split diamond. Tracr requires a precision of three digits. Polished * participant\_id – Your unique identifier for the diamond. This can be your ERP ID or any other ID which will help you to identify the diamond in your system. * participant\_parent\_id – Your identifier for the parent split or rough diamond (if the rough was polished without splitting). * participant\_timestamp – A date and time of your choosing. For example, this may be when you added the diamond into to your system or when it was processed. * carats – The weight of the polished diamond. Tracr requires a precision of three digits. * cut\_grade – The grade of cut. * shape – The shape of the polished diamond. * clarity – The relative absence of inclusions and blemishes. * symmetry – The symmetry of the polished diamond. * polish\_quality – The quality of the polished diamond. * scan – The scan of the polished diamond (for example, Sarine scan). * scan\_report – The extracted report of the scan. {% hint style="info" %} **Note** We require mutual exclusivity of `colour` and fancy\_colour fields. You may only provide fancy\_colour (`fancy_colour`, `fancy_colour_intensity` and optionally `fancy_colour_overtone`) or colour values for any given diamond being registered or updated via the integration tool. {% endhint %} Transfer * participant\_id – Your unique identifier for the diamond. This can be your ERP ID or any other ID which will help you to identify the diamond in your system. * transfer\_type – The type of transfer: in or out. * transfer\_timestamp – The date when the diamond was transferred. * box\_id – The parcel identification number. * platform – The name of the participant that purchased or sold the diamond. ## Video quality requirements If you are providing a video of your diamond, please note the following: * Format – .mp4, .avi, .mkv, .mov * Rotation – At least one full 360° rotation horizontally (clockwise or anticlockwise) * Number of frames: At least 30 * Resolution – At least 400 x 400 pixels * Good contrast between the stone and the background * Unobscured background, clean without clamps * (Optional) Additional video in fluorescence #### Examples

Videos with good contrast.

A video with poor contrast.

Videos with visible clamps.

## Tracr data control After uploading diamond data, Tracr runs following control processes: Rough diamonds * For a given sight box, that the total carat weight submitted does not exceed the total carat weight invoiced by De Beers. * For a given sight box, that the number of diamonds submitted does not exceed the number of diamonds invoiced by De Beers (where applicable). Child rough (split) diamonds * That the sum of all the children's carats does not exceed the carat weight of the parent diamond. Polished diamonds * That the carat weight of the polished diamond does not exceed the carat weight of the parent diamond. ## View integration session history Tracr maintains a list of all the sessions that you create, save or abandon.

Session history showing submitted and in progress sessions.

To view your session history: * From the Tracr menu, select **Integration > Integration Tool**.\ The **Session history** page displays a list of your integration sessions. Each session has a status, which shows whether the session was submitted, is in progress, or was abandoned. * **Submitted** – Data has been uploaded and Tracr is processing the diamonds. * **In progress** – The session was not submitted, either because the user did not click **Submit** or chose to save and quit the session, possibly because not all the required files were available. To complete the session, in the **Action** column, select **Continue session**. * **Abandoned** – The session was abandoned. Note that you can only abandon a session if the CSV file has passed validation. ### Session information For each session, Tracr gives the following information: * **Session ID** – The ID allocated to the session by Tracr. * **Session start** – The date and time the session started. You can filter on the start date if you only want to display sessions started on a particular date. * **Session submitted** – The date and time the session was submitted to Tracr. If this is blank, check the **Status** column to see if the session is ‘In progress’ or was ‘Abandoned’. * **Integration type** – The integration type selected when the CSV was uploaded to Tracr. You can filter on integration type if you only want to display sessions of a certain type. * **Diamonds submitted** – The number of diamonds submitted to Tracr. * **Diamonds excluded** – The number of diamonds excluded when the dataset was uploaded to Tracr. * **Status** – The status of the session. You can filter on status if you only want to display sessions at a certain status. * **Details** – Provides more information about the status of the session. * **Action** – The available options depend on the status of the session. * For a ‘Submitted’ session, select the ellipsis to access the following options:\ **Monitoring** – Display the **Integration monitoring** page for the selected session.\ \&#xNAN;**.xlsx file** – Download a simple or detailed report for the selected session. * For an ‘In progress’ session, select **Continue session** to complete and submit the session. ### Filter your session history You can filter the list of sessions by event date, integration type, or status. To filter by event date: * Select **Start date**, choose the date from the calendar, and select **Apply**.\ Tracr only displays sessions for the selected date. To filter by integration type: * Select **Integration type**, select the type(s) that you want to display, and select **Apply**.\ Tracr only displays sessions for the selected integration type(s). To filter by status: * Select **Status**, select the status(es) that you want to display, and select **Apply**.\ Tracr only displays sessions for the selected status(es). ### Continue a session If a session has been saved (status = ‘In progress’), you can select **Continue session** in the **Action** column on the **Session history** page to complete and submit the session. {% hint style="info" %} If you want to quit a session without submitting it and then continue the session later, select the **Quit** button at any time during file upload and then select **Save and quit**. Tracr saves your session which appears on the **Session history** page with a status of ‘In progress’. {% endhint %} ### Export a session report You can export details of a selected session currently displaying on the **Session history** page as a report (xlsx file). {% stepper %} {% step %} ### 1. Filter sessions * Use the filters to display the session(s) that you want to export. {% endstep %} {% step %} ### 2. Choose report type * In the **Action** column, select the ellipsis and do one of the following: * To download a simple report for the selected session, under **Download a session report as**, select **.xlsx file**.\ [**View example report**](/tracr-user-guide/10.-example-reports.md#integration-tool-transaction-report) * To download a detailed report for the session, under **Download full session report**, select **.xlsx file**.\ [**View example report**](/tracr-user-guide/10.-example-reports.md#integration-tool-full-transaction-report) {% endstep %} {% step %} ### 3. Download * Tracr generates the report which is downloaded and saved in your default downloads folder. {% endstep %} {% endstepper %} --- # 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/4.-integration.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.