Certain Signal Connector: Advanced Webhooks Integration Guide

Source:

Published:

Keywords: Certain Signal Connector, Advanced Webhooks, nested JSON, Flow, Connection, Retry Queue

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

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

If you are using that standard module, please see the separate guide to integrations using standard webhooks.

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

Certain Signal Connector for Advanced Webhooks is not included with Certain Platform by default. If you are interested in adding this or any other Signal Connector integration to your instance of Certain, please email features@certain.com, including your account name and 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 data from Certain Platform to your target third-party application.

The target third-party application can be any app with webhook integration.

Examples of webhook integration apps include Slack and Google Forms.

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

Almost everything is set up at the account level.

Signal Connector processes information from the events in your account.

Event-level information is based on the custom tags you attach to data such as Registration Statuses.

Important: Signal Connector processes outbound information.

Signal Connector processes information from Certain.

Signal Connector sends the outbound information to your target application.

Prerequisites

Data-Flow Considerations

This section lists data-flow considerations for advanced webhooks integrations.

Credentials in Target Application

You set up a Connection in Signal Connector.

The Signal Connector Connection setup requires information from the administrator of your target third-party application.

The required information is described under "Adding a Connection" on page 6.

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

The OAuth2 app setup provides the following:

Overview of Setup Steps

This section lists setup steps on Certain Platform and in Certain Signal Connector.

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 can apply those tags to generic items in events.

Generic items include custom registration statuses and custom registration properties for use in Certain Signal Connector.

Tags can be used for other purposes, but this guide does not cover those other purposes.

For example, 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 also give each custom status its own Tag.

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

You specify tags instead of specifying the statuses themselves.

That tag approach allows the flow to 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.

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. See page 10:

7. Also add enough tags to apply to all of the following that you will use in filters for flows. See page 10:

Applying Tags in an Account

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

Relevant information includes Registration Statuses and Registration Custom Properties.

You can also tag Attendee Types and Events so that you can filter registration records by attendee type or event. See Filters on page 10.

Default Registration Statuses

These tags apply to all events.

An Administrator applies these tags at the account level.

1. Go to Account Settings > Management > Registration Statuses. 2. Select or more Tags for each status. 3. Important: If you do not use any standard registration statuses, best practice is to set up tags for all of them. 4. Tag setup must include the New status. 5. Certain uses the New status behind the scenes when first processing each registration. 6. If you use standard reg statuses, tag them all. 7. Tagging standard reg statuses allows you to use them in the Flows you configure in Signal Connector. See page 8.

Applying Tags in an Event

Custom Registration Statuses

Some Flows 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

Some Flows 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)

These tags are set up for you automatically.

The tag names are identical to the properties themselves.

Standard registration properties include:

You only see these tags in Signal Connector.

Signal Connector supports activating Flows for these tags.

There is nothing to edit on Certain Platform.

Attendee Types

Attendee Types are optional.

Attendee Types support use with filters. See page 10.

1. In each event, go to Plan > Event Setup > Attendee Types. 2. Select one or more Tags for each attendee type that you may wish to filter registrations by. 3. Filters described on page 10.

Events

Events are optional.

Events support use with filters. See page 10.

1. In each event you may wish to include in a filter. 2. For example, the filter ensures that only registrations for that event are passed to your target application. 3. Go to Plan > Event Setup > Details. 4. Select one or more Tags for the event.

Registration Questions

Registration Questions are optional.

Registration Questions support mapping Certain fields to fields in your target application. See page 11.

1. In each event, go to Plan > Event Setup > Questions. 2. Use registration questions to capture data from attendees. 3. Use the captured answers to pass data to your target application. 4. Select just one Tag for each question. 5. Selecting more 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 option is available to Administrators.

The extra option is:

Click the link to open Certain Signal Connector in a separate window.

Certain 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.

Multiple connections can include 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.

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 are setting up the Connection first.

Adding a Connection

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

You need only do this 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.

Target field settings

Your choice determines the other fields displayed.

| 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

This level has the lowest level of security.

Open / No Auth uses the same setup as Basic Authentication, but without a User Name or Password.

API Key / Token

OAuth2

All OAuth2 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.

You can configure several flows for an account.

Multiple flows can use the same Connection.

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

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

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

If you edit a flow, the same slight delay occurs before that change takes 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.

A toggle button changes a flow from Active to Inactive, or vice versa.

Configuring a Flow

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

The flow 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 picks up all registrations in test events.

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

Best Practice: Set a new flow up as Test and test it before setting it to Live.

Flow Data Source

Specify the Source of data for the flow.

You can optionally apply Filters.

The Source of a Flow determines what the Flow watches for in your data in Certain.

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

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

The Flow might activate if an attendee's status changed to a status tagged as "Registered".

Available sources

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

Note: You can always save an incomplete Flow and complete it at a later date.

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, the tags for Registration Statuses include Registration Status tags.

Registration Status tags can apply to:

Flow Filters

You can filter the 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 are those with pre-configured answers.

Enumerated question types include:

Flow Destination

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

