TIBCO Engage Integration Guide

Transcription

1 TIBCO Engage Integration Guide Release May 2014 Two-Second Advantage

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, Two-Second Advantage, and TIBCO Engage are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 Contents iii Contents Preface vi Related Documentation vi Typographical Conventions vii Connecting with TIBCO Resources ix How to Join TIBCOmmunity ix How to Access TIBCO Documentation ix How to Contact TIBCO Support ix Chapter 1 Data Integration Introduction Implementation and Data Integration TIBCO Engage as an Integration Hub Chapter 2 Data Integration Process Technical Integration Process Data Integration Prerequisites Data Integration Project Plan and Tasks Project Task Descriptions Chapter 3 Data Exchange Overview Data Content Types Transaction Customer Product Catalog Store Location Rewards List Profile Generic Event

4 Contents iv Data Exchange Requirements Data Exchange Methods Batch-file Exchange Real-time SOAP-based APIs Data Exchange: Batch and API Differences Chapter 4 Batch Imports About Batch Files File Processing Constraints Batch File Summary Descriptions Data Content Types Transaction Customer Product Catalog Location Rewards List Profile Generic Event Batch File Guidelines and Specifications Upload Products Using Batch Files How to Upload Product Data via Batch Files Upload Transactions Using Batch Files What s In The Transaction File I - Transaction Details What s In The Transaction File II - Returns What s in the Transaction File III - Customer Data Chapter 5 On-Demand File Exchange About On-Demand File Exchange List Import File Format Sample File

5 Contents v List Export Profile Export Statistics Export Reward Catalog Import File Format Custom Questions Import Custom Question File Details and Requirements Chapter 6 Flat File Formats and Examples Import Files Sample of Product File from Clients Format and Sample of Store File Chapter 7 File Import Reports About the File Import Report Creating a File Report Chapter 8 Update Import File General Description Update Import File Use Cases Standard XML Sample File and XSD Schema File Usage Guidelines, Data Elements and Formats Samples and Formats of Update Files from Clients Update File and Record Failures Chapter 9 SSO Integration SSO Overview Secure Data Transfer How SSO Works Implementation Details Query String Authentication Parameters Configuration of Client SSO Handler Return Codes for SSO Authentication Index

6 vi Preface This book explains the technical requirements for enabling specific TIBCO Engage features and benefits. It includes How-To information for managers, project managers, technical leads, data managers, programmers, and anyone responsible for implementing a TIBCO Engage solution. Topics Related Documentation, page vi Typographical Conventions, page vii Connecting with TIBCO Resources, page ix Related Documentation The following documents form the TIBCO Engage documentation set: This book serves as a guide for exchanging customer, product, and transaction information with TIBCO Engage. TIBCO Engage API Reference This document explains how to use TIBCO Engage API calls, including authentication, and provides useful information about the entities involved. TIBCO Engage Release Notes The release notes provide a list of new and changed features. These documents are located on the TIBCO Product Documentation site:

7 Preface vii Typographical Conventions The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention ENV_NAME TIBCO_HOME <ProductAcron ym>_home Use TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties: Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu. Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME. TIBCO <ProductName> installs into a directory within a TIBCO_HOME. This directory is referenced in documentation as <ProductAcronym>_HOME. The default value of <ProductAcronym>_HOME depends on the operating system. For example on Windows systems, the default value is C:\tibco\<ProductAcronym>\<ReleaseNumber>. code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process. bold code font Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable disable]

8 Preface viii Table 1 General Typographical Conventions (Cont d) Convention italic font Key combinations Use Italic font is used in the following ways: To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts. To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q. The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

9 Preface ix Connecting with TIBCO Resources How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to How to Access TIBCO Documentation You can access TIBCO documentation here: How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows. For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a user name and password. If you do not have a user name, you can request one from your Customer Loyalty Management representative.

