Helpful guidance from setup to successful task runs

Getting started

Install and connect Charity Automate

Install the plugin in WordPress by searching for ‘Charity Automate’ on the Add Plugin screen. Activate it and click Charity Automate on the WordPress menu on the left.

New installations take you to the Setup screen, where essential services can be configured.

1. Enter your Beacon account ID and API key (learn more here) and test the connection.
2. Import Beacon record types so the app understands your system.
3. Import Beacon users for owner and assignee dropdowns.
4. Add optional SendGrid API (to send mass emails) and OpenRouter (for AI integration) credentials when those services are needed.
5. Use Test Connections to confirm that each configured service can retrieve data.

Note: your API credentials are encrypted before being stored in the WordPress database.

Beacon Workflow to Zapier to Charity Automate

You can pass data from Beacon via its Workflow element/module (requires an additional subscription from Beacon to use) to Zapier, which forwards data to Charity Automate. This is useful if you need tasks to trigger on events like a new record being added to Beacon or a form being submitted.

Note: this is a more advanced set-up so proceed with caution!

Beacon > Create Workflow

1. Create a new Beacon Workflow for a record type, e.g. a Payment.
2. Choose a trigger, e.g. on form submission or on record create.
3. Set a filter if required or choose a form. For testing, it’s useful to set a filter to your personal record or someone on your team.
4. Add an action: Trigger a Zap.
5. Save the workflow and activate it.

Zapier > Step 1. Beacon – Workflow Action

1. Create a new Zap in Zapier.
2. Add a Beacon step as the trigger. The trigger event must be Workflow Action, and if you haven’t already, connect to your Beacon database by providing an API key and your account ID.
3. In the Configure section, choose the new Beacon Workflow.
4. Test the step, and you should see relevant data appear.

Zapier > Step 2. API by Zapier – Get Beacon References

1. Add a second step and choose the API by Zapier type.
2. Choose API Request as the Action Event.
3. You may need to add your Beacon CRM API information again to use this step. Use these details, then click Connect:
   • Authentication Type = None
   • Connection Name = Beacon CRM (or whatever you wish)
   • Headers = (copy/paste this list):
     Content-Type: application/json
     Beacon-Application: developer_api
     Authorization: Bearer API_KEY
   • Query Parameter (API Key) = API_KEY
   • API Key = your Beacon API Key, e.g h238h9h8wekrh2k23838383n2jk2k2
4. On the Configure screen, use these details:
   • Method = GET
   • URL = https://api.beaconcrm.org/v1/account/ACCOUNT_ID/entity/RECORD_TYPE/RECORD_ID
     • ACCOUNT_ID = your Beacon account ID, e.g. 302291.
     • RECORD_TYPE = the name of the record type, usually payment or person.
     • RECORD_ID = the placeholder of the Record ID from the previous Beacon trigger step.
5. Test the step, and you should see the full details of the record type, including ‘references’ or related records, like the full Person record or Gift Aid declarations.

Zapier > Step 3. Code by Zapier – Prep Webhook

1. Add a Code by Zapier step and choose JavaScript as the programming language.
2. Copy/paste the following code to overwrite the default content:
   const raw = JSON.parse(inputData.raw) || {};
   const body = JSON.parse(raw?.response?.body) || {};
   return {“total”: 1,”results”: [body]}
3. Copy/paste the following code to overwrite the default content:
   const raw = JSON.parse(inputData.raw) || {};
   const body = JSON.parse(raw?.response?.body) || {};
   return {“total”: 1,”results”: [body]}
4. Test the step, and you’ll see the data appear in the correct format for the final step.

Zapier > Step 4. Webhooks by Zapier – Post to Charity Automate webhook

Before adding this step in Zapier, open the Charity Automate task you wish to pass data to:

• Go to Step 2: Trigger
  • Trigger Type = Webhook
  • Webhook Trigger = click the Copy Webhook URL button
• Go to Step 3: Beacon data
  • Data Source = Use the incoming webhook payload as the task data
  • Click the Listen for Test Webhook button

Go back to Zapier, then:

1. Add a Webhooks by Zapier step.
2. Select Custom Request as the Action event.
3. On the Configure section:
   • Method = POST
   • URL = paste the Charity Automate task webhook URL
   • Data Pass-Through? = True
   • Unflatten = Yes
   • Headers = add a new header:
     • Content-Type = application/json
   • Return Raw Response = Yes
4. Test the step

Return to the Charity Automate task. If still listening, the app will pick up the data from Zapier and display it. Congratulations!

