Desktop Sync

Fulcrum Desktop is an experimental command line tool for intelligently syncing your Fulcrum Organization data to an on-site database. The local database is a complete API representation with search indexes and query tables, making it ideal for integrating Fulcrum with data driven applications, such as Business Intelligence (BI) and Geographic Information Systems (GIS).

❗️

This application is still very much under active development and has been designed to support extensibility and customization via plugins, so expect changes, improvements, and additional functionality in the coming weeks and months. While we encourage developers to test out this experimental tool and provide feedback, it is not a first-class Fulcrum product and official support should not be expected.

How it works

You first run the setup command to authenticate to your Fulcrum account and setup the local Fulcrum SQLite database. Next you can run the sync command to sync with your Fulcrum organization. This will build all the necessary database tables, indexes, views, etc. and sync down all of your Fulcrum resources, including forms, records, choice lists, classification sets, projects, members, and roles.

The internal fulcrum.db SQLite database is not very user-friendly, so you will likely want to install one of the database plugins.

Installation

Fulcrum Desktop has installers for Windows (32-bit and 64-bit), macOS and Linux, which are available from the releases page on GitHub.

Linux (Ubuntu x64)

curl -o- -L https://raw.githubusercontent.com/fulcrumapp/fulcrum-desktop/master/install.sh | sudo bash
  • Command installation location: /opt/Fulcrum/scripts/fulcrum
  • Plugin installation directory: /home/username/.fulcrum/plugins
  • Internal SQLite database: /home/username/.config/Fulcrum/data/fulcrum.db
  • Daily log files: /home/username/.config/Fulcrum/log

macOS

Open the .dmg, drag the icon to Applications. That's it! While running, the program will auto-update if there's a new release available.

  • Command installation location: /usr/local/bin/fulcrum -> /Applications/Fulcrum.app/Contents/scripts/fulcrum
  • Plugin installation directory: /Users/username/.fulcrum/plugins
  • Internal SQLite database: /Users/username/Library/Application Support/Fulcrum/data/fulcrum.db
  • Daily log files: /Users/username/Library/Application Support/Fulcrum/log

Windows

Install from the Setup .exe and follow the instructions. This will create a shortcut icon on your desktop (and open up a GUI window - which is not currently functional - you can close this window). Double-clicking the shortcut icon will open the GUI again; doing this also triggers the auto-updater. If there is an updated release available, it will be downloaded and installed. Windows users on older operating systems may experience a TLS issue - please see this for a workaround to enable more modern versions of the protocol.

  • Command installation location: \Users\username\AppData\Local\Programs\Fulcrum\scripts\fulcrum.cmd
  • Plugin installation directory: \Users\username\\.fulcrum\plugins
  • Internal SQLite database: \Users\username\AppData\Local\Fulcrum\data\fulcrum.db
  • Daily log files: \Users\username\AppData\Local\Fulcrum\log

Getting started

After installing the core command line tools, you should authenticate with your Fulcrum account to setup your local database, sync your Organization's data down, install one of the database plugins, and then setup auto-syncing. You can authenticate to Fulcrum via username/password or API token.

Setup the local Fulcrum database

Note: --org is now required when running fulcrum setup so that the role can be verified.

OSCommand
macOS / Linux (prompt)fulcrum setup --org 'Organization Name'
macOS / Linuxfulcrum setup --org 'Organization Name' --email 'EMAIL' --password 'SECRET'
Windows.\fulcrum.cmd setup --org "Organization Name" --email "EMAIL" --password "SECRET"
Allfulcrum setup --org 'Organization Name' --token '<token>'

Sync your Organization

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name'
Windows.\fulcrum.cmd sync --org "Organization Name"

Note: if you have already installed the PostgreSQL plugin (below), you will also need to pass any parameters that your connection requires.

Example: fulcrum sync --org 'Organization Name' --pg-user 'myuser' --pg-password 'mypassword' --pg-database 'mydatabase'

Install the PostgreSQL database plugin

By default, the PostgreSQL plugin expects a database named fulcrumapp with the PostGIS extension installed.

OSCommand
macOS / Linuxfulcrum install-plugin --name postgres
Windows.\fulcrum.cmd install-plugin --name postgres

Setup continuous sync

Continually sync the database to pull down changes from Fulcrum.

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name' --pg-user 'myuser' --pg-password 'mypassword' --forever
Windows.\fulcrum.cmd sync --org "Organization Name" --pg-user "myuser" --pg-password "mypassword" --forever

Windows seems to prefer double quotes with command parameters.

Command Reference

Usage

