Sub customer stock import

Introduction

This will import sub customer stock for a lease company (vehicle, contract, customer, address, driver, policy, and ancillary flags onto existing sub customers).

Important

• Each row must identify a vehicle with at least one of VIN or registration (VRM). Rows with neither are skipped and logged.
• Customer account number must match an existing sub customer for the lease. The importer resolves the sub customer by account number and then allocates or updates stock on that sub customer (see createSubCustomer.ts in the import-manager repo).
• If stock for the same VIN/VRM already exists with identical data (hash match), the row is skipped and logged.

File format

Comma Separated Values - *.csv
Encoding - UTF-8

Header names are trimmed and converted to camel case for mapping (see readCSVFile in the import manager). The CLI entry point is importCustomerContract.ts under imports/lease/subCustomerStock/; it validates rows with importCustomerContract.validation.ts and calls createCustomerContract when persist is true.

download sample sub customer stock import file.

Date values

Dates are accepted either as:

• Eight digits DDMMYYYY (for example 01092022 for 1 September 2022), or
• Any string that parses as a valid JavaScript Date (for example ISO dates), per toFormattedDate.

Fields

Sub customer stock CSV fields

CSV column (example)	Description	Max length	Data type	Rules / notes	Mandatory	Example
Registration	Vehicle registration (VRM)	9	String	Valid UK or IE registration format	Y	AB72YLL
VIN	Vehicle identification number	17	String	Alphanumeric; whitespace stripped	N	ABHC751CVNU294937
Registration Date	First registration date	8+	Date	DDMMYYYY or parseable date	Y	01092022
Make	Vehicle make	20	String	Allowed character set per validation	Y	HYUNDAI
Model	Vehicle model	100	String	Required; pattern per validation	Y	IONIQ
Specification	Variant / specification	100	String	Optional	N
Fuel Type	Fuel type	50	String	Optional	N	HYBRID ELECTRIC
Vehicle Type	Category (e.g. Car, LCV)	20	String	Required	Y	Car
CAPID	CAP identifier	20	String	Optional	N
Argic Code	ARGIC code	20	String	Optional	N
Colour	Colour	100	String	Optional	N
MOT Due Date	MOT due date		Date	Optional; same date rules as above	N
Maintained	Maintained flag (drives managed/maintained on vehicle)	4	String	Required; alphanumeric (e.g. Y/N)	Y	Y
Contract Start Date	Contract start		Date	Optional	N	12022026
Contract End Date	Contract end		Date	Optional	N	12022027
Contract Mileage Term	Contract mileage term	6	Numeric string	Optional	N
Vehicle Product	Vehicle product	30	String	Optional	N
Service Schedule	Service schedule	8	Number	Optional	N
Warranty Parameter Months	Warranty months		Number	Optional	N
Warranty Parameter Mileage	Warranty mileage		Number	Optional	N
Asset Number	Asset number	20	String	Alphanumeric	N
SMR	SMR / maintenance contract flag		String	Optional; letters only (A–Z); typically Y/N	N	Y
Tyres	Tyres contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Glass	Glass contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Accident Management	Accident management contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Breakdown	Breakdown contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Insurance	Insurance contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Rental	Rental contract flag		String	Optional; letters only (A–Z); typically Y/N	N	N
Fridge	Fridge fitted (ancillary equipment)		String	Optional; letters only (A–Z); typically Y/N	N	N
Tail Lift	Tail lift fitted (ancillary equipment)		String	Optional; letters only (A–Z); typically Y/N	N	N
Crane	Crane fitted (ancillary equipment)		String	Optional; letters only (A–Z); typically Y/N	N	N
Customer Name	Customer / company display name	100	String	Required	Y	CarFinance247 Limited
Customer Account Number	Sub customer account number (must exist on lease)	15	String	Required; alphanumeric pattern per validation	Y	402
VAT Number	VAT number on contract	9	String	Optional	N	932900908
Title	Title (e.g. salutation)	50	String	Optional	N
Address 1	First address line (mapped to ViSN building / number)	20	String	Optional; allowed character set per validation	N
Address 2	Second address line	50	String	Optional; allowed character set per validation	N
Address 3	Third address line	50	String	Optional; allowed character set per validation	N
Address 4	Fourth address line	50	String	Optional; allowed character set per validation	N
Postcode	Postcode	10	String	Alphanumeric pattern	N	M126JH
Customer Number	Customer reference / phone etc.		String	Optional; whitespace stripped from number	N
Customer Email	Customer email	50	String	Optional	N
Cost Centre	Cost centre code	10	String	Optional; alphanumeric pattern per validation	N
Invoice Centre	Invoice centre code	10	String	Optional; alphanumeric pattern per validation	N
Customer Contact	Customer contact details	100	String	Optional; allowed character set per validation	N
Customer Policy Notes	Policy notes on the customer	250	String	Optional; pattern per validation	N
Customer Recharge Limit	Customer recharge limit		Number	Optional	N
Customer Referral Limit	Customer referral limit		Number	Optional	N
Driver First Name	Driver given name	30	String	Optional; letters only when provided	N	Test
Driver Last Name	Driver family name	30	String	Optional; letters only when provided	N	Test
Driver Email	Driver email	50	String	Optional	N
Driver Number	Driver phone number		Number	Optional	N
Employee Start Date	Driver employment start		Date	Optional; if omitted, mapper may default start date	N
Policy Number	Policy reference	100	String	Optional	N
Policy Start Date	Policy start		Date	Optional; same date rules as above	N	12022026
Policy End Date	Policy end		Date	Optional; same date rules as above	N	12022027
Policy Term	Policy term		Number	Optional	N	12
Product Type	Policy product type	20	String	Letters only when provided	N	Warranty

