Zapier CLI Integration

Source code for the Zapier integration with Kontent.ai: https://zapier.com/apps/kentico-kontent/integrations.

Integrations

This integration contains 4 triggers, 4 actions, and 4 searches:

• Triggers
  • Variant workflow step change
  • Variant published status change
  • Variant created or deleted
  • Taxonomy group changed
• Actions
  • Create content item
  • Change variant workflow step
  • Update language variant
  • Delete language variant
• Searches
  • Find content item
  • Find workflow step
  • Find language
  • Find asset

Triggers

Using the Kontent.ai integration, you only need to configure the Zap in Zapier. The creation of the webhook in Kontent.ai is handled automatically by the integration; the webhook will be created when you turn on the Zap, and deleted when you turn it off.

The output of a trigger in Zapier is exactly what Kontent.ai's webhook POSTs to Zapier. It will look something like this:

{
  data: {
    items: [
      {
        item: {
          id: '42c21e82-0772-4d79-a6b3-c916e51b24ff'
        },
        language: {
          id: '00000000-0000-0000-0000-000000000000'
        }
      }
    ]
  },
  message: {
    id: 'a268da50-b3c5-4d09-9b36-6587c8dea500',
    project_id: '11a3492b-cd32-0054-51d2-8234ec4244a6',
    type: 'content_item_variant',
    operation: 'restore',
    api_name: 'content_management',
    created_timestamp: '2019-07-18T10:52:33.1059256Z',
    webhook_url: 'https://hooks.zapier.com/hooks/standard/47991d003732'
  }
}

In each trigger, you have the option to provide a language ID. If you do, the Zap will be halted at this step if the content item is not in the provided language. If you leave it empty, the Zap will proceed for all languages.

There is also another optional field called Content Type For Samples. If you choose a content type, the trigger will attempt to output a content item ID of that type. This allows you to test the Zap more efficiently, and has no effect on the functionality of the trigger.

Creating a trigger in Zapier

1. Create a new Zap: https://zapier.com/app/zaps.
2. In the Choose App & Event field, search for Kentico Kontent then choose your trigger.

3. Click Continue then Sign in to Kentico Kontent on the next screen. You can find the credentials on the API Keys page in Kontent.ai.

4. Configure the conditions for your trigger. Most triggers have multiple events that can be "listened" to, and you can select multiple options or leave the field empty for all events.

5. Click Test and Review to get a sample item from your Kontent.ai project. This allows you to configure later steps using fields from your content items.

The output of the triggers will be the payload sent from Kontent.ai, which you can read more about in webhooks reference. To find additional data about the item which triggered the webhook, you can use the Find Content Item action.

Actions

The integration contains actions to upsert/delete variants, create a content item, and change a variant's workflow step. For many of these steps, you are required to enter data in a particular format that Kontent.ai will understand, e.g. in a Linked items element.

You can find descriptions of formats that Zapier expects in fields here. As for the Kontent.ai integration, here's some examples of the data to provide action steps:

• Linked items:
  

Acceptable values are content item IDs and external IDs. These can be used in any combination- for multiple linked items, some can be item IDs and some can be external IDs. You can use the Find Content Item action if you need to locate items for this field. You can add a single value to each line, or multiple values separated by comma. For example, the output of a previous step might be an array like "external_item_1, external_item_2." You can refer to this output in the linked item field on a single line.

• Taxonomy:
  

This field accepts taxonomy IDs or codenames. Similar to linked items, you can provide one value per line or comma-separated values on a single line.

• Assets:
  

Like taxonomy fields, you can provide the asset ID or codename of an asset, and values can be added on a single line separated by commas, or multiple lines. You can use the Find Asset action to locate assets in your project.

• Dates and times

This follows the formats specified by Zapier. You can also pass a value obtained from a previous step as in the screenshot above. Some examples of acceptable datetimes are:

• 11/11/2011
• 11/11/2011 4PM CST
• next friday at 7pm
• 2019-03-27T13:10:01.791Z

Searches

Because the webhook notification from Kontent.ai only contains basic information such as a content item ID and language ID, you may need to search your project for more information. For example, to load all data about a content item you can use a Find Content Item action. You can search for an item based on the id, codename, external_id, or any of the content type's elements.