OSCommand
macOS / Linuxfulcrum <cmd> [args]
Windows.\fulcrum.cmd <cmd> [args]

Options

OptionDescriptionType
--versionShow version number[boolean]
--helpShow help[boolean]

Commands

All command line arguments are also configurable via environment variables, prefixed with FULCRUM_. e.g. setting --home-path from an environment variable using FULCRUM_HOME_PATH. Explicit CLI arguments win. e.g. fulcrum setup --home-path <path> (to set the file system location for data, config, plugins, etc.); required for setup, sync, and install-plugin if not set as an environment variable.

setup

Setup the local Fulcrum database. Requires that the API token belong to an account owner.

Note: setup by default is run interactively on Linux/macOS, via prompts for email/password. Windows requires passing email/password parameters.

OptionDescriptionRequiredDefault
--orgorganization nametruena
--emailemail associated with your Fulcrum accounttruetrue
--passwordpassword for your Fulcrum accounttruetrue
--token <token>skip email/password and use an API tokenfalsefalse
OSCommand
macOS / Linuxfulcrum setup
Windows.\fulcrum.cmd setup --email EMAIL --password SECRET

sync

Sync an organization to the local database. Defaults to a one-time sync, but can continually sync (15 second intervals) using the --forever option.

OptionDescriptionRequiredDefault
--orgorganization nametruena
--foreverkeep the sync running forever, every 15 seconds (default). Specify interval by including --interval 30, e.g. for a 30 second intervalfalsefalse
--cleanstart a clean sync, all data will be deleted before startingfalsefalse
--after-sync-command <command>run an arbitrary command after each syncfalsefalse
--no-progressdisable progress logs, automatically disabled if stdout isn't a ttyfalsefalse
--simple-outputreplace emoji-based status indicators with text-basedfalsefalse
--no-colorsdisable console colors, automatically disabled for dumb terminalsfalsefalse
--form <id>filter by form ID, use multiple --form params for multiple formsfalsefalse
OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name'
Windows.\fulcrum.cmd sync --org "Organization Name"

Windows seems to prefer double quotes with command parameters.

reset

Reset an organization.

OSCommand
macOS / Linuxfulcrum reset --org 'Organization Name'
Windows.\fulcrum.cmd reset --org "Organization Name"

install-plugin

Install a plugin.

OptionDescriptionRequiredDefault
--namethe plugin namefalsena
--urlthe URL to a git repofalsefalse
OSCommand
macOS / Linuxfulcrum install-plugin --url https://github.com/fulcrumapp/fulcrum-desktop-postgres
Windows.\fulcrum.cmd install-plugin --url https://github.com/fulcrumapp/fulcrum-desktop-postgres

create-plugin

Create a new plugin.

OptionDescriptionRequiredDefault
--namethe new plugin nametruena
OSCommand
macOS / Linuxfulcrum create-plugin --name 'MyPlugin'
Windows.\fulcrum.cmd create-plugin --name "MyPlugin"

update-plugins

Update all plugins.

OSCommand
macOS / Linuxfulcrum update-plugins
Windows.\fulcrum.cmd update-plugins

build-plugins

Build all plugins.

OSCommand
macOS / Linuxfulcrum build-plugins
Windows.\fulcrum.cmd build-plugins

watch-plugins

Watch and recompile all plugins.

OptionDescriptionRequiredDefault
--nameplugin name to watchfalsena
OSCommand
macOS / Linuxfulcrum watch-plugins
Windows.\fulcrum.cmd watch-plugins

query

Run a query in the local database.

OptionDescriptionRequiredDefault
--sqlsql querytruena
OSCommand
macOS / Linuxfulcrum query --sql 'SELECT COUNT(*) FROM memberships'
Windows.\fulcrum.cmd query --sql "SELECT COUNT(*) FROM memberships"

Plugins

Fulcrum Desktop was designed to be easily extended via a plugin architecture. The core function of Desktop is an intelligent synching mechanism, which can be extended to build out custom integrations with databases, web services, and more.

Database Plugins

Fulcrum Desktop syncs with an internal SQLite database, similar to the database embedded within the mobile applications. This internal fulcrum.db database is not very user-friendly, so you will likely want to install one of the database plugins, which include more user-friendly app record views.

PostgreSQL

PostgreSQL is a popular and powerful, open source object-relational database management system (ORDBMS) with an emphasis on extensibility and standards compliance. Combined with the PostGIS spatial database extension, Postgres powers Fulcrum's back-end database.

Once this plugin is installed, the sync command will keep your PostgreSQL database in sync with your Fulcrum Organization. Source code on GitHub.

