Cisco Customer Response Applications Editor Step Reference Guide (3.1)
Http Contact Step Descriptions

Table of Contents

Http Contact Step Descriptions
Get Http Contact Info
Http Redirect
Send JSP
Send Response
Set Http Contact Info

Http Contact Step Descriptions


The steps in the Http Contact palette of the Cisco Customer Response Applications (CRA) Editor provide script designers with a way to enable scripts to receive HTTP requests and send HTTP responses in web-enabled server applications.


Note   Use steps in the Document palette to compose the server response. For more information, see "Document Step Descriptions."

The Http Contact palette contains the following steps:

Figure 6-1 shows the steps in the Http Contact palette as they appear in the Palette pane of the Cisco CRA Editor.


Figure 6-1   Http Contact Palette Steps



Note   If you apply any of these Http Contact steps to a contact that is not an HTTP contact, a ChannelUnsupportedException results.

Get Http Contact Info

Use the Get Http Contact Info step to map parameters from an HTTP request to locally defined variables.

The Get Http Contact Info step gets URL parameters, HTTP headers, cookies, or Common Gateway Interface (CGI) environment variables. This information is stored in variables you define using the Edit Variables window.

The Get Http Contact Info customizer window contains the following five tabs:

The following sections describe these tabs.

General

Use the General tab of the Get Http Contact Info customizer window to get trigger contact information.

Figure 6-2 shows the General tab of the Get Http Contact Info customizer window.


Figure 6-2   Get Http Contact Info Customizer Window—General Tab


Table 6-1 describes the property of the General tab of the Get Http Contact Info customizer window.

Table 6-1   Get Http Contact Info Property

Property Description

Http Contact

Contact variable that triggers the execution of the step.

Default is Triggering Contact, unless another contact is specified.

To use the General tab of the Get Http Contact Info customizer window to get trigger contact information, perform the following procedure:

Procedure

Step 1   If necessary, click the General tab.

The General tab of the Get Http Contact Info customizer window appears.

Step 2   From the Http Contact drop-down menu, choose the Contact variable you want to trigger the execution of the step.

Step 3   Click Apply.

You are now ready to configure the Headers tab of the Get Http Contact Info customizer window.





Headers

Use the Headers tab of the Get Http Contact Info customizer window to display the HTTP headers that you have mapped to local variables.

HTTP headers contain general information such as the type of browser or the version of HTTP used. Each header provides one value, which is identified by the header name.

As an example, you may use information from HTTP headers in advanced scripts to customize the behavior of your script for different HTTP versions or for different browser types.

HTTP provides four types of headers:

  • General—Used by both servers and clients (browsers).
  • Server—Used only by servers.
  • Request—Used only by clients (browsers).
  • Entity—Used by servers and by clients using POST or PUT methods.

Table 6-2 lists some common HTTP Request headers.

Table 6-2   Common HTTP Request Headers

Header Contents

Accept

Preferred media type

Authorization

Client user name and password

From

E-mail address of the client

Host

Host name and port number of the server receiving the original request

Referrer

URL of the source document

User-Agent

Browser type


Note   For detailed information about these or other headers, refer to any HTTP reference guide.

Figure 6-3 shows the Headers tab of the Get Http Contact Info customizer window.


Figure 6-3   Get Http Contact Info Customizer Window—Headers Tab


Table 6-3 describes the properties of the Headers tab of the Get Http Contact Info customizer window.

Table 6-3   Get Http Contact Info—Headers Tab Properties

Property Description

Header

Name of the header

Variable

Variable that maps to the header

To use the Headers tab of the Get Http Contact Info customizer window to map a local variable to a specific HTTP header, perform the following procedure:

Procedure

Step 1   If necessary, click the Headers tab.

The Headers tab of the Get Http Contact Info customizer window appears.

Step 2   Click Add.

The Header dialog box appears. (See Figure 6-3 .)


Figure 6-4   Header Dialog Box


Step 3   In the Header field, enter the value of the HTTP header.

Step 4   From the Variable drop-down menu, choose a String variable to be mapped to the HTTP header.

