Connectors
Click here to see this page in full context

Connectors

Overview

Connectors are used to integrate the Engagement Data Platform with other Cheetah Digital applications, and with third-party platforms. Connectors contain the information needed to manage that integration, such as API endpoints, login credentials, etc. The collection of settings and properties are saved as a reusable asset called a Connection Profile.

Access

To access the Connectors screen, select Integrations from the Main Navigation Menu, then select Connectors from the Sub-Category menu.

Additional Resources

Features

The Connectors screen provides the following features related to managing your Connection Profiles:

 Create a New Connection Profile -- Cheetah Messaging

Click hereClick here

To create a Connector to Cheetah Messaging:

  1. Click the "Cheetah Messaging" tile. The platform displays a list of existing Connection Profiles.

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. If you have the Smart Messaging Framework (SMF) enabled in your account, you should select it as your Send Pipeline. Check edit send pipeline and click ok in the confirmation dialog box. From the Send Pipeline drop-down menu, select "Smart Messaging Framework."

Note: The Smart Messaging Framework provides faster performance and improved scalability. SMF is not yet available in every global region. Please speak to your Client Services Representative if you have any questions about how to enable SMF in your account. 

  1. In the Base URL field, enter the following API endpoint based on the selected Send Pipeline:

  • Smart Messaging Framework: https://smf.eccmp.com/smartmessage/api/v1/SendAsync

  • Advanced Event Trigger: https://edpaet.eccmp.com/services2

  1. In the Access Token URL field, enter the endpoint you entered above, followed by: 

  • /oAuth2/Token

  1. In the "Username" field, enter the Consumer Key for the Messaging system user.  

  2. In the "Password" field, enter the Consumer Secret for the Messaging system user. By default, this value is obscured; optionally click show to view the value.

Note: The Username and Password values can be found within Messaging on the API Keys screen. Please see the Messaging Online Help for more details.

  1. In the "Token Expiration" field, enter the duration of the authentication token.

  2. Click save.

 

 

 

 Create a New Connection Profile -- Secure FTP

Click hereClick here

To create a Connector to an FTP Server:

  1. Click the "Secure FTP" tile. The platform displays a list of existing Connection Profiles.

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. In the "FTP Host" field, enter the FTP server filepath.

  7. In the "FTP Port" field, enter the desired server port.

  8. In the "Username" field, enter the FTP server username.

  9. From the "Auth type" drop-down menu, select either:

  • Password: In the "Password" field, enter the FTP server password.

  • Public Key: From the "Private Key File" drop-down menu, select an Encryption Key. 

Note: EDP supports the use of SSH2 (Secure Shell protocol version 2) for importing and exporting data. To use SSH2, you must create an Encryption Key that uses "RSA Private Key" as the encryption type, then assign that Encryption Key to an SFTP Connection Profile as described above. Then, select that Connection Profile for your Import and Export Definitions in EDP. 

  1. In the "Root Path" field, optionally enter the root path to the desired location on the FTP server. This value will be used as a prefix for all objects that use this Connection Profile.

  2. Click save.

 

 Create a New Connection Profile -- Amazon S3

Click hereClick here

Amazon's Simple Storage Service (S3) allows you to store and retrieve data, at any time, from anywhere on the web. This service uses the concept of a container called a "bucket" to store data. You can store an infinite amount of data in a bucket, and download it whenever you need.

Note: For more information on Amazon S3, please see the Amazon S3 User Guide. 

You can configure buckets so that they are created in a specific AWS Region. The combination of an optional prefix, the bucket name, and the region together comprise the URL for the bucket. For example, let's say you have an object named cheetah.jpg stored in the awsexamplebucket1 bucket in the US West (Oregon) Region. This object is addressable using the URL: https://awsexamplebucket1.s3.us-west-2.amazonaws.com/cheetah.jpg.

