Sync Fulcrum data to a local database. The local database is a complete API representation with search indexes and query tables. It's intended to be the foundation for local/disconnected data synchronization and reporting.
https://learn.fulcrumapp.com/dev/desktop/intro/
git clone git@github.com:fulcrumapp/fulcrum-desktop.git
cd fulcrum-desktop
yarn
The first step to use the application is to enable the plugins you want to use during the execution in the plugin.json
file in the config folder of the repository:
{
"postgres": true,
"mssql": false,
"media": false,
"reports": false,
"geopackage": false,
"s3": false
}
*NOTE - Only 1 plug-in at a time - to verify
To run the application on your local machine, you must first build it as a Docker image:
docker build -t fulcrum-desktop:latest .
docker run -it -d --name fulcrum-desktop --network="host" fulcrum-desktop:latest
Each application command must be executed as follows:
docker exec -it fulcrum-desktop bash ./run [COMMAND]
*NOTE - explain the --network & --add-host flags per the following 3 deployment patterns:
Usage example:
docker exec -it fulcrum-desktop bash ./run fulcrum setup --org 'Organization Name' --token '<token>'
If you have already executed a plugin and want to use another one, you must execute the following command:
docker run -it -d --name fulcrum-desktop --network="host" -v $PWD/config:/fulcrum-desktop/config fulcrum-desktop:latest
Remove the current image and run again to see the changes reflected during the app.
Fulcrum Desktop has several built-in commands to setup your database with your Fulcrum account.
Run the fulcrum
command to list the various arguments and options available.
fulcrum setup --org 'Organization Name'
You can pass the credentials or Api token to authenticate with your Fulcrum account to configure your local database:
fulcrum setup --org 'Organization Name' --token '<token>'
fulcrum setup --org 'Organization Name' --email 'EMAIL' --password 'SECRET'
Sync an organization to the local database:
fulcrum sync --org 'Organization Name'
Use --forever
option for keep the sync with your database(Postgres in this case) running forever, every 15 secords:
fulcrum sync --org 'Organization Name' --pg-user 'myuser' --pg-password 'mypassword' --pg-database 'mydatabase' --forever
You can run SQL queries from your synchronized database:
fulcrum query --sql '<QUERY>'
For example:
fulcrum query --sql 'SELECT COUNT(*) FROM forms'
Run the fulcrum console:
fulcrum console
Reset the organizaton and data in your Fulcrum sync database:
fulcrum reset --org 'Organization Name'
Plugins are extensions to the Fulcrum Desktop application. Each plugin has its own functionality to accomplish a specific task.
You can enable which plugins to use during the execution of the application.
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. Note that none of these plugins automatically creates the database.
If you want to sync your PostgreSQL database with your Fulcrum Organization, you can enable this plugin. Be sure you have a database already created with the PostGIS extension installed. You can name your database "fulcrumapp" to use the default settings.
To enable PostGIS you can run:
CREATE EXTENSION postgis;
Keep the database in sync with your Organization:
fulcrum sync --org 'Organization Name' --pg-database 'mydatabase' --forever
If you want to sync your Fulcrum Organization with MS SQL Server, enable this plugin. Be sure you have a database already created. You can name your database "fulcrumapp" to use the default settings.
Keep the database in sync with your Organization:
fulcrum sync --org 'Organization Name' --forever --mssql-user 'USERNAME' --mssql-password 'PASSWORD' --mssql-host 'localhost'
If you want to sync your Fulcrum Organization with your GeoPackage database for transferring geospatial information, enable this plugin.
Setup the database:
fulcrum geopackage --org 'Organization Name'
This will create a GeoPackage file in the following path:
/.fulcrum/geopackage/Organization Name.gpkg
Keep the database in sync with your Organization:
fulcrum sync --org 'Organization Name' --forever
In addition to syncing database records. Fulcrum Desktop supports intelligently downloading media files.
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).
Download all media files for your Organization with the following command. You can pass the directory where you want to storage these files with the --media-path
option:
fulcrum media --org 'Organization Name' --media-path ~/.fulcrum/media
Sync media to your own Amazon Simple Storage Service (Amazon S3) bucket.
fulcrum sync --org 'Organization Name' --s3-access-key-id 'KEY' --s3-secret-access-key 'SECRET' --s3-bucket 'MYBUCKET'
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.
fulcrum reports --org 'Organization Name' --form 'Form Name' --template custom.ejs
This is a list of possible errors that may appear during the execution of the app:
Enabling Plugins Error
If you have enabled more than one sync plugin (MSSQL, Postgres, S3), the following error will be executed:
It's no allowed to enable more than one sync plugin at the same time.
Please, make sure to enable only one synchronization plugin during app execution.
Authentication error
If you pass to the geopackage command an organization that is not setup or is invalid you will get the following error:
Unable to find account InvalidOrganizationName
Make sure you define the organization name correctly or re-setup your Fulcrum credentials.
Reset organization error
If you get this error when executing the reset
command:
ConnectionError: Login failed for user ''.
You must pass it the username and password of the plugin you used to sync. For example:
fulcrum reset --org 'Organization Name' --mssql-user 'MYUSER' --mssql-password "MYPASSWORD"
MSSQL Plugin
If you're synchronizing your database with MSSQL Plugin and you get this error:
CREATE TABLE failed because column '' in table '' exceeds the maximum of 1024 columns.
Contact your provider.
Reports Plugin
If you have an error similar to this one:
Error Error: write EPIPE
Error: spawn [ROUTE] ENOENT
You must make sure to pass the correct directory of --reports-wkhtmltopdf
option in your machine:
Default path:
/usr/local/bin/wkhtmltopdf