Data Importer - Overview

The CoolR Data Importer enables bulk creation and updating of data in your CoolR system via spreadsheet or API. Instead of entering records one by one, prepare a file and upload everything at once.

Key benefits:

• Import hundreds of records in seconds
• Two-phase validation ensures data quality before committing
• All-or-nothing processing — no partial imports
• Complete audit trail for compliance
• Available in Portal and Playbook App

---

Supported import types

Import Type	API type value	Columns	Required	Operation	UI Access
Outlet	Outlet	58	3	Create / Update	Portal: Outlet Management Playbook: Master Data → Outlets
Planogram	Planogram	7	2	Create Only	Portal: Planogram Management Playbook: Master Data → Planograms
Product	Product	30	5	Create / Update	Playbook: Master Data → Products
User	User	11	5	Create / Update	Playbook: Master Data → Users
Asset	Asset	18	2	Create / Update	Playbook: Master Data → Assets
Asset Type	AssetType	14	5	Create / Update	Playbook: Master Data → Asset Types
Outlet Action	ImportOutletAction	5	2	Create	Portal: Outlet Management → Outlet Actions
Factory Asset	FactoryAsset	5	3	Create / Update	Portal: Asset Management → Factory Assets

---

Import order

When importing related data, follow this sequence to satisfy dependencies:

1. Asset Types — must exist before creating Assets
2. Users — must exist before assigning to Sales Reps or Actions
3. Outlets — must exist before assigning Assets or Actions
4. Assets — import parent assets before child assets (if using Parent Asset)
5. Products — must exist before creating Planograms
6. Planograms — after Products and Assets exist
7. Outlet Actions — after Outlets and Users exist
8. Factory Assets — after Asset Types exist

Specific Dependencies

• Assets with Parent Assets: Import parent assets first (without Parent Asset column), then child assets (with Parent Asset column)
• Outlet Actions: Requires Outlets and optionally Users (if assigning)
• Factory Assets: Requires Asset Types, optionally Outlets (if pre-assigning location)

---

How it works

Two-phase validation

Phase 1 — File-level (immediate):

• File format detection (CSV / Excel / JSON)
• Required columns present
• Data types correct (numbers, emails, dates)
• Field lengths and patterns within limits

Phase 2 — Database-level (after Phase 1 passes):

• Referenced records exist (Countries, States, Users, etc.)
• Business rules and dependencies satisfied
• No duplicate keys
• Complex relationships valid

Either all rows import successfully or none do. There are no partial imports.

---

File formats

All import types support:

Format	Extension	Notes
CSV	.csv	Recommended. UTF-8, comma-delimited. Wrap values containing commas in double quotes.
Excel	.xlsx, .xls	First sheet only; automatically converted during processing.
JSON	.json	API only. Structure: {"data": [...]}. Accepts camelCase property names (see each guide).

CSV example:

"Product Name","SKU-001","Description with, comma"

JSON structure:

{
  "data": [
    { "code": "NYC-001", "name": "Store Name" }
  ]
}

File format tips

• Always include a header row with column names (case-insensitive)
• File extensions are case-insensitive (.csv, .CSV, .xlsx, .XLSX all work)
• Column headers are case-insensitive (Product SKU, product sku, PRODUCT SKU all map correctly)
• Keep file size under 10 MB for optimal performance
• Remove empty trailing rows
• Test with 2–3 rows before a full import

---

Authentication

All import endpoints support two authentication methods.

Method 1: Session cookie

Obtained by logging in to the CoolR Portal. Pass the cookie on every request:

Cookie: .ASPXAUTH=your-auth-token

curl -X POST 'https://portal.coolrgroup.com/Controllers/Import.ashx?type=Outlet' \
  -H 'Cookie: .ASPXAUTH=your-auth-token' \
  -F 'file=@outlets.csv'

Method 2: Basic authentication

Pass your CoolR username and password using HTTP Basic Auth. The credentials are base64-encoded as username:password.

Authorization: Basic base64(username:password)

curl -X POST 'https://portal.coolrgroup.com/Controllers/Import.ashx?type=Outlet' \
  -u 'user@example.com:yourpassword' \
  -F 'file=@outlets.csv'

