Summary

Yext Functions let you write custom TypeScript functions that extend built-in Yext functionality with your own logic. Functions run within Yext, so you don't need to manage a server or runtime environment. For example, if a Data Connector transform you need isn't supported out of the box, you can write a Function to perform the transformation and invoke it whenever the Connector runs.

This article covers how to:

1. Create a Plugin
2. Apply a Plugin using the Yext CLI
3. Define global values, such as an API key, on a Plugin
4. Use Functions in Connectors and Webhooks

Prerequisites

• The Yext CLI installed and connected to your account. See Get Started with the Yext CLI.

Create a Plugin

A Plugin is a resource that contains at least one Function. Plugins are configured using Configuration as Code (CaC). To create a new Plugin, add a new Plugin CaC resource.

A Plugin is a multi-file resource. It requires at least two files:

_resource.json, which defines the Plugin's metadata:

mod.ts, defined in the same directory, where your Functions are written in TypeScript. A single mod.ts file can contain multiple Functions.

Apply a Plugin

Plugins are configured on an account using the Yext CLI. See Get Started with the Yext CLI for CLI setup steps.

For example, to create a Plugin with a Function that converts a string to uppercase, define the following files:

default/platform/plugin/_resource.json:

{
    "$id": "UppercasePlugin",
    "$schema": "https://schema.yext.com/config/platform/plugin/v1"
}

default/platform/plugin/mod.ts:

export function fn(a: string) {
    return `${a.toUpperCase()}`;
}

Then apply the resource:

yext resources apply ~/path/to/directory

Expected result

After you apply the resource, Yext creates a Plugin with the ID you provided.

Define Global Values on a Plugin

Use the globals property to make values, such as an API key, available inside your Plugin's Functions.

For example, to create a Plugin with a Function that returns an API key, define the following files:

default/platform/plugin/_resource.json:

{
    "$id": "PluginWithApiKey",
    "$schema": "https://schema.yext.com/config/platform/plugin/v1",
    "globals": {
        "API_KEY": "abcd1234"
    }
}

default/platform/plugin/mod.ts:

declare const API_KEY: string;

export function getApiKey() {
    return `${API_KEY}`;
}

Use Functions in Connectors and Webhooks

Connector transforms

Write a Function to use as a transform in a Data Connector, either on a single row or a single cell. See the Connector Transform reference for details. 

Connector sources

Invoke a Function as a data source for a Connector. See the Function Source reference for details.

Function Hooks

Function Hooks trigger a Function in response to account and profile events. Set them up from the Webhooks UI.

To create a Function Hook:

1. Click Developer Console.
2. Create an app, or open an existing app.
3. Click the Webhooks tab.
4. Click + Add a Webhook.
5. Select the webhook type.
6. Enter the webhook details.
7. Click … or invoke a function.
8. Click the Select a Function dropdown and select the Function to invoke.
9. Click Finish and Add.