Event Wire and Your External System

Setting the Landing Page URL Dynamically

You can pass the Landing Page URL dynamically to the external system by either:

• Inserting the URL in a redirect command.

• Including the URL in a cookie.

After the URL is received by the external system, it must be saved during the customer’s session so that it can be included in the processtrxn call to Event Wire. The external system can save the URL in a variety of ways, including hidden fields and cached information during the customer’s browser session.

Setting a Landing Page URL Statically

When the customer arrives at the external system directly (without being redirected by an Online Marketing dialog), the Landing Page URL must be preset in the external system so that it can be passed to Event Wire in the processtrxn call. For example, the URL could be placed in a configuration file for the external system to read and set. The URL could also be placed in a GIF image tag on the page or in a cookie.

Specifying Parameters to Event Wire

Calls to Event Wire must specify two types of parameters: those specific to Event Wire, and those specifying the data to be submitted to the Online Marketing dialog.

The external system can pass parameters to Event Wire via the query string of an HTTP GET or POST call or via a cookie. (The query string is everything that follows the question mark in the HTTP call.) Cookies must only specify the Event Wire parameters.

Depending on how your external system is set up, it is possible to pass parameters to Event Wire using more than one of these methods. To avoid conflicts due to the same parameter being sent via different methods, Event Wire uses the following precedence rule:

1. Parameters specified using the GET method.

2. Parameters specified using the POST method.

3. Parameters specified in cookies.

4. If useDefaultValue = 1, default profile and document values.

This rule means that when the same parameters are specified in more than one method, Event Wire takes the value set in the method with the highest precedence. The parameters specified using GET have the highest, followed by those using POST, then those in cookies, and finally any default profile or document values if useDefaultValue is set to true.

If parameters contain any special characters, they must be URL-encoded before being sent to Event Wire.

Using IMAGE Tags

One way of making a processtrxn call is to embed an IMAGE source tag into an HTML page of the external system. This method is easy to implement: specify the Event Wire call as the image source. When the page is submitted, the call is made automatically.

However, when using an IMAGE tag you should keep in mind the following:

• Any respondent can view the Event Wire call by simply displaying the web page source.

• If Event Wire is not available, the page containing the image may take longer to load.

• You cannot retrieve the Event Wire result codes from an IMAGE tag, making it impossible to be notified whether a call was successful.

Using IMAGE tags to place calls to Event Wire is convenient because it is simple to integrate with web sites; just insert the IMAGE tag on the web page, and include the specific call. The following example shows an IMAGE tag.

<IMG SRC="http://estartup.com/Apps/DES/wire?method=processtrxn&
lpurl=http:%3a%2f%2festartup.com%2fApps%2fDES%2fmcp%3fr=iwedf139df
&externid=estore&First$Name=Joe&Last$Name=Smith" HEIGHT=0 WIDTH=0>

Some important notes on using IMAGE tags include:

If you are using IMAGE tags to call Event Wire on the subsequent page after a SUBMIT and that subsequent page contains links that a user might access and then click the Back button on the browser to re-access the subsequent page, then every Back access will make another Wire transaction for that user.

If you are not using IMAGE tags to call Event Wire but if an Event Wire call occurs for every SUBMIT, then a user submitting the same page more than once can cause this problem to occur.

You can do one of the following to avoid this problem:

1. If it is acceptable for Event Wire to be called multiple times by the external system but the business requirement is for the dialog to be triggered only once per visit, use a transaction ID (trxnid) to force actions involving a single user to be recorded only once. Event Wire will ignore subsequent transactions with the same trxnid after the first successful transaction.

   To implement this, add the trxnid parameter to the Event Wire call, and program a unique transaction id generator to create a distinct trxnid for each visit. For example, in the HTTP call you might add something similar to:

   &trxnid=110900123sdf

   You must also access the Event Wire Control Center to turn on the trxnid parameter requirement for that external system. If you do not change the settings in the Event Wire Control Center, then the trxnid will be ignored.

   Note: trxnid values should be unique among all the Event Wire transactions for a specific external system.

2. If the application server is experiencing heavy load and you want to reduce the number of Event Wire calls being made to only one per user, you must restructure how Event Wire is called.

   Do one of the following:

   • Do not call Event Wire using IMAGE tags on pages that users might return to or access more than once.

   • Programmatically check in your external system before calling Event Wire that this request has not already been submitted to Event Wire.

See The Event Wire API, .

Using Cookies

Using cookies to pass a parameter to Event Wire produces the same results as specifying the parameter in the query string of an HTTP GET or POST call.

When using cookies to pass parameters, you should keep in mind that when customers have cookies turned off in their browsers, the Event Wire call will fail. You may want to set the external system to check for this condition and use a preset Landing Page URL (lpurl) in the call to Event Wire.

When using cookies, you should only include the processtrxn specific parameters (trxnid, lpurl, externid, returntype, and method). The parameters that specify values for fields on the Landing Page should be included in the query string. (The query string is everything that follows the question mark in the HTTP call.)

To test that you are setting the cookies properly, use the Event Wire short method, which displays all the cookies that Event Wire can read in the current browser. For example: http://machine_name[:port]/DES/wire?method=short.

See The Event Wire API.

See Unofficial Cookie FAQ at http://www.cookiecentral.com/faq.

Programming Calls to Event Wire

Event Wire can be called by any application that can make HTTP requests, including:

• Web browsers.

• Applications written in Perl, C/C++, Java, and so on.

• Application server modules.

• HTML documents through IMAGE tags, JavaScript, and so on.

• Database callouts (for example, the Oracle UTL_HTTP package).

Writing a program to call Event Wire has the advantage that it is flexible. You can create a custom solution for each situation, and you can check status codes and take actions based on the results. However, altering existing programs can require significant resources and may not be an attractive prospect.

Consider the following programming scenarios:

An e-commerce site wants to use Event Wire to submit purchase data to the Online Marketing profiles. Here are two programming options to implement this scenario:

• Modify the external program that handles the confirmation of the purchase to also call Event Wire.

  This solution allows the program to check the status codes and resubmit any calls that were not completed. For example, if a network problem exists, the program can store the requests and retry them later.

• Insert JavaScript in the confirmation page to call Event Wire in a separate small window and display the results in that window.

  In this case, calls to Online Marketing will not be automatically resubmitted by the external system if they fail due to a network problem.

Another scenario is an external registration system that stores data into its own database, and wants to add this data to the Online Marketing profiles. In this case, you can write a Perl script to go through the database at night and call Event Wire with the new data for that day.

See The Event Wire API.