Signal Integration with Advanced Webhooks Guide

This document is a guide to using Certain Signal to integrate with other applications by using Advanced Webhooks. This guide includes the use of nested JSON and everything available in the standard ‘Webhooks’ integration module.

If Certain Platform uses the standard module, see the separate guide for integrations using standard webhooks.

Certain Signal also integrates with Marketo, Eloqua, and Salesforce. See the separate guides for those integrations.

Certain Signal for Advanced Webhooks is not included with Certain Platform by default.

Contents

What is Signal? How does it work?

Certain Signal processes data from events in real time.

Certain Signal passes processed data from Certain Platform to a target third-party application.

A target third-party application can be any app with webhook integration, such as Slack or Google Forms.

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

Almost everything in Certain Signal is set up at the account level.

Certain Signal processes information from events in the account.

Event-level information depends on custom tags attached to data such as Registration Statuses, as explained in this guide.

Important: Certain Signal processes outbound information by processing information from Certain. Certain Signal sends that processed information to the target application.

Prerequisites

Data-Flow Considerations

Data-Flow Considerations determine whether Certain Signal can send the required information to the target third-party application.

Data-Flow Considerations include the following questions.

• Do registration questions capture data that will be synced to the third-party app used for the integration?
• If registration questions capture data, apply tags to those questions.
• Data-Flow Considerations include applying tags when registration status or attendee type requires different data mappings.
• If registration status or attendee type requires different data mappings, apply tags to those items.

Credentials in Target Application

Signal Connections require target application administrator-provided information.

The target third-party application administrator provides the information described under ‘Adding a Connection’.

For example, if the chosen Authentication Method is OAuth2, the target administrator must create an OAuth2 app in that system.

The OAuth2 app configuration requires the Endpoint, Client Id, and Client Secret.

Overview of Setup Steps

Setup steps appear in two parts: steps on Certain Platform and steps in Certain Signal.

On Certain Platform

1. Add tags in the account. 2. Apply those tags.

In Certain Signal

3. Add a Connection. 4. Configure a Flow.

Setting up Tags

What Are Tags?

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

Certain Signal uses tags to apply those tags to generic items in events.

Certain Signal uses tags for custom registration statuses and custom registration properties for use in Certain Signal.

This guide notes that tags can be used for other purposes. This guide does not cover other purposes.

For example, events may include several custom registration statuses in addition to standard ones.

A flow can apply the same Tags to more than one status.

A flow setup can also give each status its own Tag.

When Certain Signal sets up a Flow to send data to the target application when an attendee’s Registration Status changes, the flow uses tags applicable to those statuses.

The flow does not use statuses themselves.

This tag-based setup means the flow can apply to any event in the 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.

4. Click Add.

5. Repeat as required for as many tags as needed.

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

• Registration Statuses
• Custom Registration Properties

7. Also add enough tags to apply to all of the following that will be used in filters for flows.

• Attendee Types
• Events

Applying Tags in an Account

In each event, apply tags to relevant information that should flow through Certain Signal.

Relevant information includes Registration Statuses and Registration Custom Properties.

The events tagging process can also include tagging Attendee Types and Events to filter registration records by attendee type or event. See Filters.

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 standard registration statuses are not used, best practice is to set up tags for all standard registration statuses. It is essential to tag at least the ‘ New ’ status.

‘New’ is required because Certain uses it “behind the scenes” when first processing each registration.

If standard reg statuses are used, tag them all.

Tagged standard reg statuses are required for use in Flows configured in Signal. See ‘Configuring a Flow’.

Applying Tags in an Event

Custom Registration Statuses

Custom Registration Statuses apply to Flows that watch or activate for Custom Reg Statuses.

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

Custom Registration Properties

Custom Registration Properties apply to Flows that watch or activate for Custom Reg Properties.

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)

Standard Registration Properties (Automatic) include the following tags.

• Complete
• Badge Printed
• On To Do List
• Invoice Generated
• Test