Use session cookies for interactive workflows and Basic Auth for automated / server-to-server integrations.

---

API endpoint pattern

POST https://portal.coolrgroup.com/Controllers/Import.ashx?type={ImportType}

Parameter	Required	Description
type	Yes	Import type (see table above)
file	Yes	File to import (CSV, Excel, or JSON)
dryRun	No	Set to "true" for validation-only mode (no data written)

---

Response format

Success:

{
  "success": true,
  "data": {
    "TaskStatus": 2,
    "StatusInfo": {
      "Total": 100,
      "Imported": 100,
      "Failed": 0
    }
  },
  "info": "Import completed successfully. Processed 100 rows, Imported 100, Failed 0"
}

Failure (all-or-nothing — if any row fails, nothing is imported):

{
  "success": false,
  "data": {
    "TaskStatus": 3,
    "StatusInfo": {
      "Total": 100,
      "Imported": 0,
      "Failed": 100
    }
  },
  "moreInfo": [
    [5, "Import Type", "Error message for row 5", false]
  ],
  "info": "Import failed. Processed 100 rows, Imported 0, Failed 100. All-or-nothing policy: no rows were imported."
}

The moreInfo array (present only on failure) lists row numbers with specific errors to help you fix and retry.

---

Error handling

Common error categories

Category	Typical message	Fix
Required field missing	Missing required field: [field]	Fill in all mandatory fields for every row
Invalid format	Invalid [type] format	Check format requirements in the column spec
Reference not found	[Entity] '[code]' not found in system	Import dependencies first or verify codes
Duplicate key	Duplicate [field]	Check for duplicate rows; use update mode if needed
Value too long	Value exceeds maximum length	Shorten value to fit within the listed max length

Diagnosing failures

Symptom	Common causes	Next step
100% failure rate	Wrong column names, wrong encoding, wrong delimiter, or any row with invalid data	Verify header spelling/spacing and required columns match template (casing not significant); re-save as CSV UTF-8; check moreInfo for specific row errors and fix all issues
Import succeeds but data looks wrong	Data in wrong columns, wrong codes updated	Review column mapping; export and verify before a large import

Error resolution workflow

1. Review moreInfo in the response for row numbers and error messages
2. Fix errors in original file
3. Re-import corrected file (full file or failed rows only)
4. Verify success counts and spot-check records in UI

---

Record matching: create vs update

Each import type uses one or more match keys to decide whether to create a new record or update an existing one. If a record with the same key already exists, it is updated; otherwise a new record is created.

Import Type	Primary match key	Secondary match key
Outlet	Code	External Code
Product	SKU	External Code
User	Email	—
Asset	Serial Number	External Code
Asset Type	Model Number	External Code
Factory Asset	Asset serial number	—
Planogram	Planogram Name	—

Update behaviour: Only columns included in the file are updated. Empty cells are ignored — the existing value is left unchanged. This means you can import a file with only the columns you want to change.

Note

Following import types are append only

1. Outlet Action

External Code

The External Code column (where supported) is the identifier used in your internal system (e.g. your ERP or CRM). When provided, CoolR uses it as an alternative match key — useful when your system's identifier differs from the CoolR-assigned code.

Match priority:

1. If External Code is supplied and matches an existing record → that record is updated
2. Otherwise, the primary key is used to match

Storing your system's identifier in External Code simplifies ongoing sync: you can always reference records by your own IDs without needing to track CoolR-internal codes.

Deactivating records

CoolR does not support hard deletion of master data records that may be referenced by historical or transactional data. To retire a record without deleting it, set its Active / Is Active? column to No. Inactive records are hidden from operational workflows but remain in the system for reporting and audit purposes.

Supported on: Outlet (Active), Product (Is Active?), User (via UI only).

---

Best practices

Before importing:

1. Download and use the official template
2. Validate data in your spreadsheet (formats, formulas)
3. Remove duplicate rows
4. Verify all required fields are filled
5. Test with 5–10 rows first

After importing:

1. Review success / failure counts
2. Check moreInfo for failed rows
3. Spot-check 10–20 imported records in the UI
4. Save the import result for your audit trail

---

For questions or support: support@coolrgroup.com