The Event Wire API

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.

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:

Field or Control	Definition
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.

The getparams call returns the list of document fields used on an Online Marketing dialog Landing Page. This list enables you to see the fields on the Landing Page and their exact spelling so that you can specify them properly as parameters in the processtrxn call to Event Wire. The getparams call 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:

Field or Control	Definition
EventWire_domain	The domain name of the machine where Event Wire is installed. (This is also the machine where the DES is installed.)
port	The port on which to connect to Event Wire. The default is port 80.
method	Specify 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	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 that contains 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, including their type, whether they are required, and any preset values, are listed in the following table. 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 selected, then an error message will appear.

Field or Control	Definition
Name	The name of the field. Notice that the column lists field names containing a $. Online Marketing uses this symbol to represent spaces. When specifying parameters in the processtrxn call, you must use the $ symbol in the field name instead of spaces.
Type	The field 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, then this column contains NA.
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, then 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.

The processtrxn call 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 discussed previously, Event Wire does not support Text Block or File fields. Therefore, 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, and 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:

Field or Control	Definition
EventWire_domain	The domain name of the machine where Event Wire is installed. (This is also the machine where the Dialog Server is installed.)
port	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	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 If 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. You specify this setting through the Event Wire Control Center. The trxnid appears 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. Values are: `0:` This is 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) Thisvalue indicates the type of content to be returned in the body of the response HTML page. Values are: `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 return type 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 setting can be useful in debugging.
useDefaultValue	(Optional) Used to preload the default values for Online Marketing Dialog documents or profile fields.
field_n	(Optional) 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, the profile field First Name 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, the profile field Favorite Color 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 multiple types of books can be specified for a field named Booktype, then to specify Mystery and Comedy you would write: 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 Registering External Systems.

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.

The gettrxnstatus call enables 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, the Event Wire response to a call may not reach the external system because of network problems. 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; thus, they are not returned by the gettrxnstatus call.

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

See Registering External Systems.

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:

Field or Control	Definition
EventWire_domain	The domain name of the machine where Event Wire is installed. (This is also the machine where the Dialog Server is installed.)
port	The port on which to connect to Event Wire. The default is port 80.
method	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	The external system making the call. The externid is set up via the Event Wire Control Center.
trxnid	(Optional) This value identifies the specific request for a particular external system.
startdate	(Optional) This value 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 through 24 hours (for example, to specify 1:00 a.m. on April 23, 2004, use 20040423010000).
enddate	(Optional) 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 through 24 hours (for example, to specify 2:30 p.m. 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 the externid with a startdate and an 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:

Field or Control	Definition
WireStatusCode	One of the Event Wire status codes.
WireStatusMsg	One of the Event Wire status messages.
WireNumTrxns	The number of transactions that match the criteria specified in the gettrxnstatus call.
WireTrxn-1	Information about the transaction specified. This field is returned only when the gettrxnstatus call specifies a trxnid.
date/time_called	The date and time that the call was made to Event Wire. The format is YYYYMMDDhhmmss, where hh is 0 through 24 hours (for example, 20040423173000 specifies 5:30 p.m. on April 23, 2004).
trxn_status_code	The status code for the transaction. If the transaction completed properly, the status code is 0.
trxn_status_message	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.

The short call 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.