Certain Signal Connector: Webhooks Integration Guide

Source:

Published:

Keywords: Certain Signal Connector, Webhooks, Certain Platform

Document ID: https://platform-support.certain.com/hc/en-us/articles/42303314667543#split1

This document is a guide to using Certain Signal Connector to integrate with other applications by using Webhooks. It does not cover the "Advanced Webhooks" product. The "Advanced Webhooks" product includes everything described here. The guide also includes the use of nested JSON. Please see the separate guide to integrations using that product.

(Signal Connector also integrates with Marketo, Eloqua, and Salesforce. See separate guides.)

Certain Signal Connector for Webhooks is automatically included with Certain Platform for new customers. This guide explains how to use the integration.

If you are interested in adding this or any other Signal Connector integration to your instance of Certain, email . Include your account name. Include the Signal Connector integration(s) you are interested in.

What is Signal Connector? How does it work?

Certain Signal Connector processes data from your events in real time.

Certain Signal Connector passes event data from Certain Platform to your target third-party application.

The target third-party application can be any app with webhook integration. Slack is an example target application. Google Forms is an example target application.

This real-time integration enables sales and marketing teams to take intelligent action on the right event data.

Signal Connector processes information at the account level.

Signal Connector processes information from events in your account.

Event-level information is based on custom tags you attach to data. Registration statuses are an example of tagged data. This guide explains tags in the guide.

Important: Signal Connector processes outbound information.

Signal Connector processes information from Certain. Signal Connector sends information to your target application.

Prerequisites

Data-Flow Considerations

You capture data in registration questions that will be synced to the third-party app to which you are integrating.

You need to apply tags to those registration questions.

You have different data mappings based on registration status or attendee type.

You need to apply tags to those items.

Credentials in Target Application

To set up a Connection in Signal Connector, the administrator of your target third-party application needs to provide information described under "Adding a Connection" in the guide.

If your chosen Authentication Method is OAuth2, then your administrator creates an OAuth2 app in that system.

Your administrator provides the following OAuth2 values: Endpoint, Client Id, and Client Secret.

Overview of Setup Steps

On Certain Platform

| Step | See Page | |---|---| | 1. Add tags in the account | 3 | | 2. Apply those tags | 3 & 4 |

In Certain Signal Connector

| Step | See Page | |---|---| | 3. Add a Connection | 6 | | 4. Configure a Flow | 8 |

Setting up Tags

What Are Tags?

Tags are a way of identifying event-level data using labels you set at the account level.

You apply those tags to generic items in events.

Tags especially apply to custom registration statuses and custom registration properties for use in Certain Signal Connector.

(Tags can be used for other purposes as well. This guide does not cover other purposes.)

Your events may have several custom registration statuses in addition to standard ones.

You can apply the same Tags to more than one status.

You can give each status its own Tag.

When you set up a Flow in Certain Signal Connector to send data when an attendee's Registration Status changes, the Flow uses the tags applicable to those statuses.

The Flow does not use the statuses themselves.

This setup means the flow can apply to any event in your account.

Setting Tags Up for an Account

1. As an Administrator, go to Account Settings > Management > Tags.

2. Enter a Name and a Label for the tag.

3. Select the Object(s) to which the tag can apply. For example, "Registration Statuses" and/or "Custom Registration Properties".

4. Click Add.

5. Repeat as required for as many tags as you need.

6. Important: Add enough tags to apply to all of the following that you will use in flows:

7. Add enough tags to apply to all of the following that you will use in filters for flows:

Applying Tags in an Account

In each event from which you want information to flow through Certain Signal Connector, apply tags to the relevant information.

The relevant information includes Registration Statuses and Registration Custom Properties.

You can also tag Attendee Types and Events. You can use those tags to filter registration records.

Default tagging covers:

Default Registration Statuses

Default Registration Statuses apply to all events.

An Administrator applies the tags at the account level.

1. Go to Account Settings > Management > Registration Statuses. 2. Select one or more Tags for each status.

Important: Even if you do not use any standard registration statuses, best practice is to set up tags for all of them.

At least the New status must be tagged.

Certain uses the New status "behind the scenes" when it first processes each registration.

If you do use standard reg statuses, you tag all of them.

You tag standard reg statuses so that Signal Connector flows can use them.

Applying Tags in an Event

Custom Registration Statuses