Options

OptionDescriptionRequiredDefault
--versionShow version numberfalsena
--helpShow helpfalsena
--orgorganization nametruena
--pg-hostpostgresql server hostfalselocalhost
--pg-portpostgresql server portfalse5432
--pg-userpostgresql userfalsena
--pg-passwordpostgresql passwordfalsena
--pg-databasepostgresql database namefalsefulcrumapp
--pg-schemapostgresql schema for the datafalsepublic
--pg-schema-viewspostgresql schema for the friendly viewsfalsepublic
--pg-before-functionpostgresql function to call before the sync starts. It's invoked as SELECT function_name();falsena
--pg-after-functionpostgresql function to call after the sync finishes. It's invoked as SELECT function_name();falsena
--pg-underscore-names / --no-pg-underscore-namescreate the views with underscored names instead of the app namefalsetrue (underscored names = yes)
--pg-custom-modulethe path to a custom JavaScript module to load, see examplefalsena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name postgres
Windows.\fulcrum.cmd install-plugin --name postgres

Setup the database

Be sure you have a database already created with the PostGIS extension installed. You can name your database "fulcrumapp" to use the default settings, and execute the following query to enable PostGIS: CREATE EXTENSION postgis;

Keep the database in sync with your Organization

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name' --pg-database 'mydatabase' --forever
Windows.\fulcrum.cmd sync --org "Organization Name" --pg-database "mydatabase" --forever

GeoPackage

GeoPackage is an open, standards-based, platform-independent, portable, self-describing, compact format for transferring geospatial information. Built on the SQLite platform, the GeoPackage standard defines the schema for a GeoPackage, including table definitions, integrity assertions, format limitations, and content constraints.

Once this plugin is installed, the sync command will keep your GeoPackage database in sync with your Fulcrum Organization. Source code on GitHub.

Options

OptionDescriptionRequiredDefault
--versionShow version numberfalsena
--helpShow helpfalsena
--orgorganization nametruena
--gpkg-namethe name of the .gpkg file (not a full file path, just the name)(org name)na
--gpkg-paththe path to the directory to create the .gpkg file(depends on OS)na
--gpkg-dropdrop and re-create the tablestruena
--gpkg-underscore-names / --no-gpkg-underscore-namescreate the views with underscored names instead of the app namefalsena
--gpkg-user-info / --no-gpkg-user-infoadd user info to the app views (updated_by_email and created_by_email), incurs a significant performance penalty for large accounts. This data can still be joined via SQL if it's omitted.truena
--gpkg-joined-names / --no-gpkg-joined-namesadd the project name and assigned to email to the app views (_assigned_to_email and _project_name), incurs a significant performance penalty for large accounts. This data can stil be joined via SQL if it's omitted.truena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name geopackage
Windows.\fulcrum.cmd install-plugin --name geopackage

Setup the database

OSCommand
macOS / Linuxfulcrum geopackage --org 'Organization Name'
Windows.\fulcrum.cmd geopackage --org "Organization Name"

This will create the following GeoPackage file:

OSPath
macOS / Linux/Users/username/.fulcrum/geopackage/Organization Name.gpkg
Windows\Users\username\AppData\Local\Programs\Fulcrum\geopackage\Organization Name.gpkg

Keep the database in sync with your Organization

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name' --forever
Windows.\fulcrum.cmd sync --org "Organization Name" --forever

MS SQL Server

MS SQL Server is a popular relational database management system (RDBMS) developed by Microsoft.

Once this plugin is installed, the sync command will keep your MS SQL Server database in sync with your Fulcrum Organization. Source code on GitHub.

Options

OptionDescriptionRequiredDefault
--versionShow version numberfalsena
--helpShow helpfalsena
--orgorganization nametruena
--mssql-connection-stringMSSQL connection string (overrides all other connection parameters). Example: mssql://username:[email protected]/database. If on Azure, add ?encrypt=truefalsena
--mssql-databaseMSSQL database namefalsefulcrumapp
--mssql-hostMSSQL server hostfalselocalhost
--mssql-portMSSQL server portfalse1433
--mssql-userMSSQL userfalsena
--mssql-passwordMSSQL passwordfalsena
--mssql-schemaMSSQL schema for the datafalsedbo
--mssql-schema-viewsMSSQL schema for the friendly viewsfalsedbo
--mssql-underscore-names / --no-mssql-underscore-namescreate the views with underscored names instead of the app namefalsetrue (underscored names = yes)
--mssql-before-functionStored procedure to call before the sync starts. It's invoked as EXECUTE function_name;falsena
--mssql-after-functionStored procedure to call after the sync finishes. It's invoked as EXECUTE function_name;falsena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name mssql
Windows.\fulcrum.cmd install-plugin --name mssql

