Zapier

Zapier is an Integration Provider as a Service (IPaaS) that enables automated interactions between Brightspot and third-party applications. While the possibilities of this integration are up to your individual business requirements, consider the following scenarios:

• Create an equivalent Google Doc whenever an article in Brightspot is published or translated.
• Create an equivalent Brightspot asset whenever a Google Doc is added to a certain folder in Google.
• Create a Salesforce campaign whenever a newsletter in Brightspot is published.
• Log workflow transitions in Microsoft Excel.
• Use a spreadsheet to import tags into Brightspot.

Currently, Brightspot has implemented three different components of a Zapier workflow (referred to as a zap):

• Trigger—Webhooks and polling.
• Search—Finds more data.
• Action—Takes an action, like saving an asset in Brightspot.

For more information on which integrations are available to Zapier (like Google Docs, Salesforce, and Microsoft Excel), see Zapier apps.

Note

The Brightspot Zapier connector is currently a private connection. Please contact your Brightspot contact for an invitation to access.

Overview of the configuration process

Note

These topics cover the Brightspot end of configuration, as well as how you can use Brightspot in various ways as you make Zapier workflows, referred to as zaps. For details on how to use Zapier, please refer to Zapier online help.

To configure the Zapier plugin, you take the following steps:

1. Create API endpoints in Brightspot. Depending on whether you are using GraphQL, the second endpoint you create may vary (see How GraphQL relates to Zapier). For details on the configuration of these endpoints, see Adding API endpoints.

2. Create an API client in Brightspot, and link it to the previous endpoints. For details, see Adding an API client.

3. Using credentials from the API client, connect Brightspot to Zapier in the Zapier console. For details, see Connecting a Brightspot instance to a Zapier account.

4. Build triggers, search queries, and actions in Brightspot for use in Zapier zaps. Depending on whether you are using GraphQL, the objects you create may vary (see How GraphQL relates to Zapier). For details, see the following topics:

   • Creating a topic subscription
   • Creating a GraphQL polling trigger (GraphQL only)
   • Creating a GraphQL query (GraphQL only)
   • Creating a GraphQL mutation (GraphQL only)
   • Creating a general Zapier search

After these configuration steps are complete, all additional configuration happens in the Zapier console. For details on that process, please refer to Zapier online help.

Including Zapier in a build

The following table lists the dependencies to include in your build configuration.

Note

The Zapier tool uses timeseries for request analytics. Ensure that you have a timeseries implementation dependency included in your build, such as com.psddev:timeseries-mysql.

Artifact	Description
com.psddev:zapier	Exposes core Zapier functionality for configuration.
com.psddev:zapier-graphql	Enables GraphQL-powered searches, mutations, and polling triggers.
com.psddev:zapier-topic-webhook	Enables notification-based webhook triggers.

How GraphQL relates to Zapier

Brightspot uses GraphQL as one out-of-the-box implementation of the Zapier plugin. To use GraphQL with Zapier, you must include the GraphQL-related dependency listed above, and then take the following route:

1. In Brightspot, in addition to creating a Zapier API endpoint, create a GraphQL API endpoint (see Adding API endpoints).

2. Create an API client to be used by the Zapier API endpoint (see Adding an API client).

3. Create one or more of the following based on the zap you are creating:

   • Topic subscription (trigger) to initiate a zap (see Creating a topic subscription).
   • Polling trigger (trigger) to initiate a zap (see Creating a GraphQL polling trigger).
   • Query (search) to fetch more data from Brightspot (see Creating a GraphQL query).
   • Mutation (action) to take an action in Brightspot (see Creating a GraphQL mutation).

All other configuration happens in the Zapier console.

Note

If you do not want to use GraphQL, you can take the following route:

1. In addition to creating a Zapier endpoint, create a different kind of endpoint in the area described in Adding API endpoints.
2. Create an API client to be used by the Zapier endpoint (see Adding an API client).
3. Create a topic subscription to serve as the first step (the trigger) of your Zapier zap (see Creating a topic subscription).
4. Create a general Zapier search to fetch more data from Brightspot using a different query language that you define in Zapier (see Creating a general Zapier search).

Adding API endpoints

The first step of configuring the Zapier plugin is adding two API endpoints—a GraphQL endpoint and a Zapier endpoint, both of which you can add in Brightspot. Each endpoint serves a different purpose:

