When to use this endpoint

Create the DataSync record first, then generate the installer matching its type. Save/run the returned file on the machine hosting the accounting data; this API does not execute it.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; session requests require the dispatcher’s CSRF token where configured. Tenant rows and settings belong to that authenticated account.

These handlers add no accounting page or CRM2 role check. The dispatcher has no Accounting/DataSync object-scope mapping. Settings-screen access controls are separate from these shared API handlers; CRM2 screen roles are not a CRM1 API requirement.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive DataSync record ID from DataSync_new or DataSyncs_list, not an instruction ID.
targetStringYesExactly sage 50 accounts or gnucash after trim. The Sage target differs from saved sync_type=sage50accounts. Blank error text incorrectly names target_id.
configJSON object textYes for useful installationJSON object text. GnuCash requires nonblank string data_path. Sage requires nonblank strings username,data_path,version; version contains dot-separated numeric components. password defaults to blank (valid), and optional network_share_username/network_share_password must be supplied together. These string fields reject control characters; native arrays are not supported.

Example request

$result = FM_api('DataSync_getInstaller', ['id'=>'14', 'target'=>'gnucash', 'config'=>json_encode(['data_path'=>'/srv/accounts/example.gnucash'])]);

Example response

{
  "ok": 1,
  "file": "#!/bin/bash\n\n# Fieldmotion GnuCash Accounting Agent Installer\n..."
}

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"DATASYNC_URL not defined. please contact Fieldmotion support"}Server installer base URL is missing.
{"error":"missing or invalid parameter: id"}ID is absent or integer-converts to zero.
{"error":"missing or invalid parameter: target_id"}Actual target parameter is blank.
{"error":"invalid parameter: target"}Unknown nonblank target.
{"error":"that datasync does not exist: 14"}The selected connection does not exist.
{"error":"Network Share Username and Network Share Password must both be filled in"}Only one optional Sage network-share credential was supplied.
{"error":"cloud Data Sync is retired and no longer available"}The saved record is not local Sage/GnuCash.
{"error":"target does not match DataSync type"}A valid target differs from the connection’s saved type.
{"error":"missing or invalid parameter: config"}config is not a JSON object.
{"error":"missing or invalid parameter: config.data_path"}Required path is absent/blank, structured, or contains control characters.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The response example abbreviates file; the real response contains the complete installer script. GnuCash returns a shell installer; Sage returns Windows batch text. CRM1 saves the Sage response as install.bat; GnuCash is a separate target.
  • The generated configuration includes the authenticated client_id, DataSync record ID as key_id, stored connection secret, Data Sync JSON-RPC URL and target configuration. The returned file contains credentials; keep it private and do not paste it into shared tickets.
  • Sage selects the 32-bit SDK archive using version, derives major_version before the dot, packages PHP 8.4 x86 and agent-25, and installs under C:\FieldmotionDataSync\<client ID>\<DataSync ID>. Network share username is trimmed; its password is preserved verbatim.
  • GnuCash uses sqlite target version. DATASYNC_URL must be configured server-side. This route accepts any nonzero integer-converted id before lookup, unlike the positive-ID checks in most other DataSync handlers.
  • The installer generates scheduled/local agent configuration; completion needs the target operating system and accounting SDK/data access. Linux API tests cannot establish a successful Windows installation.
  • The GnuCash template JSON-encodes config.data_path into target.config.database_path, installs under /opt/fieldmotion/gnucash and creates/enables/starts a systemd service. Its generated config.json is explicitly chmod 600 after installation permissions are applied.
  • The selected target must match the saved local sync_type. Historical cloud records are rejected with the retired-cloud error. Generating a new installer does not repair files already installed on a host; download and rerun it there or correct the existing config.json permissions.

Side effects

  • Builds text from repository templates and saved connection credentials. No server-side download, installation, agent login or remote sync is triggered by generating it.

See it in Fieldmotion

CRM1

Open Settings → Data Sync. The pageSettingsDataSync screen uses this route for the operation described above; filter browser Network requests by the exact function name. Local-agent setup is separate from the cloud Finance integrations. Choose the installer action and supply the target configuration; the UI saves the returned file text.

CRM2

Open Settings → Data Sync. The CRM2 pageSettingsDataSync screen retains this local-agent workflow; filter browser Network requests by the exact function name. Its screen permissions do not add a role check to this shared handler. Choose the installer action and supply the target configuration; the UI saves the returned file text.

Related endpoints