Say Hello to Google Sheets V4
August 14th, 2017
We have migrated Ultradox to the newGoogle Sheets API (v4).
With the new API many basic concepts have changed, but we have worked hard to make the transition for you as painless as possible.
Keep on running
As long as you do not touch any building block that works with Google Sheets, all flows will simply use the old API - as long as Google keeps it up and running.
You will get a warning in the console though that you are still on the old API.
Adjusting the settings of a building block by clicking on the bold text in the title will migrate the building block to the new API when saving the new configuration.
Migration Guide[a]
The new API is much cleaner and provides a lot of additional features.
Some features like queries on rows have been removed, so we had to implement some of these features right in Ultradox instead.
Please read this section very carefully as it covers the most significant changes.
Column headers and variable names
Variable names used to be derived automatically from the column headers.
Now you can specify the variable for each column independently from the column header. This will make your templates much cleaner while keeping nice headers in the sheet.
The default variable names are still based on the column headers, but they will now be in camelCase instead of only lowercase letters.
If you have a column header called My Header the resulting variable used to be called myheader while it will be called myHeader when creating new building blocks that load data from a sheet.
Row numbers
The old API used to provide a unique ID for each row in your sheet. This feature has been removed and you will always have to work with the rowNumber instead.
The old ID was pretty nice as it would stays the same, even if you'd add or remove rows in your sheet.
The new approach is much simpler and easier to understand, but you may have to reload a row based on a query to retrieve the actual row number if you insert or add rows at the beginning of your sheet.
The Update row(s) or Insert row building blocks now only accept row numbers (integer values starting with 1 for the first row).
The Update row(s) building block accepts multiple row numbers separated by a comma to change multiple rows at once.
Column format detection
With the new API it is now finally possible to detect the format of your columns!
If you have specified a number format for your columns the proper type will now also show up in Ultradox.
This will also automatically select the correct renderer when inserting these variables using the Ultradox Template Editor or Email Designer.
Formatting
When loading values from a sheet, they will not be formatted any more. This is great as you can now work with sheets with different locale settings.
When loading a number from a sheet it used to show up as 1,000.50 when using Google Sheets in the US, but the same number would show up as 1.000,50 in Germany.
This caused a lot of headaches especially when performing calculations in a script.
Numbers will now always be loaded in a raw format, in the example above you will now get 1000.50 which can be used in computations - Yay!
When merging data from Google Sheets into you documents or emails, please make sure to specify the proper formatting options in Ultradox!
If you are not specify any formatting options in your templates a variable holding a currency from your sheet will show up just as a plain unformatted number instead.
If you have a variable called ${amount} in your template reflecting a currency in your sheet it used to print $10,000,50 but it will now just display 10000.50
Use ${amount;currency(op=USD)} to format the currency according to your needs.
Query Builder
The new API removed a feature that many users loved: Fetching rows based on a query.
We have implemented our own query engine into Ultradox to be able to still provide this feature to you!
As the queries are now handled natively by Ultradox you can even take advantage of our famous query & condition builder to create the queries in a simple way - which also avoids typos.
While some of your old queries can be migrated automatically you will have to specify more complex queries again with the new query builder.
Issues
We have tested the new API with a lot of different flows. But due to the number a required changes it is quite likely that you encounter some weird issues.
If you are running into problems, please report them to the Ultradox community.
[a]Hi, so I was hoping that this would actually guide me through migrating from the old building blocks to the new building blocks. Please can you add some instructions on how to do this? My integrations are broken, and I'm guessing this is why. Thanks
Questions and Feedback
If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.
If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.
Last Updated: 9/11/18