AutoCrat Users Guide

Version 3.0.0.beta

Welcome to the new AutoCrat, which we are referring to as 3.0. Version 1.0 was the original
from way back before they were calling them “Add-ons”. Version 2.0 is the current version in
the Add-ons gallery. And version 3.0 is a new version that is now in limited beta release.

This new version improves a number of issues around usability and trigger performance.

To report a new bug, please head to the Autocrat Google Group.

Contents
Contents
About the new AutoCrat
About the upgrade process
The Development Roadmap
Known Bugs & Issues
Getting Started
Creating or selecting a template
Tags
Using data from your merge sheet in your settings
Creating or Editing a Merge Job
1. Name your merge job
2. Choose template
3. Map Source Data to Template
4. File Settings
File Name
File Type
Output as
5. Choose destination folder(s)
6. Add dynamic folder reference (optional)
7. Set Merge Condition (Optional)
8. Share docs & send emails
9. Add/remove job triggers
Previewing Your Job
Job Details Summary
Preview for first mergable row
Further Reading
Where do I find my document or folder’s ID?
Understanding Triggers in AutoCrat 3.0
What is a trigger?
 Enabling vs Adding triggers
Trigger owner
Changing trigger owners
Sending emails via triggered jobs
Enabling form triggers will automatically enable the time triggers
How to Set autoCrat (or formMule) to Merge On a Specific Day
Troubleshooting
Duplicate Headers
Image Merge Not Working

About the new AutoCrat

The main changes and additions include:
1. A single user interface. We got rid of the sidebar. Everything happens through the
primary dialogue. Hopefully this simplifies everything and improves performance.
2. More modern design/interface.
3. Cleaner code under the hood. We have grown a lot as developers and our code is far
more performant. Hopefully this will be immediately apparent.
4. Single document mode. You can now produce a single document for a merge job. E.g.
a single doc or PDF, with each row of data that meets your job criteria merged into it
(see step 4). Optionally you can add page breaks between. Previously you could only
create one document per row of data. This was one of the most asked for feature
requests. NOTE: This only works for docs at the moment, not spreadsheets.
5. During the template/tag mapping process, you can now select a tag type (see step 3).
The current types are hyperlink and image.
a. Image merge. You can now merge images into your docs from a publicly hosted
image URL. Select a tag type of image and optionally provide AutoCrat with a
height and width (in either pixels or as a percentage). Unfortunately, it doesn’t
seem like google allows you to set word wrap on an image programmatically. So
all images must be merged in-line.
b. Hyperlink merge. This has secretly existed for a while in v2.0, but it was finicky
and only worked some of the time. Hopefully it’s better now.

About the upgrade process

● You can choose to upgrade early by clicking the “Upgrade to AutoCrat v3” link in the
bottom of the v2 sidebar.
● All of your old jobs can be imported into the new version after the upgrade has
completed for your account.
○ NOTE: Upgrading your account does NOT mean that your jobs have been
upgraded. This means that existing jobs that have not been explicitly imported
 into v3 will remain in v2 indefinitely. However, once you upgrade your account
you will not be able to view/edit/manually run your v2 jobs without importing them
into v3.
● If one user of a spreadsheet has upgraded to v3, all other collaborators on that
spreadsheet will see v3 when they open AutoCrat in that spreadsheet.

The Development Roadmap

Here are the things we’re currently working on (sort of, but not necessarily in this order):
1. if merge sheet does not have headers, prompt user to drop tags in as headers
2. Detect whether a form submission is a new submission vs a re-submission and if so, re-
run the merge.
a. Need to figure out a workflow around whether a new merge doc is created and
the old one is preserved OR the same doc is emptied and re-merged
3. Allow single output mode to be run for spreadsheets
a. This is actually pretty tricky. For a doc, I’m just copying the body of the template
and pasting it over and over again into the output. But for a spreadsheet, if the
template has multiple tabs, what exactly am I copying?
4. Allow user to capture edit form URL on form submissions.
5. Google Slide Templates!
6. Better support for multiple languages

