Uploading Data to Flat File Sources
SailPoint certifications review access data loaded into ISC from sources. For apps without a direct connector, use flat file sources — uploading CSV files of accounts and entitlements.
Three Ways to Upload
| Method | Best for | Java required? |
|---|---|---|
| TypeScript SDK (this project) | Automated/scheduled uploads, CI/CD, validation | No |
SailPoint CLI (sail api) | Quick one-off uploads from the terminal | No |
| File Upload Utility (Java JAR) | Legacy bulk uploads, built-in batching | Yes (11+) |
TypeScript Uploader (Recommended)
Upload accounts or entitlements to any flat file source via the SailPoint API. Streams files to avoid loading them entirely into memory — safe for files up to 500 MB.
Build
just build
# or: npm run build
Find Your Source ID
Your source ID is a 32-character hex string. Find it in the ISC admin console:
- Go to Admin > Connections > Sources
- Click on your flat file source
- The source ID is in the URL:
https://{tenant}.identitynow.com/ui/admin/sources/{sourceId}
Or via the CLI:
just sources
# or: sail api get "/v3/sources" | grep -E '"id"|"name"'
Prepare Your CSV
Use the sample files in data/ as templates. Your CSV must match the schema defined on your source.
Accounts CSV:
id,name,email,department,entitlements
jsmith,John Smith,jsmith@acme.com,Engineering,"ENT001,ENT002"
Entitlements CSV (4 required columns):
id,name,displayName,description
ENT001,read_access,Read Access,Read-only access to shared resources
Validate (Dry Run)
Always validate before uploading:
just upload-dry <your-source-id> data/accounts.csv
Upload
# Upload accounts
just upload <your-source-id> data/accounts.csv
# Upload entitlements
just upload-entitlements <your-source-id> data/entitlements.csv
On success you'll see Upload accepted (202) with a task ID.
All Options
node dist/upload_accounts.js --sourceId <id> --file <path> [options]
Required:
--sourceId <id> Source ID (32-char hex from ISC)
--file <path> Path to CSV file
Options:
--type <type> "accounts" (default) or "entitlements"
--disableOptimization Reprocess all records, not just changes
--dryRun Validate the file without uploading
--help Show this help
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
No config.json found | Missing credentials | Copy config.json.example and fill in values |
API Error 401 | Bad credentials | Check ClientId/ClientSecret in config.json |
API Error 403 | Insufficient permissions | PAT needs ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN |
API Error 400 | CSV doesn't match source schema | Download the schema template from ISC |
File exceeds 500 MB limit | File too large | Split into files of 400,000 rows or fewer |
Entitlement CSV missing required columns | Wrong headers | Must have: id, name, displayName, description |
CLI Method (Quick One-Off)
sail api post "/beta/sources/{sourceId}/load-accounts" -f "file=@accounts.csv"
File Constraints
| Constraint | Accounts | Entitlements |
|---|---|---|
| Max file size | 500 MB | 1 MB |
| Max records | 400,000 per file (recommended) | 2 million per aggregation |
| Encoding | UTF-8 | UTF-8 |
| Sorting | Must be sorted by account ID | — |
| Special chars | No emojis, no + | No emojis, no + |
| Description length | — | Truncated at 2,000 chars |
File Upload Utility (Java)
The File Upload Utility (v4.1.0) automates bulk file uploads for account and entitlement aggregations. Requires Java 11+.
java -jar file-upload-utility/sailpoint-file-upload-utility.jar \
--url https://<tenant>.api.identitynow.com \
--clientId <your-client-id> \
--clientSecret <your-client-secret> \
--file /path/to/csv/files/ \
--recursive
Files must be named with the source ID prefix: <sourceId>-<description>.csv
See file-upload-utility/README.md for full documentation.