If any of the Flows you configure in Signal Connector will watch or activate for Custom Reg Statuses, then configure tags for custom statuses in each event.

1. In each event, go to Plan > Event Setup > Custom Statuses. 2. Select at least one tag for each status.

Custom Registration Properties

If any of the Flows you configure in Signal Connector will watch or activate for Custom Reg Properties, then configure tags for custom registration properties in each event.

1. In each event, go to Plan > Configure. 2. Under Custom Registration Properties, select at least one tag for each custom reg property in the event.

Standard Registration Properties (Automatic)

These tags are set up for you automatically.

The tag names are identical to the properties themselves: Complete, Badge Printed, On To Do List, Invoice Generated, and Test.

You only see these tags in Signal Connector.

Signal Connector lets you activate flows for these tags.

Certain Platform does not include any editing steps for these tags.

Attendee Types

Attendee Types are optional. You use them with filters.

1. In each event, go to Plan > Event Setup > Attendee Types. 2. Select one or more Tags for each attendee type.

You may filter registrations using those tags.

Events

Events are optional. You use them with filters.

1. In each event you may wish to include in a filter. 2. Go to Plan > Event Setup > Details. 3. Select one or more Tags for the event.

Registration Questions

Registration Questions are optional.

You use them for mapping Certain fields to fields in your target application.

1. In each event where you use registration questions to capture data from attendees, and you wish to pass those answers to your target application: 2. Go to Plan > Event Setup > Questions. 3. Select just one Tag for each question.

Selecting more than one tag could result in duplicate data in your target application.

Opening Certain Signal Connector

When Signal Connector is activated for your account, the Account Settings > Implementation menu includes an extra option.

The menu option is available to Administrators.

The option is:

Click Signal Connector Real-Time Data Integration to open Certain Signal Connector in a separate window.

Signal Connector runs separately from Certain Platform.

Note: To return from Signal Connector to Certain Platform at any time, click the exit icon.

Setting up a Connection

What are Connections?

A Connection in Certain Signal Connector specifies how to connect to your target application.

You can have multiple connections, including to other third-party applications.

Marketo, Eloqua, and Salesforce connections are covered in separate guides.

Each Flow requires a Connection.

Multiple flows may use the same Connection.

You can set up a Connection before configuring your first Flow.

You can also set up a Connection while configuring a Flow.

This guide assumes you set up the Connection first.

Adding a Connection

As an Administrator, you may set up one or more Connections for your account.

You need to set up Connections only once.

After setup, you use Connections in the Flows you set up.

1. Go to Account Settings > Implementation > Signal Connector Real-Time Data Integration. 2. Certain Signal Connector opens in a separate window. 3. Click Connections in the left navigation panel. 4. Click Add A Connection in the Connection List page that opens. 5. Enter the details in the Connection Setup screen that opens.

| Basic Authentication | Open / No Auth | API Key / Token | OAuth2 | |---|---|---|---| | URL | URL | API Key / Token | Grant Type | | Content Type | Content Type | | Client ID | | Request Method | Request Method | | Client Secret | | User Name | | | Authorization URL | | Password | | | Access Token URL | | | | | Refresh Token URL | | | | | Scope | | | | | Test Connection URL | | | | | |

Basic Authentication

Open / No Auth

The lowest level of security.

API Key / Token

OAuth2

All values must be provided by the administrator of your target application.

1. Click Save & Test. 2. If the test is successful, click Close. 3. If the test is not successful, check that the values in step 5 are all correct.

Setting Up Flows

What is a "Flow"?

A flow is a configuration to manage the flow of data from Certain to your target application.

You create Flows from the landing page in Signal Connector.

The landing page includes "Configuring a Flow".

You may configure several flows for an account.

Several flows might all use the same Connection.

You only need to configure a flow once at the account level.

When a flow is complete, the flow starts picking up data for each event in that account within about a minute.

The minute delay occurs because Signal Connector runs independently from Certain Platform.

If you edit a flow, then the same slight delay occurs before the flow changes take effect in the processing of the registrations.

The Flow List

As an Administrator in Certain Platform, go to Account Settings > Implementation > Signal Connector Real-Time Data Integration.

Certain Signal Connector opens in a separate browser window.

The main screen in Signal Connector is the Flow List.

The Flow List lists all flows.

The Status column shows whether a flow is completely set up.

The Active column shows whether a flow is running.

Click the toggle button to change a flow from Active to Inactive, or vice versa.