Step 5   Click OK.

The Header dialog box closes, and the values for the header and variable appear in the Header and Variable columns of the Headers tab of the Get Http Contact Info customizer window.

(If you want to modify the mapping of an existing header, select a header displayed in the Header/Variable list of the Header tab of the Get Http Contact Info customizer window, and then click Modify. The Header dialog box appears again. Follow the same procedure you used to add header and variable information.)

Step 6   Click Apply.

You are now ready to configure the Parameters tab of the Get Http Contact Info customizer window.





Parameters

Use the Parameters tab of the Get Http Contact Info customizer window to map the parameters for your script to variables you have defined in the Cisco CRA Editor.

When you fill in an HTML form, the values are typically passed as parameters to the web server. The Get Http Contact Info step reads the values of these parameters from the HTTP request and updates the current values of the local variables in your application.

The Get Http Contact Info step reads values from both the GET and POST methods.

Figure 6-5 shows the Parameters tab of the Get Http Contact Info customizer window.


Figure 6-5   Get Http Contact Info Customizer Window—Parameters Tab


To use the Parameters tab of the Get Http Contact Info customizer window to map a local variable to a specific parameter, perform the following procedure:

Procedure

Step 1   If necessary, click the Parameters tab.

The Parameters tab of the Get Http Contact Info customizer window appears.

Step 2   Click Add.

The Parameter dialog box appears. (See Figure 6-6 .)


Figure 6-6   Parameter Dialog Box


Step 3   In the Parameter text field, enter the parameter name.

Step 4   From the Variable drop-down menu, choose the variable you want to map to the parameter.

Step 5   Click OK.

The Parameter dialog box closes, and the parameter and variable names appear in the Parameter and Variable columns of the Parameter tab of the Get Http Contact Info customizer window.

(If you want to modify the mapping of an existing parameter, select a parameter displayed in the Parameter/Variable list box of the Parameter tab of the Get Http Contact Info customizer window, and then click Modify. The Parameter dialog box appears. Follow the same procedure you used to add parameter and variable information.)

Step 6   Click Apply.

You are now ready to configure the Cookies tab of the Get Http Contact Info customizer window.





Cookies

Use the Cookies tab of the Get Http Contact Info customizer window to map information from a local variable to a cookie.

A cookie is information maintained by the browser that is typically sent by an HTTP server.

The information in cookies can improve performance and convenience when a user repeatedly accesses the same web page. Most cookies store authentication or identifying information. Once the server authenticates a browser, it can send authentication credentials or other user identifiers to the browser cookie. The user can then access the web page without further authentication or identification.

Another use for cookies is to store a mapping identifier to a Session object so you can, on subsequent requests, retrieve the original Session object associated with the previous HTTP request and re-associate it to the new Http Contact.


Note   The use of cookies for authentication may present a security risk if a user leaves an authenticated browser unattended.

Figure 6-7 shows the Cookies tab of the Get Http Contact Info customizer window.


Figure 6-7   Get Http Contact Info Customizer Window—Cookies Tab


Table 6-4 describes the property of the Cookies tab of the Get Http Contact Info customizer window.

Table 6-4   Get Http Contact Info—Cookies Tab Property

Property Description

Cookie(s)

Name or names of the cookies mapped to variables

To use the Cookies tab of the Get Http Contact Info customizer window to map a local variable to a specific parameter, perform the following procedure:

Procedure

Step 1   If necessary, click the Cookies tab.

The Cookies tab of the Get Http Contact Info customizer window appears.

Step 2   Click Add.

The Cookie dialog box appears. (See Figure 6-8 .)


Figure 6-8   Cookie Dialog Box


Step 3   In the Name text field, enter the Cookie name.

Step 4   From the Variable drop-down menu, choose the variable you want to map to the Cookie.

Step 5   Click OK.

The Cookie dialog box closes, and the cookie name appears in the Cookie(s) column of the Cookie tab of the Get Http Contact Info customizer window.

(If you want to modify the mapping of an existing cookie, select a cookie displayed in the Cookie(s) list box of the Cookie tab of the Get Http Contact Info customizer window, and then click Modify. The Cookie dialog box appears. Follow the same procedure you used to add cookie and variable information.)

