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

Table of Contents

Document Step Descriptions
Cache Document
Create File Document
Create URL Document
Create XML Document
Extract XML Document Data
Text Substitution for Keywords
Write Document
XSL Transform Document

Document Step Descriptions


The steps in the Document palette of the Cisco Customer Response Applications (CRA) Editor provide script designers with a way to handle various kinds of documents.

The Document palette contains the following steps:

The Document palette provides three types of Document steps, which are usually used in the following order: source, transformation, and output steps.

  • Source steps—Used to define a document object using different parameters, such as a URL or a file name. Three Document steps are Source steps:
    • Create File Document
    • Create URL Document
    • XSL Transform Document

Source steps define the parameters for a document variable but do not read data at the time they execute. You can use the Cache step to cause the system to obtain and store the document defined by a Source step. Otherwise, the document is read when passed to a transformation or output step.


Note    Other source steps used for documents are DB Get (a Database step), Recording (a Media step), Get User Info (a User step), and Get Session Info when retrieving document objects stored in the session (a Session step). For information on these steps, see the appropriate chapters in this guide.

  • Transformation steps—Used to process an input document and store the results in an output document. The output document can use the same variable as the input document. Three Document steps are Transformation steps:
    • Create XML Document
    • Cache Document
    • Text Substitution for Keywords
  • Output steps—Used to direct a document to an output destination, such as a URL or file system. Two Document steps are Output steps:
    • Write Document
    • Extract XML Document

Note    Other steps can act as output steps for documents. You can use any Media or Prompt step to accept a document as input representing a prompt to be played back. You can use the Set User Info step (a User step) to upload a document as the spoken name for the user. You can use the Attach To eMail step (an eMail step) to attach a document to an e-mail message. You can use the DB Write step (a Database step) to upload a document to a database. You can use the Send Response step (an Http Contact step) to send a document as a response to an HTTP request. You can use the Set Session Info step (a Session step) to store a document in the session context.

Figure 11-1 shows the steps in the Document palette as they appear in the Palette pane of the CRA Editor.


Figure 11-1   Document Palette Steps


Cache Document

Use the Cache Document step to perform an input/output (I/O) operation (such as reading a file or making an HTTP request) and cache the resulting document in the memory buffer.


Note   Because the Cache Document step can use a great deal of memory, you should use it with caution.

The I/O operation is specified by the document defined in a preceding step (such as Create File Document or Create URL Document) or by a document expression that contains a hard-coded document. When the Create File Document or Create URL Document step executes, it creates the document variable but does not send the URL request or access the file system.

The actual I/O operation occurs when another step (such as Send Response or Write Document) references the document. The Cache Document step allows you to complete the I/O operation before executing any subsequent steps.

Example 11-1 shows script pseudocode demonstrating how you can use the Cache Document step.


Example 11-1   Using the Cache Document Step
doc=Cache Document(doc)
. . .
SendResponse(doc)

In Example 11-1, the Cache step makes the HTTP request to mybank.money.com. Without the Cache step, the I/O does not occur until the Send Response step executes.

Figure 11-2 shows the customizer window for the Cache Document step.


Figure 11-2   Cache Document Customizer Window


Table 11-1 describes the properties of the Cache Document customizer window.

Table 11-1   Cache Document Properties

Property Description

Document

The document you want to obtain and cache from the Document variable drop-down list.

Maximum Buffer Size (KB)

The maximum buffer size that you want to use.

Assign this value carefully because the buffer size you assign may affect system performance. The Maximum Buffer Size can be set to 0 to request everything to be cached in memory. If the document is bigger than the specified size, it will be truncated.

To use the Cache Document customizer window to cache a document in the memory buffer, perform the following procedure:

Procedure

Step 1   From the Document drop-down menu, choose the variable that stores the document value.

Step 2   In the Maximum Buffer Size (KB) field, enter a value directly or take one of the following actions:

  • From the Maximum Buffer Size (KB) drop-down menu, choose the variable that stores the maximum buffer size value.
  • Click the Expression Editor (...) button and enter an expression that specifies the maximum buffer size value.

Step 3   Click OK.

The Cache Document customizer window closes, and the maximum buffer size variable appears next to the Cache Document step icon in the Design pane of the CRA Editor.





Create File Document

Use the Create File Document step to define a document variable by referencing the file name you supply.

The Create File Document step does not read the file. The script reads the file when the document variable is used by another step, such as the Write Document step or the Create XML Document step.


Note   The Create File Document step (a Document step) is exactly equivalent in functionality to using the FILE[filename] expression form for a Document.

Figure 11-3 shows the customizer window for the Create File Document step.


Figure 11-3    Create File Document Customizer Window