You may also have other integrations to choose from.

Setting up a Destination

1. Give the Destination a Name of your choice. 2. Select the Connection to use. 3. Select Advanced 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 is the same as 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.

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

Select a mapping from a drop-down list.

If no mappings exist yet, or if you need something other than existing mappings, click New Mapping.

The Mapping Setup screen opens.

1. Mapping Name: Give the mapping a name of your choice. 2. Select Root Element Type: In most cases, leave this set to the default value, Object. 3. Hint: Obtain a sample JSON from the source, paste it into the text box, and Signal Connector will parse the structure. 4. "Parsed Structure" Option: Continue here if you paste a sample JSON and let Signal Connector parse it. 5. Obtain a sample JSON payload from your target application. 6. Paste the sample JSON into the Sample JSON from Destination text box. 7. Click Parse JSON. 8. Signal Connector determines the target fields and displays them. 9. Proceed to step 10.c to map those fields to source fields in Certain Platform.

"Manual Setup" Option (and mapping parsed fields)

For each target field in your target application:

Manual setup step 10 includes:

a. If you chose not to let Signal Connector parse a pasted JSON

b. Click the select-source icon.

Select the "source" field in Certain that matches that target field.

For example, if the target field is "Title", the source field might be "Position".

The Certain field value populates the Title field in the target application.

Certain source fields depend on what your flow will activate for.

For example, if the flow activates for Event Statuses, you can only map event fields.

Certain source fields can include:

Note: Unlike a standard Webhooks integration, an Advanced Webhooks integration can include arrays.

Certain source fields can include lists such as Registration Question List.

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

You can also type fixed text.

For example, for target field "Title", you could choose source fields "Position" and "Organization", separated by two spaces and "@".

c. Make a target field required

To make a target field a required field, select the checkbox next to it.

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

This validation error is not normally fixable.

Signal Connector does not put the failed update into the Retry Queue.

d. Delete a source field

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

11. Transformation options

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

The default is no selection.

No selection sends the data to the target application unchanged.

The transformation options are:

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

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

12. Continue adding mappings

Continue adding more target/source field pairs as necessary.

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

13. Save the mapping

Click Save the mapping.

Example Mapping from Pasted JSON

This section shows an example process when you choose the "Parsed Structure" option in Step 4.

The example illustrates: 1. An example JSON you paste for parsing. 2. How Signal Connector parses that JSON into target fields. 3. How those target fields map to source fields in Certain.

Example JSON

"attachments": [
"author_name": "Sample Event Survey",
"color": "#FF8C00",
"pretext": "*Event Name:* My Test Event `Event Survey Response`",
"text": "Survey responses below:",
"fields": [
"short": "true",
"title": "Testing",
"value": "Correct"
],
"title": "Attendee: Matt Cash (75876-4308060-1172)"
]

When Signal Connector parses this JSON, it identifies these target fields (nested under attachments):

In an example mapping, those target fields might be mapped to these Certain source fields:

Metrics Dashboard

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

The choices in the Metrics navigation panel depend on the flows and their targets.

The first choice is Insights.

Other links may include Webhook Posts.

All links work in the same way as Account Insights.

Account Insights

Account Insights supports choosing Live Flows or Test Flows.

Account Insights supports selecting the period to view.

Examples of time periods include:

Account Insights includes three tabs:

Summary tab

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

The figures shown depend on the flows and actions.

For some figures, you can click the number to drill down.

You can filter records after drilling down.

You can filter on an Event Code to see only the registrations in that event.

The figures listed below are shown for the whole account.

The figures cover all events and registrations.

The figures also cover all flows in your account.

Some flows might not be Webhooks integrations.

That means some figures might not apply to webhooks.

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

Troubleshooting tab

The Troubleshooting tab on the Insights page shows information that can help with troubleshooting.

This tab can help if some registrations are not processed because a Registration Status is not tagged.

Fixing the tagging allows the registrations to process on the next retry.

The numbers shown are as follows.

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

Activity Feed tab

The Activity Feed tab lists the registrations processed.

The listing includes success or failure, Registration Code, Event, Flow, etc.

The Activity Feed is a rolling history by date.

The Activity Feed provides another way to access lower-level data available through drilling down in the Summary or Troubleshooting tabs.

The Retry Queue

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

The action takes its turn to run 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 failures under your control as a planner, such as a registration with a status that has not been tagged.

Causes also include technical failures, such as a connection being down.

If you can resolve a failure cause, such as tagging a registration or setting a flow back to being active, the action should succeed when retried.

Other failures that do not resolve themselves require contacting your administrator or asking Certain for help.

The interval between retries depends on severity.

The more serious the reason, the sooner the retry.

Filtering the Queue

You can filter the 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 the knowledge is enough for you to solve the problem, you can click Submit to Retry Queue.

Submitting 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 for some time, you may want to replay that flow.

Replay acts as if the changes had been made earlier for the same registrations.

This replay action is not something you can do directly.

Certain can arrange the replay.

You may be able to specify a date range.

You may also be able to specify an event.

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