Step 6   Click Apply.

You are now ready to configure the Environment tab of the Get Http Contact Info customizer window.





Environment

Use the Environment tab of the Get Http Contact Info customizer window to map information from CGI environment variables to local variables.

Figure 6-9 shows the Environment tab of the Get Http Contact Info customizer window.


Figure 6-9   Get Http Contact Info Customizer Window—Environment Tab


Table 6-5 describes the properties of the Environment tab of the Get Http Contact Info customizer.

Table 6-5   Get Http Contact Info—Environment Tab Properties

Property Description

Name

Name of the environment variable

Variable

Variable that maps to the environment variable

Table 6-6 describes the purpose of each environment variable.

Table 6-6   Http Contact Environment Variables

Name Description

SERVER_NAME

The server's hostname, DNS1 alias, or IP address as it would appear in a self-referencing URL.

SERVER_PROTOCOL

The name and revision of the information protocol of the request, in the format: protocol/revision.

SERVER_PORT

The TCP port number of the request.

REQUEST_METHOD

The method of the request that was made, such as GET or POST.

PATH_INFO

Extra path information as given by the client. Scripts can be accessed by a virtual pathname, followed by extra information at the end of the path. The extra information is sent as PATH_INFO. The server decodes this information if it comes from a URL before it is passed to the script.

PATH_TRANSLATED

Translated version of PATH_INFO, with any associated virtual-to-physical mapping.

SCRIPT_NAME

A virtual path to the script being executed, used for self-referencing URLs.

QUERY_STRING

The information that follows the question mark (?) in the URL that references this script.

This information is the query information. Do not decode it. Always set this variable when there is query information, regardless of command line decoding.

REMOTE_HOST

The hostname making the request.

If the server does not have this information, it will instead set REMOTE_ADDR.

REMOTE_ADDR

The IP address of the remote host making the request.

AUTH_TYPE

The protocol-specific authentication method used to validate the user when the server supports user authentication and the script requires authentication.

REMOTE_USER

The authenticated user name when the server supports user authentication and the script requires authentication.

CONTENT_TYPE

The content type of the data for queries such as HTTP GET and HTTP POST that have attached information.

CONTENT_LENGTH

The content length of the data as specified by the client.

1DNS = Domain Name Service

To use the Environment tab of the Get Http Contact Info customizer window to map an environment variable to a local variable, perform the following procedure:

Procedure

Step 1   If necessary, click the Environment tab.

The Environment tab of the Get Http Contact Info customizer window appears.

Step 2   Click Set.

The Environment dialog box appears. (See Figure 6-10.)


Figure 6-10   Environment Dialog Box


Step 3   From the Variable drop-down menu, choose the variable you want to map to the environment variable and click OK.

The Environment dialog box closes, and the name of the variable appears in the Variable column of the Environment tab of the Get Http Contact Info customizer window, next to the selected environment variable.

Step 4   Click OK.

The Get Http Contact Info customizer window closes, and the name of the Http Contact variable appears next to the Get Http Contact Info step icon in the Design pane of the CRA Editor.





Http Redirect

Use the Http Redirect step to redirect the browser to go to a specified URL instead of responding directly to an HTTP request.

You can, for example, use this step to redirect the browser to a different server.

A script should use only one of the following steps from the Http Contact palette to respond to an HTTP request:

  • Http Redirect
  • Send JSP (Java Server Pages)
  • Send Response

If you use the Http Redirect step, you should not use either a Send JSP or Send Response step in the same sequence within a script, because using any one of these three steps moves the Http Contact into a final state when the response is returned back to the browser. The script cannot attempt to send another response back because one has already been sent. If, however, a script has some conditional logic, you can use one of these three steps in one condition and another in another condition.


Note   You can also use the Reject and Terminate steps from the Contact palette as responses to an HTTP request. For more information, see "Contact Step Descriptions."

Figure 6-11 shows the customizer window for the Http Redirect step.


