Customer SFTP imports
Patch mapped SFTP configuration
/a/ImportCustomersFtp_updateData
Patch one or several source rows using mapped field names.
When to use this endpoint
This generic CRM2 table contract differs from the owner-specific save/status editor; understand the scope and secret-handling caveats before using it.
Authentication and permissions
Use signed API-key authentication or a logged-in CRM session. API keys act as their owner; session requests use dispatcher CSRF protection when configured.
Requires a valid tenant account and View on pageImportsCustomersFtp plus Edit. Source IDs and counts are restricted to the authenticated account owner; client-supplied ownership cannot expand access.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive ID or native/JSON list | Yes | Update one or several owned sources. Duplicate IDs collapse; an empty native list makes no row changes. |
Mapped fields | Native request fields | No | Writable fields are server, metaUsername, metaType, metaDirectory, metaPassword, status and importMap. server/username/directory/type are nonblank text up to 255 bytes; type is ftp or sftp. status is exactly 0 or 1. importMap is a positive ID of an existing customers map in this account. Blank or "0" metaPassword preserves the saved password (maximum 65535 bytes). meta accepts a JSON object/native associative array containing only username, type, directory, password and import_map; these merge with existing metadata. owner and lifecycle timestamps are server-owned; same-owner ownerID is tolerated for client compatibility. Unknown top-level fields are ignored. |
Example request
$result = FM_api('ImportCustomersFtp_updateData', ['id'=>'18','server'=>'new-imports.example.invalid']);Example response
{
"ok": 1
}Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error": "permission denied"} | The user lacks the required Imports page action. |
{"error": "missing or invalid parameter: id"} | A required row ID is missing or invalid. |
{"error": "no such entry"} | The requested owned source or tenant row does not exist. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Writable fields are server, metaUsername, metaType, metaDirectory, metaPassword, status and importMap. server/username/directory/type are nonblank text up to 255 bytes; type is ftp or sftp. status is exactly 0 or 1. importMap is a positive ID of an existing customers map in this account. Blank or "0" metaPassword preserves the saved password (maximum 65535 bytes). meta accepts a JSON object/native associative array containing only username, type, directory, password and import_map; these merge with existing metadata. owner and lifecycle timestamps are server-owned; same-owner ownerID is tolerated for client compatibility. Unknown top-level fields are ignored.
- New sources derive their owner and timestamps from the authenticated account and default to Disabled. A supplied valid status can override that default on the mapped create route. Updates stamp last_edited only when data changes and preserve unrelated saved metadata.
- All target IDs are checked before a bulk write. A missing/foreign row or invalid field rejects the whole transaction, preserving earlier rows. No-change mapped updates return {ok:1,warning:"No Change."}. No oldData or credentials are returned.
- Every path reconciles features_used bit 8 from whether this account has any nonzero-status source, preserving unrelated bits. Source creation, update and bookkeeping commit together. This marker is usage bookkeeping, not an entitlement check.
- Checked database writes roll back within their database transaction. Global source settings and tenant audit writes are separate commits: saved=1 with a warning means the setting was saved but a follow-up failed. Inspect the saved state; do not blindly repeat a write.
- Saving settings does not contact the remote server, run an import or validate a spreadsheet. Passwords remain in saved metadata; response and audit redaction does not provide encryption at rest.
Side effects
- Writes global source configuration and timestamps, reconciles the usage marker, invalidates source cache and records a tenant audit with passwords removed. No customer import or notification.
See it in Fieldmotion
CRM1
In CRM1, open Settings > Imports > Customers FTP. No direct mapped-writer caller was found; CRM1 uses save and setStatus.
CRM2
In CRM2, open Imports > Customers FTP. The generic table uses the ImportCustomersFtp prefix. Edit Status and inspect the mapped writer request; the custom connection dialog instead uses save.
Related endpoints
ImportCustomersFtp_save— Configure an owned source.ImportsCustomersFtp_getDataTable— Discover source rows and IDs.ImportCustomersFtp_getImportMaps— Inspect map choices before running.ImportCustomersFtp_runOnce— Understand import writes and remote cleanup.