10 1 Chapter 1 Data Integration Introduction This section introduces key concepts about integrating data with TIBCO Engage and discusses the various files needed for information exchange. Topics Implementation and Data Integration, page 1 TIBCO Engage as an Integration Hub, page 2 Implementation and Data Integration Your company, as a TIBCO Client, uses our code base, infrastructure, and professional services to set up and maintain a experience management program. TIBCO imports your data into our normalized and highly scalable databases. This greatly reduces the impact of our technology on your IT department. TIBCO data integration specialists define any necessary data file format transformations necessary. Data is transferred via batch files and real-time API processes. Once the integration setup work is completed, your technical staff is responsible only for routine batch file data transfers (for example, automatically generating and forwarding report files). When the basic file transfer mechanisms are in place, your data is normalized, matched, transformed, and processed to help you with marketing segmentation, targeting, reporting, and analysis. All data in the system is regularly updated, and includes data volunteered by site visitors and the information tracked by the system across all channels. Profiles are updated daily and applied across the platform to revise offers, communications, messages, notifications, and results. The platform provides a wide set of flexible reports that enable you to evaluate performance, learn from the results, and modify activities accordingly.

11 TIBCO Engage as an Integration Hub 2 TIBCO Engage as an Integration Hub The TIBCO Engage integration hub is made up of application interfaces that allow for seamless data flow between TIBCO Engage and customer point of contact and analytical systems such as POS, ecommerce, , and CRM systems. The simplicity of our integration reduces the high cost and time requirements of a custom-built solution.

12 Data Integration Process 3 Chapter 2 Data Integration Process This section explains the TIBCO Engage data integration process. Topics Technical Integration Process, page 3 Data Integration Project Plan and Tasks, page 4 Project Task Descriptions, page 5 Technical Integration Process As part of the initial integration process, TIBCO Professional Services Group (PSG) devotes a day to review integration requirements and develop the project plan. Using our Onboarding Checklist, Pre-built Project Plan along with the technical documentation, we review the process in collaboration with clients. Required participants from your company might include the Program Manager, Marketing, the IT Manager, IT Developers, and Finance (to discuss customer crediting processes), as needed. Data Integration Prerequisites Once the integration process has started, participants typically want to make rapid progress, without stopping or slowing to collect fundamental data and resources. TIBCO has therefore identified the following information gathering and planning milestones, which should be completed before the technical data integration effort begins: Client receives and completes the Onboarding Questionnaire, or completes it to a reasonable degree. The TIBCO PSG representative for the individual client determines when there is sufficient information to proceed.

13 Data Integration Project Plan and Tasks 4 Client receives documentation, data-mapping guidelines, templates, and sample files to define the mapping between the TIBCO native representation of transaction data and the client s native data format. Client receives standard site flow diagrams and Client Review Documents (CRDs) from TIBCO for reference. (Working with these standard design starting points, the client can customize the design of its own site.) Completion of the final site flow design is not required at this point. Client receives a project plan and tentative timeline from TIBCO. These planning tools allow TIBCO and its clients to work efficiently together towards their shared implementation goals. TIBCO applies standard project management tools and its own practical experience to guarantee progress. Note that the integration progress can begin only after all four of these prerequisites are met. Data Integration Project Plan and Tasks TIBCO typically manages the data integration process with a project plan similar to the one represented in this table. This summary plan information includes both the tasks performed by TIBCO and the tasks that you perform as a client. Table 2 Data Integration Project Requirements and Project Plan Summary Task Send Technical Integration Documents and Sample Data Technical Integration kickoff Client sends sample data in accepted format Create client data mapping and requirements documents Set up a secure FTP connection Review sample data and give feedback Client revises and sends sample data (round 1) Review revised sample data and give feedback Owner Data Integration Data Integration Client Data Integration Client Data Integration Client Data Integration

14 Project Task Descriptions 5 Table 2 Data Integration Project Requirements and Project Plan Summary (Cont d) Task Client revises and sends sample data (round 2) TIBCO signoff on final client data formats Send Final Data Mapping document to client Client signs off on Data Mapping document Owner Client Data Integration Data Integration Client Note: The project description details listed above are only samples. Actual project plans are customized for each client, according to specific needs and circumstances. Project Task Descriptions The data integration tasks for which you, as a client, are primarily responsible are listed in Table 3. Table 3 Data Integration Task Descriptions Actions Task TIBCO Client Allocate a technical point of contact in the client organization to receive technical integration information. Provide the client with the contact information for the TIBCO Technical Integration Lead and a back- up contact. Provide TIBCO with the name, address, phone number, and time of availability of the technical point of contact who will receive technical integration documents and sample data. Confirm that technical contact has access to the TIBCO Client Extranet." Provide links and passwords to client technical contact, as necessary. Confirm access. Resolve any access problems, as necessary.