Save your task and publish the Zap. The task will not run unless it is made Active.

beacon/SendGrid/Openrouter credentials

Connection Details

Use the guides below to help you connect to the different services the app uses to automate your tasks.

Beacon CRM

1. Log in to Beacon CRM as an Administrator.
2. Scroll to the bottom left on the navigation menu and click ‘Settings’.
3. In the browser address bar (click on the address to view the full website link for Safari users), you will see a number like 30913. This is your Beacon account ID. Make note of it.
   
   For example: https://app.beaconcrm.org/account/30913/settings
4. Click ‘API Keys’ then click ‘Create API Key’ at the top right. A new API key will be created. Click the ‘Copy’ button.
5. On the Charity Automate > Setup or Settings screen, type in your Beacon account ID and paste in your Beacon API key.
6. Click ‘Test Connection’ in the Setup screen or click ‘Save Connections’ in the Settings screen to test the Beacon CRM connection. Green means you’re good to go!

SendGrid API (Mass Email Integration)

1. Log in to SendGrid API as an Administrator.
2. Click on ‘Settings’ on the left navigation menu, then ‘API Keys’.
3. Click ‘Create API Key’, then give it a name, e.g. Charity Automate.
4. Give the API key appropriate access. The app needs the following types set to ‘Full Access’ (you can choose the overall ‘Full Access’ option if you want a simple connection process):
   • Email Activity
   • Email Testing
   • Mail Send (all sub-options)
   • Mail Settings (all sub-options)
   • Stats (all sub-options)
   • Suppressions (all sub-options)
   • Tracking (all sub-options)
5. Click ‘Create & View’ to save the API key. You can then copy the key.
6. On the Charity Automate > Settings screen, paste in the API key and click ‘Save Connections’. The app will check the SendGrid connection, and green means it works!
7. You can also use SendGrid to send all emails for all your WordPress plugins. This overcomes any email sending limits that your hosting company may enforce.
   • Select the ‘Use SendGrid to deliver normal WordPress wp_mail() email’ box
   • Enter a default from email and from name
   • Click ‘Save Connections’ to start the service.

OpenRouter (AI Integration)

1. Log in to OpenRouter as an Administrator.
2. Click ‘API Keys’ on the navigation menu, then click ‘+ New Key’.
3. Give the key a name and alter any settings you wish
4. On the Charity Automate > Settings screen, paste in the API key and click ‘Save Connections’. The app will check the OpenRouter connection, and green is great!

Notes: your API credentials are encrypted before being stored in the WordPress database. When copying an API key, you should also save it somewhere safe for a temporary time for reference if you wish. You can revoke a key at any time in the service settings page. Some keys give FULL ACCESS to your database or the service, so treat them with care.

Build Reusable Templates

Content Templates

There are two types of templates you can create that can be used by your tasks: Email and Word Document.

Email Templates

1. Create a new content template, give it a meaningful name, then choose Email as the type.
2. Enter some meaningful tags to help categorise your template, e.g. thank-you.
3. You can import SendGrid API dynamic templates if you have added an active API key:
   • Click the SendGrid Templates button.
   • Choose a template.
   • Choose a version.
   • Click Import Selected Version to replace the current email subject and body
4. Ensure you add an email subject and body. You can choose placeholders and placeholder functions that the task will replace with matching data from Beacon.
5. The email body editor enables you to add images and tables, etc. and format text. You can click the Code tab to view the raw HTML and edit the markup directly, if you wish.

Word Document Templates

1. Create a new content template, give it a meaningful name, then choose Word Document as the type.
2. Enter some meaningful tags to help categorise your template, e.g. thank-you.
3. You need to have the Word Document already prepared. Add placeholders that act as merge tags that will be replaced by Beacon data.

Build with confidence

Follow the seven-step task wizard

Tasks turn a repeatable process into a dependable workflow. Save at any point and return when you have the information you need.

• Basics: name, describe and choose the task type: Standard or Mass Email
• Trigger: run on a schedule or wait for a unique webhook.
• Beacon Data: paste a Beacon filter or use incoming webhook data.
• Rules: decide which records should continue.
• Actions: arrange emails, documents, CRM updates, AI responses and webhooks. Learn more here.
• Final Actions: send summaries, trigger exports, forward data to a webhook, or continue another task.
• Test: use sample data before setting the task to Active.

Active scheduled tasks show their next run time. Webhook tasks provide a unique URL that can be copied into Zapier or another external system or even your browser. For example, you could run a script on your computer that calls a webhook as part of a different system.

Mass Emails