These tags are set up automatically with names identical to the properties themselves.

These tags appear in Signal.

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

Attendee Types

Attendee Types are optional for use with filters. See ‘Flow Filters’.

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

Events

Events are optional for use with filters. See ‘Flow Filters’.

1. In each event, include the event in a filter when only registrations for that event should be passed to the target application. 2. Go to Plan > Event Setup > Details. 3. Select one or more Tags for the event.

Registration Questions

Registration Questions are optional for use with mapping Certain fields to fields in the target application. See ‘Mappings’.

1. In each event, use registration questions to capture data from attendees when that data should be passed to the target application. 2. Go to Plan > Event Setup > Questions. 3. Select just one Tag for each question. Selecting more can result in duplicate data in the target application.

Opening Certain Signal

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

The extra option is • Signal Real-Time Data Integration.

Click that link to open Certain Signal in a separate window.

Certain Signal runs separately from Certain Platform.

Note: To return from Signal to Certain Platform at any time, click the provided control.

Setting up a Connection

What are Connections?

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

An account can include multiple connections, including connections to other third-party applications.

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

Each Flow requires a Connection.

Multiple flows may use the same Connection.

A Connection can be set up before configuring the first Flow.

A Connection can also be set up while configuring a Flow.

This guide assumes the Connection is set up first.

Adding a Connection

1. As an Administrator, go to Account Settings > Implementation > Signal Real-Time Data Integration. 2. Certain Signal 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 details in the Connection Setup screen that opens.

Connection Setup fields

• Target: Use the pre-selected value – Advanced Webhook.
• Connection Name: Enter a name.
• Authentication Type: Select the authentication type to be used from available options.

The authentication type selection determines other fields displayed.

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

Basic Authentication

• • URL: The endpoint to which Signal must send data.
• • Content Type: Select one of the two options.
• application/json
• x-www-form-urlencoded
• • Request Method: Select ‘POST’ or (if appropriate) ‘GET’.
• • User Name: A user in the target system must have the necessary minimum permissions if any are required.
• • Password: That user’s password.

Open / No Auth

Open / No Auth is described as the lowest level of security.

• Open / No Auth is as for Basic Authentication but without a User Name or Password.

API Key / Token

• • API Key / Token: Provided by the administrator of the target application.

OAuth2

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

• • Grant Type: Select ‘Client Credentials’ or ‘Authorization Code’
• • Client Id and Client Secret: Unique to the OAuth2 app created by the administrator.
• • Authorization URL
• • Access Token URL
• • Refresh Token URL
• • Scope: Depending on the target app, requirements, and security policies, Scope might be blank, a keyword, or a URL.
• • Test Connection URL

• Is this a primary connection – Leave clear.
• This check box appears for all connections.
• This checkbox is only relevant to Eloqua, Marketo and Salesforce integrations requiring backwards compatibility.

6. Click Save & Test. 7. If the test is successful, click Close. 8. If the test is not successful, check that 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 the target application.

Flows are created from the landing page in Signal. See ‘Configuring a Flow’ below.

Multiple flows can be configured for an account.

Multiple flows might all use the same Connection.

A flow only needs configuration once at the account level.

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

The minute delay exists because Signal runs independently from Certain Platform.

Editing a flow causes the same slight delay before changes take effect in the processing of registrations.

The Flow List

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

Certain Signal opens in a separate browser window.

The main screen in Signal is the Flow List.

The Flow List includes 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:

• Name
• ‘Live’ or ‘Test‘ status. See immediately below.
• Source: What information the Flow will look for, and what it will activate for in events.
• Filters: Optional filters to narrow down that information.
• Destination: Where and how that information goes into the target application.

‘Live’ or ‘Test’

The Live toggle switch determines whether the 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 registrations in test events.

A Test Flow includes any registrations marked as ‘Test’ in live events.

Flow Data Source

Specify the Source of data for the flow, optionally applying Filters.