15 Project Task Descriptions 6 Table 3 Data Integration Task Descriptions (Cont d) Actions Task TIBCO Client Send Data Mapping document templates and file samples. TIBCO Customer Loyalty Management representative sends data mapping documents and sample files (and related links) for the baseline data integration. The set of documents sent to the client corresponds to the client s needs, as documented by their responses to the Onboarding Questionnaire. Client receives all appropriate data mapping templates, sample files, and related documentation (including this Integration Guide). Client initiates data file mapping project. Set up a secure FTP connection. Client provides completed data mapping documents and sample files for transaction, product, and retail stores data. Note: This step is repeated as necessary (round 1, round 2, etc.). TIBCO s native file format is XML, but flat files are accepted. Sample files must not contain valid credit card numbers. Configure secure file transfer protocol to allow access to ToInStorecard and FromInStorecard directories for the client. Deliver SFTP or FTPS username and password to client in a secure manner: by secure , phone, personal meeting. Verify that completed data mapping documents and sample files have arrived, are readable. Help the client make corrections. Download secure client software, as necessary. Complete SFTP or FTPS setup and log in. Attempt to upload a file to ToInStorecard directory. Attempt to download a file from FromInStorecard directory. Communicate attempts and results to TIBCO. Transfer completed data mapping documents and sample files to TIBCO over secure transfer (or , if secure path is not yet set up). Provide a point of contact to answer questions and make corrections relating to the file formats.

16 Project Task Descriptions 7 Table 3 Data Integration Task Descriptions (Cont d) TIBCO provides client with sample reward and sample customer files. Actions Task TIBCO Client Test file transfer process. Provide files for export to client. Test file transfer process. Test ability to consume export data. Provide technical assistance. TIBCO provides client with sample reward and sample customer files. TIBCO reviews files, ensures that transaction, product and retail store file formats have required fields. Notes: Transaction data should include customer (customer) data. This step is repeated as necessary (round 1, round 2, etc.). Client signs off on final data mapping document. TIBCO creates a process to import the client s transaction, product and retail store data into the client s account. In some cases, set up for transfer of historical transaction data file. More rarely, set up for transfer of address update file. Test file transfer process. Provide files for export to client. Check the documentation and sample files to ensure that all of the TIBCO required fields exist and that the file format is understood. The TIBCO QA department develops a test plan based on the approved data mapping document. Create import process for client-specific file formats if the data is not in TIBCO native format. Provide technical assistance. Test file transfer process. Test ability to consume export data. Provide technical assistance. Provide technical assistance. Ensure that TIBCO file format and transfer requirements are understood by technical associates at client. (For example: If the file format ever changes, the changes must be communicated to TIBCO. ) Client approves (via ) a final data mapping document that identifies the final formats to be used in production. Provide technical assistance. Set up plan to notify TIBCO and implement changes if a local (client-specific) file format changes. Provide technical assistance.

17 Project Task Descriptions 8 Table 3 Data Integration Task Descriptions (Cont d) Client creates a process to export transaction, product and retail store data to the ToInStorecard directory. Actions Task TIBCO Client Provide technical assistance. Ensure successful secure transfer capability. Automate uploading/downloading to/from sftp directories. Automate export of three files: transaction, product, and retail store data. Client creates a process to accept/consume the customer file and rewards file from the FromInStorecard directory. TIBCO tests and validates import process. Provide technical assistance. Test import process and validate data. Provide technical assistance. Provide technical assistance. Test regular end-to-end import process. This requires a period of live file transmissions from the client to ensure that systems on all sides are working correctly. Establish file monitoring process (to ensure timely file processing and catch errors). Turn on automated import process. Data Integration Team monitors the status of all incoming and outbound files. Turn on automated file delivery process. Provide technical assistance during test period. Establish an contact (ideally an alias for several people in the client organization) for any data integration/monitoring issues. Turn on production import process. Turn on production processes. Turn on production processes.

18 Data Exchange Overview 9 Chapter 3 Data Exchange Overview This section introduces the types of data that TIBCO exchanges with its clients, and briefly describes the available methods Batch file transfer, Real-time API, and On Demand transfer for performing these data exchanges. Topics Data Content Types, page 9 Data Exchange Requirements, page 13 Data Exchange Methods, page 15 Data Content Types TIBCO and its clients exchange the following types of data files: Transaction Customer Product Catalog Store Location Rewards List Profile Generic Event Notes: Import text files must be in ASCII format. Other text formats may cause imports to fail.