Known Bugs & Issues

To report a new bug, please use the AutoCrat G+ Community. Note that you are using v3.

1. In the "Share docs & send emails" step, the "share doc as" menu will show "editable
doc" and will be disabled so you can’t change it, even though the doc type in step 4 is
PDF. This is only an issue in the interface. The shared doc will still be shared as a
PDF.
2. Large Files in Single Doc Merge Mode - If you have lots of rows, this may end up
creating more than one doc. It will merge as many rows into a single doc as it can
before hitting a Google imposed time limit of 6 minutes. It will then start over with a new
doc. We are working on resolving this.
3. Copying the header tags from the drawer menu to the clipboard does not work in Safari
4. <<Image>> tags in your template will not work if they are on the same line as other text.
So if you have an image of a digital signature, and you have a <<Signature>> tag, you
can’t put “Signature: <<Signature>>” on the same line. You would need to put

Signature:
<<Signature>>
5. In some cases, a trigger set by one user cannot be removed so that a second user can
become the “trigger owner”
AutoCrat Users Guide
Getting Started
Welcome to the new AutoCrat! AutoCrat is a basic document merge utility that allows you to
take data from a spreadsheet and paste (or merge) it into a document. Documents can be
Google docs or spreadsheets, or even PDFs.

Each spreadsheet will be referred to as a “project”. Each project can have one or more “jobs”.
A job is a set of instructions telling AutoCrat what to do. When you run a job, a new merge is
created.

Start AutoCrat by clicking “Open” from the AutoCrat menu under Add-ons in your spreadsheet.
Click the new job button, and follow the instructions in the setup wizard. Click next to progress
to the next step, and click save when you are finished. Not all steps are required. If you failed
to set any settings that are required, AutoCrat will tell you.

Creating or selecting a template

AutoCrat requires a template. (Click here to view a sample). This is how it knows what your
final document or documents should look like. A template can be either a Google document or
Google spreadsheet. Put <<tags>> in your template everywhere you want to dynamically pull in
data from your spreadsheet. Format your template however you like!

Tags
Tags look like this: <<I am a tag>>. They are a string of text wrapped in double less than and
double greater than symbols. During the job setup process, you will need to map each tag found
in your template to a column in your spreadsheet. If you make the tag text match a spreadsheet
column exactly, AutoCrat will find it and auto map it for you. Beware, tags are case sensitive!

Using data from your merge sheet in your settings

What if you want each document that AutoCrat creates to have a different file name? Well you
can do this by using <<tags>> in the file naming convention setup step. For example, say you
have a “Student Name” column in your spreadsheet. Simply put “<<Student Name>> - Bio
Assignment 1” in the file name field to give each file a helpful and unique name.

Almost all of the text fields in the AutoCrat3 job settings can pull data dynamically from your
merge sheet.
A note on upgrading from v2 to v3: In version 2 of AutoCrat we used the syntax $iAmAHeader
for each of the settings fields like email address, file name, etc. We are now using the new <<I
Am A Header>> syntax because this is one fewer convention to remember AND it is the same
as how we do things in our other Add-on formMule. However, your $iAmAHeader tags should
still work with the new AutoCrat. You should not need to change them from $ to <<>> when you
upgrade.

To make adding columns easier, there is a drawer panel on the left side of any settings step that
allows for these dynamic fields. Open the drawer by clicking the little triangle and click a column
header to copy it to your clipboard with the <<tags>> already wrapped around it.

As a bonus, you can use <<TODAY>> to add today’s date (formatted in your local convention)
and <<NOW>> to add your local Date + Time. So for example, “<<Student Name>> - Bio
Assignment 1 [ Created on <<NOW>>]”.

Creating or Editing a Merge Job

When you click the “New Job” button OR the little pencil icon on an existing job, the job editor
wizard will open. This is where you will enter or edit all of AutoCrat’s settings for a particular job.

1. Name your merge job

Give your job a useful name so that and your collaborators can easily recognize it.
2. Choose template
Choose a template that you have previously created. You can either pick from your Drive or
choose a recently selected template from the list at the bottom of this step.