The Source of a Flow determines what the Flow will watch for in Certain.

The Source also determines when the Flow activates based on that data.

For example, the Flow might watch for a change to a Registration Status.

The Flow might activate when an attendee’s status changes to a status tagged as ‘Registered’.

Available sources

A flow can watch for one of the following:

• Registration Create Update: When a registration is created or updated.
• Registration Status Change: When a registration’s status changes.
• Session Registration Status Change: When a registration’s session registration status changes.
• Event Create Update: When an event is created or updated.

After a Flow becomes complete, the Flow starts picking up data after the usual minute’s delay.

Activate for …

Choose what the flow activates for by selecting one or more tags in each appropriate object’s dropdown list.

Tags for activation come from objects selected based on what the Flow watches.

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

Other activation options can depend on the Flow watching type.

• If the Flow watches for Registration Status Change, the flow must activate for Registration Statuses.
• If the Flow watches for Session Registration Status Change, the flow must activate for Session Registration Statuses.
• If the Flow watches for Event Create Update, the flow must activate for Event Statuses.

The tags available for selection are the tags set up for the object.

For example, Registration Statuses include Registration Status tags, which can be applied to:

• standard registration statuses at account level
• custom registration statuses at event level

Flow Filters

Flow Filters narrow down the data going into a flow.

Flow Filters work by selecting fields in these three filter types:

• Event fields
• Profile fields
• Attendee Type tags

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

Event

Available fields include:

• standard event fields (e.g., Event Code)
• custom event fields
• event tags

Profile

Available fields include:

• standard profile fields (e.g., Position)
• custom profile fields

Attendee Type Tags

Available fields include:

• tags that can be applied to Attendee Types

Enumerated questions are questions with pre-configured answers.

Pre-configured answer types include:

• Select
• Multi-select
• Checkbox
• Radio

Flow Destination

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

A flow destination selection can also include other integrations.

Setting up a Destination

1. Give the Destination a Name of choice. 2. Select the Connection to use. 3. Note: New Connection can be clicked to add a connection. 4. Select Advanced Webhook as the Action for this connection. 5. Select or add mappings to use, as described next.

Mappings

Select or set up a set of mappings.

Two mappings can exist.

One mapping is for the Payload.

One mapping is for the Http Header if required.

The setup process is the same for each mapping.

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

Select a mapping from the drop-down list.

If no mappings exist yet, click New Mapping to add a mapping.

Clicking New Mapping opens the Mapping Setup screen.

Mapping Setup steps

1. Mapping Name: Give the mapping a name.

• Best Practice: For multiple mappings, use self-explanatory names for different flows.
• For example, ‘Lead Mapping’ and ‘Form Mapping’.

2. Select Root Element Type: In most cases, leave this set to default value, Object.