19 Data Content Types 10 The particular set of batch files your company provides or consumes depends on your particular experience management program. Typically, only a subset of the batch files is required. These files are identified during your onboarding process (when you first define and implement your program with TIBCO). Transaction Transaction files include data concerning purchases or returns of products or services, and also customer data. The Transaction File describes a client s (retailer s) transactions, and usually contains the transactions for a 24-hour period. The Transaction file includes data about the client s customer, the item (product or SKU), and the store or location associated with the transaction, as well as the quantities and amounts. Transaction data allows TIBCO Engage to award points and give other rewards based on offers. In addition, it enables targeting customers based on their purchase behavior. Typical TIBCO Engage implementations involve the loading of a historical transaction file that provides two years worth of data and a daily transaction file. The daily transaction files transmitted to TIBCO includes new transaction information. During initial setup, TIBCO will work with you to determine the historical and daily volume of data transfers. Customer Sometimes called Shopper data or experience management Member data, the Customer file data refers to a client s customers. Clients submit customer information together with transactions to be able to track behavior, report, target, and communicate to customers. After the initial loading of the customer data, customer updates (changes only or the delta) can be provided to TIBCO on a daily, weekly, or monthly basis, using the Transaction File format.

20 Data Content Types 11 Product Catalog The Product Catalog includes information for each individual product SKU or service supported by a client. Use this file if you want to: Present SKU-specific and category-specific offers. Target on past purchases of specific SKUs or categories. Collect category preferences from Customers and target on them. The Product Catalog file should always be the master file. All Product data will be overwritten on each file load. Product files can be transmitted daily, weekly, or monthly depending on how frequently your product catalog changes. Store The Store file provides a list of client stores or locations, and may include variations such as web-based retail channels. This data is required for any features that include store-based offers. Similar to the Product file, clients should always transmit their master store list to TIBCO since the latest transmitted file completely replaces the previous. Location The Location file includes store or sales channel information for each store. The Location file allows clients to target on store information, including store locations. For example, the zip/postal code of stores can be compared to the zip/postal code for experience management program members to determine their proximity to a store for targeting. Similar to the Product Catalog data load, the Location file should always be the master file. All store information will be overwritten on each file load. Rewards The Rewards file provides the current list of rewards due to be delivered to customers for a given period. It includes specific data about the reward and the recipient customer. Rewards refer to goods, gift cards, credits to a reward account, etc. Point-based programs generate rewards, typically by converting points into rewards, such as gifts or gift cards. Rewards data (for example, Reward Export files) generally go to the client or a client-designated third party for fulfillment of the rewards.

21 Data Content Types 12 List Lists are fixed groups of customers as defined by their addresses. Most marketing systems treat customer groups as lists; TIBCO Engage also provides native support of the concept. Exchanges of list information typically involve transferring lists from one system to another so that the recipient can perform an action based on the list. Clients can import customer lists to be used for sending within TIBCO Engage or for reporting. Clients can also export customer lists to be used in external systems. List data import includes addresses. Note: Because the address serves as a unique identifier, it allows access any other existing customer data. Profile A profile is a set of business rules that defines a group of customers. A profile dynamically defines a customer segment by filtering a customer population with targeting parameters such as gender, location, prior purchases, etc. For example, a profile might comprise a set of demographic criteria that are used to filter one list of customers in order to define a new list. Clients can define profiles in TIBCO Engage and export profile information from TIBCO Engage (for example, lists of customers who match a profile). Generic Event Use generic events to capture data about customer activities and behavior beyond the TIBCO Engage system. Examples of generic events include customer actions such as writing a product review, abandoning a product in an online shopping cart, playing a game online, or adding an item to a list of favorite products. This is not a standard option. The Update Import file allows clients to update addresses in the TIBCO Engage database. TIBCO Engage imports this batch file when the address is the only available identifier for the customer and TIBCO is not the party responsible for maintaining the "system of record. System of record refers to when the customers new and current addresses are maintained in another non-tibco application. In this case, the updated record is imported by TIBCO Engage to update its database. Refer to Update Import File for more information.

22 Data Exchange Requirements 13 Data Exchange Requirements TIBCO accepts data from clients in XML, flat delimited ASCII files, or flat fixed-format ASCII files. XML files are much less prone to error and require less maintenance over the medium and long term. Notes: Import text files must be in ASCII format. Other text formats may cause imports to fail. TIBCO also delivers data files to clients. There are two options for delivery: XML or a flat, delimited ASCII file. Data exchanges containing client data must be done via a secure file transfer system, never through an unsecured file transfer mechanism. However, the sample files used to set up data mapping standards, which have no live or sensitive data, can be sent via . Notes: Make sure your file names are consistent with the naming convention and in XML format. Make sure the data in your file is consistent with your data mapping. Validate your files using the TIBCO Engage XML Validation tool at Table 4 shows the methods(s) of data exchange that may be used for transferring each different type of data. As indicated in this table, there is not a one-to-one relationship between the method of transferring and the content-type of the data. To convey some types of data, two or more different methods may be used. For example, customer data may be updated by a Transaction file as a batch process or by a real-time API.

23 Data Exchange Requirements 14 Table 4 Data Exchange Methods used for Data Content Types Batch Transfer On Demand Transfer Real-Time API * Transaction Customer Product Catalog Location Transaction file (ISCLog.xsd) Transaction file (ISCLog.xsd) External Registration File For export only: Customer Registration File (Shopper.txt) Product File (ISCProduct.xsd) Store File Example*: GetTransactions (by Customer) Examples*: CreateShopper GetRegisteredCard GetShopperOffers GetShopperPointBalance RedeemReward Content Reward Reward File (RewardsSample.txt) List List.txt Import List (TIBCO Engage) Export List (TIBCO Engage) Example*: RedeemReward Profile Reward Catalog Points Export Profile (TIBCO Engage) Reward Catalog Import (TIBCO Engage) Point Expiration Forecast Report Export (TIBCO Engage) Example*: GetShopperPointBalance Generic Events ISCEventInstance.xsd Example*: CreateEventInstance Custom Questions CustomQuestions.csv Custom Question Import (TIBCO Engage)

24 Data Exchange Methods 15 * Note: For specific information about obtaining and updating data in real time, and API methods involved, see the TIBCO Engage API Reference. Each type of data mentioned in Table 4 is explained in the Data Content Types section. The TIBCO Customer Loyalty Management team can assist you with instructions, guidelines, and data mapping templates, and other tools to help you with data exchange processes. Data Exchange Methods The standard data exchange options include: Batch-file exchange Real-time SOAP API On-demand file exchange (TIBCO Engage) Each data exchange method supports different sets of data. During on-boarding, and depending on your requirements, TIBCO advises clients on the data exchange methods that are available and recommended. For example, you can import transactions as batch files but not on demand. During the process of defining and setting up the experience management program for a new client (the onboarding process) the emphasis is on Batch-file exchange and/or Simple Object Access Protocol (SOAP) APIs. Batch-file Exchange Batch file processing is ideal for high-volume, asynchronous processing. Most of the TIBCO Engage batch processes require files in XML format that adhere to common retail standards, such as ARTS and IXRetail. Note, however, that TIBCO can usually use files in your existing proprietary format, if you make arrangements with TIBCO during your onboarding process. TIBCO can write transformations to convert flat files in delimited text format (for example, commaor tab-separated value files) into usable XML files.

25 Data Exchange Methods 16 The TIBCO batch file integration works as follows: By default, you send data files using a secure transfer protocol (for example, SFTP) according to The TIBCO standard schedule, unless your company has negotiated a different batch file transmission schedule. TIBCO picks up these files and processes them, applying different transformation routines, as necessary, to convert the data into our required format. Inbound XML files are processed in their native format. Flat files that match The TIBCO standard file formats are handled using standard transformations. Flat files that do not match The TIBCO standard file formats are handled using custom transformations. Requests to change these file formats must be submitted through TIBCO's Customer Loyalty Management team and may incur a fee. (Consult your TIBCO Customer Loyalty Management representative for details.) In return, TIBCO posts the resulting files using a secure transfer protocol according to our standard schedule, unless your company has negotiated a different batch file transmission schedule. Refer to File Import Reports to see a file report that provides data about file imports. Batch File Exchange Benefits Flexible frequency based on your needs and capabilities. Rapid transfer of large quantities of data (up to 200K transactions or 200M per day). Flexible file requirements use common XML retail standards including ARTS and IXRetail, or use existing data feeds and TIBCO can write the transformations. Monitoring monitor your imports using the File Import Report. High security Visa CISP-certified, secure FTP. Real-time SOAP-based APIs The TIBCO Engage real-time SOAP-based APIs are used to add, retrieve, update, or delete one record at a time, with almost instantaneous response to the request for service.