Configuring a Flow

Click ADD A FLOW to start setting up a new flow.

The configuration consists of:

"Live" or "Test"

The Live toggle switch determines whether your Flow is Live or Test.

A Live Flow picks up all live registrations in live events.

A Live Flow ignores test registrations, even in live events.

A Test Flow picks up all test registrations.

A Test Flow includes all registrations in test events.

A Test Flow also includes registrations marked as "Test" in live events.

Best Practice: Set a new flow up as Test.

Then test the flow.

Then set the flow to Live.

Flow Data Source

Next, specify the Source of data for the flow.

Optionally apply Filters.

The Source of a Flow is what the Flow will watch for in your data in Certain.

The Source also determines when the Flow activates.

A Flow example watches for any change to a Registration Status.

The Flow activates when an attendee's status changes to a status tagged as "Registered".

Available sources

You set a flow to watch for one of the following sources:

Note: You can save an incomplete Flow and complete it later.

A completed Flow starts picking up data after the usual minute's delay.

Activate for …

Choose what the flow should activate for by selecting one or more tags in each appropriate object's dropdown list.

You can activate for tags applied to Registration Statuses and/or Registration Properties.

Other options may be added depending on what the Flow is watching for:

The tags available for selection are those set up for that object. See page 3.

For example, Registration Statuses tags include Registration Status tags.

Registration Status tags you can apply include:

Flow Filters

You can filter data going into a flow by selecting fields in any of these three filter types:

The flow only includes a registration if the registration meets the rule(s) specified in the filter.

Note: For custom fields, you can only select "enumerated" questions.

"Enumerated" questions have pre-configured answers.

Examples include questions of types Select, Multi-select, Checkbox, or Radio.

Flow Destination

Select Webhooks from the integrations set up by Certain for your account.

You may have this option and other options.

Setting up a Destination

1. Give the Destination a Name of your choice. 2. Select the Connection to use. 3. Select Webhook as the Action for this connection. 4. Select or add the mappings to use.

Note: You can instead click New Connection to add a connection.

The process to set one up matches the process described on page 5.

Mappings

Select or set up a set of mappings.

You can have two mappings:

The setup process is the same for each mapping type.

A mapping specifies how each target field in your third-party application matches a source field in Certain.

Select a mapping from the drop-down list.

If there are no existing mappings or if existing mappings do not meet your needs, click New Mapping.

1. Give the mapping a name of your choice. 2. Obtain a sample JSON from the source. 3. For each target field you identify in that JSON, such as FirstName in the example, configure mapping steps.

The guide includes an example sample JSON.

``auto { "FirstName": "Joe", "Surname": "Citizen", "Email": "jcitizen@example.com", "RegCode": "123-456789-4321", "EventName": "Summer Product Launch", "Status": "Registered" } 

4. Enter the name of that target field and click **Add**.
5. Click to select the "source" field in Certain that matches that target field.

In the example, the target field in your target application is "First Name".

You select the source field `FirstName` in Certain.

The value of the Certain field populates the "First Name" field in your target application.

The Certain fields you can choose from as the source of the data going into each target field include some of the following, depending on what your flow will activate for.

- Profile Standard Fields
- Profile Custom Fields
- Registration Standard Fields
- Registration Custom Question Tags — one field for the question, and one for its answer.
- Registration Standard Properties
- Account Standard Fields (Account Code)
- Event Standard Fields (for example, Event Code and Event Name)
- Event Custom Fields
- Flow Fields (Flow Name)
- Macros (for example, Current Date)

You can concatenate multiple source fields for the same target field.

You can also type fixed text.

For example, for target field "Title", you can choose source fields "Position" and "Organization", separated by two spaces and "@":
auto Title = Position + " @" + Organization `` To make a target field a required field, select the checkbox next to it.

If a required field is missing, there is a validation error when the flow tries to update the target application.

This validation error is not normally fixable.

The guide states that this scenario would not go into the Retry Queue.

To delete a source field, click the x after its label.

In the second column, you can select a transformation option for each field.

The default of no selection means the data is sent to the target application unchanged.

The options are:

You can select more than one transformation for a field.

For example, you can change it to Proper Case and trim it.

Note: You can select more than one transformation for a field.

5. Continue adding more target/source field pairs as necessary.

6. If you have selected a mapping, two other buttons are enabled:

7. Save the mapping.

Metrics Dashboard

