TIBCO Scribe® Online Connector For SendGrid

The TIBCO Scribe® Online Connector for SendGrid is based on the CData driver for SendGrid. This Connector provides read and write access to SendGrid objects like Recipients, Lists, and MarketingCampaigns. Integrating SendGrid with CRM systems like Dynamics 365 and Salesforce can make your email marketing efforts more efficient and easier to manage by automating manual steps in your business process. You can also integrate SendGrid with eCommerce platforms like Shopify and Magento. This Connector is based on Scribe.Connector.AdoNet library and CData ADO.NET Provider for SendGrid.

Possible use cases for the SendGrid Connector include:

Get information about Lists, MarketingCampaigns, Recipients, Segments.
Manage the list of recipients.
Consume statistics about Campaigns, such as spam reports or unique clicks.
Send emails.

Connector Specifications

This Connector supports version 3 of the SendGrid API.

	Supported
Agent Types
Connect on-premise	X
Connect cloud	X
Data Replication Apps
Source
Target
On Schedule Apps
Source	X
Target	X
On Event Apps
Source	X
Target	X
Flows
Integration	X
Request-Reply	X
Message

Note: This Connector is available from the TIBCO Cloud™ Integration Marketplace. See Marketplace Connectors for more information.

Supported Entities

The SendGrid Connector supports the entities from the SendGrid account you are accessing. For more information see Data Model in the CData Documentation. Depending on the age of your SendGrid account, you may not have access to all possible entities.

If you have a new SendGrid account that includes the new Marketing Campaigns feature, attempting to access the following entities generates Access Denied errors:

CustomFields
Lists
MarketingCampaigns
Messages
Recipients
ReservedFields
Segments
SenderIdentities

If you have a SendGrid account that includes the legacy Marketing Campaigns feature, you can access these entities with no errors.

Special Operations

Supports the Execute Block to execute stored procedures, where each stored procedure is represented as an entity and each input parameter is represented as a field within that entity. See Execute Block and the CData SendGrid documentation for additional information.

Setup Considerations

SendGrid provider supports two types of authentication, which affect the features that are available. Login and password are required, but they do not include access to using stored procedures. An API key is required to use stored procedures, such as SendEmail.

API Usage Limits

SendGrid API rate limit is set for each API call individually. Refer to the SendGrid API documentation for additional details.

Note: Refreshing metadata for the Connector consumes API calls.

Selecting An Agent Type For SendGrid

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To SendGrid

Note: Best practice is to create Connections with credentials that limit permissions in the target system, following the principle of least privilege. Using Administrator level credentials in a Connection provides Administrator level access to the target system for TIBCO Cloud™ Integration - Connect users. Depending on the entities supported, a TIBCO Cloud™ Integration - Connect user could alter user accounts in the target system.

