This section details file import reports.
Topics
• About the File Import Report, page 57 • Creating a File Report, page 58
The TIBCO Engage File Import Report provides TIBCO staff and clients with information about the processing status of individual files. The File Import report tells you which files were successfully imported by TIBCO Engage, which report imports failed, and – where applicable – which reports were partially successful.
(Note that some files cannot be "partially successful": either the entire file is imported or the entire file fails.) The File Report also provides details and failure reasons for the records in a file that failed processing.
About the File Import Report
To set up a File Import report, use the controls at the top of the report. Among other things, these controls allow you to specify what period of time the report should cover.
For each file that was imported within the time frame that you specify, the File Import Summary report lists the following fields:
• File Import ID – This is a file ID assigned by the system in accession order.
Each new file is assigned the next number, so higher numbers indicate a more recent file. Files are listed from highest ID to lowest (within the specified time frame for the report)
• File Name – Name composed of standard filename elements, including date.
• Start Date – The start date of the file generation.
• End Date – The end date of the file generation.
Creating a File Report
|
58• File Type – The type of file that was imported, for example:
TransactionImport, StoreImport, ProductImport, etc.
• Status – Successful or Failed.
• Details link – Click this link in the File Import Summary report to see the File Import Details report for the associated file.
The File Import Details report has two variations:
• Failure: If the file import failed, the File Import Details report lists information in fields titled "Failure Reason and Suggested Action."
• Success: If the file import succeeded, then the File Import Details report lists file data and statistics, including the record type, the number of records in the file, and the number of records that were successfully transmitted.
Creating a File Report
The File Import report provides status updates and other useful information about the results of batch imports or list file uploads. It also provides access to details about each import file.
Use TIBCO Engage to set up and generate this report with these steps:
1. Navigate to Reports>Specialized>File Import Report.
2. Click File Import Report.
The File Import Report opens.
3. Use the controls at the top of the report to set up this report.
If the time period specified by default is not the time period that you want the report to cover, select a new date range or period immediately. Do not wait for the default report to compile if it is not what you want to see. To select a time frame for the report, choose from the drop-down list of standard options, or customize the time frame by specifying a range of dates. If you change the time frame, click View Report to be sure that the report is regenerated.
Note: In the case of certain files, a file import may partially succeed (some records are transmitted but others are not) and the file import is considered a success. In this case this report will specify the number of records successfully transmitted, and the number of records that failed to be transmitted.
Creating a File Report
|
594. Navigate through the report by using the arrow icons. You can also find data by searching for strings that occur in the report: use the data entry box in front of the Find control.
To create another copy of the report with a different format, select a formatting option from the Select a Format drop-down box, then click Export.
Click the Printer icon to print the current report.
|
60Chapter 8 Email Update Import File
This section provides information about the email update import file.
Topics
• Email Update Import File Use Cases, page 61
• Standard XML Sample File and XSD Schema, page 61 • File Usage Guidelines, Data Elements and Formats, page 62 • Samples and Formats of Email Update Files from Clients, page 62 • Email Update File and Record Failures, page 63
For special circumstances, TIBCO provides an Email Update Import file. This is not a standard file import option.
The Email Update Import file allows clients to update email addresses in the TIBCO Engage database. This batch process is used when TIBCO Engage does not maintain the “system of record”, that is, when the “master version” of each customer’s email address is maintained in another, non-TIBCO application. In this case, the updated record is imported to update the TIBCO Engage database.
This import is included because the email address is the TIBCO Engage primary means of identifying customers, and there is no way to update email addresses using the Transaction and Customer Import File.
Contact TIBCO for information about using the Email Update Import file.
General Description
The email update file is simply a file that includes the old email address and the updated email address. If TIBCO Engage can successfully identify a record based on the email address, it will update the email to the new address provided in the file.
Email Update Import File Use Cases
|
61Initial Integration Notes
This integration is optional. The Email Update Import file is used only when TIBCO Engage is not the system of record (that is, the definitive, “master version”
of the customer’s records are maintained by the client) and when the email address on file with TIBCO Engage must be identical to the address maintained by the client.
Email Update Import File Use Cases
The Email Update Import file is typically used in the following cases:
• The client maintains its customer records and wants to synchronize that data with the TIBCO Engage corresponding data on a periodic basis.
• Customers update their information on the client’s website or system, including their email addresses.
These scenarios require data integration to enable the creation and transfer of the Email Update Import File.
Standard XML Sample File and XSD Schema
Note: At present, because of its simplicity, the Email Update file is processed as a flat file. There is no XML schema for this file. Refer to sections File Usage
Guidelines, Data Elements and Formats and Samples and Formats of Email Update Files from Clients for details.
File Usage Guidelines, Data Elements and Formats
|
62File Usage Guidelines, Data Elements and Formats
If the client maintains the “master list” of customer email addresses, then it can send TIBCO a list of email addresses to be changed in the TIBCO Engage database. In this file, each record consists of a pair of email addresses: the first email is the old “previous” email address; the second address is the new
“replacement” email address. Each old email address is used to identify a customer record in the TIBCO Engage system. If a record with a matching old email address is found, the record is updated by replacing the old address with the new address.
Samples and Formats of Email Update Files from Clients
Sample Email update file in CSV format:
[email protected], [email protected] [email protected], [email protected]
Table 9 Email Update Data Table TIBCO Engage Field
Name Description DataType Size Sample Data
OldEmailAddress Previous Email Address: Use this field to populate the source email address
String 100 [email protected]
NewEmailAddress Current Email Address: Use this field to populate the updated email address
String 100 [email protected]
Email Update File and Record Failures
|
63Email Update File and Record Failures
The following table includes the error codes that apply to Email Update file imports.
Table 10 Email Update File Errors and Error Notes
Error Code Error Type Error Reason Suggested Action
1 Invalid E-mail
address.
Email address format is invalid.
Fix the email address and resend the file. An Email address cannot include spaces and has to include the following
elements:<alphanumeric>
@<alphanum eric>.<alpha> For additional, more specific details, see the "Email Address Validation Criteria " section.
2 Record failed to
update
Old Email address duplicates in dropped file
No action necessary.
Records with errors are skipped.
3 Record failed to
update
New Email address duplicates in dropped file
No action necessary.
Records with errors are skipped.
4 Record failed to
update
New Email address exists as old email address for another record
No action necessary.
Records with errors are skipped.
5 Record failed to
update
New Email Address already exists in the system
No action necessary.
Records with errors are skipped.
6 Record failed to
update
Old Email Address does not exist in the system
No action necessary.
Records with errors are skipped.
Email Update File and Record Failures
|
64Some of the above error types are described below with more specific information and examples.
11 File failed This file is a duplicate of a
previously sent file.
Check the file sending process to ensure it is working properly and sending the correct file. If this file is expected to be a duplicate, ignore this notice.
12 File failed The file failed to import
because it does not include any records.
Check the file sending process to ensure it is working properly and sending the correct file. If this file is expected to be empty, ignore this notice.
13 File failed The file failed to import
because of a general error.
Contact TIBCO for diagnosis.
14 File failed The file failed to import of a
data format error.
You can correct the file by fixing data format errors.
Common issues include having an alphanumeric value in a date field.
15 File failed The file failed to import
because the file type is incorrect.
This file was not
recognized by our process.
Common reasons for this issue include misnaming the file or accidentally sending a different file.
You can correct this issue by sending the correct file.
17 File failed The file failed to import
because it failed a validation rule.
Contact TIBCO for diagnosis.
Table 10 Email Update File Errors and Error Notes (Cont’d)
Error Code Error Type Error Reason Suggested Action
Email Update File and Record Failures
|
65Email Update File Error Descriptions and Related Notes • New Email address duplicates in dropped file
A file failure will occur if the client’s file includes multiple entries with the same new email address, for example:
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
The records are not processed and the file is rejected with an error: “New Email address duplicates in dropped file”
• Old Email address duplicates in dropped file
A file failure will occur if the client’s file includes multiple entries with the same old email address, for example:
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
The records are not processed and the file is rejected with an error: “Old Email address duplicates in dropped file”
• New Email address exists as old email address for another record A file failure will occur if the client’s file includes an updated email address that is used as an old email address in another record, for example:
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
— [email protected],[email protected]
The records are not processed and the file is rejected with an error: “New Email Address exists as old email address for another record.”
SSO Integration
|
66Chapter 9 SSO Integration
This chapter provides an information about Single Sign On (SSO) integration.
Topics
• SSO Overview, page 66 • How SSO Works, page 67 • Implementation Details, page 70
• Return Codes for SSO Authentication, page 72
SSO Overview
The TIBCO Engage Single Sign On (SSO) feature provides shoppers with access to loyalty- building presentations and offers, such as your ecommerce sites and our integrated loyalty sites, without requiring them to log in twice.
To implement SSO, your development staff must provide some coding to the TIBCO integration team to perform integration testing. The resulting SSO
technology provides you with a secure means of giving your shoppers convenient and secure access to experience management program information.
To use SSO, you must implement the following functions:
• When a customer logs in, use a TIBCO Engage real time API call to obtain an Authentication Ticket for that customer.
When a customer opts into the experience management program, use a TIBCO Engage real time API to create a new customer record, if one does not already exist.
• When a customer clicks a link to the experience management program pages hosted by TIBCO Engage, retrieve the Authentication Ticket from the TIBCO Engage API Call and pass it with the URL as a query string.
• Provide a logout and error handling page.
How SSO Works
|
67• When shoppers need information other than their password, use the TIBCO Engage Real Time API to update the customer information. The TIBCO Engage Real Time API can also be used to mark a customer as Inactive.
Secure Data Transfer
TIBCO Engage is Visa CISP (Cardholder Information Security Program) compliant. This means that all data with sensitive information transferred between TIBCO Engage and the retailer must be transmitted using an encrypted protocol. Single Sign On uses 128-bit SSL for all connections and encrypts and encodes authentication tokens to ensure they are reasonably impervious to attack.
This includes both the API call and the link to the customer application.
How SSO Works
TIBCO Engage provides a secure mechanism to pass customer credentials to the TIBCO Engage system and authenticate the customer on the TIBCO Engage customer-facing web site without requiring the customer to perform a second login.
Single Sign On must handle the following five basic scenarios:
1. Customer opts into the experience management program
When your customer is on your web site and agrees to join (opt in), you must create a customer record in the TIBCO Engage database using the Real Time API that we provide. The interface provides for exception handling in the case where the customer already has a record in the database.
2. Customer requests access to his or her experience management program information
When the customer clicks on a link on your site to review personal experience management program information, your web site must retrieve the customer’s email address and pass it to the TIBCO Engage API. The TIBCO Engage API will respond with an Authentication ticket for that customer, which is good for 30 minutes. Encode this ticket as a query string parameter named auth_t and add it to the URL of the TIBCO Engage - hosted experience management program pages. TIBCO Engage parses and decrypts the query string information, and then validates the authentication of the customer before redirecting the customer to the experience management program information.
How SSO Works
|
683. Customer’s credentials are not accepted
When a customer’s credentials are not accepted by TIBCO Engage for any reason, TIBCO Engage will return an HTTP redirect response to a web page that you host.
This response contains the error type so that you can provide appropriate messaging to your customer about the problem, or take other programmatic action to resolve the problem (like retrieve a new public key to replace one that has been rotated). For more information about error codes, refer to Return Codes for SSO Authentication, page 72.
4. Customer logs out of the experience management program pages
When the customer clicks the logout link on our site, we will return an HTTP redirect response to the same URL that you host with a return code of 2 on the query string that implies that the customer logged out of our system. For more information about error codes, refer to Return Codes for SSO Authentication, page 72.
5. Customer makes changes to their information
When the customer makes changes to the same information that we store about your customer (email address, mailing address, etc.), you must use the Real Time API we provide to update the information in the TIBCO Engage database. It is particularly important to keep the customer email up to date so that the customer can always access their loyalty information.
How SSO Works
|
69Figure 1 SSO Process Flow Diagram
Implementation Details
|
70Implementation Details
This section provides information on implementing SSO via API.
Engage API Call
• This is a SOAP call
• Basic authentication using your “API User” is required. (Note: Refer to XXX for how the API User is created using the TIBCO Engage
application.)
• This call must be done over SSL 1. GetShopperAuthenticationToken
This API returns Authentication Ticket for a given customer. Email address of customer is required.
Implementation Details
|
71This API returns Authentication Ticket for a given Customer. RetailerShopperID of the customer is required.
Sample Request
Return Codes for SSO Authentication
|
72<GetShopperAuthenticationTokenByRetailerIDResult>31-2F-43-44-32-55-6E-37-78-39-64-47-30-69-73-79-51-7F-53-65-2F-6E-38-66-61-4A-71-35-55-4C-52-36</GetShopper AuthenticationTokenByRetailerIDResult>
</GetShopperAuthenticationTokenByRetailerIDResponse>
</soap:Body>
</soap:Envelope>
Query String Authentication Parameters
The value of the ShopperLoginToken should then be passed in as the auth_t parameter to the requested Loyalty Pages.
Example
/../..?auth_t=-64-35-37-79-69-69-30-71-72-2F-57-66-4E-70-35-59-30-73-39-4D-44-73-2F-70 -70-67-6B-34-30-56-4F-35-46-72-56-61-58-50-53-55-48-73-3D
Configuration of Client SSO Handler
As mentioned above, you can configure one URL for handling SSO logout and error scenarios. To configure this URL you will have to work with TIBCO and provide the URL so it can be set in our system. This URL can also be changed at any time from its initial setup. Again, the change can only be handled through TIBCO.
Return Codes for SSO Authentication
The SSO functions can fail to authenticate a customer’s credentials for several reasons. When that happens, the software directs the user’s browser to a URL that you code and host with an ‘rc=’ query string parameter containing one of the following values:
• (-1) Decryption of Customer Credentials failed (the most probable cause is it is an invalid ticket)
• (-4) Client GUID is missing from the query string and the cookies sent to the server
• (-5) Email address is invalid
• (-6) Customer record was not found
• (-7) Customer account is disabled
Return Codes for SSO Authentication
|
73• (-8) Customer account is deleted
• (-9) Authentication failed – Ticket expired
• (1) Redirect to the signup page. The signup page was requested with a missing authentication cookie – this implies that the customer needs to be directed to the initial signup page on your site to complete the first couple of steps of signup and then be transferred to TIBCO Engage customer pages using SSO.
• (2) Redirect to logout page. Customer logged out of TIBCO Engage pages.
• (3) Redirect to Customer Account page. Customer chose to edit account preferences, which must be done on your site.
• (3) Redirect to Customer Account page. Customer chose to edit account preferences, which must be done on your site.