Table 11-2 describes the properties of the Create File Document customizer window.

Table 11-2   Create File Document Properties

Property Description

Filename

Path and file name for the document

Document

Document variable that represents the specified document

To use the Create File Document customizer window to define a document variable, perform the following procedure:

Procedure

Step 1   In the Filename field, enter a value directly or take one of the following actions:

  • From the Filename drop-down menu, choose the variable that stores the filename value.
  • Click the Expression Editor (...) button and enter an expression that specifies the filename value.

Step 2   In the Document text field, enter the name of the document variable that stores the document value.

Step 3   Click OK.

The Create File Document customizer window closes.





Create URL Document

The Create URL Document step defines a document variable by referencing a URL you supply.

The Create URL Document step does not issue the HTTP request. The actual request occurs when the document is used by another step, such as the Send Response step or the Send JSP step.

For a GET HTTP request, parameters are usually appended to a URL in an HTTP request to provide data required to execute the request. For example, the following HTTP request is made when the value of the total parameter is set to 500.

For POST, the parameters are passed in the body of the HTTP request as if entered in an HTML form.

Figure 11-4 shows the customizer window for the Create URL Document step.


Figure 11-4    Create URL Document Customizer Window


Table 11-3 describes the properties of the Create URL Document customizer window.

Table 11-3   Create URL Document Properties

Property Description

URL

URL for the document.

Method

Method to use if the URL represents an HTTP request.

  • The GET method appends parameters to the URL. (This step is equivalent to using the document expression form: URL[url?name=value,name=value].)
  • The POST method includes the parameters as if they were entered in an HTML form.

Parameters

Name and value pairs that form a parameter string to send to the web server.

The URL-encoded parameter string allows special characters.

Document

Variable in which the resulting document object is stored.

To use the Create URL Document customizer window to define a document variable, perform the following procedure:

Procedure

Step 1   In the URL field, enter a value directly or take one of the following actions:

  • From the URL drop-down menu, choose the variable that stores the URL value.
  • Click the Expression Editor (...) button and enter a relative or absolute URL.

Step 2   In the Method field, click the Get radio button to append parameters to the URL, or click the Post radio button to include parameters as if they were entered in an HTML form.

Step 3   To map a parameter to a local variable, click Add.

The Parameter dialog box appears. (See Figure 11-5 .)


Figure 11-5    Parameter Dialog Box


Step 4   In the Name text field, enter the name of the parameter you want to define.

Step 5   From the Value drop-down menu, choose the variable that stores the parameter value.

Step 6   Click OK.

The Parameter dialog box closes, and the names of the parameter and variable appear in the Name and Value columns of the Create URL Document window.

Step 7   Repeat Steps 3 to 6 as needed to add parameters and variables as desired.

(If you want to modify an existing parameter, click Modify. The Parameter dialog box appears again. Follow the same procedure you used to add parameters.)

Step 8   Click OK.

The Create URL Document customizer window closes.





Create XML Document

Use the Create XML Document step to create a logical document that maps a document to another document variable (where the document has already been pre-parsed as an XML document and is ready to be accessed by the Extract XML Document step).

Use this step before the Extract XML Document step to obtain data from a document formatted using the Extensible Markup Language (XML).

Figure 11-6 shows the customizer window for the Create XML Document step.


Figure 11-6   Create XML Document Customizer Window


Table 11-4 describes the properties of the Create XML Document customizer window.

Table 11-4   Create XML Document Properties

Property Description

Result Document

Document that contains the resulting XML document.

You can use the same variable that you used for the Source Document field if you do not need to use the original document again with subsequent steps. The variable assigned to the Result Document is used as the input to the Extract XML Document Data step.

Source ID (Optional)

Source identifier (URL) to be used when parsing the document.

If the document is a URL document, this field is not required; otherwise, you can supply it if known.

Source Document

Variable containing the source document from which you want to create an XML document.


Note   Note: When creating a non-English XML files, you must accurately set the character encoding. XML uses Unicode (UTF-8) by default, but you can use other encoding methods. For example, many Western European language text editors use ISO-8859-1 (latin-1) encoding by default. In this case, you must set the encoding attribute of the XML declaration, as in the example below:
<?xml version="1.0" encoding="ISO-8859-1"?>"

To use the Create XML Document customizer window to map a document to another document variable, perform the following procedure:

Procedure

Step 1   From the Result Document drop-down menu, choose the variable that stores the resulting XML document.

Step 2   In the Source ID (Optional) field, enter a value directly or take one of the following actions:

  • From the Source ID (Optional) drop-down menu, choose the variable that stores the ID value of the source document.
  • Click the Expression Editor (...) button and enter an expression that specifies the ID value of the source document.