Figure 6-11   Http Redirect Customizer Window


Table 6-7 describes the properties of the Http Redirect customizer window.

Table 6-7   Http Redirect Properties

Property Description

Http Contact

Contact variable that triggers the execution of the set.

Default is Triggering Contact, unless another contact is specified.

URL

URL to which the browser is redirected.

To use the Http Redirect customizer window to redirect the browser, perform the following procedure:

Procedure

Step 1   From the Http Contact drop-down menu, choose the Contact variable that will trigger the execution of the step.

Step 2   From the URL drop-down menu, choose a variable containing the URL, or click the Expression Editor (...) button to enter an absolute or relative URL.

Step 3   Click OK.

The Http Redirect customizer window closes, and the name of the triggering contact appears next to the Http Redirect step icon in the Design pane of the CRA Editor.





Send JSP

Use the Send JSP step to use Java Server Pages to generate dynamic output to a browser.

The Send JSP step lets you define local variables that you can pass to the JSP. When the Send JSP step executes, these variables are passed as parameters to the JSP. The JSP uses these parameters to format the output that is sent to the user.

You can use the Send JSP step instead of the Text Substitution for Keywords step (see the "Text Substitution for Keywords" section) if you are already using JSP or if you need the full capabilities of the Java programming language.

A script should use only one of the following steps from the Http Contact palette to respond to an HTTP request:

  • Http Redirect
  • Send JSP
  • Send Response

If you use the Send JSP step, you should not use either a Http Redirect or Send Response step in the same sequence within a script, because using any one of these three steps moves the Http Contact into a final state when the response is returned back to the browser. The script cannot attempt to send another response back because one has already been sent. If, however, a script has some conditional logic, you can use one of these three steps in one condition and another in another condition.


Note   You can also use the Reject and Terminate steps from the Contact palette as responses to an HTTP request. For more information, see "Contact Step Descriptions."

With JSP, you can access the parameter value by creating a parameter bean and by retrieving the parameter passed by the Send JSP step. The following example, which you create using a text editor, shows how to access and retrieve the parameter name.


Example 6-1   Sample JSP file (hello.jsp) for Accessing a Parameter
<html>
<body>
<!-- Create the "parameters" bean -->
<jsp:useBean id="parameters" type="java.util.Dictionary" scope="request"/>
<!-- Retrieve the parameter "name" -->
Hello <%= parameters.get("name") %>
</body>
</html>

Figure 6-12 shows the customizer window for the Send JSP step.


Figure 6-12   Send JSP Customizer Window


Table 6-8 describes the properties of the Send JSP customizer window.

Table 6-8   Send JSP Properties

Property Description

Http Contact

Contact variable that triggers the execution of the step.

Default is Triggering Contact, unless another contact is specified.

JSP Template

URL for the Java Server Pages.

Keyword

Keywords in the JSP form.

Local Variable

Variables to be mapped to the keywords in the JSP form.

To use the Send JSP customizer window to generate dynamic output to a browser, perform the following procedure:

Procedure

Step 1   From the Http Contact drop-down menu, choose the Contact variable to trigger the execution of the step.

Step 2   In the JSP Template text field, enter the URL that contains the Java Server Pages.

Step 3   To map a variable to a parameter that will be passed to the JSP, click Add.

The Parameter dialog box appears. (See Figure 6-13 .)


Figure 6-13   Parameter Dialog Box


Step 4   In the Keyword text field, enter the name of the keyword that identifies the parameter.

Step 5   From the Variable drop-down menu, choose the variable that will supply the value of the keyword.

Step 6   Click OK.

The Parameter dialog box closes, and the keyword and variable appear under their respective columns in the Keyword/Local Variable list box in the Send JSP customizer window.

Step 7   Click OK.

The Send JSP customizer window closes, and the name of the triggering contact and the URL of the JSP template appear next to the Send JSP step icon in the Design pane of the CRA Editor.





Send Response

Use the Send Response step to send a document to a browser.

The document, which is stored in a document variable, must be ready to be sent. You may, for example, place the Text Substitution for Keywords step before this step in your script to update the document with dynamic information before it is sent to a user.

