New features and changes in version 8.2.0

Offer marketplace enhancements

The following enhancements have been made in Interact 8.2.0 to support working with large numbers of offers:

  • Ability to use SQL queries to get a desired set of candidate offers. OffersBySQL allows users to configure SQL to query a table or tables, to which offer lists or offers have been written, at run time.
  • New command line tool for deploying candidate offers. A Campaign batch flowchart can be configured to run on a periodic basis. When the flowchart run completes, a trigger can be called to initialize deployment of the offers in the OffersBySQL table.

How to use the OffersBySQL feature

Basic steps for using the OffersBySQL feature are as follows:

  1. Organize offers in folders or in offer lists.
  2. Using Campaign batch features, or any external ETL process, populate the UACI_ICBatchOffers table with the final list of candidate offers.
  3. Deploy the interact channel using a trigger.

  4. On the run time side:

    Configure SQL to be called by creating an SQL template under configuration: Interact/profile/audienceLevels/<AudienceLevel>/offers By Raw SQL.

    • SQL may contain references to variable names that are part of the visitor's session data (profile). For example, "select * from MyOffers where category = ${preferredCategory}" will rely on the session containing a variable named preferredCategory.
    • SQL should be configured to query the offer tables generated in Step 2 above.

The execution of the SQL will happen for every startSession call if the offersBySQL feature is enabled.

To have the execution occur for every getOffers call, a postEvent may be called prior to getOffers with the parameter UACIQueryOffersBySQL set to 1. The getOffers call (and all subsequent getOffers) will execute the SQL.

To execute a different SQL, set the value of the parameter UACIOffersBySQLTemplate to the name of the preferred SQL template.

About the command line tool

The command line tool (runDeployment.sh/.bat) can be found under the Interact Design Time install directory tools/deployment. The usage of the script is simply: runDeployment <propertiesFile> for each interactive channel/server group deployment combination.

A sample properties file called deployment.properties outlines all the possible parameters and is available in the tools/deployment folder.

New configuration parameters

The following new configuration parameters are introduced in Interact 8.2 to support the OffersBySQL feature.

Table 1. New Design Time configuration parameters
Path name Description Default
Interact/whitelist/<audienceLevel>/offersBySql/defaultCellCode The default cell code to be used for any offer in the OffersBySQL table(s) that has a null value in the cell code column (or if the cell code column is missing altogether. This value must be a valid cell code. None
Table 2. New Run Time configuration parameters
Path name Description Default
profile/audienceLevels/<AudienceLevel>/offers By Raw SQL/enableOffersByRawSQL Boolean flag to enable the offersBySQL feature for this audience level. FALSE
profile/audienceLevels/<AudienceLevel>/offers By Raw SQL/cacheSize Size of cache; used to store results of the OfferBySQL queries. NOTE: Using cache may have negative impact if query results are unique for most sessions. -1 (off)
profile/audienceLevels/<AudienceLevel>/offers By Raw SQL/cacheLifeInMinutes The number of minutes before the system will clear the cache to avoid staleness. -1 (off)
profile/audienceLevels/<AudienceLevel>/offers By Raw SQL/defaultSQLTemplate The name of the SQL template to use if not specified via the API None
profile/audienceLevels/<AudienceLevel>/offers By Raw SQL/<SQLTemplate>/name The name of the SQL template. None

New distance macro

The new Distance macro, available in both HCL® Campaign and HCL Interact, supports calculating the distance between two geographical points, when two pairs of latitude and longitude coordinates are provided. For complete details, refer to the HCL Macros for IBM EMM User's Guide.

Ability to set JDBC fetchSize when retrieving records from staging tables

A new configuration parameter, fetchSize has been added to allow setting the JDBC fetchSize when retrieving records from staging tables.

The path to the parameter in Configuration Manager in Marketing Platform is Affinium | Campaign | partitions | partition1 | Interact | contactAndResponseHistTracking | fetchSize

The 8.2 installation automatically adds this parameter to your configuration.

On Oracle databases especially, adjust the setting to the number of records that the JDBC should retrieve with each network round trip. For large batches of 100K or more, try 10000. Care must be taken not to go too large as that will have an impact on memory usage and the gains will become negligible, if not detrimental.

Interact contact and response history ETL script enhancements

The following enhancements have been made in Interact 8.2.0:

  1. Ability to specify a larger batch size for ETL using the new configuration property maxJDBCFetchBatchSize.

    The CH/RH records will be read from the Interact Runtime data source in chunks of the size specified in the maxJDBCFetchChunkSize property, and written to the Campaign data source.

    For example, to process 2.5 million contact history records a day, you should set maxJDBCFetchBatchSize to a number greater than 2.5M so that all records for one day will be processed. maxJDBCFetchChunkSize and maxJDBCInsertBatchSize should be set to smaller values, say 50,000 and 10,000 respectively. Some records from the next day will be processed as well, but retained until the next day.

  2. Ability to schedule an ETL run

    An option is now available to run the ETL once a day, with the ability to specify a preferred time window for the run. The ETL will start during the specified tiem interval and will process at most the number of records specified using maxJDBCFetchBatchSize.

  3. Option to retain process contact and response history records

    An option is now available to retain processed contact and response history records.

  4. ETL completion notification

    You can now specify an absolute path to a script that will be run when ETL completes. Four arguments are passed to the completion notification script: start time, end time, total number of CH records processed, and total number of RH records processed. The start time and end time are numeric values representing number of milliseconds elapsed since 1970.

Note: If ETL takes more than 24 hours to execute, and thus misses the start time for the next day, it will skip that day and run at the scheduled time the following day. For example, if ETL is configured to run between 1AM to 3AM, and the process starts at 1AM on Monday and completes at 2AM on Tuesday, the next run, originally scheduled for 1AM on Tuesday, will be skipped, and the next ETL will start at 1AM on Wednesday.
Note: ETL scheduling does not account for Daylight Savings Time changes. For example, if ETL scheduled to run between 1AM and 3AM, it could run at 12AM or 2AM when the DST change occurs.

Start/Effective dates of offers now taken into consideration in Interact

Two new configuration parameters have been added to allow managing start/effective date behavior with offers. Both are located in the following path in Configuration Manager in Marketing Platform:

Affinium > Interact > offerServing

Table 3. Summary of start/effective date changes
Parameter name Description
effectiveDateBehavior

This parameter is a global configuration that impacts all offers. By default, it is set to 0 (use effective date).

Possible values are:

  • -1 -- Ignore effective date (equivalent to behavior prior to this enhancement)
  • 0 -- Use effective date (default)
  • >0 -- Grace period (number of days added to currect date. If the effective date is greater than the calculated date (current date plus grace period), the offer will be filtered out)
effectiveDateGracePeriodOfferAttr

This parameter allows each offer created from a template to have a different grace period value. It maps to a custom offer attribute for setting the number of days before the effective date that an offer can be served.

The value is the name of the custom attribute created in the offer template, and the default is blank or no value.

If effectiveDateGracePeriodOfferAttr is set, Interact looks for the named attribute in each offer. If an offer contains the named attribute, Interact reads the value and determines the grace period.

If an offer does not contain the named attribute or if effectiveDateGracePeriodOfferAttr is not set, Interact uses the effectiveDateBehavior setting.

To configure effectiveDateGracePeriodOfferAttr,

  1. Create a custom offer attribute in Campaign.
  2. Set the value of effectiveDateGracePeriodOfferAttr to the name of the new custom offer attribute.
  3. Assign the custom offer attribute to each offer template for which you want to specify a grace period.
  4. In offers created from the offer template, set this attribute to the number of days to be added to the current date to allow as a grace period.