Event Wire and Your External System
This section discusses:
Passing the Landing Page URL to the external System.
Calling Event Wire.
Using required fields on Landing Pages.
Field matching rules in the dialog.
Displaying web pages to customers.
Checking the status of Event Wire.
Making changes to a Live dialog
For two of the calls to Event Wire (getparams and processtrxn), the external system must include the URL of the Online Marketing dialog landing page (the external event trigger entry). The external system can receive this URL dynamically, or the URL can be hard-coded into the external system (a static URL).
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.
The main call that the external system will make to Event Wire is the processtrxn call. This call specifies the Landing Page URL to be used, and includes any data to be passed to Online Marketing.
You can make this call to Event Wire in several ways:
You must decide how you will make the calls to Event Wire. This decision has several factors, such as: what you want displayed to your respondents, whether the Landing Page URL is dynamic or static, how easily you want to be able to track the successful completion of your calls from the external system, and the length of the call to be made (HTTP limitations).
When the Landing Page URL is passed dynamically, the external system must be able to store this information and then include it in the processtrxn call.
See The Event Wire API.
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:
Parameters specified using the GET method.
Parameters specified using the POST method.
Parameters specified in cookies.
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:
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:
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.
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 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:
Applications written in Perl, C/C++, Java, and so on.
Application server modules.
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.
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.
When a Landing Page uses required fields, Event Wire performs additional processing to ensure that the requirements are met for each processtrxn call. Specifying required fields can be helpful during the design and testing phase of your dialog to ensure that the external system is passing the appropriate parameters. However, using required fields in a dialog results in slower overall performance. Therefore, after testing the implementation to ensure proper operation, you may want to change the fields so that they are not marked required. This improves system performance but increases the chance of invalid or missing data (for example, if the matching field is not specified).
Along with other types of errors, missing required fields from the processtrxn call is considered an invalid request. Invalid requests are not logged in the Event Wire tables and thus are not retried. However, they may be logged in the DES log file, depending on the error logging level set.
Event Wire performs specialized data validation depending on whether the field is required or not:
If the field is required: An incorrect value passed in means that the entire transaction in error, and none of the document/profile fields are inserted.
If the field is not required: Event Wire ignores the bad data (inserts an empty value) and continues with the other fields in the request.
In either case, an error message appears in the Event Wire log files and the transaction report.
Note: If the matching field is not required and not passed to Event Wire, then Event Wire returns success even though the contact or company profile is not updated. This is because the Event Wire call is still correct, but the matching rule for Online Marketing is not fulfilled.
Online Marketing dialogs can use profile rules to determine whether a customer from the external system is known in the Online Marketing profiles.
If any matching rules are used by the dialog, you must ensure that your Event Wire call provides all of the matching fields in addition to the required fields on the Landing Page. Without specifying these fields, you cannot update the profile database.
If matching fields are not included in an otherwise valid Event Wire call, the data will be available through the CRM Analytics company reports, but no data will be saved in the profile database.
When an external system makes a call to Event Wire, it may take a few seconds for Event Wire to respond, depending on the configuration and load on the Online Marketing Dialog Server.
If the external system is to display a web page to the customer based on the response it receives from Event Wire, the external system can be set to display two different web pages to ensure that the user does not experience a long wait time: one page containing a confirmation from the external system that can be displayed immediately, and the other containing the Online Marketing dialog page that will be displayed as soon as Online Marketing responds to the call.
For example, imagine that the external system is an e-commerce storefront, and Event Wire is called after a customer has purchased an item. After the purchase, the storefront can display two browser windows. The first window displays the storefront’s confirmation page. The second window can contain the call to Event Wire with the appropriate parameters and display the landing page for the Online Marketing dialog. If the call to Event Wire does not succeed, the alternate URL configured in the Event Wire Control Center appears.
Under normal conditions, after Event Wire performs a call, it returns an HTML response to the external system, indicating the status of the call. However, because the external system and Event Wire communicate across a network, it is possible that either the call to Event Wire or its response will not arrive.
You should keep this possibility in mind when determining how to implement Event Wire with your external system. Depending on the goals of your dialog, you may want to log and review Event Wire responses received by the external system. Event Wire provides the gettrxnstatus call as well as the Report feature in the Event Wire Control Center that return the status of Event Wire transactions.
See The Event Wire API.
See Retried Transactions.
After your Online Marketing dialog is integrated with your external system, if changes are made to the live dialog, you may need to make changes to the external system call.
For example, if changes are made to the Landing Page, you need to check whether these changes affect the parameters being passed to Event Wire. If so, you should modify the call from the external system. If the parameters are not changed to match the fields on the Landing Page, a previously valid processtrxn call will become invalid and fail.