Another useful example would be to translate language or workflow step IDs into codenames. The webhook notification contains IDs, but if you need to compare a language codename ("en-US") later on in the Zap, or if you're writing values to a Google Sheet and want to add the user-friendly name, you could add a Find language step. You can search for the language via ID, and in the output you will find all the details of the language:

{
  id: '1c37a40c-9158-031d-9d2d-adf65a568cd6',
  name: 'Czech',
  codename: 'cz-CZ',
  external_id: 'lang_czech',
  is_active: true,
  is_default: false,
  fallback_language: {
    id: '00000000-0000-0000-0000-000000000000'
  }
}

Example - Google calendar

Let's say your company manages events for a client. At this point, you've been using Kontent.ai to store information about the events, but you've been manually creating the event in Google Calendar and emailing the attendees. We can now use Zapier to do this for us whenever a new event is published.

The final Zap will look something like this:

Content types in Kontent.ai

To start, we should have an Event content type with fields for basic event information, and a Linked items element which can only contain items from your Contact content type:

The Contact content type can contain whatever information you'd like, but should at least have an email element:

Create some Contact content items and publish them, then create an Event and leave it in Draft step.

Creating the Zap

To reduce the amount of manual work that needs to be done, we want Zapier to create a calendar item and send emails whenever an Event is published in Kontent.ai.

Step 1

Of course, we start with the trigger. For the Trigger event choose Variant Published Status Changed. In the configuration of the step, set the following:

Under Webhook Name you can enter any value you'd like such as "Google Calendar Event Creation" which will appear in Kontent.ai's Webhooks page, or you can leave it empty to use the default "Variant published status changed (Zapier)."

Step 2

The trigger will fire when any variant is published, but we only want to continue if it is an Event item. We can use the type value from the trigger and a Filter by Zapier action to stop the Zap if the type is not "event:"

Step 3

To get information about the event, we need to add a Find Content Item action. In this step, you can search for an item by ID, external ID or codename. Since the trigger output contains the item ID, you can load that value in the Search value field:

Step 4

To send emails to the event attendees, we will need to get the contacts stored in the attendees_list element. The value of this element will be an array of content item IDs which correspond with the items in step 3's modular_content output. So, we can use a Code by Zapier step to get the email addresses of the attendees for the next step.

If you're not familiar with the basics of code steps, please read Zapier's documentation. In the Input data field we can load some values from the content item to use in javascript:

• json: The raw JSON of the modular content from step 3.
• attendees: The value of the attendee_list element, which contains the IDs of the linked items.

In the code of the step, use JSON to parse the json variable, then use Object.values() to create an array. Filter the array so that only contacts from the attendees variable remain, then map the email addresses to a new array. Then, output the emails:

const email = Object.values(JSON.parse(inputData.json) || {})
        .filter(m => inputData.attendees.includes(m.system.id))
        .map(m => m.elements.email);

return [{emails: emails}];

Step 5

Now we can create the Google Calendar event. In Choose App & Event select Google Calendar and Create Detailed Event. On the next screen, you'll need to authorize a Google Account which has access to the calendar you wish to modify.

On the Customize Detailed Event screen, select your calendar then use data from step 3 to populate these fields:

In the event's Attendees field you can load the list of emails from step 4. Google will automatically email the attendees when the event is created.

Testing

We're pretty much done. Turn on the Zap to create the webhook in Kontent.ai. If the On/Off switch is greyed-out in Zapier, you most likely need to test one of the steps (or, choose Skip test). All steps should have a green check mark in the top-left corner.

When the Zap is turned on, you should see this in Kontent.ai:

The endpoint and secret are automatically generated by the Zapier integration and will start to work immediately. Do not change the secret! Webhook signatures are automatically validated by the integration for your security, but it relies on using this exact secret which is generated by hashing several values.

You can now test the Zap by publishing an Event content item in Kontent.ai which has some Contacts linked as attendees. After a short time, you should see the "dot" next to the webhook turn green indicating that the POST was sent to Zapier. In Zapier, you can check Task History in the right sidebar to check whether the Zap executed successfully: