Event Wire API Reference

To use Event Wire, you must program your external system to make HTTP or HTTPS calls with the appropriate information. Event Wire returns the status of the requested operation to the external system via HTTP calls.

This chapter includes the following sections:

The Event Wire API
Status Codes and Messages
Sample Java Code

The Event Wire API

Event Wire is accessed through an HTTP API that accepts calls in URL encoding. Event Wire also accepts secure HTTP calls (HTTPS).

Event Wire supports the following calls:

getparams	Obtains the list of fields used on an Online Marketing Dialog Landing Page.
processtrxn	Passes to Event Wire the Landing Page URL to be accessed and the values for each field on the Landing Page.
gettrxnstatus	Obtains the status of Event Wire transactions.

See getparams.

See processtrxn.

See gettrxnstatus.

getparams

getparams returns the list of document fields used on an Online Marketing dialog Landing Page. This allows you to see the fields on the Landing Page and their exact spelling so that they can be properly specified as parameters in the processtrxn call to Event Wire. getparams is typically used only while developing the calls or while troubleshooting problems that arise from changes to a dialog.

getparams Syntax

To get the parameters for a particular landing page URL, you must make the following HTTP request (this request must be written as one line without any blank spaces):

http://<EventWire_domain[:port]>/Apps/DES/wire?
		method=getparams&
		lpurl=<landing_page_URL>

where:

EventWire_domain	is the domain name of the machine where Event Wire is installed. (This is also the machine where the DES is installed.)
port	is the port on which to connect to Event Wire. The default is port 80.
method	specifies the operation to be performed by Event Wire. For this call, method must be set to getparams. (The default value for method is processtrxn.)
lpurl	is set to the URL for the Online Marketing landing page. It should be URL encoded. For example: http://mystore.com/Apps/DES/mcp?q=iwedf139df

For example:

http://estartup.com/Apps/DES/wire?method=getparams&lpurl=
http%3a%2f%2festartup.com%2fApps%2fDES%2fmcp%3fq=
iwedf139df

getparams Return Values

Event Wire responds to all getparams calls with an HTML page, containing a status code, status message, and the fields used on the specified page.

The status code and status message are listed in the HTTP headers of the returned page, in the following syntax:

WireStatusCode: <status_value>
	WireStatusMsg: <status_message>

The fields used on the specified landing page are listed in the HTTP body of the HTML page. The fields are listed in the following table, including their type, whether they are required, and any preset values. Event Wire does not support Text Block or File elements, so if the landing page includes elements of that type, an error message will appear. Also, Event Wire does not work with survey dialogs, so if the dialog contains any documents with “Survey Document” checked, then an error message will appear.

Name	The name of the field. Notice that the column lists field names containing a “$”. This is the symbol used by Online Marketing to represent spaces. When specifying parameters in the processtrxn call, you must use the “$” in the field name instead of spaces.
Type	The field’s type (for example, Text Entry, Single Choice, and so on). If the page contains Text Block or File elements, then the getparams call will return an error page.
Required	Whether the field is required.
Valid Values	The acceptable values defined for the field.
Use Profile Default	Indicates whether the default profile value will be populated by Event Wire if the useDefaultValue parameter is 1. Values are Yes or No depending on whether the profile default will be used. If the field is not a profile field, this column contains “N/A”.
Document Default Value	Indicates whether the default value (if any) for the document field will be populated by Event Wire if the useDefaultValue parameter is 1. If the field is not a document-specific value or has no defaults, this column is empty.

If the getparams request is not successful, the WireStatusCode will not be 0, and Event Wire will return WireStatusCode and WireStatusMsg in the body of the HTML page.

See Status Codes and Messages.

processtrxn

processtrxn is the function used to pass the Landing Page URL to Event Wire, and to specify values for the fields on the Landing Page. After each processtrxn call, Event Wire accesses the Landing Page specified in the call and passes any values specified for the fields on that page.

This call also specifies whether any Online Marketing dialog pages can be displayed to the customer (through the returntype parameter).

As with the getparams call above, Event Wire does not support Text Block or File fields and so the processtrxn API will fail if the landing page contains any of those types of fields.

processtrxn Syntax

To make a processtrxn call, you must use the following HTTP request (this request must be written as one line without any blank spaces):

http://<EventWire_domain[:port]>/Apps/DES/wire?
		[method=processtrxn&]
		lpurl=<landing_page_URL>&
		externid=<external_sys_id>&
		[trxnid=<transaction_id>&]
		[returntype=<type_of_response>&]
		[dblog=<value_of_dblog>&]
		[useDefaultValue=1&]
		[ <field_1>=<field_value>&
		  <field_2>=<field_value>&
		  ...
		  <field_n>=<field_value> ]
		[ &<choice_field>=<choice_1>;...;<choice_n>]

where:

EventWire_domain	is the domain name of the machine where Event Wire is installed. (This is also the machine where the Dialog Server is installed.)
port	is the port on which to connect to Event Wire. The default is port 80.
method	specifies the operation to be performed by Event Wire. The default value for method is processtrxn. For this call, method is optional, since it is the default operation.
lpurl	is set to the URL for the landing page. It should be URL-encoded if it will be called programmatically. For example: http://mystore.com/Apps/DES/mcp?q=iwedf139df The landing page contains a submit button, Event Wire will attempt to simulate the submit information on that Landing Page, and the Online Marketing Dialog Server will log the transaction as a submit. If the Landing Page does not contain a Submit button (a Standalone page), the Dialog Server will log the transaction as a visit and not a submit. You can view the logged information through CRM Analytics.
externid	identifies the external system making the call. The externid is set up via the Event Wire Control Center. The only characters allowed in the externid are alphanumeric characters, underscores, and dashes.
trxnid	identifies the specific request for a particular external system. The only characters allowed in the trxnid are alphanumeric characters, underscores, and dashes. The maximum allowable length is 40 characters. For each externid, the trxnid can be configured as either required or optional. This is set through the Event Wire Control Center. The trxnid is displayed on the transaction reports generated through the Event Wire Control Center. If the transaction ID is set to Not Required in the External System Setup of the Control Center, then this field is entirely ignored for the external system, and it is not saved in the trxnid column of the log. However, if this setting is later changed, any subsequent trxnids will be logged.
dblog	(Optional) This parameter specifies whether successful transactions should be logged and the way in which they are logged. Valid failed transactions are always stored in the Event Wire database, regardless of the dblog value. After a transaction is updated from failed to successful during retry, it will still exist in the Event Wire database. 0: The default. Successful transactions will be completely logged in the Event Wire database. This value is backward compatible with previous versions of Event Wire. 1: Successful transactions will be logged in the Event Wire database, but without the URL. This option saves space in the Online Marketing database. 2: Successful transactions will not be logged in the Event Wire database. The exception to this is when trxnid is required; in this case, this value is treated the same as if dblog were set to 1.
returntype	(Optional) This is a number indicating the type of content to be returned in the body of the response HTML page. 0: The default. A clear 1x1 pixel GIF image is always returned in the body, regardless of whether the call succeeds or fails. 1: Indicates that an empty HTML page is always returned in the body, regardless of whether the call succeeds or fails. 2: Used to allow the external system to display an Online Marketing dialog page to the customer. This returntype indicates that if the processtrxn call succeeds, the body of the response page is either the content of the Standalone Page, or the content of the next web page in the flow (when the call is to a Landing Page). If the processtrxn call fails, the body of the response page is the HTML page specified in the Event Wire Control Center (External System Setup). 3: Indicates that the WireStatusCode and WireStatusMsg values are to be returned as text inside the body. This can be useful in debugging.
useDefaultValue	(Optional) is used to preload the default values for Online Marketing Dialog documents or profile fields.
field_n	(Optional) This is the name of a field on the landing page. This field must be written in the Online Marketing format (spaces are replaced with “$”). For example, for the profile field First Name, it would be written as First$Name. You can use the getparams call to obtain the fields on a landing page in this format. However, the required fields must be provided. All other fields are optional.
field_value	(Optional) This is the value to be assigned to the field. The value must be in URL-encoded format. If the field is a date field, it must match the format specified in the dialog Landing Page.
choice_field	(Optional) This is the name of a multiple choice field on the landing page. This field must be written in the Online Marketing format (spaces are replaced with “$”). For example, for the profile field Favorite Color, it would be written as Favorite$Color. You can use the getparams call to obtain the fields on a landing page in this format. However, the required fields must be provided. All other fields are optional.
choice_n	(Optional) When the field is a multiple choice field, you must specify each value separated by a semicolon. For example, if there are multiple types of books that can be specified for a field named Booktype, to specify Mystery and Comedy, then you would include the following: Booktype=Mystery;Comedy

For example:

http://estartup.com/Apps/DES/wire?method=processtrxn&
lpurl=http://estartup.com/Apps/DES/mcp?p=iwedf139df&externid=ecom5
&trxnid=123&returntype=2&dblog=1&First$Name=Sacha&Last$Name=Smith&
Email=sasha@esail.com&purchase=500

See getparams.

See Using the Event Wire Control Center.

processtrxn Return Values

Event Wire responds to all processtrxn requests with an HTML page, containing a status code and status message in the HTTP headers, and the return information specified by the returntype parameter in the HTTP body of the HTML page. This page can be viewed in the browser by using returntype=B.

The status code and status message are listed in the following syntax:

WireStatusCode: <status_value>
	WireStatusMsg: <status_message>

See Status Codes and Messages.

gettrxnstatus

gettrxnstatus allows you to query Event Wire for the current status of transactions submitted via the processtrxn call. Since Event Wire communicates with the external system across a network, it is possible that due to network problems, the Event Wire response to a call may not reach the external system. Using the gettrxnstatus call, you can have Event Wire send to you:

All responses to all valid transactions from a specific external system.
All responses to all valid transactions from a specific external system within a specified time period.
The response to a specific valid transaction.

Note. Invalid transactions (for example, those with missing parameters) are not stored in the Event Wire database, and thus are not returned by the gettrxnstatus call.

The Event Wire Control Center provides the Report feature that performs the gettrxnstatus function.

See Using the Event Wire Control Center.

gettrxnstatus Syntax

The syntax for the gettrxnstatus call is as follows (this request must be written as one line without any blank spaces):

http://<EventWire_domain[:port]>/Apps/DES/wire?
	method=gettrxnstatus&
	{externid=<external_sys_id> | 
	 externid=<external_sys_id>&trxnid=<transaction_id> |
	 externid=<external_sys_id>&startdate=<date_time>&
		enddate=<date_time> }

where:

EventWire_domain	is the domain name of the machine where Event Wire is installed. (This is also the machine where the Dialog Server is installed.)
port	is the port on which to connect to Event Wire. The default is port 80.
method	specifies the operation to be performed by Event Wire. For this call, method must be set to gettrxnstatus. (The default value for method is processtrxn.)
externid	identifies the external system making the call. The externid is set up via the Event Wire Control Center.
trxnid	(Optional) This identifies the specific request for a particular external system.
startdate	(Optional) This is the starting date and time of the time period used to select transactions from the Event Wire database. The format is YYYYMMDDhhmmss, where hh is 0-24 hours (for example, to specify 1:00am on April 23, 2004, use 20040423010000).
enddate	(Optional) This is the ending date and time of the time period used to select transactions from the Event Wire database. The format is YYYYMMDDhhmmss, where hh is 0-24 hours (for example, to specify 2:30pm on April 23, 2004, use 20040423143000).

Note. Depending on the responses you want to receive, you must specify either the externid alone, the externid and trxnid, or externid with a startdate and enddate.

gettrxnstatus Return Values

Event Wire responds to the gettrxnstatus request with an HTML page, containing a status code and status message in the HTTP headers, and the requested transactions in the body of the HTML page.

The status code and status message are listed in the following syntax:

WireStatusCode: <status_value>
	WireStatusMsg: <status_message>
	WireNumTrxns: <number_of_matching_transactions>
	WireTrxn-1: <externid>+<trxnid>+
		<date/time_called>+<trxn_status_value>+
		<trxn_status_message>

where:

WireStatusCode	is one of the Event Wire status codes.
WireStatusMsg	is one of the Event Wire status messages.
WireNumTrxns	is the number of transactions that match the criteria specified in the gettrxnstatus call.
WireTrxn-1	is information about the transaction specified. This field is returned only when the gettrxnstatus call specifies a trxnid.
date/time_called	is the date and time that the call was made to Event Wire. The format is YYYYMMDDhhmmss, where hh is 0-24 hours (for example, 20040423173000 specifies 5:30pm on April 23, 2004).
trxn_status_code	is the status code for the transaction. If the transaction completed properly, the status code is 0.
trxn_status_message	is the status message for the transaction.

An example of some headers containing a returned successful WireTrxn-1 field is given here:

