Syncing to ChartHop

ÔĽŅ

You may want to push data into ChartHop, for any number of reasons. For example you may want to submit metrics attributed to people and jobs.

Or perhaps you have your own payroll system and want to write your own payroll sync to automatically update the ChartHop roster from the payroll system.

ÔĽŅÔĽŅImporting data

The best API call to use to update data in bulk in ChartHop is the importDataCsv API call https://api.charthop.com/v1/org/{orgId}/import/csv/data

This call lets you post a multipart/form-upload of the CSV file to push a large amount of data into ChartHop.

This call has lots of optional parameters. For most purposes we'd recommend using:

  • upsert¬†- set this to true if you expect to add new people or jobs that aren't in ChartHop already. Don't use it if you're just updating existing people in the roster.
  • createGroups¬†- set this to true if you want to create departments and locations on the fly if they are in the source system. If you are not creating departments and locations, no need to use it.
  • notifyUserIds¬†- set this to a list of user-ids (you can retrieve these ids via the¬†findUsers¬†API call) to send an email following the completion of the API call.
  • notifyAppName¬†- set this to the name of the app that you want to show up in the notify email

ÔĽŅÔĽŅChecking on the status of the import

The importDataCsv call runs asynchronously. Depending on the size of the import, it can take anywhere from a few seconds to an hour. It returns a Process object. You can check on the status of the process by calling the getProcess call.

ÔĽŅÔĽŅInteracting with the ChartHop Apps UI

If your sync is for your own private use, then run the above API call whenever you please, on your own schedule. It's your world!

But, if you are building a sync that is intended for distribution for other ChartHop users, those users will expect the sync to run when they press the "Sync Now" button from the app configuration page in ChartHop.

When the user presses "Sync Now", this starts an asynchronous "sync process" for your app that you, the app developer, are expected to manage the state of. We'll ping your webhook URL to tell you that the user has hit sync, and you ping us back when you're done syncing.

To implement this, you will want to use the following flow:

  • Set up an¬†Event Notification Webhook¬†on your own URL, matching on the¬†process.create.{appname}¬†event.
  • When your Webhook URL receives this event, the¬†entityId¬†will contain the sync process id.
  • Run your sync, implementing calls to¬†importDataCsv¬†or whatever else you need to complete the sync.
  • When your sync is complete (or errors out), call the¬†updateProcess¬†API call to mark the sync process as complete.
    • For bonus points and a nicer user experience, call¬†updateProcess¬†periodically during your sync, passing a¬†progress¬†value from 0 to 1 and a¬†message¬†with the last status message. This will control the state of the progress bar the user will see as your sync runs.

ÔĽŅÔĽŅPermissions

Your app will need Primary Editor permissions to sync data into ChartHop.