A script should use only one of the following steps from the Http Contact palette to respond to an HTTP request:

  • Http Redirect
  • Send JSP
  • Send Response

If you use the Send Response step, you should not use either a Http Redirect or Send JSP step in the same sequence within a script, because using any one of these three steps moves the Http Contact into a final state when the response is returned back to the browser. The script cannot attempt to send another response back because one has already been sent. If, however, a script has some conditional logic, you can use one of these three steps in one condition and another in another condition.


Note   You can also use the Reject and Terminate steps from the Contact palette as responses to an HTTP request. For more information, see "Contact Step Descriptions."

Figure 6-14 shows the customizer window for the Send Response step.


Figure 6-14   Send Response Customizer Window


Table 6-9 describes the properties of the Send Response customizer window.

Table 6-9   Send Response Properties

Property Description

Http Contact

Contact variable that triggers the execution of the step.

Default is Triggering Contact, unless another contact is specified.

Document

Variable that stores the document to be sent.

To use the Send Response customizer window to specify a document to be sent, perform the following procedure:

Procedure

Step 1   From the Http Contact drop-down menu, choose the Contact variable that will trigger the execution of the step.

Step 2   From the Document drop-down menu, choose the variable that stores the document to be sent, or click the Expression Editor (...) button to enter the document expression containing the completed document.

Step 3   Click OK.

The Send Response customizer window closes, and the name of the triggering contact and the document variable appear next to the Send Response step icon in the Design pane of the CRA Editor.





Set Http Contact Info

Use the Set Http Contact Info step to set the values of HTTP headers and cookies in an HTTP response.


Note   Use this step in advanced scripts. You need specialized knowledge of HTTP to make this step useful.

The Set Http Contact Info customizer window contains the following three tabs:

The following sections describe these tabs.

General

Use the General tab of the Set Http Contact Step customizer window to specify the Contact variable that triggers the execution of the step.

Figure 6-16 shows the General tab of the Set Http Contact Step customizer window.


Figure 6-15   Set Http Contact Customizer Window—General Tab


Table 6-10 describes the property of the General tab of the Set Http Contact Info customizer window.

Table 6-10   Set Http Contact Info Property

Property Description

Http Contact

Contact variable that triggers the execution of the step.

Default is Triggering Contact, unless another contact is specified.

To use the General tab of the Set Http Contact Info customizer window to specify the contact variable that triggers the execution of the step, perform the following procedure:

Procedure

Step 1   If necessary, click the General tab.

The General tab of the Set Http Contact Info customizer window appears.

Step 2   From the Http Contact drop-down menu, choose the Contact variable you want to trigger the execution of the step.

Step 3   Click Apply.

You are now ready to configure the Headers tab of the Set Http Contact Info customizer window.





Headers

Use the Headers tab of the Set Http Contact Info step to map each HTTP header to a local variable or a valid expression from which the header value will be obtained when the step executes.

HTTP headers contain general information such as the type of browser or the version of HTTP used. When you design a browser script, you can add information to the HTTP header to identify the HTTP version or browser type you are using.

You can also, for example, use this tab to control how long the browser maintains a cached copy of a document, by setting a value for the Expires header.

Figure 6-16 shows the Headers tab of the Set Http Contact customizer window.


Figure 6-16   Set Http Contact Customizer Window—Headers Tab


Table 6-11 describes the properties of the Headers tab of the Set Http Contact Info customizer window.

Table 6-11   Set Http Contact Info—Headers Tab Properties

Property Description

Header

Name of the header

Variable

Variable that maps to the header

To use the Headers tab of the Set Http Contact Info customizer window to map a local variable to a specific HTTP header, perform the following procedure:

Procedure

Step 1   If necessary, click the Headers tab.

The Headers tab of the Set Http Contact Info customizer window appears.

Step 2   Click Add.

The Header dialog box appears. (See Figure 6-17 .)


Figure 6-17   Header Dialog Box


Step 3   In the Header text field, enter the value of the HTTP header.