Step 3   From the Source Document drop-down menu, choose the variable that stores the source document.

Step 4   Click OK.

The Create XML Document customizer window closes, and the name of the source document, the Source ID variable, and the result document appear next to the Create XML Document step icon in the Design pane of the CRA Editor.





Extract XML Document Data

Use the Extract XML Document Data step after the Create XML Document step to obtain data from a document formatted with XML.


Note   You can use the Extract XML Document Data step only on a document that was returned by the Create XML Document step. If you attempt to use it on any other type of document, errors will occur.

Example 11-2 shows a few lines from a typical XML file, created with a text editor, which formats dynamic stock price data.


Example 11-2   A Sample XML File
<?xml version="1.0" standalone="yes"?>
<STOCKLIST>
<STOCK symbol="MSFT" error="0">
<HIGH>58.0625</HIGH>
<PCT_CHANGE>0.67114094</PCT_CHANGE>
<LOW>55.1875</LOW>
<LAST>56.25</LAST>
<CHANGE>0.375</CHANGE>
<VOLUME>31,973,600</VOLUME>
<REC_STATUS>0</REC_STATUS>
<DATE>02/21/2001</DATE>
<TIME>15:52</TIME>
</STOCK>

To extract data from an XML file, you must identify the exact XML path, as in Example 11-3:


Example 11-3   Typical XML Path
/descendant::STOCKLIST
/child::STOCK[attribute::symbol="CSCO"]
/child::LAST

The XML path is composed of location steps separated by a forward slash (/). In the example above, the XML path has three location steps. Each location step is composed of three parts:

  • Axis—Relation to the context (for example, descendant or child).
  • Node test—Field name (for example, STOCK).
  • Predicates (optional)—Properties and values within a field (for example, [attribute::symbol="CSCO"]).

  • Note   You must execute a separate Extract XML Document Data step for each field in the XML file that you want to use.

Figure 11-7 shows the customizer window for the Extract XML Document Data step.


Figure 11-7   Extract XML Document Data Customizer Window


Table 11-5 describes the properties of the Extract XML Document Data customizer window.

Table 11-5   Extract XML Document Data Properties

Property Description

Result Data

Document variable that contains the XML data.

XML Path

XML path that defines a specific field or value in an XML document.

Document

Document variable created as the Result Document in a preceding Create XML Document step.

To use the Extract XML Document Data customizer window to specify a document variable that will contain XML data, perform the following procedure:

Procedure

Step 1   From the Result Data drop-down menu, choose the variable that stores the resulting XML document.

Step 2   In the XML Path field, enter a value directly or take one of the following actions:

  • From the XML Path drop-down menu, choose the variable that stores the XML Path value of the source document.
  • Click the Expression Editor (...) button and enter an expression that specifies the XML Path value of the source document.

Step 3   From the Document drop-down menu, choose the variable that stores the source document.


Note    Make sure that the Document variable you choose here matches the one you chose for the Result Document in a preceding Create XML Document step.

Step 4   Click OK.

The Extract XML Document Data customizer window closes, and the names of the Result Data, Document, and XML Path variables appear next to the Extract XML Document Data step icon in the Design pane of the CRA Editor.





Text Substitution for Keywords

Use the Text Substitution for Keywords step to replace keywords in a predefined template with values contained in local variables, in order to display dynamic data to users.

You map these keywords to variables. When the script runs, the current values of the local variables replace the keywords.

You can load keyword definitions from a source document, or you can add each keyword manually.

Figure 11-8 shows the customizer window for the Text Substitution for Keywords step.


Figure 11-8   Text Substitution for Keywords Customizer Window


Table 11-6 describes the properties of the Text Substitution for Keywords customizer window.

Table 11-6   Text Substitution for Keywords Properties

Property Description

Result Document

Variable that stores the resulting document.

Source Document

Variable that identifies a source template document.

Local Variable/Data Type/Keyword

Values that specify the mapping of variables to keywords in the source document.

To use the Text Substitution for Keywords customizer window to map keywords to local variables, perform the following procedure:

Procedure

Step 1   From the Result Document drop-down menu, choose the variable that stores the resulting document.

Step 2   From the Source Document drop-down menu, choose the variable that stores the source template document.

Step 3   Take one of the following actions:

  • To define a keyword manually, click Add.

The Keyword Mapping dialog box appears. (See Figure 11-9 .)


Figure 11-9    Keyword Mapping Dialog Box


  • From the Local Variable drop-down menu, choose the variable you want to map to the keyword.

The variable type of the variable selected in the Local Variable drop-down list automatically appears in the Data Type field.

  • In the Keyword field, enter an alphanumeric string to uniquely identify the purpose of the keyword.