To see the statistics available in Signal Connector, click Metrics in the left navigation panel when looking at flows.

The new navigation panel shows Metrics choices.

The first Metrics choice will be Insights.

Other links may include, for example, Webhook Posts.

Other links work in the same way as Account Insights.

Account Insights

Select whether you want to see Live Flows or Test Flows.

Select the period for which you want to see data.

Examples include the last 15 minutes, 1 hour, 4 hours, or a number of days.

There are three tabs:

Summary tab

This is the default tab on the Insights page.

The figures depend on the flows and actions.

You can click a number to drill down further.

Example drill-down includes clicking Unique Registrations to see the registrations processed by flows in the selected time frame.

You can filter or search for records after drilling down.

Example filter includes filtering on an Event Code to see only the registrations in that event.

The figures shown are for the whole account:

The account may include flows that are not Webhooks integrations.

This guide includes a statement that some figures shown may not be applicable to webhooks.

For each figure, you can click the number to drill down to details.

Changes Processed increments each time a registration is created or updated in Certain.

Signal Connector processes the registration by a flow.

Note: This will often include the same registration more than once.

Example includes creating a registration and then updating it twice.

This example totals three "changes".

Unique Registrations counts any single registration only once.

Unique Registrations may be the most relevant figure on the page.

Unique Registrations is likely to be lower than Changes Processed.

Example includes Joe Citizen's registration processed three times.

Changes Processed increases by 3.

Unique Registrations increases by only 1.

If the account has one flow with one action, Actions Triggered could match Changes Processed.

More flows and more actions configured in those flows increase the number of actions that may be triggered.

An example cause includes a registration having an untagged status.

Active Flows is not related to whether the flow appears as "Active" or "Inactive" on the Flow List.

Drilling down into the failures provides a high-level troubleshooting view.

The view can show why an action failed.

If the reason can be addressed, you can expedite the fix.

You do this by going back to Flows and clicking Retry in the left navigation panel.

This Retry Queue step is described on page 17.

Troubleshooting tab

The second tab on the Insights page shows information for troubleshooting.

Example includes registrations not processed because a Registration Status is not tagged.

This setup gives a chance to rectify tagging.

Rectifying tagging lets registrations be processed on the next retry.

Numbers in this tab are as follows.

Click a number to drill down to see details of the actual records.

Maximum automatic retries per action equals 3.

If an action was retried twice, that would add 2 to this number.

Example includes a lead that could not be created because a mandatory target field had no value in the source field.

This example references "Mappings" on page 11.

Categories include "General", "System", "Config", "Connection", and more.

Activity Feed tab

The third tab on the Insights page lists registrations processed.

The listing notes success or failure.

The listing also notes Registration Code, Event, Flow, and other details.

This is a rolling history by date.

This is another way to access lower-level data accessible by drilling down in Summary or Troubleshooting tabs.

The Retry Queue

When an action fails, the action usually joins the "Retry Queue".

The action takes its turn to run again.

Failures that cannot be resolved join exceptions.

Missing mandatory fields are an example of failures that cannot be resolved.

These failures do not join the queue.

An action can be retried up to three times.

After three retries, the action does not rejoin the queue.

To see the Retry Queue, click Retry in the left navigation panel on the Flows page.

Causes of failure include planner-controlled causes.

Planner-controlled causes include a registration with a status that has not been tagged.

Causes also include technical causes.

Technical causes include a connection being down.

Where you can resolve the cause of a failure, you resolve that cause.

Examples include tagging a registration or setting a flow back to being active.

After resolving the cause, the action should succeed when retried.

For other failures that do not resolve themselves, contact your administrator or ask Certain for help.

The interval between retries depends on severity of the reason.

The guide states that more serious reasons retry sooner.

Filtering the Queue

You can filter records shown in the Retry Queue using three filters:

Submitting to the Queue

When you click an item in the Retry Queue, you see full details.

If that knowledge is enough to solve the problem, click Submit to Retry Queue.

Submitting to Retry Queue adds the item straight to the front of the queue.

Replaying a Flow

If you change an aspect of a flow while it has been running, you may want to replay that flow for the same registrations as before.

Examples include changing flow filters.

This replay acts as if the changes had been made earlier.

This replay is not something you can do directly.

You can ask Certain to arrange it for you.

You may specify a date range.

You may also specify an event.

© 2019 Certain, Inc. | Certain Signal Connector for Webhooks