Step 4   From the Variable drop-down menu, choose the variable to map to the HTTP header, or click the Expression Editor (...) button to enter an expression specifying the HTTP header.

Step 5   Click OK.

The Header dialog box closes, and the name of the variable appears in the Variable column of the Headers tab of the Set Http Contact Info customizer window, next to the selected header variable.

Step 6   Click Apply.

You are now ready to configure the Cookies tab of the Set Http Contact Info customizer window.





Cookies

Use the Cookies tab of the Set Http Contact Info customizer window to map each cookie to a local variable from which the cookie value will be obtained when the step executes.

A cookie is information maintained by the browser that is sent by the HTTP server in response to an HTTP request.

Figure 6-18 shows the Cookies tab of the Set Http Contact customizer window.


Figure 6-18   Set HTTP Contact Customizer Window—Cookies Tab


Table 6-12 describes the property of the Cookies tab of the Set Http Contact Info customizer window.

Table 6-12   Set Http Contact Info—Cookies Tab Property

gn="top">

clock timezone

Specify the time zone for the storage router.

ntp peer

Specify the name or IP address of the NTP server with which the storage router will synchronize date and time.

setup time

Run the wizard to configure the system date and time.

show clock

Display the current system date and time, including the system timezone.

Property Description

Cookie(s)

Name or names of the cookies mapped to variables

To use the Cookies tab of the Set Http Contact Info customizer window to map variables to cookies, perform the following procedure:

Procedure

Step 1   If necessary, click the Cookies tab.

The Cookies tab of the Set Http Contact Info customizer window appears.

Step 2   Click Add.

The Cookie Dialog Box appears. (See Figure 6-19 .)


Figure 6-19   Cookie Dialog Box


Table 6-13 describes the properties of the Cookie window.

Table 6-13   Cookie Dialog Box Attributes

Cookie Attributes Description

Name

Alphanumeric string that identifies the cookie.

Excluded characters include the semicolon, comma, and space. Names beginning with $ are reserved and can not be used by scripts.

Each cookie begins with a NAME = VARIABLE pair.

Variable

Variable assigned to the NAME attribute that identifies the cookie.

Each cookie begins with a NAME = VARIABLE pair.

Comment

Alphanumeric string that identifies the purpose of the cookie to the user.

The user may use this information to decide whether to establish or continue a session with this cookie.

Domain

Domain of hosts that can set a cookie.

The domain must contain at least two periods.

The default value is the host name of the server that generated the cookie response.

Max Age

Length of time the cookie exists.

A positive value represents the number of seconds before the cookie expires. A negative value means the cookie will be deleted when the web browser closes. A value of 0 causes the cookie to be deleted immediately.

Path

The subset of URLs in a domain for which the cookie is valid.

The default path is the path of the document described by the header that contains the cookie.

Secure

Cookie marked secure, so that it will be transmitted only to SSL1 servers.

Version

Decimal integer that identifies the version of the state management specification to which the cookie conforms.

1SSL = Secure Sockets Layer

Step 3   In the Name text field, enter the alphanumeric string that identifies the cookie.

Step 4   From the Variable drop-down menu, choose the variable that you want to map to the cookie.

Step 5   From the Comment drop-down menu, choose the variable that stores the purpose of the cookie to the user.

Step 6   From the Domain drop-down menu, choose the variable that stores the domain of hosts that can set a cookie.

Step 7   From the Max Age drop-down menu, choose the variable that stores the number of seconds before the cookie expires.

Step 8   From the Path drop-down menu, choose the variable that specifies the subset of URLs in a domain for which the cookie is valid.

Step 9   From the Secure drop-down menu, choose the variable that specifies the secure cookie.

Step 10   From the Version drop-down menu, choose the variable that identifies the version of the state management specification to which the cookie conforms.

Step 11   Click OK.

The Cookie dialog box closes, and the name of the cookie appears in the Cookie(s) column of the Cookies tab of the Set Http Contact Info customizer window.

Step 12   Click OK.

The Set Http Contact Info customizer window closes, and the name of the triggering contact appears next to the Set Http Contact Info step icon in the Design pane of the CRA Editor.