3. Map Source Data to Template

When setting up your merge you will need to “map” (i.e. match) the tags in your document
template to the columns in your spreadsheet. If the tags match their corresponding header
exactly, the mapping will be done for you automatically. But they do not need to match, in which
case you must manually match them.

AutoCrat 3.0 now provides the ability to indicate the type of data that is being merged:

Standard: a normal text field. Will be merged into the document exactly as it appears in
the spreadsheet. Same as AutoCrat v2
Image: Autocrat can now pull an image URL from a sheet and merge the image (not the
URL) into the document.
● The image must be publicly hosted. Images stored in Drive will not work.
● You can optionally provide a width in pixels (e.g. 50 or 50 px) or percentage (e.g.
50%). Pixels are an absolute size, whereas the percentage is relative to the
actual image file’s size. Leaving these fields blank will simply merge the image
at 100% of its actual size.
Hyperlink: Autocrat can identify text as a URL so that it is live (clickable) in the
document. When selecting this option you will also be able to include a “link label”. Use
this option if you wish to hide the URL behind a word or sentence.
● With a Link Label: Click to View (i.e. the link label is “click to view” to which the
hyperlink “www.google.com” is applied)
● Without a Link Label: www.google.com

4. File Settings

File Name
This is the name that each merged document will be given. Use <<tags>> that match a column
header to make the names unique. Use <<NOW>> or <<TODAY>> to give each doc a
timestamp.

File Type
Either Google Document or PDF. Note that some hyperlinks may not work correctly if exported
directly to PDF. As a work around, save as a Google Doc and export to PDF manually
afterwards.
Output as
Choose to output one document per row of data that satisfies your merge condition, or a single
document (new!) with each row merged into the same document.

A note on single document mode: On very large jobs you may end up with 2 or 3 separate
documents. We’re working on fixing this.

5. Choose destination folder(s)

Choose a folder for every merged document to be dropped into. This is actually optional IF you
include a “dynamic folder reference”.

6. Add dynamic folder reference (optional)

AutoCrat always provided this functionality, but it’s being renamed for clarity. It was formerly
referred to as a “Secondary Folder Key”, which isn’t super clear.

The idea is that sometimes you want a merged doc to be dropped into certain folders and not
others. E.g. Say you want to create a document for each teacher at your school and organize
those docs by grade team. Create a folder for each team, put the proper folder ID into a column
in your data sheet, and then tell AutoCrat which column contains these “dynamic” folder
references.

7. Set Merge Condition (Optional)

A merge condition tells AutoCrat whether or not to merge a particular row of data. By default,
AutoCrat will run for all rows in a job’s data sheet that do not have a value in the status column
for that job. You can optionally add additional conditions that must be met for AutoCrat to
include a row of data.

Specifically, you can tell AutoCrat to only merge a row of data IF the value for a specified
column is equal to a particular value, is NULL or is NOT NULL. NULL means empty or blank,
and NOT NULL means not empty or blank (i.e. it has any value at all). You should NOT include
quotes around the value.

AutoCrat v2 only let you add a single condition, but AutoCrat v3 now allows for multiple.

8. Share docs & send emails