WireStatusCode: 0 WireStatusMsg: Success WireNumTrxns: 1 WireTrxn-1: Mystore+a1203+20040223143000+0+Success

If the gettrxnstatus request is not successful, the WireStatusCode will not be 0, and Event Wire will return WireStatusCode and WireStatusMsg in the body of the HTML page.

See Status Codes and Messages.

short

short returns a list of all cookies in the current browser that are readable by Event Wire.

Except for the method=short name/value pair, it takes no parameters. Use this method for debugging only.

Status Codes and Messages

The following table lists the status codes and messages returned by Event Wire.

Status Code	Status Message	Description and Solution
0	Successful call.	This is the normal response for successful calls.
1	Could not connect to the Dialog Server: <hostname>	The Dialog Server is not running. (Not currently used)
2	Invalid Dialog Page URL: <lpurl>	The lpurl did not match a known URL. Verify that there are no typographical errors in the URL and that you are using the correct URL.
3	Missing Wire required parameters	Not all of the Event Wire required parameters were included in the call.
4	Invalid method	The method specified is not a valid Event Wire method. The method must be either getparams, processtrxn, or gettrxnstatus.
5	No available page exists for the lpurl	The Dialog Server dialog ID may have changed due to a change in the dialog’s status. To resolve this, ensure that the dialog is live.
6	Duplicate trxnid	The transaction was processed previously and was successful. This message only appears when Transaction ID is set to Required in the Event Wire Control Center.
7	DB connection failed	Event Wire cannot establish a connection with the database. The values set in the configuration file may be incorrect or another problem may be inhibiting the connection.
8	Event Wire internal error	Restart the application server. If this error persists, report it to PeopleSoft technical support.
9	Invalid external system ID	Either the externid was specified incorrectly or it was not set up in the Event Wire Control Center.
10	Missing dialog page required parameters (could not submit)	Fields on the Landing Page that are specified as required in the Online Marketing dialog are missing from the processtrxn call.
11	Invalid p, q, or r value	The tracking number (magic number) being passed to Event Wire is not valid. The URL may have been generated while the dialog was in Testing status, or a mistake was made when specifying a static URL in the external system. Check and correct the URLs being used.
12	The dialog is paused	The Online Marketing dialog is paused. Event Wire can only access live dialogs. The transaction will be automatically retried if the Scheduler has been set for this external system.
13	Invalid date	A date specified in the gettrxnstatus call is not in the correct format. Correct the date format and resubmit the call.
14	Invalid trxnid	The value of the trxnid parameter is invalid (such as incorrect characters, or too long).
15	Invalid returntype	The value of the returntype parameter is invalid. The returntype must be either 0, 1, 2, or 3.
16	The dialog is inactive.	The dialog is not in an active status to accept requests. (For example, it might be in the In Design or Complete status.)
17	Invalid trxn log option	The value for dblog is not valid (valid values are 0, 1, and 2).
18	Invalid useDefaultValue option	The value for the useDefaultValue parameter is not 0 or 1.
19	Invalid dialog parameter value	The input parameter value is not one of the acceptable choices.
20	Missing Event Wire required parameters (could not submit)	An Event Wire required parameter (not covered by the other error messages) is missing or invalid.
21	r number points to an external web link	The target of the VC Web Link is an external URL. Event Wire only supports “r” magic numbers that point to a dialog standalone or landing page.
99	Webserver or DCS error	Possibly due to the webserver's not being able to forward the request from Event Wire to the Dialog Server, or some other unexpected error. The transaction will be automatically retried if the Scheduler has been set for this external system.

Sample Java Code

The following simple Java example makes a processtrxn call and prints the status code and status message.

import java.lang.*;
import java.net.*;
import java.io.*;
	class wiretest
	{
		public static void main(String[] args)
			throws Exception
		{
			URL wire_url = new 
	URL("http://test.foo.com/Apps/DES/wire?lpurl=http%3a%2f%2f
test.foo.com%2fApps%2fDES%2fmcp%3fq=ST100tTEjyc_t8&externid=test2&returntype=3
&Email=x@a.com&useDefaultValue=1");
			URLConnection yc = wire_url.openConnection();
			System.out.println("WireStatusCode: " +
			yc.getHeaderField("WireStatusCode"));
			System.out.println("WireStatusMsg: " +
			yc.getHeaderField("WireStatusMsg"));
		}
}