26 Data Exchange Methods 17 Clients most often use real-time data transfer to get, add, or update customer data, or to get or update a customer s reward balance in operational systems. For data security, this data is sent via Hypertext Transfer Protocol over Secure Socket Layer (https). Real-time APIs are used for client companies who require real-time processing, and who can dedicate technical resources to the project. Typically, the real-time SOAP-based APIs provide for Point of Sale (PoS), ecommerce Shopping Cart sites, and/or Payment Terminals or Gateways. Implementing a real-time API requires additional effort, including programming, from the client s technical staff. This data transfer method is meant for experienced programmers already familiar with web services and programming via SOAP-based APIs. SOAP-based API benefits include: Near-instantaneous data exchange. Support for POS and/or Payment Terminals or Gateways. Different solutions for each channel. The ability to mix real-time with batch by location and/or channel. The TIBCO Engage SOAP-based APIs provide a simple language- and platform-independent interface that enables implementers to work in whatever language and platform they are most comfortable. The only requirements are that the implementation language and platform support https and XML. For more information about the TIBCO Engage SOAP-based APIs, please see: Data Exchange: Batch and API Differences API and batch file processing are the two key technologies for data transfer between TIBCO and its clients. There are some basic differences between two methods of data integration: API and batch processing. The two processes are designed to serve different needs, and as such behave differently. Record Level Business Process Application Batch Process: The batch process enforces certain data requirements and business logic based on the setup decisions made during the TIBCO onboarding process. Loyalty API: The Loyalty API will not apply any business logic to your incoming data regardless of application settings. API use assumes that business logic is implemented and applied in the application that calls the API. The application set up completed during the onboarding process does not apply to API processing.

27 Data Exchange Methods 18 Dates and Times Batch Process: Batch processing will apply default date and time stamps to various data. Loyalty API: The Loyalty API will not automatically populate all relevant date-time fields. However, you can populate them yourself using external business logic. Shopper Matching Batch Process: Using the batch process you can configure multiple matching criteria (unique customer identifiers). This ensures that shoppers are matched correctly. For example, this ensures that shoppers are correctly matched to transactions when you are using a transaction batch file. Loyalty API: The Loyalty API will only enforce address uniqueness when adding a record. If you use other customer identifiers, TIBCO suggests that you use available Loyalty API methods to check for uniqueness before adding the record. Bulk Data Processing Batch Process: The batch process is designed for inserting multiple records at once, thus much of the processing overhead is streamlined for this process. Loyalty API: The Loyalty API is meant for singleton manipulation of data. Although processing may occur almost instantaneously, only one record is processed at a time. Null Data Processing Batch Process: The batch process will not update a non-null field to a null. If null data is passed through by means of a batch file and there is existing data, the existing information in the database will be retained. Loyalty API: The Loyalty API will allow you to null out any field that is nullable.

28 Batch Imports 19 Chapter 4 Batch Imports This section provides information about batch file imports. Topics About Batch Files, page 19 Batch File Summary Descriptions, page 20 Data Content Types, page 22 Batch File Guidelines and Specifications, page 25 Upload Products Using Batch Files, page 26 Upload Transactions Using Batch Files, page 28 About Batch Files Use batch files to update the TIBCO Engage database and to provide updates with the latest information maintained by TIBCO. Most of the data exchanged between TIBCO and its clients is transmitted through batch files. Batch processing is a highly efficient method of transferring large volumes of data. File Processing Constraints Under normal circumstances, TIBCO Engage processes data at a rate of approximately 100,000 records per hour. Note that regularly scheduled file import processes are not intended to support the population or re-population of a client's entire collection of records, nor is normal file export processing set up to handle large "dumps," that is, downloads of the complete collection of a client's records. If you believe you may need to import or export batch files that far exceed the normal and customary processing limits, contact TIBCO Customer Loyalty Management.