Currently, if you want to share a merged document with others, you must also send them an
email. The merged document will be shared with each email recipient. You can optionally
prevent editors from re-sharing the merged doc and/or send the email from a generic no-reply
email address (e.g. no-reply@myschool.org).
9. Add/remove job triggers
Optionally tell AutoCrat to run every time a form is submitted (only works if there is a form
attached to the spreadsheet. And/or to run at a given time interval (E.g. every 3 hours). Note: A
limitation of Google Add-ons is that they cannot run more frequently than every hour. Check out
Understanding Triggers in AutoCrat3 for further reading.

Job Details Summary

Previewing Your Job

Job Details Summary

Click on the information icon to quickly see a summary of your job settings

Note that you can see the number of rows of data that will be merged if you ran the job as is. If
the number is zero you will see the message “No rows will be merged. None meet merge criteria.”
This means that you either have a status message in every row, or you have a merge criteria set
that is not true for any rows.

Preview for first mergable row

You can also run a test merge for the first available row of data by clicking the “Preview for first
mergable row” button at the bottom of the Job Details pop up. This will run the merge for the first
row of data that is eligible to merge, however it will NOT add a status message to your merge
column (meaning the next time your run the actual merge, this row will be merged again). When
run in preview mode, the merge will NOT send emails to the designated recipients. It will,
however, send an email to the email address of the person running the preview so that you can
preview it and make any desired changes before actually sending.

Further Reading

Where do I find my document or folder’s ID?

Every Google document, spreadsheet, folder, etc. has a unique identifier that can be found in
the URL for that doc - usually after the /d/. For example, the doc ID for this help guide is
“1WTGSSlH6gwUHpipusPKLIsgfFUamDbFbJ7JaoG6-ZBo”. AutoCrat uses these IDs to
manage your merge documents, templates and destination folders.

Understanding Triggers in AutoCrat 3.0

What is a trigger?
A trigger allows an Add-on to run without you having to do anything manually. For example,
AutoCrat allows you to set either a time trigger that will automatically run at a given time interval
(say every hour or every 6 hours), or a form trigger that will run automatically every time a user
submits a new Google form response (if you have a form attached to your spreadsheet).

Enabling vs Adding triggers

A given type of trigger (i.e. form or time) must be enabled before it can be added to any of your
jobs. A single AutoCrat time trigger and a single AutoCrat form trigger can be enabled for any
project (FYI a “project” is a spreadsheet with AutoCrat 3.0 installed). Any number and
combination of jobs in a project can have a trigger added (I.e. be set to run via either trigger
type).

The first time you try adding a trigger to any job in a spreadsheet, you will be prompted to
enable triggers in the project. You can edit these triggers by clicking the trigger management
link in the bottom left corner of the dialog.

So a given project can have at most a single form trigger and a single time trigger. However,
you can set multiple jobs to run via either trigger type. This is more of a technical issue than
anything you should need to worry about.

Trigger owner
Only one user can enable triggers in a given spreadsheet. This person is considered the trigger
owner, and you can find out who they are by clicking “Manage triggers” in the bottom left corner
of the dialog. Once a trigger is enabled, only the trigger owner can disable it.

Changing trigger owners

If all triggers are disabled, the trigger owner will be removed and a different user will be able to
enable triggers, thereby becoming the trigger owner.

Sending emails via triggered jobs

When a job is run via a time or form trigger, it is run on behalf of the trigger owner. This means
any emails sent by those jobs will be sent from the trigger owner’s email address.

Enabling form triggers will automatically enable the time triggers

This is because there still seems to be a bug that causes form triggers to disappear. If you set a
form trigger, a time trigger will run every hour making sure the form trigger has not disappeared.
If it has, it will repair it.

How to Set autoCrat (or formMule) to Merge On a Specific Day

A great resource via Adam Davis

Troubleshooting

Duplicate Headers
If you get the warning “Warning - Duplicate merge sheet headers found. Your job may not run
correctly if not resolved” it is because you have more than one of the same header in your
merge sheet. If the duplicate value is [EMPTY HEADER] it means you have more than one
empty cell in your header row. AutoCrat considers your last data column to be the last column
with data in any cell. It considers every column to the left of your last data column to also be
data columns. It requires all data columns have headers.

For example, if the above spreadsheet was your merge sheet AutoCrat would show you the
following error: “Warning - Duplicate merge sheet headers found. Your job may not run
correctly if not resolved. Duplicate Values: Last, [EMPTY HEADER]”

A common way to get this error is when creating a new job and your first spreadsheet tab has
empty headers. This is because AutoCrat makes the first tab the merge sheet by default. In this
case, just change your merge sheet to the correct sheet and you will not get this error again.

Image Merge Not Working

Images must be publicly hosted to work. As far as I can tell, this is how Google’s API works.
Putting an image file in Google Drive and making it “Public on the web” is NOT the same as
having a publicly hosted image.