Documentation

Templated Exports

Suggest Edits

Overview

Lytics Templates combined with the Lytics Webhooks Export workflow provide a powerful mechanism by which users can create bespoke integrations with arbitrary third party destinations. Templates can be defined in Jsonnet or Handlebars, and once created, can be selected for use in a Webhooks Export, where they will be executed against the outgoing payload for each request.

Creating and Managing Templates

Templates can be created, tested, and managed using the Lytics Template APIs. Full API documentation can be found here. To create a template, simply submit a Jsonnet or Handlebars file to the /v2/template endpoint like this (see below for more information on using the lytemplates.libsonnet library in Jsonnet templates):

➜  ~ cat test.jsonnet 
local event = (import 'lytemplates.libsonnet');
local emailField = event.jobConfGet('email_field', 'email');
local userEmail = event.get(emailField);

{
        email_address: userEmail,
        email_address_sha256: event.sha256(userEmail),
        [if event.isEnter() then 'lytics_audience']: event.segSlug(),
        [if event.has('first_name') then 'first_name']: event.get('first_name'),
}

➜  ~ http POST $LIOAPI/v2/template name==test-template type==jsonnet description=="A test template for demos" Authorization:$LIOTOKEN account_id==$LIOACCTID < test.jsonnet
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 228
Content-Type: application/json
Date: Wed, 20 Sep 2023 21:10:45 GMT
Request-Id: 2a42314b-57fa-11ee-bc0f-0242ac110039
Server: lytics.io

{
    "data": {
        "created": "2023-09-20T20:38:24.579029236Z",
        "description": "A test template for demos",
        "id": "83d1439ff457ab94377e697180e8f8f1",
        "name": "test-template",
        "type": "jsonnet",
        "updated": "2023-09-20T20:38:24.579029236Z"
    },
    "request_id": "2a42314b-57fa-11ee-bc0f-0242ac110039",
    "status": 200
}

The endpoint requires name and type query parameters. An optional description can also be included.

Testing Templates

Once templates have been created, the /v2/template/:id/test endpoint makes it easy to test the template's behavior given a particular job configuration and outgoing user profile. A configuration can be included in your request, as well as a custom entity profile. If no entity is included in the request, the API will auto-generate one from your Lytics user table schema:

➜  ~ echo '{
        "job_config": {
                "email_field": "email"
        },
        "entity": {
                "email": "[email protected]",
                "first_name": "Tester",
                "segment_events": [
                        {
                                "id":"e4c8ef6712fc40d76d8202394095f3a6",
                                "slug": "test_audience",
                                "event":"enter",
                                "enter":"2017-10-15T19:12:00.661749884Z"
                        }
                ]
        }
}' | http POST $LIOAPI/v2/template/83d1439ff457ab94377e697180e8f8f1/test Authorization:$LIOTOKEN
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 222
Content-Type: application/json
Date: Wed, 20 Sep 2023 20:53:16 GMT
Request-Id: b8cd77f4-57f7-11ee-bc0f-0242ac110039
Server: lytics.io

{
    "data": "{\n   \"email_address\": \"[email protected]\",\n   \"email_address_sha256\": \"e43763399e5318f14cd7473c4902a6b319343d577ec8283898a5edf9dbc6d711\",\n   \"first_name\": \"Tester\",\n   \"lytics_audience\": \"test_audience\"\n}\n",
    "request_id": "b8cd77f4-57f7-11ee-bc0f-0242ac110039",
    "status": 200
}

Activating Templates

To activate a template, create a Webhook Export job. See the Lytics Webhooks documentation for full instructions on configuring outgoing webhooks. From the Lytics Template dropdown menu, select the template you would like to activate against each outgoing request.

The lytemplates.libsonnet Library

For convenience, Jsonnet templates can import Lytics' custom lytemplates.libsonnet library, which contains utilities for common operations on profiles in exports. To import the library, simply include the following line at the top of your template:

local event = (import 'lytemplates.libsonnet');

The following methods on event can be used to access data on the profile and job configuration:

has(field)

Reports whether the entity on the event contains a field named field.

get(field, def=null)

Retrieves the field on the profile named field. If field does not exist on the profile, the optional default will be returned, or null if default is not supplied.

jobConfGet(key, def=null)

Retrieves the job configuration field named key. If key does not exist in the job configuration, the optional default will be returned, or null if default is not supplied.

inSeg(id)

Reports whether the user is a member of the segment with ID id.

isEnter()

Reports whether the trigger event is an enter event.

isExit()

Reports whether the trigger event is an exit event.

segSlug()

Returns the segment slug for the trigger event.

sha256(obj)

Returns the sha256 hash of obj

isValidSha256(obj)

Returns whether obj matches the formatting of a sha256 hash

sha1(obj)

Returns the sha1 hash of obj

isValidSha1(obj)

Returns whether obj matches the formatting of a sha1 hash

profileFieldFromConfig(configField, default=null)

If a field call configField exists on the job configuration, retrieves the field corresponding to the field's value from the user profile. For example, if the job configuration contains { "foo": "bar" }, profileFieldFromCOnfig('foo') is equivalent to get('bar'). If 'foo' does not exist on the job configuration, the optional default will be returned, or null is default is not supplied.

validatedEnum(field, enumOptions, default)

Returns the value for field on the job config, verifying that the resulting value is contained in the enumOptions array. If the value is not contained in enumOptions, default is returned. For example, if the job configuration contains {"num": "Three" }, validatedEnum('num',['One', 'Two', 'Three'], 'Zero') will return 'Three'. If the job configuration contains { "num": "bar" }, validatedEnum('num',['One', 'Two', 'Three'], 'Zero') will return 'Zero'.

Examples

Using assert to skip events that don't have email

This simple template will only send events if email is set on the user event. If

local event = (import "lytemplates.libsonnet");

local email() =  
  local email = event.get("email", "");  
  assert email != "" : 'email must be set';  
  email;

{  
  "email": email()  
}

Updated 2 days ago