29 Batch File Summary Descriptions 20 Batch File Summary Descriptions This section describes the batch files and their usage, and includes guidelines and specifications to help you define and format the batch files. Note: Import files must be ASCII text files. Other formats may cause imports to fail. This section includes detailed information about the following files: Transaction and Customer Import File Also called the Transaction file, describes a client s (retailer s) transactions, and usually contains the transactions for a 24-hour period. The Transaction file includes data about the client s customer, the item (product or SKU), and the store or location associated with the transaction, as well as the quantities and amounts. Product Catalog Import File - Sometimes called the Product file, this is a complete listing of all products offered by the client. To use TIBCO Engage features that include SKU-based programs or offers, you must supply product data. The Product and Store files are the only complete replacement files at this time. Each time the Product File is loaded, all previous product data is inactivated. Product files can be transmitted daily, weekly, or monthly depending on how frequently your product catalog changes. Store Import File - Provides a list of client stores or locations, and may include variations such as web-based retail channels. This data is required for any features that include store-based offers. Similar to the Product File, clients should always transmit their master store list to TIBCO since the latest transmitted file completely replaces the previous file. Reward Export File Provides the current list of rewards due to be delivered to shoppers for a given period. It includes specific data about the reward and the recipient customer.

30 Batch File Summary Descriptions 21 Customer Export File - TIBCO Engage extracts all customers whose profile information was updated in the system between the current time and the time at which the previous extract occurred. More specifically, a customer's record is included in the Customer Export File if there are changes in the following types of information in that customer's record: Customer Name Customer Address Address Opt-In/Out of Change in point balance Custom attribute data changes Tier status Loyalty membership status Customer Status Registered card/loyalty card. Generic Event Import File - This file allows clients to submit instances of events to be tracked with the Generic Event framework. The file includes new event data such as the event ID, subject, object, master value, and time. A wide variety of information can be passed using the generic event file; for example, instances of customers writing product reviews, instances of customers adding items to a wish list or favorites list, data about customer activities captured from social networking sites, and web analytics data about customer activities. Update Import File - This is not a standard option. The Update Import file allows clients to update addresses in the TIBCO Engage database. TIBCO Engage imports this batch file when the address is the only available identifier for the customer and TIBCO is not the party responsible for maintaining the system of record. System of record refers to when the customers new and current addresses are maintained in another non-tibco application. In this case, the updated record is imported by TIBCO to update its database. Refer to Update Import File for more information. The particular set of batch files your company provides or consumes depends on your particular experience management program. Typically, only a subset of the batch files is required. These files are identified during your onboarding process (when you first define and implement your program with TIBCO). Based on your business needs, TIBCO Customer Loyalty Management designates the batch files that your company needs to send and receive.

31 Data Content Types 22 Data Content Types TIBCO and its clients exchange the following types of data files: Transaction Customer Product Catalog Location Rewards List Profile Generic Event Transaction Transaction files include data concerning purchases or returns of products or services, and also customer data. The Transaction File is the data feed that clients most commonly provide to TIBCO. Transaction data allows TIBCO Engage to award points and give other rewards based on offers. In addition, it enables targeting customers based on their purchase behavior. Typical TIBCO Engage implementations involve the loading of a historical transaction file that provides two years worth of data and a daily transaction file. The daily transaction files transmitted to TIBCO include new transaction information. During initial setup, TIBCO will work with you to determine the historical and daily volume of data transfers. Customer Sometimes called Shopper data or Loyalty Member data, this data refers to our client s customers. Clients provide TIBCO customer information together with transactions to be able to track behavior, report, target, and communicate to customers. After the initial loading of the customer data, customer updates (changes only) can be provided to TIBCO on a daily, weekly, or monthly basis, using the Transaction File format.

32 Data Content Types 23 TIBCO returns new registration and updated customers so that clients can maintain their own records. Product Catalog The Product Catalog includes information for each individual product SKU or service supported by a client. Use this file if you want to: Present SKU-specific and category-specific offers. Target on past purchases of specific SKUs or categories. Collect category preferences from Customers and target on them. This file should always be the master file. All Product data will be overwritten on each file load. Location The Location file ncludes store or sales channel information for each store. The Location file allows clients to target on store information, including store locations. For example, the zip/postal code of stores can be compared to the zip/postal code for experience management program members to determine their proximity to a store for targeting. Similar to the Product Catalog data load, the Location file should always be the master file. All store information will be overwritten on each file load. Rewards Rewards refer to goods, gift cards, credits to a reward account, etc. Point-based programs generate rewards, typically by converting points into rewards, such as gifts or gift cards. Rewards data (for example, Reward Export files) generally go to the client or a client-designated third party for fulfillment of the rewards. List Lists are fixed groups of customers as defined by their addresses. Most CRM and marketing systems treat customer groups as lists, so TIBCO provides native support of the concept.