• The Zapier endpoint is needed to connect Brightspot to Zapier in the Zapier console.
• The GraphQL endpoint is needed to perform queries and mutations on Brightspot data for use in Zapier workflows (referred to as zaps).

To add a Zapier API endpoint:

1. Click > Admin > APIs.
2. From the Create list, select Zapier Endpoint, then click New.
3. Retain the default Name and Path.
4. Click Save.

Once created, note the full URL of the Zapier endpoint (for example: https://"your-brightspot-domain".com/api/zapier), as you will need it when connecting Brightspot to Zapier. For details, see Connecting a Brightspot environment to a Zapier account.

To add a GraphQL endpoint for the Zapier plugin:

1. From the Create list, select GraphQL Content API Endpoint, then click New.

   Note

   You can technically use any GraphQL endpoint type; these topics assume you are using a GraphQL Content API endpoint.

2. In the Name field, enter a name for the endpoint.

3. Under Schema Settings, under Read/Write Types, select the content types that you want to expose to Zapier. For example, if you want to allow Zapier to at some point in the zap create articles, select Article. Select as many content types as needed.

4. Under API Access, retain the default selection API Key Required.

5. Click Save.

Once you have added the APIs, you must create an API client. For details, see Adding an API client.

Adding an API client

After you have created the necessary API endpoints, you must create an API client. For details on creating these endpoints, see Adding API endpoints.

To create an API client:

1. Click > Admin > APIs.

2. Under Clients, click New API Client.

3. In the Name field, enter a name for the API client.

4. Under Endpoints, select the two API endpoints you created for the integration. For details, see Adding API endpoints.

5. Under Keys, click Add API Key. Brightspot automatically generates an API key.

   Caution

   Store this key in a safe place, as you will need it later in the configuration.

6. Click Save.

Once created, you will need to enter the client ID and the API key into Zapier when setting up access to Brightspot. For details, see Connecting a Brightspot environment to a Zapier account.

Creating a topic subscription

You can create topic subscriptions to notify Zapier whenever a relevant event occurs related to the subscribed topic. Once created, the subscription appears in Zapier as a webhook trigger for use as the first step of a zap.

To create a topic subscription for the Zapier plugin:

1. Click > Admin > Zapier.

2. From the Create list, select Topic Subscription, then click New.

3. Enter an internal name for this asset. Brightspot uses this name internally, such as in the search panel and recent activity widget. This name is not visible to visitors to your site.

4. In the Description field, enter a description about what this topic subscription achieves, such as Webhook trigger when an asset is translated.

5. In the Zapier Label field, enter a value that will appear when creating actions in Zapier. Use something short but descriptive of what the query achieves (for example, Article Translation Events).

6. Under Topic, select a notification topic. For an example of a topic subscription to translation events, see the note below.

   Note

   See the following example of a topic subscription to article translation events. According to this example, any time an article is translated by any service, has any translation status, and is created by anyone, Brightspot sends a trigger to Zapier.

   To create an article translation event topic notification:

   1. Under Topic, select Translation.
   2. Under Translations Filter, click Add Services & Statuses.
   3. Under Translation Service, Translation Status, and Translation Creator, retain the default values (All Services, All Statuses, and Any Creator, respectively).
   4. Under Content Filters, click Add Sites & Types.
   5. Under Sites, retain the default (All Sites).
   6. Under Types, select Article.

7. Depending on your selection, fill out additional configuration fields. For details, see Subscriptions to topics.

8. Under Sample Data, do one of the following:

   • Retain Auto Generated to have Brightspot automatically generate and send random sample data to populate the test record in Zapier.

   • Select Custom to manually populate the data in the test record in Zapier, then do the following:

     • Under the second Sample Data field, select Set, then enter values into the Content ID and Content Label fields and select a status under the Status field.

9. Click Publish.

Once published, this topic subscription appears in Zapier as a webhook trigger for use as the first step of a zap.

Note

Once published, check the Debug tab to view the associated Zapier webhook address for this topic subscription.

Note

Once published, you may view analytics pertaining to this asset in the Analytics tab. The tab includes when it was last used, its success count, the number of its total requests, and the number of errors it has generated.

Creating a GraphQL polling trigger

At times, Brightspot may not have a topic type for the scenario in which you want Brightspot to initiate a Zapier zap (for example, you have a task that creates a record in the database each time it runs, and you do not have an associated topic type for this record). In these scenarios, you can use a polling trigger to notify Zapier about the new record.

Polling triggers periodically check for updates or changes in data at specified intervals. They serve as a way for Zapier to ask Brightspot if new data of a certain type exists at a certain interval. In this case, GraphQL polling triggers require that a GraphQL query returns data in chronological order and with a unique ID so that Zapier knows that it is a new record.

Note

Brightspot recommends that you use a webhook trigger whenever possible, as they are more performant than polling triggers.

To create a GraphQL polling trigger for the Zapier plugin:

1. Click > Admin > Zapier.

2. From the Create list, select GraphQL Polling Trigger, then click New.

3. Enter an internal name for this asset. Brightspot uses this name internally, such as in the search panel and recent activity widget. This name is not visible to visitors to your site.

4. In the Description field, enter a description about what this polling trigger achieves.

5. In the Zapier Label field, enter a value that will appear when creating actions in Zapier. Use something short but descriptive of what the query achieves (for example, Publish New Article).

6. Under Endpoint, select the GraphQL API endpoint you added that you associated with the API client. For details, see Adding API endpoints.

7. Under Query, enter the desired query. Brightspot recommends using the GraphQL explorer to more easily build the query from the schema.

   Note

   To use the GraphQL explorer, you must have the developer permission HTML Toggle.

8. Under Results Path, enter the appropriate keys to flatten the response so that it is at the root level. A raw response causes the polling trigger to fail.

9. Click Publish.

Note

Once published, you may view analytics pertaining to this asset in the Analytics tab. The tab includes when it was last used, its success count, the number of its total requests, and the number of errors it has generated.

Creating a GraphQL query

At times, you may want to send more information to Zapier (like the subheadline, body, and tag fields) than would otherwise be fetched from a standard request or webhook trigger (like the ID and other basic data). In this case, you can create a GraphQL query to supply Zapier with additional data. Once published, the query is available for use in a Zapier workflow (referred to as a zap) as a search event.

To create a GraphQL query for the Zapier plugin:

1. Click > Admin > Zapier.

2. From the Create list, select GraphQL Query, then click New.

3. Enter an internal name for this asset. Brightspot uses this name internally, such as in the search panel and recent activity widget. This name is not visible to visitors to your site.

4. In the Description field, enter a description about what this query fetches.

5. In the Zapier Label field, enter a value that will appear when creating actions in Zapier. Use something short but descriptive of what the query achieves (for example, Find Article by ID).

6. Under Endpoint, select the GraphQL API endpoint you added that you associated with the API client. For details, see Adding API endpoints.

7. Under Query, enter the desired query. Brightspot recommends using the GraphQL explorer to more easily build the query from the schema. (To use the GraphQL explorer, you must have the developer permission HTML Toggle). See the example below for a simple query that returns articles by ID.

   1
   query MyQuery($articleId: UUID) {
   2
     Get {
   3
       Record(with: {_id: $articleId}) {
   4
         State {
   5
           ... on Article {
   6
             __typename
   7
             headline {
   8
               raw
   9
             }
   10
             subheadline {
   11
               raw
   12
             }
   13
             body {
   14
               raw
   15
             }
   16
           }
   17
           _globals {
   18
             Content__ObjectModification {
   19
               scheduleDate
   20
             }
   21
           }
   22
         }
   23
       }
   24
     }
   25
   }

8. Click Publish.

Once published, this query appears in Zapier as a search event for use in a zap.

Note

Once published, you may view analytics pertaining to this asset in the Analytics tab. The tab includes when it was last used, its success count, the number of its total requests, and the number of errors it has generated.

Creating a GraphQL mutation

You can create a GraphQL mutation that enables Zapier to modify Brightspot assets. For example, an editor working in a Google Doc can trigger the creation of an article in Brightspot. Once created, this mutation appears in Zapier as an action event for use in a zap.

To create a GraphQL mutation for the Zapier plugin:

1. Click > Admin > Zapier.

2. From the Create list, select GraphQL Mutation, then click New.

3. Enter an internal name for this asset. Brightspot uses this name internally, such as in the search panel and recent activity widget. This name is not visible to visitors to your site.

4. In the Description field, enter a description about what this mutation achieves, such as Publishes new article in Brightspot.

5. In the Zapier Label field, enter a value that will appear when creating actions in Zapier. Use something short but descriptive of what the query achieves (for example, Publish New Article).

6. Under Endpoint, select the GraphQL API endpoint you added that you associated with the API client. For details, see Adding API endpoints.

7. Under Mutation, enter the desired mutation. Brightspot recommends using the GraphQL explorer to more easily build the mutation from the schema. (To use the GraphQL explorer, you must have the developer permission HTML Toggle). See the example below for a simple mutation that publishes a new article.

   1
   mutation MyMutation($headline: String = "", $body: String = "") {
   2
     Save {
   3
       Record(
   4
         args: {diffs: {ArticleDiff: {headline: {html: $headline}, body: {html: $body}}}, urls: {generate: {}}}
   5
         context: {dryRun: false, site: {_name: "Demo"}}
   6
       ) {
   7
         state {
   8
           ... on Article {
   9
             __typename
   10
             _id
   11
           }
   12
         }
   13
       }
   14
     }
   15
   }

8. Click Publish.

Once published, this mutation appears in Zapier as an action event for use in a zap.

Note

Once published, you may view analytics pertaining to this asset in the Analytics tab. The tab includes when it was last used, its success count, the number of its total requests, and the number of errors it has generated.

Creating a general Zapier search

At times, you may want Zapier to query for specific data without performing an action. In these scenarios, you can create general Zapier searches. This function is similar to the GraphQL search, but does not have a dependency on GraphQL. As such, you may find it simpler to use this option.

To create a general Zapier search:

1. Click > Admin > Zapier.
2. From the Create list, select General Zapier Search, then click New.
3. In the Internal Name field, enter an internal name. Brightspot uses this name in selection fields.
4. In the Description field, enter a description about what this general Zapier search achieves.
5. In the Zapier Label field, enter a value that will appear when creating actions in Zapier. Brightspot recommends using something short but descriptive of what the query achieves (for example, Verify Content Exists).
6. Under Supported Types, select the content types that you want to expose to Zapier for the purposes of general searches.
7. Click Publish.

Note

Once published, you may view analytics pertaining to this asset in the Analytics tab. The tab includes when it was last used, its success count, the number of its total requests, and the number of errors it has generated.

Connecting a Brightspot instance to a Zapier account

After creating the API endpoints and client, and before you create triggers, search queries, and actions, you must connect your Brightspot environment in the Zapier console. For details on this process, see Zapier online help.

Note

The following procedure describes an activity in a third-party application. While Brightspot periodically validates this procedure, individual steps may change in the interim without our knowledge. If you notice an inaccuracy, please leave feedback using the widget at the bottom of this topic.

To connect a Brightspot environment to the Zapier account:

Note

The following procedure requires assistance from your Brightspot representative.

1. Log in to Zapier.

2. In the left rail, click Apps.

3. Under Other Apps, select the Brightspot connector app that you want to connect to Zapier (typically the most recent version, if more than one exists).

4. Click Add Connection.

5. Enter the following values:

   • Brightspot Zapier Endpoint—The full URL of the Zapier API endpoint you configured in Brightspot (for example, https://"your-brightspot-domain".com/api/zapier). For details, see Adding API endpoints.
   • Client ID—The ID that Brightspot generated when you added the API client. For details, see Adding an API client.
   • Client Secret—The API key that you generated when adding the API client. For details, see Adding an API client.
   • Apache Auth Username—Only required when setting up the Zapier plugin on non-production environments that have Apache Auth enabled.
   • Apache Auth Password—Only required when setting up the Zapier plugin on non-production environments that have Apache Auth enabled.

6. Click Yes, Continue to Brightspot.

When done, you can test the connection and begin creating triggers in Brightspot and building automations (called zaps) in Zapier.

For information on building triggers, search queries, and actions in Brightspot, see the following topics:

• Creating a topic subscription
• Creating a GraphQL query
• Creating a GraphQL mutation
• Creating a GraphQL polling trigger
• Creating a general Zapier search

For information on creating zaps in Zapier, see Zapier online help.