Converting VoiceXML 1.0 and 2.0 files to 2.1

Changes from VoiceXML 1.0 and 2.0

The VoiceXML 2.1 specification supported in this version of the toolkit is available on: http://www.w3.org/TR/voicexml21/

A typical conversion includes:

• Updating the DTD and <vxml> tag for VoiceXML 2.1.
• Checking for the "encoding" setting in the source file heading. If the setting is missing, the conversion is based on the Voice Language selected on the Voice Tools preference page by clicking Window > Preferences > Voice Tools > Speech Engines > WebSphere Voice Server (MRCP).
• Modifying VoiceXML tags. For example, inline grammars that were JSGF format in the source file will be converted to SRGS XML format.
  Note: The wizard will not modify .jsp tags or any user-specified namespace tags.
• Removing some obsolete tags. If the removal results in a logic change, comments are added in the file with information about the change.

You can refer to the VoiceXML 2.0 specification available on: http://www.w3.org/TR/voicexml21/, Appendix J - Changes from VoiceXML 1.0 for a list of changes since VoiceXML 1.0.

Using the VoiceXML Conversion wizard

You must be in the Voice perspective to use the wizard.

1. Save any open VoiceXML files (including file extensions ..vxm, .vxml, .jsp, and .jsv) in the toolkit, making sure that the files you intend to convert are valid (well-formed and free of errors).
2. Use one of the following methods to open the wizard:
   • From the Run menu, select VoiceXML Conversion, and when the wizard opens, click Next to select the files to convert (including files with extensions .vxm, .vxml, .jsp, and .jsv). Then click Next.
     Note: If the item does not appear in the Run menu, select Window > Reset Perspective, and then open the Run menu again.
   • From the Navigator, select one or more VoiceXML files (with the same file extension only), right-click the selection, and select VoiceXML Conversion from the menu.
3. On the Summary of Files screen, select the Convert Reserved Action Tag Fields check box if you want Action Tag constructs (such as "$tts," "$token," and "$utterance") to appear in the conversion. If deselected, the fields are ignored and the constructs will be commented out in the converted file. For information on convert these fields, in the online help, see the topic Converting JSGF to SRGS, and go to the section "Conversion of IBM ECMAScript Action Tags to SISR."  
4. After reviewing the list of files that you have chosen to convert, click Next.  
5. The conversion progress bar starts and the files are converted based on the VoiceXML Version and DTD as specified in the Voice Tools DTD Catalog Preferences, by clicking Window > Preferences > Voice Tools > Catalog Defaults. If you are converting many files, it could take a few minutes for the workspace to refresh.
   Note: If you have already converted one or more files (they are already included in the Converted Files folder) and you are attempting to convert them again, you can choose whether to overwrite your previously converted files. Select Yes or Yes to all to overwrite the files. Select No or No to all to back up the old files before creating new ones.
6. When the conversion finishes, the Status window shows the results of the conversion for each selected file:

   Pass

   (Green) The conversion completed successfully, and a new file was created. (This message does not indicate validation, which must take place in the VoiceXML editor.)

   Fail

   (Red) The conversion did not complete properly, and the new file was not created. Read the message for more information. Fix any errors, save the file, and run the conversion again.

   Skipped

   (Black) The file was already converted and in that process you selected NOT to overwrite this original file.

7. After reviewing the status, click Finish to close the wizard. The new files are created in a folder called Converted Files.

Continue with the manual steps listed next.

Required manual steps to complete the conversion process

Complete the following actions manually:

• Open the converted files in the VoiceXML editor to check for new errors or any comments left as a result of the conversion. The comments (preceded by VXML_CONVERSION), if added, will give you more information about an action taken during the conversion process.
• Change the external speech grammars to SRGS-XML format (internal grammars are converted by the wizard). VoiceXML 2.1 supports XML Form of the W3C Speech Recognition Grammar Specification (SRGS-XML). If necessary, format the converted file by right-clicking in the file and selecting Format > Document.
• The toolkit provides a Grammar Conversion wizard to automatically convert grammars. Remember to move the converted files into the paths specified in the project files, or create a new project using the converted files. You can delete the original files, if desired. If necessary, format the converted file by right-clicking in the file and selecting Format > Document. For more information, see

Troubleshooting

If errors occur as a result of the conversion, the errors appear in the Task or Problems views with a brief description of the error. To troubleshoot, do the following:

• Fix the errors, basing changes on the VoiceXML 2.1 specification (see link above) and the logic you intend.
• If there is no active Internet connection an error might occur when converting a VoiceXML (e.g., No route to host: connect). Ensure there is an active Internet connection before executing the conversion.
• A common error that occurs in JSP files is an end-tag error, as shown in the following example:

...
<% 
if (ThisIsTrue) { 
%> 
      <record name="Example" beep="true" maxtime="10s"
finalsilence="2s"> 
<% 
   } else { 
%> 
      <record name="Example" beep="false" maxtime="20s"
finalsilence="2s" 
            type="audio/wav" > 
<% 
   } 
%> 
      <prompt bargein="false"> 
         <break msecs="500" /> 
   </prompt> 
      <noinput> 
      <reprompt /> 
       </noinput> 

   </record>
...

VoiceXML 2.1 requires documents to be well-formed. To fix the error above, the element type <record> must be terminated by the matching end-tag </record>, either following the initial <record> tag or following the existing ending </record> tag, depending on the logic.