Table of Contents

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 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.

---

---

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.

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.

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.

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

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

Procedure

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

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.

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

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

Procedure

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.

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

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

Procedure

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 .)

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.

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

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 2   In the Source ID (Optional) field, enter a value directly or take one of the following actions:

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.

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

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:

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

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

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 2   In the XML Path field, enter a value directly or take one of the following actions:

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.

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

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

Procedure

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:

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

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

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

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.

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

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.

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

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

Procedure

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

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.

Table 11-8 describes each element in the representation.

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

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

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

Procedure

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.