PossibleNOW MyPreferences Connector
The PossibleNOW MyPreferences Connector supports bi-directional preference data integration with MyPreferences and other applications. It allows you to seamlessly sync preference data captured in MyPreferences with other systems, or retrieve data from other systems and update MyPreferences, all in near real-time. For the latest release notes see, PossibleNOW MyPreferences Release Notes.
Connector Specifications
Supported | |
---|---|
Agent Types |
|
On Premise | X |
Cloud | X |
Replication Services |
|
Source | |
Target | |
Integration Services |
|
Source | X |
Target | X |
Migration Services |
|
Source | X |
Target | X |
Maps |
|
Integration | X |
Request-Reply | X |
Message |
Note: This Connector is available only from PossibleNOW.
Supported Entities
The PossibleNOW MyPreferences Connector supports the following entities. Click a linked entity name for additional information when using that entity in TIBCO Scribe® Online. For a list of additional operations by entity see Special Operations.
Standard Operations
Entity | Query | Create | Update | Delete | Upsert |
---|---|---|---|---|---|
|
|
|
|
X |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
X |
|
|
|
|
|
|
|
|
|
|
|
X |
|
|
|
|
|
X |
|
|
|
|
Special Operations
Entity | Operations |
---|---|
-Deactivate |
|
-UpsertWith |
|
-Add |
- UpsertWith — Container Block used with hierarchical data to create or update a parent record that contains one or more child records. This Block collects all the data for a single record before writing the entire record to the target. For example, if the record is a SalesOrder containing five SalesOrderItems, the UpsertWith Block, along with an Add Block, retrieves both the SalesOrder and the associated SalesOrderItems and writes the entire record at once to the target. See UpsertWith Block.
- Add — Used for hierarchical data to add child records to the parent selected in the UpsertWith Block. See Add Block.
Note: Operation results are not available for subsequent operations when using UpsertWith or Add Blocks.
Setup Considerations
Required Connection information, such as Client Id and Hash Key, is provided by PossibleNOW.
Selecting An Agent Type
Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.
Connecting To PossibleNOW MyPreferences
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 Scribe® Online users. Depending on the entities supported, a TIBCO Scribe® Online user could alter user accounts in the target system.
- Select More > Connections from the menu.
- From the Connections page select Add to open the Add a New Connection dialog.
- Select the Connector from
the drop-down list in the Connection Type field, 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.
- Client ID — ID associated with .your MyPreferences account.
- User Id— Your MyPreferences User ID. The MyPreferences Connector associates the preference data submissions with this UserId. To change the UserId associated with preference submissions, you must re-establish the Connection by entering a new User ID.
- Hash Key — Provided by PossibleNOW.
- BaseUrl — URL of the MyPreferences REST API.
- 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
Consider the following for data fields and entity types.
Reseting metatdata is only necessary when upgrading to a newer version of the Connector. There is no mechanism in the API to retrieve metadata changes, therefore the Connector must be updated to provide access to those changes.
Metadata Notes
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.
Retry Logic
If a request fails, the Connector retries three times with a delay of 1000 milliseconds before the first retry, 2000 before the second, and 3000 before the third.
PossibleNOW MyPreferences Connector As IS/MS Source
Consider the following when using the PossibleNOW MyPreferences Connector as an Integration Solution or Migration Solution source.
Supports querying Hierarchical data. See Hierarchical Data.
Relationships
This Connector only supports the Return records with or without relationship option when selecting related entities on the Include tab of source operation Blocks, such as Query, Fetch, and Lookup. This option is an outer join and returns all records for the parent or higher-level entity whether or not there are any matching related entity records. For example, if contact is the higher-level entity and account is the related entity, all contact records are returned whether there is a related account record or not.
Filtering
Using Net Change to query for new and updated records is supported for the LastDateTimeUTC field. Using the LastDateTimeUTC field for Net Change requires that you also use Segment as a filter on the Filter tab.
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 Scribe® Online 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 Scribe® Online 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.
- Data can be filtered:
- From the Filter tab, Lookup Criteria tab, or Matching Criteria tab in Integration Maps.
- Only supported fields display in the Field drop-down list for any filter.
- Complex filters using AND are supported. OR is not supported, except where noted for specific entities. See Block Properties Filter Tab.
- Only the equals operator is supported.
PossibleNOW MyPreferences Connector As IS/MS Target
Consider the following when using the PossibleNOW MyPreferences Connector as an Integration Solution or Migration Solution source.
- Strings that exceed the field length of the target field are truncated and no error message is generated.
- Supports writing Hierarchical data. See Hierarchical Data.
Notes On Standard Entities
Special information about standard entities appears below.
BatchPreference
Supports Batch Processing. Use this entity to bulk process Preference data.
- Upsert —
- Creates a new Preference record if any of the ContactElement field values are changed, even if the CID is the same.
- Updates the record for a Filter if the CID, Name, and ContactElement fields match.
- PreferenceType — Preference Type designates the opt-in or opt-out state of a preference. An existing preference record is only updated if the Customer Date specified is equal to or newer than the Customer Date on the existing record. MyPreferences assigns the current date/time if you don’t specify a Customer Date.
- PreferenceAttributes — This field accepts JSON in the following format: $"{ ""[key]"": ""[value]""}"
Note: If the PreferenceAttributes values you are mapping are already strings, the $ is unnecessary and the inner quotes may not be required: "{ [fieldnameforkey]: [fieldnameforvalue]}"
If you add PreferenceAttributes that are not configured in PossibleNOW MyPreferences, they are stored in the database and are returned when querying Preferences, however they do not display in the PossibleNOW MyPreferences User Interface.
ContactElement
- ContactElement is a child of the Preference entity.
- Query — Access ContactElement child records by selecting ContactElement on the Include tab when querying the Preference entity.
- UpsertWith — ContactElement child record fields are included on the Preference and ChannelPreference entities in the UpsertWith Block and can be mapped there.
ChannelPreference
- UpsertWith —
- Creates a new record if any part of the related ContactElement entity is changed, even if the CID or Name is the same.
- Updates or creates Preference records for an entire channel based on the ProgramId or ProgramGroupId and, using the Add Block, creates or updates related PreferenceAttributes child records. See UpsertWith Block.
- Required fields include:
- UpdateNestedGroups — Boolean that affects nested program groups if set to true.
- GlobalPreferenceType — Contains the preference type value to determine whether to set the entire channel to opt-in (1) or opt-out (2).
CustomProperties
- Query — Access CustomProperties child records by selecting CustomProperties on the Include tab when querying the Program or ProgramGroup entities. CustomProperties can also be accessed as a grandchild of Program by selecting Program.Filters on the Query Block Include tab when querying the Program entity.
- UpsertWith — CustomProperties child record fields are read only and are not supported for UpsertWith even though they are visible in the Include and Field tabs for the Preference and ChannelPreference parent entities. If you map CustomProperties fields, a record error is generated.
DeactivatePreferenceInput
DeactivatePreference is a virtual entity used to deactivate a Preference and include the related ContactElement entity.
- Matching Criteria —
- Requires the following:
- FilterID or ChannelId or both
And
- A ContactElement, Name, or CID. Note that the Name must accompany a CID or ContactElement.
- FilterID or ChannelId or both
- Matching criteria may require more than one field in certain cases. For example, if you match by Address, you need Street, City, State, and Zip Code fields.
- Deactivates or deletes all matching records.
- Requires the following:
PreferenceAttributes
- PreferenceAttributes is a child of the Preference entity.
- Add — Use the Add Block inside an UpsertWith Block to add PreferenceAttributes when creating or updating Preference records via the Preference or ChannelPreference entity. See UpsertWith Block and Add Block. PreferenceAttributes can also be added using the PreferenceAttributes field on the BatchPreference Entity. See BatchPreference.
- If you add PreferenceAttributes that are not configured in MyPreferences, they are stored in the database and are returned when querying Preferences, however they do not display in the Preference Manager User Interface.
PreferenceGET
- Query — When filtering a query for Preference records:
- Segment — This field is required on the Filter tab when filtering by any of the following fields:
- LastDateTimeUTC — Field on the Net Change tab to filter for new and updated records.
- PageSize — Filter field that controls the number of records returned when paging through query results to return the results in smaller subsets. Requires thatLastDateTimeUTC be set on the Net Change tab to filter for new and updated records.
- QueryStatusPollingInterval — Filter field that sets the interval between calls to the API for the status of a query when querying Preference. This is an integer value set in milliseconds and must be greater than or equal to 3000.
- QueryStatusPollingTimeout — Filter field that modifies the default timeout setting if it has not received a success status from the MyPreferences Bulk API call when polling for query status on the Preference entity. This is an integer value set in milliseconds with a minimum of 0.
- If the timeout time is exceeded, a fatal error is generated and the Solution stops running.
- If set to a number lower than the Polling Interval, the timeout defaults to at least one polling interval.
- If not set, it never times out and continues polling.
Note: No other filters are supported with Segment.
- Filtering by User Profile Preferences, such as Phone or Address, is supported. Some filters may require more than one filter field. For example, if you filter by Address you need Street, City, State, and Zip Code fields.
- Complex filters using OR are supported for the CID field only when using both CID AND ChannelID. For example, you can have a filter that is CID AND ChannelID OR CID AND ChannelID, to return multiple CID and ChannelID combinations.
- If your filter settings are invalid or incomplete, the following error is generated detailing what is and is not supported:
ERROR: Exception Type : InvalidExecuteQueryException Message : When Querying Preferences the following filters are supported: [Preference.CID equals (value) (operator)And Preference.ChannelID equals (value)] [Preference.CID equals (value) (operator)And Preference.ChannelID equals (value) (opertor)OR Preference.CID equals (value) (operator)And Preference.ChannelID equals (value)...] [Preference.Email equals (value)] [Preference.Phone equals (value)] [Preference.Fax equals (value)] [Preference.SMS equals (value)] [Preference.Fax equals (value)] [Preference.MailAddress1 equals (value) (operator)And (optional)Preference.MailAddress2 equals (value) (operator)And Preference.MailCity equals (value) (operator)And Preference.MailPostalCode equals (value) (operator)And Preference.MailStateProvince equals (value)] Also when Querying Preferences By Segment the following fields are supported: [Segment] [Segment (operator)And (optional)LastDatetimeUTC (operator)And (optional)QueryStatusPollingTimeout (operator)And (optional)QueryStatusPollingInterval (operator)And (optional)PageSize]
- Segment — This field is required on the Filter tab when filtering by any of the following fields:
PreferencePOST
- UpsertWith —
- Creates a new record if any part of the related ContactElement entity is changed, even if the CID is the same.
- Updates or creates a Preference record and, using the Add Block, creates or updates related PreferenceAttributes child records. See UpsertWith Block.
- NULL fields are not included in new or updated Preference records.
- PreferenceType — Designates the opt-in or opt-out state of a preference. An existing preference record is only updated if the Customer Date specified is equal to or newer than the Customer Date on the existing record. MyPreferences assigns the current date/time if you do not specify a Customer Date,
Program
- Query — Using Net Change to filter for new and updated records is not supported for this entity.
ProgramGroup
- Query —
- Using Net Change to filter for new and updated records is not supported for this entity.
- Program — The Program entity is a child of ProgramGroup. On the Query Block Include tab where you can select the Program entity, the Return only records with this relationship option is not supported. You must select Return records with or without this relationship.
TIBCO Scribe® Online API Considerations
To create connections with the TIBCO Scribe® Online API, the PossibleNOW MyPreferences Connector requires the following information:
Connector Name |
PossibleNOW MyPreferences |
Connector ID |
E6DAE32E-FA4E-49F2-948B-780DEF07D195 |
TIBCO Scribe® Online 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 | Usage |
---|---|---|---|---|
ClientId |
string |
Yes |
No |
|
UserId |
string |
Yes |
No |
|
Saltvalue |
string |
Yes |
Yes |
|
BaseUrl |
string |
Yes |
No |
|
License Agreement
The TIBCO Scribe® Online End User License Agreement for the PossibleNOW MyPreferences 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.