For example, if you are using a keyword to display the results of a database query, you might define a keyword named "QueryResult".

  • Click OK.

The Keyword Mapping dialog box closes, and the variable, data type, and keyword appear in their respective columns in the display list of the Text Substitution for Keyword customizer window.

    • Repeat this procedure as needed to map all keywords to local variables.
  • To load keyword definitions from a file, click Import.

The Select a File dialog box appears. (See Figure 11-10 .)


Figure 11-10   Select a File Dialog Box


  • In the Select a File dialog box, browse to the file that contains the keywords you want to import, and then click Open.

Keywords must be flagged by percentage signs in the source document (%keyword%).

The Select a File dialog box closes, and any words in the document that are enclosed by percentage signs are displayed in the Keyword column of the Text Substitution for Keywords customizer window.

(If you want to map imported keywords to local variables, select the keyword in the list box, and click Modify. The Keyword Mapping dialog box appears again. Follow the same procedure you used to add variables.)

Step 4   Click OK.

The Text Substitution for Keywords customizer window closes, and the names of the Result document and Source document appear next to the Text Substitution for Keywords step icon in the Design pane of the CRA Editor.





Write Document

Use the Write Document step to write the document to disk on the CRA server.

For example, you can save a recorded announcement to disk that replaces
a "Message of Day" announcement.

Figure 11-11 shows the customizer window for the Write Document step.


Figure 11-11   Write Document Customizer Window


Table 11-7 describes the properties of the Write Document customizer window.

Table 11-7   Write Document Properties

Property Description

Document

Variable that stores the resulting document

Filename

Name of the file that contains the information to be saved

To use the Write Document customizer window to specify the filename and Document variable, perform the following procedure:

Procedure

Step 1   From the Document drop-down menu, choose the variable that stores the resulting document.

Step 2   In the Filename field, enter a value directly or take one of the following actions:

  • From the Filename drop-down menu, choose the variable that stores the filename value.
  • Click the Expression Editor (...) button and enter an expression that specifies the filename value.

Step 3   Click OK.

The Write Document customizer window closes, and the name of the Filename variable appears next to the Write Document step icon in the Design pane of the CRA Editor.





XSL Transform Document

Use the XSL Transform Document step to apply eXtensible Stylesheet Language (XSL) transformation to produce an output document.

XSL transformation is performed by an XSL processor provided by the Cisco CRA Engine. The XSL processor performs the transformation using an XSL Stylesheet, which contains formatting and other processing instructions.

When the XSL Transform Document step executes, it converts the specified variables into an internal XML document. This internal XML document is passed to the XSL processor in conjunction with an XSL Stylesheet to form the resulting document.

Example 11-4 shows the structure of an internal XML representation.


Example 11-4   Structure of Internal XML Representation
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ExecutionState[
     <!ELEMENT ExecutionState (scriptName, OutputContext)>
     <!ELEMENT scriptName (#PCDATA)>
     <!ELEMENT OutputContext ANY>
]>

Table 11-8 describes each element in the representation.

Table 11-8   Elements of XML Internal Representation

Element Function

ExecutionState Element

Result after the script is executed

ScriptName Element

Name of the script being executed

OutputContext

Variables added to the Output Parameters box within the XSL Transform Document customizer

Figure 11-12 shows the customizer window for the XSL Transform Document step.


Figure 11-12   XSL Transform Document Customizer Window


Table 11-9 describes the properties of the XSL Transform Document customizer window.

Table 11-9   XSL Transform Document Properties

Property Description

Result Document

Variable that stores the document resulting from this step

Output list

Available String type variables

Output Parameters

Variables passed to the XSL processor

XSL Stylesheet

Stylesheet used to form the result document

To use the XSL Transform Document customizer window to apply XSL transformation to produce an output document, perform the following procedure:

Procedure

Step 1   From the Result Document drop-down menu, choose the variable that stores the resulting document.

Step 2   To choose a variable in the Output list to pass to the XSL processor, select the variable, and then click the >> button.

The selected variable appears in the Output Parameters list.

Step 3   Repeat Step 2 as needed to add variables to pass to the XSL processor.

(To remove a variable from the Output Parameters list, select the variable and click the << button. The selected variable returns to the Output list. To change the order of the variables in the Output Parameters list, select a variable and click Up to move it up the list or Down to move it down the list.)

Step 4   In the XSL Stylesheet text field, enter the name of the XSL stylesheet.

Step 5   Click OK.

The XSL Transform Document customizer window closes, and the name of the XSL stylesheet and the result document appear next to the XSL Transform Document step icon in the Design pane of the CRA Editor.