The Push API

The Push API

When integrating agileBase with third party systems, the API is really useful. Programmers can use it to send data to websites, to other software such as PowerBI, a  Business Intelligence tool, or to external systems such as label/barcode printers for example. The opportunities are endless.

We now have a way to ‘push’ data from agileBase, rather than ‘pulling’ it from a third party system.

What’s the difference? Simply put, if pulling, a third party system has to regularly ask agileBase whether there’s any new data. It may do this once an hour, once every few minutes or however often it needs. That means extra work for both systems – new data may be reasonably infrequent but when it is there you want it to be transferred quickly, which means polling often even when there’s nothing to send.

Conversely, with ‘push’, agileBase sends a message to the third party system only when there’s relevant data to send.

Not only is this more efficient, it’s less costly too. Each agileBase API call costs a small amount, as set by the capacity that’s been purchased. Third party systems may also have capacity limits or costs which build up over a number of calls. In the ‘pull’ scenario, each call would use server resources and generate costs even when there’s no data to send.

When using push, calls are made only when necessary. Further, you can specify in the settings the maximum number of calls to make per day, so you can control the maximum possible cost. You can set it to anything from once every 5 minutes to once a day – different integrations may require more or less timely data. For example invoice totals may be ok to push to an accounting system once a day but individual customer orders may be best sent as soon as they’re received.

Setting up the push API

1. Firstly, set up a view to operate as a standard ‘pull’ API
2. Enter a URL into the ‘Push URL (optional)’ area below the other details on that screen. This is the URL that agileBase will POST to when there’s new data.
3. In the table that the API view was created from, add a new date/time field, accurate to the second, for the system to record when the API push was last used
4. Go to the ‘workflow’ section under the view’s ‘manage’ tab.
   1. for ‘workflow action’, select ‘send data to a third party system using the API’
   2. for ‘recording the time of the last action’, choose the date/time field created above
   3. choose a minimum interval to wait between pushes

The system will now make a POST to the URL specified in step 2 whenever there’s new data to send. It will contain one parameter, ‘json’, which is a JSON representation of all the data in the view.

Selecting data to push

How do we know which data is new and wants to be sent out via the API?

That’s up to you – any filters can be added to the view to select data you want. Commonly, you’d use the date/time field set up in step 3. When a push successfully completes, every record in the view has this field set to the current time.

Note: if the push encounters an error for any reason, say the third party system returns a HTTP error code rather than the expected ‘200’ code for success, the timestamp won’t be set.

A few common scenarios would be:

Pushing any data modified since it was last pushed

To do this, add a boolean calculation to your view, something like

needs pushing = {last modified [auto]} > {last pushed}

where ‘last pushed’ is the name of the timestamp field you added in step 3 above.

Then add a filter on the view ‘needs pushing equals true’

Pushing any new rows that have never been pushed before

For this scenario, simply add a filter to the view ‘last pushed is empty’

Pushing only rows not yet marked as received

In some cases, you may want to be even more prudent than using the internal timestamp. The third party system could make a separate API call to agileBase for every row that’s received, telling it to update the row with an ID to prove receipt. That’s more API calls of course, but some situations may warrant it.