Choosing Mass Email as the task type in Step 1 enables you to send large batches of emails based on your Beacon CRM database. That includes sending data to Person and Organisation record types!

You will see two default actions in Step 5:

• Send Email – choose email options here and a content template.
• Add Record > Activity – generate an activity to log the email. Be sure to select the Related To field to match the person or organisation.

Be careful to choose a limited filter for this step and don’t schedule it regularly if it will produce lots of emails. Don’t spam your constituents and be sure to adhere to all local, national, and international email spam regulations.

Run Beacon Exports

Beacon allows you to create export templates which contain filtered data or the entire list of records. You can use Charity Automate to schedule these exports to begin and then either send an email notification or forward data to a webhook.

Log in to Charity Connect and open the Beacon Exports screen. Enter the Beacon export ID given by the task to download the file. Webhooks can be tailored to do this automatically: download the exported file and save it on, for example, Google Drive or Microsoft OneDrive.

AWESOME ACTIONS

Task Actions

You have access to several powerful actions within your tasks that can be activated in any order and as many times as you need:

• Send email – send a customised email to a specific person or group. You can also use Charity Automate to send thousands of emails at a scheduled time using the SendGrid API connector.
• Find record – find any type of Beacon record by giving a value to search. The first result is chosen, or it can create a new record if there are no results.
• Add record – create any of your Beacon records, including custom types, from within Charity Automate. The powerful placeholders feature enables you to customise the values for each field, even calculating from previous values and referencing previous actions.
• Update record – update a specific Beacon record with the data you want.
• Delete record – you can also delete a specific Beacon record…but be careful!
• Generate document – create a Word document within a task workflow, like a letter or receipt.
• Call webhook – forward data from the task to another system like Zapier, Pabbly, Make or your own website.
• AI response – create your own prompts and use placeholders to generate intelligent content. You can then use the response to feed your other actions, like email content or updating a donor’s notes.

You can test each action to ensure it works correctly or test the whole workflow before going live. You can also reference previous actions, so one leads to the next.

For example, create a Person record, then create an activity record related to the new person. See placeholders for more information.

You can drag actions up and down to arrange their order. It’s easier to get your actions workflow sorted first before choosing placeholder values. That means if you need to link one to another, things won’t break or need to be added again if you reorder them.

Send emails

Send an email to one or more of your constituents using your WordPress hosting service or via SendGrid API. You can edit:

• From email address.
• To email address – choose from the available Beacon email fields.
• CC & BCC email address options.
• Content template – create content template emails with a subject and email body with placeholders/merge tags that will be replaced by your Beacon data when the task runs.

Add/Update/Delete Beacon records

Charity Automate understands your unique Beacon CRM set-up so that you can choose from all types of records, including your custom types.

When you select a record type, a list of its fields will show. You can enter static values or add placeholders to make the content dynamic. For example, add custom content to an activity note or subject.

You can add a new record, update an existing record, or delete an existing record. For updating/deleting, you need to reference a specific record type and record ID.

Find (and add) Beacon records

Search for any Beacon record type by selecting a field and adding a value. You can also use placeholders. If no records exist, you can set the system to create a new record.

For example, find a Person record by their email address. Then use that data in subsequent steps to create an Activity.

Generate documents

When creating a content template, you have the option to upload a Word document. Prefill this with placeholders and the values will be replaced when the task runs.

Generated files are saved in the WordPress uploads folder and linked from the run logs so authorised staff can download, edit and print them. You can also view them using FTP, etc. if required.

Please note that placeholders are different to the ones in Beacon CRM.

Call webhooks

Pass the current data to an external online system via a webhook. Simply enter the URL of the webhook and test it to ensure data is received on the other end.

AI responses

If you add an OpenRouter API key to the app, you can generate AI responses by writing a suitable prompt and choosing the AI provider and model you want to use.

OpenRouter lets you choose from lots of AI providers and models, like OpenAI and its GPT models, to Anthropic and Claude or Google and Gemini. However, each carries its own credit charges. Often, ‘mini’ models are more than adequate, and the cost is very low.

Responses will be available as placeholders to be used in subsequent actions.

Placeholders and placeholder functions

Bring live CRM data into your content

Placeholders are like merge tags in Microsoft Word. They will be replaced with values from the current record when a task runs.

For example, {{person.name.first}} will be replaced by the Person record First Name value.

Placeholders have double curly brackets surrounding them. They start with the record type (no spaces, only underscores _) and use a dot . to get to the correct field name. They are always lowercase.

Placeholder List

A list of all placeholders will be made available throughout the app, like:

• Content Templates – click the Placeholders and Functions buttons on the navigation toolbar. Clicking on a placeholder or function will add it to the current content.
• Task Actions – some field values let you add placeholders by using the Placeholders Drawer (see below)

{{person.name.full}}
{{payment.name}}

The task will replace these with the correct Person and Payment values:

John Smith
£20.00 from John Smith

You can view a comprehensive list of all placeholder functions at the bottom of the Content Templates screen.

Placeholder Functions

Placeholders are enhanced with Functions, which format field values, change data, and show/hide conditional content.

For example, normal placeholders look like this:

{{payment.payment_date}}
{{payment.amount.currency}}
{{payment.amount.value}}

But the values don’t always look correct.

2024-12-15T12:00:00.000Z
GBP
20.00

The date is in a strange computer format, and the donation amount should be £20.00. That’s where functions come into play.

{{payment.payment_date|date:j F Y}}
{{payment.amount|money}}

By adding special ‘functions’ after the placeholder field but before the double curly brackets, you can format the data.

15th December 2024
£20.00

You can format dates, money, numbers, and choose the person’s primary email address, postal address and phone number. You can also add a date: either today or +/- days.

{{person.emails|primary_email}}

{{person.address|address:newline}}

{{today|date:j F Y}}

These values will be replaced by the primary email of the current person record. Postal addresses will be formatted for a new line (for Word Documents), or you can choose your own format (like a comma and space).

john.smith@gmail.com

123 Street
London
WC1 1AT

22nd July 2027

Conditional Functions

You can show or hide values depending on certain conditions. For example, if the person has Gift Aided their donation, you can thank them in your email or letter.

{{#if_gt payment.c_gift_aid_amount.value 0}} Thank you for Gift Aiding your donation, adding an extra 25% to the total!{{/if_gt}}

This function checks whether the Gift Aid amount value is greater than zero (#if_gt = if greater than) and, if so, shows the message before the closing {{/if_gt}} tag.

You can select a function from the list or drawer to assist you instead of writing them from scratch. Stringing placeholders and functions together can become quite powerful once you get to grips with them!

Placeholders Drawer

The placeholders drawer shows you all available placeholders for each type of Beacon record type. That could include payment data, payer/person data, Gift Aid data, etc.

The drawer will slide in on the right side of the screen when you click the Placeholders button next to a value. You will also see a list of functions and earlier action responses without having to memorise field names.

Functions format dates, money, arrays, email addresses, phone numbers and postal addresses. Conditional blocks can include or exclude whole sections when a value is present, true, equal to a value or within a numeric range.

Use Preview in an email action to merge the first sample record into the selected template before sending anything.

Previous Action Placeholders

When you chain actions together into a workflow, you can pass a created value from one action into proceeding actions.

For example, if you add a new Person record, you can get the ID of that record to use when adding a new Activity record.

{{action.1.record.id}}

These values will be available via the placeholders drawer at the top of the lists.

Find the answer

See exactly what happened

Start with the screen closest to the issue. Charity Automate keeps test activity separate from live runs so experiments do not distort production totals.

• Test Connections confirms whether Beacon, SendGrid and other configured services can respond.
• Task Runs shows progress, successful records, failures and the current state of background processing.
• Logs provides request details, provider responses and links to generated documents.
• Test Action runs one action against the first sample record.
• Test All follows the complete action chain in order and stops when an action fails.

Pause an active task while investigating unexpected behaviour. Sensitive API keys are never included in diagnostic output.

Choose your records

Copy a filter directly from Beacon

Beacon CRM enables you to filter your records to retrieve only the information that you need. For example, you can select all Person records that have a Date of Birth value.

• Open a record type, such as a Payment or Person.
• Click the filter icon at the top right (1).
• Add items to your filter groups. You can click Apply to view the results.
• Click the Code button at the bottom-left (2).
• A development panel will show. Scroll down to the bottom beneath the cURL for APIs section and click Copy to clipboard.
• The filter is now ready to be used in your tasks.

Charity Automate Tasks

1. Create a new task within Charity Automate and move towards Step 3: Beacon data
2. Paste the cURL code into the Beacon filter box
3. Click the Load Data button.
4. The app will automatically replace the API token with your encrypted API key saved in WordPress.
5. Wait for a few seconds to see the filtered data being displayed, including related records. You can edit the test records size to view more information if you wish (max 200 records).
6. Confirm the expected records before building rules and actions.

Charity Automate will use the Beacon filter when it runs the live task. Data may change after you test it, so check your filter in Beacon to compare the full results.