Examples

All of these examples can be run locally on your computer, but may require adjustments to run on your Agillic instance due to data model differences. For more information on running Extensions locally, please refer to the Local Environment section.

Basic extension#

This example shows how to set up the most basic Extension Step that will allow a recipient to pass through with success. It does not do any operations other than returning success.

Download the following files:

To run locally, execute the command:

Helpers#

This example shows how to use the environment, dates and random helper from an Extension Step.

Documentation for the relevant helpers here:

• environment
• logger
• dates
• random

Download the following files:

To run locally, execute the command:

Http Helper#

This example shows how to use the http helper, to make API calls to external systems from an Extension Step.

Documentation for the relevant helpers here:

• http

You should download the following files:

To run locally, execute the command:

Standard Cache Helper#

This example shows how to use the cache helper to make and use a standard cache in an Extension Step.

Documentation for the relevant helpers here:

• cache

You should download the following files:

To run locally, execute the command:

While cache logic can be run standalone, it will only persist during the execution of a single recipient. It is therefore recommended to test on staging with multiple recipients, after testing on the standalone.

Loading Cache Helper#

This example shows how to use the cache helper to make and use a loading cache in an Extension Step.

Documentation for the relevant helpers here:

• cache

You should download the following files:

To run locally, execute the command:

While cache logic can be run standalone, it will only persist during the execution of a single recipient. It is therefore recommended to test on staging with multiple recipients, after testing on the standalone.

Reading and Writing#

This example shows how to read and write to the available Agillic Data Structures in an Extension Step.

Documentation for the relevant helpers here:

• reading data
• writing data

You should download the following files:

To run locally, execute the command:

Event and Target Groups#

This example shows how to check the target groups a recipient belongs to, and how to execute an event for them in an Extension Step.

Documentation for the relevant helpers here:

• reading target groups
• executing events

You should download the following files:

To run locally, execute the command:

Secure Http Extension#

This example shows how to execute a basic Http Extension using the standalone to emulate the Secure Extension API.

http-extension-data.json emulates an Extension API call in the format:

To run locally, execute the command:

Open Http Extension#

This example shows how to execute a basic Http Extension using the standalone to emulate the Open Extension API.

http-extension-data.json emulates an Extension API call in the format:

To run locally, execute the command:

Advanced Http Extension#

This is a more advanced example using the Http Extension type in conjunction with the Secure Extension API. It updates or creates a new recipient via the secure endpoint.

You can read the documentation for the relevant helper here:

• recipientService

You should download the following files:

http-extension-data.json emulates an Extension API call in the format:

To run locally, execute the command:

Google Lead Form Guide#

One of the applicable use cases of Http Extensions and the Extension API is Google lead form extensions.

Google's Search Ad "Lead Form" is a Google offering which gathers leads via Search Ads. Using this, along with Google’s webhook lead delivery option, you can send these leads to your Agillic Instance immediately, starting a double-opt in flow.

To facilitate understanding, we have developed this example Extension API and Http Extension implementation of Google's Search Ad "Lead Form".

This example will require developer modification to match your Agillic Instance, Google Lead Form configuration, and intended communication behavior. The code has relevant comments and placeholder variables to pinpoint probable areas of interest with explanations. Each implementation of this should be fully tested for each instance it is deployed to.

Full implementation requires:

• A developer to modify this example code
• A configurator with access to your Agillic Instance
• A configurator with access to your Google Ads Account

We have written a guide for the Google Ads and Agillic responsible configurators, which can be found here: Http Extension integration with Google Lead Form.

The configurator is responsible for testing the configuration defined by the Google Lead Ad, and the setup in Agillic.

This section provides the relevant information for the developer who will modify the example.

Testing the resulting extension is the sole responsibility of the developer implementing the code for the particular Agillic instance. Development of custom code is outside of the scope of Agillic Support.

General Info#

This implementation uses the Open Extension API endpoint, as Basic or OAuth authentication is not possible on Google's side. This, the type of the extension, and the name of the extension is defined in the first lines of code:

//@id:"google-ads-webhook"
//@type:"http"
//@open:"true"

This extension can then be triggered (and utilize the provided payload) by the endpoint:

https://extensions-eu1.agillic.net/extensions/open/<customerId>/google-ads-webhook

Where customerId is a specific id provided by support, of either your staging (for testing) or production (for live) instance. This endpoint is placed in the Lead Form delivery options by the configurator. If you have implemented this example with a different name, or for a different instance, the endpoint will need to be adjusted accordingly.

There are several variables in the extension to take extra notice of:

• google_key: The value configured in the Google Form Lead, which confirms the authenticity of the payload's origin. We recommend using a basic key when testing towards staging, and replacing it with a cryptographically-secure random value for production usage. Ensure the configurator setting up the Google Form Lead has input the same value. This key approach is recommended for all usage of the Open Extension API endpoint.
• google_to_agillic_mapping: The mapping from Google's Form Lead payload variables, to your Agillic Data Fields. The Discovery API, or the configurator can assist you in assessing what fields are set up in the Form Lead, and which Agillic fields should be mapped to them.
• double_optin_event: The name of the event configured in Agillic, that begins a double opt-in campaign. The Agillic configurator should provide this name to you.

You should download the following files:

It is important to read the code and definition files , and associated comments, to ensure the appropriate changes are applied. For example, depending on what fields the Google Lead Form contains, changes to the JavaScript example, and JSON data definition file may be needed.

To run locally, execute the command:

After downloading the standalone jar you can run this code locally by running this command in terminal:

When the appropriate changes have been made to the code, you can upload it to your instance's staging media browser. Then you can coordinate testing directly from the Google Ads Form UI, as described in the configuration guide.

The recipient should be created or updated (if the email address already exists), and the double opt-in event should be executed. As the Google payload has a placeholder email, the double opt-in campaign should be verified separately.

Import Monitor#

This is an example Monitor Extension which searches the current day's import logs to:

• Filter on a list of expected file names
• Increment successful imports files as information
• Increment failed import files as errors
• Flag if an expected file has neither been imported with success or failure (Was never sent to Agillic)
• Triggered via URL, asynchronous setting on
• Sends a callback containing the reporterresults to an endpoint

Documentation for the relevant access methods here:

• reading activity data
• writing reporter data
• custom callback

You should download the following files:

To run locally, execute the command:

Monitor Extensions have fixed activity type definition, as activities are identical for all instances. So while the standalone normally requires a type definition as the first input argument in the script, you can just reference the same data file as the first and the second argument of the script, as shown above. Only the second argument will be read in as the data definition file.

Outbound Monitor#

This is an example Monitor Extension which searches the previous day's outbound communication logs to:

• Filter outbound communications with names matching a regex
• Increment sent count for each matched outbound communication
• Increment error count for each matched outbound communication
• Mark if certain important communications have been sent, and raise an error if not
• Schedule execution of the monitor at 9 and 21
• On completion, send an information & error email containing reporter results
• Be able to access the most recent scheduled results via URL

Documentation for the relevant access methods here:

• reading activity data
• writing reporter data
• custom callback

You should download the following files:

To run locally, execute the command:

Comments and feedback on these examples and guides are welcome at product.feedback@agillic.com

Reading flow context#

This example shows how to read flow context in an Extension Step.

Documentation for the relevant helpers here:

• Flow Context

You should download the following files:

To run locally, execute the command:

Age calculation#

Simple extension that stores recipients age from date of birth person data.