Setup the database

Be sure you have a database already created. You can name your database "fulcrumapp" to use the default settings. The plugin does not automatically create the database.

Keep the database in sync with your Organization

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name' --forever --mssql-user USERNAME --mssql-password PASSWORD --mssql-host 'localhost'
Windows.\fulcrum.cmd sync --org "Organization Name" --forever --mssql-user "USERNAME" --mssql-password "PASSWORD" --mssql-host "localhost"

Note

If you come across this error while installing a plugin on older Windows operating systems - it may mean that your system needs support for Transport Layer Security (TLS) 1.1 and TLS 1.2. Consider reviewing (particularly the Easy fix section and download) that page for a possible update.


Media Plugins

In addition to syncing database records, Fulcrum Desktop supports intelligently downloading media files.

Fulcrum Desktop Media

Concurrent file downloads and automatic retries for Fulcrum media files (photos, videos, audio, signatures) and associated track files for spatial video & audio (gpx, kml, geojson, json, srt).

Options

OptionDescriptionRequiredDefault
--versionShow version numberfalsena
--helpShow helpfalsena
--orgorganization nametruena
--media-pathmedia storage directoryfalse~/.fulcrum/media
--concurrencyconcurrent downloads (between 1 and 10)falsena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name media
Windows.\fulcrum.cmd install-plugin --name media

Download all media files for your Organization

OSCommand
macOS / Linuxfulcrum media --org 'Organization Name' --media-path /path/to/media/storage
Windows.\fulcrum.cmd media --org "Organization Name" --media-path \path\to\media\storage

Fulcrum Desktop S3

Sync media to your own Amazon Simple Storage Service (Amazon S3) bucket.

Options

OptionDescriptionRequiredDefault
--versionShow version numberfalsena
--helpShow helpfalsena
--orgorganization nametruena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name s3
Windows.\fulcrum.cmd install-plugin --name s3

Sync media to S3

OSCommand
macOS / Linuxfulcrum sync --org "Organization Name" --s3-access-key-id "key" --s3-secret-access-key "secret" --s3-bucket "mybucket" --s3-region "region"
Windows.\fulcrum.cmd sync --org "Organization Name" --s3-access-key-id "key" --s3-secret-access-key "secret" --s3-bucket "mybucket" --s3-region "region"

Other Plugins

Other experimental plugins.

Fulcrum Desktop Reports

Generate custom PDF reports from Fulcrum data. To customize reports, edit template.ejs or use the --template option to reference a custom .ejs embedded JavaScript template file. Source code on GitHub.

Options

OptionDescriptionRequiredDefault
--versionshow version numberfalsena
--helpshow helpfalsena
--orgorganization nametruena
--formform namefalsena
--skipskip form name, can be specified multiple times to skip multiple formsfalsena
--templatepath to ejs template filefalse~/.fulcrum/plugins/fulcrum-desktop-reports/dist/template.ejs
--headerpath to header ejs template filefalsena
--footerpath to footer ejs template filefalsena
--reports-pathreport storage directoryfalse~/.fulcrum/reports
--media-pathmedia storage directoryfalse~/.fulcrum/media
--file-namefile namefalsena
--concurrencyconcurrent reports (between 1 and 10)false5
--repeatablesgenerate a PDF for each repeatable child recordfalsefalse
--recurserecursively print all child items in each PDFfalsetrue
--reports-wkhtmltopdfspecify the path to the wkhtmltopdf binaryfalsena

Install the plugin

OSCommand
macOS / Linuxfulcrum install-plugin --name reports
Windows.\fulcrum.cmd install-plugin --name reports

Note: Users will need to install wkhtmltopdf separately from Fulcrum Desktop https://wkhtmltopdf.org/downloads.html and potentially specify the location of the binary. For example: .\fulcrum.cmd reports --org "Organization Name" --form "Form Name" --reports-wkhtmltopdf "C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe"

Run reports

OSCommand
macOS / Linuxfulcrum reports --org 'Organization Name' --form 'GeoBooze' --template custom.ejs
Windows.\fulcrum.cmd reports --org "Organization Name" --form "GeoBooze" --template custom.ejs

Keep reports in sync

OSCommand
macOS / Linuxfulcrum sync --org 'Organization Name'
Windows.\fulcrum.cmd sync --org "Organization Name"

Did this page help you?