To create a Connector to an Amazon S3 Bucket:

  1. Click the "Amazon S3" tile. The platform displays a list of existing Connection Profiles

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. In the "AWS Access Key" field, enter your Amazon Web Services (AWS) Access Key ID. This ID is a 20-character, alphanumeric string that uniquely identifies an AWS account.

  7. In the "AWS Secret Key" field, enter your AWS secret access key. This key is a 40-character string. 

  8. In the "Bucket" field, enter the name of the Amazon S3 Bucket.

  9. In the "Root Path" field, optionally enter a value used as a prefix for all objects that use this Connection Profile.

  10. From the "Region" drop-down menu, select your AWS region.

  11. Click save.

 

 Create a New Connection Profile -- HTTP API

Click hereClick here

To create an HTTP API Connection Profile: 

  1. Click the "HTTP API" tile. 

  2. Select the "Connection Profiles" option to view the list of existing Connection Profiles. 

  3. In the "Display Name" field, enter the name of the new Connection Profile.

  4. From the drop-down menu, select an authentication method: No Authentication, Basic Authentication, Bearer Token, or OAuth 2.0. Please note that you can't later change this selected authentication method. 

  5. Click create. The "Connection Profile" pop-up window is displayed.

  6. The "Label" field is populated with the value you entered above; optionally edit this value.

  7. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  8. The remaining fields will vary based on the authentication method you selected above:

No AuthenticationNo Authentication

When No Authentication is selected, the platform does not include the Authorization Header in the API call. 

  1. In the "Base URL" field, enter the URL for the API endpoint.

  2. Click save. 

Basic AuthenticationBasic Authentication

When Basic Authentication is selected, the platform sends the credentials in the Authorization Header in the following format. The username and password are Base64 encoded. 

Authorization: Basic [username:password]

  1. In the "Base URL" field, enter the URL for the API endpoint.

  2. In the "Username" field, enter the username.

  3. In the "Password" field, enter the user's password. By default, this value is obscured; optionally click show to view the value. 

  4. Click save. 

Bearer TokenBearer Token

When Bearer Token is selected, the platform the platform sends the credentials in the Authorization Header in the following format.

Authorization: Bearer [token]

  1. In the "Base URL" field, enter the URL for the API endpoint.

  2. In the "Token" field, enter the bearer token. By default, this value is obscured; optionally click show to view the value.

  3. Click save. 

OAuth 2.0OAuth 2.0

The platform supports the "Client Credentials" OAuth 2.0 grant type. The platform sends the credentials in the following format:

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

  1. In the "Base URL" field, enter the URL for the API endpoint.

  2. In the "Access Token URL" field, enter the URL used to request an access token. 

  3. In the "Grant Type" field, enter "client_credentials."

  4. In the "Client ID" field, enter the authorized user's username.

  5. In the "Client Secret" field, enter the user's password. By default, this value is obscured; optionally click show to view the value.

Note: "Account" and "Scope" are not needed.

  1. Click save. 

 

 Create a New Template -- HTTP API

Click hereClick here

HTTP API Templates allow you to export data from your EDP database, and to send the data via an API request to a designated endpoint. An HTTP Template encompasses a Connection Profile, the API endpoint, the data to be sent, and the schema of API payload. To create an HTTP API Template:

  1. Click the "HTTP API" tile. 

  2. Select the "Templates" option to view the list of Templates. 

  3. In the "Display Name" field, enter the name of the new Template. 

  4. From the "Select Template Type" drop-down menu, select Outbound API (this option is currently the only supported template type). 

  5. Click create. The "Edit Template" pop-up window is displayed. 

  6. The "Display Name" field is populated with the value you entered above; optionally edit this value.

  7. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  8. From the "Resource Type" drop-down menu, select Query (this option is currently the only supported resource type). 

  9. From the "Resource Name" drop-down menu, select the desired Query. 

  10. After selecting the query, click the Download button. The platform downloads the column headers from the query, which makes it easier populate the URL Path, Header and Body sections with dynamic values

  11. From the "Connection Profile" drop-down menu, select the desired HTTP API Connection Profile. 

  12. From the "HTTP Method" drop-down menu, select an HTTP method -- POST, GET, PUT, PATCH, or DELETE.