Further columns and stricter rules are defined in importCustomerContract.validation.ts in the import-manager repo; extend this table if you add columns to the CSV.

Importing a file

Preparation

1. Create a new branch with the Jira task number in the branch name.
2. Place the CSV under the import-manager importFiles tree (or another path you pass to --file).
3. Open package.json in the import-manager repo and locate validate:subCustomerStock (and import:subCustomerStock for persisted runs).
4. Update --leaseId to the target lease company id.
5. Update --file to the path of the CSV relative to the import-manager project root.
6. Save package.json if you keep paths there, or pass the same flags on the command line when invoking the built script.

The CLI is compiled from src/imports/lease/subCustomerStock/importCustomerContract.ts and accepts the standard options from getImportArgumentsFromCommandLine (including --leaseId, --file, and --persist).

Validating locally

1. In a terminal, from the import-manager repo, run npm run build.
2. Run npm run validate:subCustomerStock.
3. Review log output under the import file directory (see logger usage in ImportCSVFile). Fix validation errors before persisting.

Validating in workflow

1. Go to Actions on the import-manager GitHub repository.
2. Find <Environment> - on-demand-import (or the equivalent workflow used for other lease imports).
3. Select the branch that contains your file path updates.
4. Enter script name validate:subCustomerStock.
5. Leave Overrides empty unless you need extra flags.

Importing the file (persist)

1. After validation succeeds, use the same workflow with script name import:subCustomerStock (this runs the validate script with --persist so rows are written to the database).
2. Alternatively, run locally: npm run import:subCustomerStock after npm run build.

Importing via Cloud Run

Cloud Run exposes POST /sub-customer-contract on the import-manager service. The default schema body field is SUB_CUSTOMER_CONTRACT when omitted (see index.ts).

Typical HTTP target (dev example; URL and bucket vary by environment):

• URL: https://import-manager-36r2bu4izq-uc.a.run.app/sub-customer-contract
• HTTP method: POST
• Auth header: OIDC token (same pattern as other import-manager schedulers)
• Service account: cloud-run-import-customer-contract

Example scheduler body (validation, no persist)

{
  "leaseId": "<leaseCompanyId>",
  "leaseCompanyName": "<lease company display name>",
  "persist": "false",
  "bucket": "biddirect-2.appspot.com",
  "appDirectory": "/usr/src/app/",
  "importPath": "imports/fileDrop/",
  "importFileDropPath": "imports/fileDrop/",
  "importFileName": "<yourFile>.csv",
  "email": "<notification email>",
  "fatalErrorEmailToAddress": "<fatal error email>",
  "schema": "SUB_CUSTOMER_CONTRACT"
}

Example scheduler body (import with persist)

Use the same JSON as above but set "persist": "true".

Bucket preparation

As with other import-manager CSV flows, upload the file to the environment’s bucket under the agreed drop path (for example imports/fileDrop/) and set importFileName to the object name. Bucket names differ between environments; align with your platform team.

Automated file validation (Pub/Sub)

When wiring Pub/Sub import file validation, the routine key subCustomerStockValidation maps to SubCustomerStockCSVFile in getImportRoutineSettings.ts. Use that folder or routing convention if your deployment validates files before import using the shared pub/sub handler.

Testing

After a successful persisted import, confirm in ViSN that:

• Stock exists for the VIN/VRM on the lease.
• The vehicle is allocated to the sub customer whose customer account number matched the row.

Status: Pending Approval
Category: Protected
Authored By: Jeyakumar Arunagiri on May 13, 2026