Select Connections from the menu.
From the Connections page select Create to open the Create a connection dialog.
Select the Connector from the list to open the Connection dialog, and then enter the following information for this Connection:
- Name — This can be any meaningful name, up to 25 characters.
- Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
- User — SendGrid account user name.
- Password — SendGrid account password.
- APIKey — Optional. If you plan to use stored procedures, such as SendEmail, you must generate an API key in SendGrid and paste it in this field.
- Additional Parameters — Optional field where you can specify one or more connection string parameters. See the Connection String Options section of the CData documentation for a list of parameters that can be used and their default values. Note that in some cases the CData ADO.NET Provider for SendGrid does not fully support all of the possible parameters.
  Syntax for the Additional Parameters field is as follows:
  - All blank characters, except those within a value or within quotation marks, are ignored
  - Preceding and trailing spaces are ignored unless enclosed in single or double quotes, such as Keyword=" value"
  - Semicolons (;) within a value must be delimited by quotation marks
  - Use a single quote (') if the value begins with a double quote (")
  - Use a double quote (") if the value begins with a single quote (')
  - Parameters are case-insensitive
  - If a KEYWORD=VALUE pair occurs more than once in the connection string, the value associated with the last occurrence is used
  - If a keyword contains an equal sign (=), it must be preceded by an additional equal sign to indicate that the equal sign is part of the keyword
  - Parameters that are handled by other fields or default settings in the Connection dialog are ignored if used in the Additional Parameters field, including:
    - User
    - Password
    - Logfile — To enable logging enter a value for the verbosity parameter in the Additional Parameters field. The default log file size is a maximum of 10MB. When the log file reaches 10MB a new log file is started, up to a maximum of five files. Once there are five files, the oldest file is deleted as needed. Any CData log files generated by this setting are stored in the default Connect on-premise Agent Logs directory, C:\Program Files (x86)\Scribe Software\TIBCO Scribe® Online Agent\logs\.
      Note: For information on setting log file verbosity, see Verbosity in the CData Help.
    - MaxLogFileCount — This parameter is set by the Connector to a maximum of five files.
    - MaxLogFileSize — This parameter is set by the Connector to a maximum of 10MB.
    - RTK
Select Test to ensure that the agent can connect to your database. Be sure to test the Connection against all agents that use this Connection. See Testing Connections.
Select OK/Save to save the Connection.

Metadata Notes

When not specified by the source, the default length of string fields is 2000. To override the default, use the Additional Parameters option on the SendGrid Connection dialog in TIBCO Cloud™ Integration - Connect. Specify the DefaultColumnSize name-value pair inside the Other property.

Example:

Other=”DefaultColumnSize=5000;”

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Relationships

Relationships are not supported for this Connector.

Hierarchical Data

Hierarchical data is not supported for this Connector.

Retry Logic

If a request fails, the Connector does not retry.

SendGrid Connector As An App Source

Consider the following when using the SendGrid Connector as an app source.

Net Change

Supports using Net Change to filter for new and updated records. See Block Properties Net Change Tab.

Filtering

When a datetime is configured on the Query block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Cloud™ Integration - Connect builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

Note: The Net Change date is ignored when previewing data on the Preview tab. Filters on the Block Properties Filters tab are used to filter the data on the Preview tab.

Filtering support varies by entity. For additional details, refer to the Notes On Standard Entities section of this document and see the Data Model section of the CData documentation.

Native Query

The SendGrid Connector supports SQL queries in Native Query Blocks to create customized queries for SendGrid. The query can be as simple or complex as you need it to be; however, it should return a single result set. The native query text is sent to SendGrid exactly as it is entered without any modifications.

You can use SELECT , UPDATE , INSERT and DELETE clauses. If support for Enhanced SQL is enabled, you can use Joins and Aggregate functions. For additional details, see the SQL Compliance section of the CData documentation .

After entering the SQL query, you must select Test to validate the query. Invalid queries are not accepted by the Connector. See Native Query Block and Creating Native Queries For Microsoft SQL Server for additional information.

When testing a Native Query in a flow, if the source datastore does not return any data, TIBCO Cloud™ Integration - Connect cannot build the schema for the underlying metadata and the flow cannot be saved. To allow TIBCO Cloud™ Integration - Connect to build the schema, do the following:

Create a single temporary record in the source datastore that matches the Native Query.
Test the Native Query and ensure that it is successful.
Save the flow.
Remove the temporary record from the source datastore.

SendGrid Connector As An App Target

Consider the following when using the SendGrid Connector as an app target.

Batch Processing

Batch processing is not supported.

Notes On Standard Entities

CategoryStats

Filtering — When filtering by Name, only the equals operator is supported.

Schedules

Filtering — When filtering by Campaign_ID, only the equals operator is supported.
Update — Only supported for campaigns where the status is scheduled.
Insert — Only supported for campaigns where the status is draft.

SubUsersStat

Filtering —
- When filtering by SubUserName, only the equals operator is supported.
- When filtering by Date, the default values vary depending on the version of the CData provider used. Refer to the Data Model section of the CData documentation.

TIBCO Cloud™ Integration - Connect API Considerations

To create Connections with the TIBCO Cloud™ Integration - Connect API, the SendGrid Connector requires the following information:

Connector Name	SendGrid
Connector ID	8931737D-A5DB-4A4D-BEC2-F43EB0A01F68

TIBCO Cloud™ Integration - Connect Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

Note: Connection property names are case-sensitive.

Name	Data Type	Required	Secured
User	String	Yes	No
Password	String	Yes	Yes
APIKey	String	No	Yes
ConnectionString	String	No	No

License Agreement

The TIBCO End User License Agreement for the SendGrid Connector describes TIBCO and your legal obligations and requirements. TIBCO suggests that you read the End User License Agreement.

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.