Note: The GET method will not retrieve data from an external system; when using the "Outbound API" Template Type, EDP will only send data to an external system. 

  1. From the "Payload Type" drop-down menu, select JSON (this option is currently the only supported payload type).

  2. The "Batch Size" drop-down menu is used to determine how records are included in each API call. If the template Body is "Form Data," then the batch size must be "1." If the template Body is "Raw," than you can select any batch size. See "Body" below for more details. 

  3. From the "Template Language" drop-down menu, select either (%) Notation or Handlebars. (see Handlebars Reserved Keywords for additional information). 

  4. The "URL Path" is used to define the API endpoint. If the "Base URL" in the Connection Profile is populated, then the platform will append the value you enter in this "URL Path" to the value in the "Base URL" to form the complete endpoint URL for the API calls. If the "Base URL" in the Connection Profile is empty, then the "URL Path" must contain the complete endpoint URL. 

Note: IF you are using values from the query in the URL Path, you can click "Select Query Column" and select a query column header. The platform inserts the string into the URL, correctly formatted using the specified Template Language. 

Request Headers

This section is used to define the Header parameters to send in the API call. 

  1. Click add. The platform adds a new row for defining a key / value pair. 

  2. Check enabled (this check box is checked by default). 

  3. In the "Name" field, enter the name of the field. 

  4. In the "Value" field, enter the value of the field as either plain text or as a dynamic value created with the selected template language. If you are using values from the query, you can click on the magnifying glass icon and select a query column header. The inserted string is already formatted using the specified template language. 

Note: If the batch size is greater than 1, then you should not populate the Header parameters with dynamic values from the query result set, since a call with more than one record still has only one set of Header parameters. If you do this, the headers will not populate with the dynamic values. 

  1. If you check static, then whatever text is typed in the "Value" text box will be sent in the API call. Unchecking this check box means that the value will be evaluated using the specified template language, and the result will be dynamic for each API call. 

  2. Repeat the above steps as needed to define additional Header parameters.

  3. Optionally, if you need to remove a key / value pair, click the Delete icon next to it. 

Body

Frequently, API calls include a JSON object in the request body, consisting of one or more key / value pairs. When defining the request Body parameters, EDP allows you to enter these key / value pairs directly into the user interface. Optionally, you can also enter the "raw" JSON object. If you don't submit the raw JSON object, the platform submits the request as form data. 

Enter as Form DataEnter as Form Data

  1. To enter the request Body parameters as Form Data, select the form data radio button.

  2. Click add. The platform adds a new row for defining a key / value pair. 

  3. Check enabled (this check box is checked by default). 

  4. In the "Name" field, enter the name of the form data field. 

  5. In the "Value" field, enter the value of the form data field as either plain text or as a dynamic value created with the selected template language. If you are using values from the query, you can click on the magnifying glass icon and select a query column header. The inserted string is already formatted using the specified template language. 

  6. If you check static, then whatever text is typed in the "Value" text box will be sent. Unchecking this check box means that the value will be evaluated using the specified template language, and the result will be dynamic for each API call. 

  7. Repeat the above steps as needed to define additional Body parameters.

  8. Optionally, if you need to remove a key / value pair, click the Delete icon next to it.

  9. Click save. Optionally, you can submit a test request message; see Preview Settings below for more details on this process. 

Enter Raw JSON ObjectEnter Raw JSON Object

To enter the request Body parameters as raw JSON: 

  1. Select the raw radio button.

  2. Enter the JSON object within the Request Body field. 

  3. Any values that are dynamic in the JSON must use the specified template language to resolve the values. If you click "Select Query Column," a drop-down menu of query columns is displayed. Select the column you want to insert into the JSON. The inserted string will be in the format of your specified template language.

  4. Click save. Optionally, you can submit a test request message; see Preview Settings below for more details on this process.