• Select Array of Objects only if the JSON payload begins with a square bracket: [

3. Hint: Obtain a sample JSON from the source.

• Paste that JSON into the text box.
• Signal parses the structure needed to support the JSON.
• Signal determines the source fields needed and saves typing those fields manually.
• If entering manually is preferred, click ‘Let me set them up myself’ and proceed.
• Caution: Manual setup requires comfort with JSON syntax.
• JSON syntax reference: https://www.w3schools.com/js/js_json_syntax.asp

4. ‘Parsed Structure’ Option

• Continue when using the paste-in-sample-JSON route.
• Otherwise skip ahead to step 10.

5. Obtain a sample JSON payload from the target application.

• This includes target fields that will map to Certain fields in step 10.c.

6. Paste the JSON into the Sample JSON from Destination text box.

7. Click Parse JSON.

8. Signal determines target fields and displays them as if entered manually.

9. Proceed to step 10.c to map target fields to source fields in Certain Platform.

10. ‘Manual Setup’ Option (and mapping parsed fields)

• For each of the target fields in the target application:
• If Signal parsing is used per steps 3 to 9, skip the next step.
• Proceed to step 10.c since the target field list is prepopulated.

10.b. If Signal parsing is not used and ‘Let me set them up myself’ was clicked in step 3:

• Enter the name of the target field and click Add.
• Select the data type for that field in the adjacent drop-down list of JSON data types:
• String
• Number
• Boolean
• Object
• Array of Strings
• Array of Numbers
• Array of Objects
• Array of Booleans
• Caution: The type must map the type of data in the JSON payload.
• Click to select the “source” field in Certain that matches the target field.
• For example, if the target field is ‘Title’, the source field might be ‘Position’.
• Selectable Certain source fields depend on the flow activation:
• 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 and Tags
• Array/List supported fields (e.g., Registration Question List > Question Name, Registration Question List > Question Code, and Registration Question List > Question Answer)
• Account Standard Fields (Account Code)
• Event Standard Fields (e.g., Event Code and Event Name)
• Event Custom Fields
• Array/List supported fields (e.g., Event Question List > Question Name, Event Question List > Question Code, and Event Question List > Question Answer)
• Flow Fields (Flow Name)
• Macros (e.g., Current Date)
• Note: Unlike a standard Webhooks integration, an Advanced Webhooks integration can include arrays.
• Note: Certain source fields can include lists such as Registration Question List.
• Note: Multiple source fields can be concatenated for the same target field.
• Note: Fixed text can be typed.
• Example: for target field ‘Title’, use source fields ‘Position’ and ‘Organization’.
• Separate those source fields by two spaces and “@”.
• Mark a target field as required by selecting the checkbox next to it.
• If a required field is missing, a validation error occurs when the flow tries to update the target application.
• Validation errors are not normally fixable.
• Validation errors do not go into the Retry Queue.
• Delete a source field by clicking the x after its label.

11. Select transformation options in the second column for each field.

• The default of no selection sends data unchanged.
• Options are:
• lower case
• Proper Case
• UPPER CASE
• Trim (removes extra spaces)
• Note: Multiple transformations can apply to one field.
• Example: Proper Case and Trim.

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

13. If a mapping is selected, two buttons become enabled:

• Edit Mapping
• Preview Mapping

14. Click Save the mapping.

Example Mapping from Pasted JSON

If the ‘Parsed Structure’ option in Step 4 is selected, the next three pages illustrate three steps:

1. An example JSON that Signal parses. 2. A screenshot showing how Signal parsed that JSON. 3. A screenshot showing those source fields mapped to target in Certain.

The screenshot below shows how Signal parses this JSON.

Parsed JSON.

The screenshot below shows how Signal might map these fields.

Parsed JSON with each target field mapped to a source field in Certain.

Metrics Dashboard

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

Metrics choices depend on the flows and their targets.

The first metrics choice is Insights.

Other links may include, for example, Webhook Posts.

Webhook Posts use the same approach as Account Insights.

Account Insights

Account Insights includes selecting whether to view Live Flows or Test Flows.

Account Insights includes selecting the period for which data appears.

Examples include:

• the last 15 minutes
• 1 hour
• 4 hours
• or a number of days

Account Insights includes three tabs:

• Summary
• Troubleshooting
• Activity Feed

Summary tab

The Summary tab is the default tab on the Insights page.

Figures in the Summary tab depend on flows and actions.

Some figures can be clicked to drill down further.

For example, click Unique Registrations to see the registrations processed by flows in the selected time frame.

The Summary tab includes filtering after drilling down.

For example, filter on an Event Code to see only registrations in that event.

Summary figures represent the whole account.

Summary figures cover all events and registrations.

Summary figures cover all flows in the account.

Some figures may not be applicable to webhooks integrations.

Each number can be clicked to drill down for details.

• Changes Processed: number of registrations processed.
• Changes Processed increments each time a registration is created or updated in Certain and processed by a flow in Signal.
• Note: Changes Processed can include the same registration more than once.
• Example: creating a registration and updating it twice totals three “changes”.
• Unique Registrations: number of registrations processed.
• Unique Registrations counts each single registration only once.
• Unique Registrations can be the most relevant figure.
• Unique Registrations is likely lower than Changes Processed.
• Example: if Joe Citizen’s registration was processed 3 times, Changes Processed increases by 3.
• Since those changes refer to the same registration, Unique Registrations increases by only 1.
• Actions Triggered: number of actions triggered by flows.
• If one flow has one action, Actions Triggered can match Changes Processed.
• The number of flows and actions configured affects Actions Triggered.
• Actions Not Triggered: only displays if registrations were processed by flows without actions being triggered.
• A cause can include an untagged status.
• Active Flows: number of flows processing registrations during the selected period.
• Active Flows does not relate to whether the flow appears as “Active” or “Inactive” on the Flow List.
• Leads Created: number of leads created in the target application by flows.
• Leads Updated: number of leads updated in the target application by flows.
• Registration Activity in Certain: overview information.
• Processing Status: pie chart comparing failures and successes.
• Drilling down into failures provides high-level troubleshooting.
• Example: drill down can show why an action failed.
• After addressing a fix, expedite by going back to Flows and clicking Retry in the left navigation panel.

Troubleshooting tab

The Troubleshooting tab provides information useful for troubleshooting.

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

Tagging can allow registrations to be processed on the next retry.

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

• In Retry Queue: if an action fails, the action joins the Retry Queue and is tried again.
• Maximum automatic retries per action is 3.
• Total Retried: the number of retries.
• Example: if an action retried twice, Total Retried increases by 2.
• Retried Abandoned: actions that failed three retries.
• Validation Errors: no retries are possible due to failed validation.
• Example: a lead cannot be created because a mandatory target field has no value in the source field.
• See ‘Mappings’.
• Retry Activity: chart showing retries by time.
• Retry Processing Category: chart showing retries by category.
• Categories include “General”, “System”, “Config”, “Connection”, etc.
• Connection Activity: chart showing activity per connection over time.

Activity Feed tab

The Activity Feed tab on the Insights page lists registrations processed.

Each entry notes success or failure.

The Activity Feed includes Registration Code, Event, Flow, etc.

Activity Feed is a rolling history by date.

Activity Feed provides access to lower-level data that can also be accessed by drilling down in Summary or Troubleshooting tabs.

The Retry Queue

When an action fails, the action usually joins the “Retry Queue”.

The Retry Queue reruns actions again.

Failures that cannot be resolved, such as missing mandatory fields, 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:

• issues under a planner’s control, such as a registration with a status that has not been tagged
• technical issues, such as a connection being down

Resolving the cause can include:

• tagging a registration
• setting a flow back to being active

After resolving the cause, retry actions should succeed.

Other failures may require contacting an administrator or asking Certain for help.

The interval between retries depends on severity.

More serious reasons trigger retries sooner.

Filtering the Queue

The Retry Queue can be filtered using these three filters:

• Integration: probably only ‘Webhooks’ or ‘Advanced Webhooks’ unless multiple integrations are set up.
• Status: ‘All Statuses’, ‘Retry’, ‘Error’, ‘Failed’, or ‘Done’.
• Category: ‘All Categories’, ‘General’, ‘System’, ‘Config’, ‘Certain API’, ‘Connection’, etc.

Submitting to the Queue

Click an item in the Retry Queue to see full details.

If the knowledge is enough to solve the problem, submit the item straight to the front of the queue.

The control adds the item to the front using “Submit to Retry Queue”.

Replaying a Flow

If a flow aspect changes while the flow has been running for some time, replaying that flow might be required.

The flow replay is needed when filters change.

Replay uses the same registrations as before.

Replay occurs as if the changes were made earlier.

Replay is not something that can be done directly.

A request to Certain can arrange replay.

Replay can specify a date range.

Replay can also specify an event.