Preview Settings

The HTTP API Template feature provides a Preview feature that allows you to test your parameters. 

  1. Optionally enter a URL in the "Test URL" field. If you provide a test URL, the platform will send the test message to this URL. If you leave this field blank, the platform will send the test message to the URL entered above in the "URL Path" field.

  2. Click generate preview. The platform generates a cURL statement in the Code Preview pane using the settings defined in the template. 

  3. In the "Batch" field, specify which batch you want to use in the generated preview. Because batch sizes can be very large, the platform displays only the first ten records in each batch. Each record is displayed in the pane, and you can expand each record to see its values. To see another batch, change the "Batch" number and click generate preview again. 

  4. Click test request to execute the cURL statement in the Code Preview pane. The response message is displayed in the "Response" section. 

 

 

 

 Create a New Connection Profile -- Salesforce Marketing Cloud

Click hereClick here

To create a Connector to the Salesforce Marketing Cloud:

  1. Click the "Salesforce Marketing Cloud" tile. The platform displays a list of existing Connection Profiles.

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. In the "Request URL" field, enter the URL used to get an OAuth token from Salesforce. This URL is usually unique per Salesforce client.

  7. Optionally, in the "Grant Type" field, enter the OAuth grant type, such as Authorization Code or Refresh Token, for example.

  8. In the "Client ID" field, enter the authorized user's username.

  9. In the "Client Secret" field, enter the user's password. By default, this value is obscured; optionally click show to view the value.

  10. Optionally, in the "Scope" field, enter the Scope value. This parameter is used to access additional permissions in the returned token.

  11. In the "Account ID" field, enter your Salesforce account ID.

  12. Click save.

 

 Create a New Connection Profile -- Sparkfly

Click hereClick here

To create a Connector to Sparkfly:

  1. Click the "Sparkfly" tile. The platform displays a list of existing Connection Profiles.

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. The "Endpoint" field is pre-populated with the standard endpoint for requesting a Sparkfly authentication token. Optionally enter a different endpoint in this field.

  7. In the "Client ID" field, enter the authorized user's username.

  8. In the "Client Secret" field, enter the user's password. By default, this value is obscured; optionally click show to view the value.

  9. In the "Token Expiration" field, enter the duration of the authentication token. The default duration is 24 hours (86,400 seconds).

  10. Click save.

 

 Create a New Connection Profile -- Google Cloud Storage

Click hereClick here

Google Cloud Storage is an online file storage web service for storing and accessing data on Google Cloud Platform infrastructure. This service uses the concept of a container called a "bucket" to store data.

Note: For more information on Google Cloud Storage, please see the Google Cloud Documentation. 

To create a Connector to a Google Cloud Storage bucket:

  1. Click the "Google Cloud Storage" tile. The platform displays a list of existing Connection Profiles.

  2. In the "Display Name" field, enter the name of the new Connection Profile.

  3. Click create. The "Connection Profile" pop-up window is displayed.

  4. The "Label" field is populated with the value you entered above; optionally edit this value.

  5. The Internal Name is automatically populated based on the Label value. This field is uneditable by default. To edit the Internal Name, check edit internal name. A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  6. From the "Primary Key File" drop-down menu, select the desired Encryption Key. 

  7. In the "Bucket" field, enter the name of the Google Cloud Storage bucket.

  8. Click save.

 

 View or Edit Connection Profile Details

Click hereClick here

To view or edit a Connection Profile

  1. Click the tile representing the type of Connector you want to edit. The platform displays a list of existing Connection Profiles of the selected type.

  2. Click the desired Connection Profile. The Connection Profile Details screen is displayed. See Connection Profile Details for more information.

 

 

 Back to Integrations Overview

Last Updated: April 2022

 

© Cheetah Digital    Engagement Data Platform Online Help 22.0  April 2022