Importing and Exporting Cypress Resource Data

This topic describes the Cypress Import/Export utilities and how you can use them with Cypress resource information.

Overview

The Cypress Import/Export utilities enable you to export Cypress resource information into XML files. Then you can import the XML files back into any Cypress DocuVault.

Cypress Import/Export can simplify configuration of a DocuVault. For example, you can easily copy reports, devices, recipients, and other resources from a test DocuVault into a production DocuVault. In addition, if you need to add 100 very similar recipients to the Address Book, you might choose to create one recipient, export that recipient’s data, and then copy and modify the XML file to create all the recipients.

The Cypress Import/Export module contains these utilities:

export_xml, which exports Cypress data to XML files
import_xml, which imports XML data into Cypress
xml_converter, which converts Cypress XML to a standard schema for use with reporting applications

If you want to use the exported XML with a reporting application such as Crystal Reports, you must first convert the file to an ADO-compatible schema. Cypress provides the xml_converter utility for this purpose.

Import Order for Cypress Resources

You must import Cypress resource data in a particular order to avoid referencing errors. For example, a device definition refers to stock and format resources. If it is imported before the stock and format resources it references, the systemproduces an error.

Resources To Create First

This table lists the Cypress resources that must be available in the DocuVault before you import any Cypress resources from an XML file because they are referenced by these imported resources:

Resource

Explanation

Font

Create all fonts before you import any resources. You can do this by:

•

Exporting/importing the fonts. This enables you to import fonts that have been exported from another DocuVault. Refer to the appropriate topic for more information on exporting or importing Cypress resources.

•

Loading the fonts using the Capture Driver or font_prog Utility. See Loading a Font into the DocuVault for more information on loading font resources.

Font Substitution

Create or import all font substitutions before you import the format resource if the resource uses them.

Resources To Import in a Specific Order

This table lists the specific order in which you must import Cypress resources from an XML file into a DocuVault to avoid referencing errors:

Resource	Referenced Resources	Note
Role		Role must be imported first as all resources with security settings reference it.
DocuVault Parameters
Region
Index		Index enables you to include the index template and maps in the import.
Bundle
Stock
Stock Substitution	Stock
Font Substitution	Font	Fonts specified in the font substitution record are searched by name. The import will be terminated with an error if a matching font cannot be found.
Image	Font
Form	Font, Stock, Image, Form	Create or import referenced stocks, images, and forms before you import the form resource.
Form Databox		Create or import all forms, images, and fonts before you import the form databox resource.
Banner	Stock, Form
Format	Stock, Banner, Form, Font, Font Substitution
Document	Font, Stock, Image, Form	Create or import referenced stocks, images, and forms before you import the form resource.
Device	Stock, Stock Substitution, Banner, Format, Device	If the device definition references children devices, the children devices must be imported first. Check the error log when you are finished to confirm that all children devices have been imported. If a printing constraint references an alternate device, the import might not catch it. Check the error log and manually import the missing device.
Address Book	Device
Imaging	Format, Device	Imaging enables you to include the image queue and image prototype resources.
RDM Group	Device, Recipient, Index, Bundle
Saved Queries	Indexes	Create or import all referenced Indexes before you import saved queries.
Document Templates

Document, form, and image resource files can contain all or part of the referenced resources. If all of the resources are contained, you can skip creating or importing those referenced resources and import the document, form, or image directly.

After you have imported all resources, check the import_debug.txt file (or the one you named with the debug parameter) to ensure that all objects have been imported correctly, especially children and substitution resources.

Importing Cypress Resources

Only a member of Import Role can use the import_xml utility. You can add members to the role using the Administration Tools module’s Role tab.

Cypress’s import_xml utility enables you to import Cypress resource data from an XML file directly into a DocuVault. You can use this utility to modify existing resources or create new ones.

Whether you choose to import the XML data untouched into a second DocuVault or to modify the data to add a second, similar object to the original DocuVault, running the import utility can be done simply and quickly. The utility requires the name of the DocuVault into which the data is to be imported as well as the name of the import file. In addition, you might need to specify how DocuVault handles resources with the same name as the resources in the XML file:

•

To leave them alone

•

To replace them

•

To issue an error when such resources are encountered

•

To specify a file name to which debug information is to be written

In addition, you can use the import_xml utility to delete or rename certain Cypress resources.

To import Cypress resource data into a DocuVault

Open a command prompt window.

Determine the DocuVault to which you want to import the data.

•

If the DocuVault is on the Cypress Server on which you are running the import_xml utility, you can enter only a period (.) at the command prompt.

•

If the DocuVault is on a different server than the one on which you are running the import_xml utility, you must enter the full name and IP address of the DocuVault at the command prompt.

For example, enter something like “Prod_DocuVault@127.0.0.1” in the command prompt window.

If your system is running in a Windows Server 2008 environment, enter something like “Prod_DocuVault@::1” in the command prompt window.

Make sure the XML file is valid and fully formed by opening it in an Internet browser. If there is a formatting error in the file, the browser displays the error.

Make sure the data file is in the same directory as the XML file for documents, forms, and images.

Determine how you want to handle resources by the same name as resources in the XML file. The import_xml utility provides these options:

•

add (valid when importing forms/images only)—the form/image is added to the DocuVault.

•

delete—the existing resource will be deleted. See Deleting Cypress Resources for more information.

•

error—import_xml will issue an error.

•

leave—the existing resource will be left alone.

•

rename—the existing resource will be renamed. See Renaming Cypress Resources for more information.

•

replace—the existing resource will be replaced by the resource definition in the XML file.

When you import DocuVault parameters, the import_xml utility always replaces the configuration data, regardless of the option you select.

When you import stocks and specify replace, the import_xml utility creates a new stock definition rather than replacing the existing one. All other options behave normally.

These options are not applicable when importing documents. When you import a document, the import_xml utility always creates a new one if the identical item (e.g., name, attributes, data, etc.) cannot be found in the target DocuVault.

When you import forms/images, Add is the only valid option. When you import a document, the import_xml utility always creates a new document.

When you import saved queries, they are always added. The option does not need to be specified and will be ignored.

When you import a Document Template, the “sample” document will not be imported with it. When viewing this Template in the UI, you have the option to select a sample document. Enter the document ID and then click on the Save icon in the Template menu to save the template with this sample document.

If the Change History feature is enabled, a record is added to the change history for the appropriate module.

When importing CPF Groups, the forms (captured pages) are always imported, replacing the previous forms, regardless of the value of the exist_flag.

Optional. Determine the name and location of a file to which you want debugging information to be written. Cypress creates the file if it does not already exist.

If you skip this step, the default file name of import_debug.txt is used.

Optional. If a document is being imported and you want to queue a JTic for this document to a device, specify the device=<device name> attribute.

Enter the import_xml command at the command prompt.

•

If you choose to write debugging information to the default file, the command line is in this format:

X:\Cypress\Server\import_xml dv=”<DocuVault name from step 2>” import_file=”<XML file name from step 3>” exist_flag=<import option from step 5>

•

If you choose to write the debugging information to a specific file, the command line is in this format:

X:\Cypress\Server\import_xml dv=”<DocuVault name from step 2>” import_file=”<XML file name from step 3>” exist_flag=<import option from step 5> debug=”<file name from step 6>”

Once the import has completed, be sure to check Cypress to verify that everything has been created or modified as you expected. You can read through the debug log to make sure that no unnoticed problems have occurred.

Examples

These are some examples of how to use the import_xml utility. See import_xml Parameters for a complete reference to all import_xml parameters.

Example 1

Assume that you have exported all RDM reports and subreports out of a test DocuVault and want to import them into your production DocuVault. In that case, your command line would look something like this:

C:\Cypress\Server\import_xml dv=”Prod_DocuVault@127.0.0.1”

import_file=”C:\Test\Exports\Test_DocuVault_RDM_Groups.XML” exist_flag=replace

Example 2

Assume that you have exported one manager’s Address Book information and duplicated and modified it for each manager in the department, and you want to specify a name and directory for your debug file to verify that each recipient was created successfully. In that case, your command line might look like this:

C:\Cypress\Server\import_xml dv=”.”

import_file=”C:\Exports\Prod_DocuVault_Address_Book_New.XML” exist_flag=leave

debug=”C:\Logs\Exports\AddressBook.dbg”

Example 3

Assume you exported a document from a DocuVault and want to import it into a different DocuVault. The command line would look something like this:

C:\Cypress\Server\import_xml dv=”DV2@11.22.33.44” import_file=”C:\Documents\DV1_Document.XML”

import_xml Parameters

Use the syntax illustrated in this figure for the import_xml.exe program. The parameters can appear in any order.

This table describes the import_xml parameters. All parameters are optional unless otherwise indicated.

Parameter

Description

Required. Enables you to specify the DocuVault into which you want to import resources. To specify the local DocuVault, you can use a period (.) instead of a DocuVault name. For example:

dv=”."

dv="ABCDocuVault@ABCCompany-3"

import_file

Required. Specifies the name of the XML file (including a fully qualified file path) that should be imported. For example:

import_file=”d:\export\format.xml"

import_file=”d:\export”

exist_flag

Required for all resource types except documents, forms, images, and saved queries. Specifies the method you want Cypress to use to process existing resources by the same name as resources in the XML file. These are the options for exist_flag:

•

add (valid when importing forms/images only)—the form/image is added to the DocuVault.

•

delete—the existing resource is deleted

•

error—import_xml issues an error

•

leave—the existing resource is left alone

•

rename—the existing resource is renamed

•

replace—the existing resource is replaced by the resource definition in the XML file

For example:

exist_flag=leave

exist_flag=replace

debug

Enables you to specify a file to which debugging information can be written. If you specify only a file name, the debug file will be written to the directory from which you ran the import.xmlutility. You also can specify a fully qualified file path with the file name to write the debug file to a particular directory. For example:

debug=”debug.txt”

debug=”D:\logs\debug.log”

If you omit this option, the default file name, import_debug.txt,will be used and the file will be placed in the directory from which you ran the import_xml executable.

device

Specifies the device to queue a JTic to. This attribute only applies when importing a document.

Deleting Cypress Resources

Cypress’s import_xml utility enables you to easily delete many Cypress resources from a DocuVault. Note that you must create your own XML file to delete resources; you cannot use an XML file generated by the export_xml utility.

Only a member of the Import Role can use the import_xml utility. You can add members to the role using the Administration Tools module’s Role tab.

You cannot delete a form, image, document, or saved query with the import_xml utility.

To delete a resource using the import_xml utility

Create the XML file you wish to use. This file can be created in NotePad or any other text editor as well as a dedicated XML editor.

Start the XML file with this line:

<?xml version="1.0" ?>

Specify your DocuVault’s name and version in the second line of the XML file. (If you do not know the version, it appears on the db_prog window. See Starting the Hub Service for more information.)

The line should look like this:

<docuvault_settings docuvault_name=”<DocuVault>” database_version=”<version/build>”

where:

<DocuVault> is the name of your DocuVault.

<version/build> is the Cypress version and build number.

For example, this is a valid <docuvault_settings> line:

<docuvault_settings docuvault_name=”ABC_DocuVault” database_version=”5.0 build 2”>

Begin the list of objects to be deleted in the third line of the XML file, for example:

<delete_obj_list>

Add one line for each object you want to export. The formatting of each line depends on the object that is going to be deleted.

This table lists all objects that you can delete and shows a properly formatted XML tag for each:

Object	XML Format
Banner	<banner obj_name=”Banner102”/>
Batch Settings	<imaging_prototype obj_name="BatchSettingEurope" />
Bundle	<bundle obj_name=”Bundle102” parent_bundle_name=”SalesBundles”/>
Device	<device obj_name="Dept102Printer" />
Format	<format obj_name="FormatEurope" />
Imaging Queue	<imaging_queue obj_name="QueueEurope" />
Index	<index obj_name="Sales Rpt ID" />
Name Map	<inx_name_map obj_name="MonthNamesFrench" />
RDM Group	<rdm_group obj_name="Dept102Reports" />
RDM Report	<rdm_report obj_name="Dept102" group_name="SalesReports" />
RDM Subreport	<rdm_subreport obj_name="Dept102Sub" group_name="SalesReports" report_name="BudgetReports" />
Recipient	<recipient obj_name="JudahB" />
Region	<region obj_name="DeptID" group_name="<Global regions>" report_name="" />
Region	<region obj_name="DeptID" group_name="Sales" report_name="Dept102" /> You can specify either a group name or the literal <Global regions> to delete a region that does not belong to a particular report group.
Role	<role obj_name="Dept 102" />
Stock	<stock obj_name="Win 11X17" stock_id="1040" />
Stock Substitution Table	<stock_substitution obj_name="Stock Sub Europe"/>
Template	<inx_template obj_name="DatesEurope" />

To delete more than one object of the same type, repeat the line in the same format with a different object name. For example, if you need to delete two devices, your XML tags might look like this:

After you have added a line for each object that you wish to delete, add a line to close the object list. This line signals to Cypress that no more objects are to be deleted:

</delete_obj_list>

Close the <docuvault_settings> tag:

</docuvault_settings>

When you have completed the XML file, save it, and record its directory and file name. Verify that this XML file is valid and fully formed by opening it in an Internet browser. If there is a formatting error in the file, the browser displays the error.

Identify the DocuVault from which the resources should be deleted. This should be the same DocuVault that you specified in step 3. .

•

If the DocuVault is on the Cypress Server on which you are running the import_xml utility, you can enter only a period (.) at the command prompt.

•

If the DocuVault is on a different server than the one on which you are running the import_xml utility, you must enter the full name and IP address of the DocuVault at the command prompt. For example, enter something like “Prod_DocuVault@127.0.0.1” in the command prompt window.

If your system is running in a Windows Server 2008 environment, enter something like “Prod_DocuVault@::1” in the command prompt window.

10.

Optional. Determine the name and location of a file to which debugging information is written. Cypress will create the file if it does not already exist.

11.

Enter the import_xml command line at the command prompt.

•

If you choose not to write debugging information to a file, the command line will be in this format:

Cypress\Server\import_xml dv=”<DocuVault name from step 9>”
import_file=”<XML file name from step 8>” exist_flag=delete

For example, a valid import_xml command that deletes resources without creating a debug file might look like this:

C:\Cypress\Server\import_xml dv=”Prod_DocuVault@127.0.0.1” import_file=”C:\Test\Exports\Test_DV_Del_RDM_Groups.XML”

If your system is running in a Windows Server 2008 environment, a valid import_xml command that deletes resources without creating a debug file might look like this:

C:\Cypress\Server\import_xml
dv=”Prod_DocuVault@::1” import_file=”C:\Test\Exports\Test_DV_Del_RDM_Groups.XML”

•

If you choose to write the debugging information to a file, the command line will be in this format:

Cypress\Server\import_xml dv=”<DocuVault name from step 9>” import_file=”<XML file name from step 8>” exist_flag=delete debug=”<file name from step 10>”

A valid import_xml command that deletes resources and creates a debug file for your review might look like this instead:

C:\Cypress\Server\import_xml dv=”.” import_file=”C:\Exports\Prod_DocuVault_del_Address_Book.XML” exist_flag=delete debug=”C:\Logs\Exports\AddressBook.dbg”

See import_xml Parameters for a complete reference to all import_xml parameters.

12.

Once the specified resources have been deleted, be sure to check Cypress to verify that everything has been deleted as you expected. If you created a debug log, read through it to make sure that no unnoticed problems have occurred.

This is an example of a complete, valid XML delete file:

<?xml version="1.0" ?>

<docuvault_settings docuvault_name="ABC_DocuVault" database_version="5.0 build 2">

<delete_obj_list>

<inx_template obj_name="DatesEurope" />

<inx_name_map obj_name="MonthNamesFrench" />

<imaging_queue obj_name="QueueEurope" />

<imaging_prototype obj_name="BatchSettingEurope" />

<rdm_group obj_name="Dept102Reports" />

<rdm_report obj_name="Dept102" group_name="SalesReports" />

<stock_substitution obj_name="Stock Sub Europe"/>

</delete_obj_list>

</docuvault_settings>

Renaming Cypress Resources

You must create your own XML file to rename resources; you cannot use an XML file generated by the export_xml utility.

Only a member of the Import Role can use the import_xml utility. You can add members to the role using the Administration Tools module’s Role tab.

You cannot use the import_xml utility to rename a form, image, or document.

Cypress’s import_xml utility enables you to quickly rename many Cypress resources from a DocuVault.

To rename a Cypress resource

Create the XML file you wish to use. This file can be created in NotePad or any other text editor as well as a dedicated XML editor.

Start the XML file with this line:

<?xml version="1.0" ?>

Specify your DocuVault’s name and version in the second line of the XML file. If you do not know the version, it appears on the db_prog window.

This line should look like this:

<docuvault_settings docuvault_name=”<DocuVault>” database_version=”<version/build>”

where:

<DocuVault> is the name of your DocuVault.

<version/build> is the Cypress version and build number.

For example, this is a valid <docuvault_settings> line:

<docuvault_settings docuvault_name=”ABC_DocuVault” database_version=”5.0 build 2”>

Begin the list of objects to be renamed in the third line of the XML file:

<rename_obj_list>

Add one line for each object that you want to rename. The formatting of each line depends on the object that needs to be renamed.

This table lists all objects that can be renamed and shows a properly formatted XML tag for each:

Object	XML Format
Index	<index obj_name="SalesRptID" new_name=”SalesRptNum” />
Recipient	<recipient obj_name="JudahB" new_name=”JBenton” />
Role	<role obj_name="Dept 102" new name=”Sales Dept”/>
Template	<inx_template obj_name="DatesEurope" new_name=”MonthsEurope”/>

If you wish to rename more than one object of the same type, repeat the line in the same format with a different object name. For example, if you need to rename two recipients, your XML tags might look like this:

After you have added a line for each object that you wish to rename, add a line to close the object list. This line signals Cypress that there are no more objects to be renamed:

</rename_obj_list>

Close the <docuvault_settings> tag:

</docuvault_settings>

Identify the DocuVault that contains the resources to be renamed. It should be the same DocuVault that you specified in step 3. .

•

If the DocuVault is on the Cypress Server on which you are running the import_xml utility, you can enter only a period (.) at the command prompt.

•

If the DocuVault is on a different server than the one on which you are running the import_xml utility, you must enter the full name and IP address of the DocuVault at the command prompt.

For example, enter something like “Prod_DocuVault@127.0.0.1” in the command prompt window.

If your system is running in a Windows Server 2008 environment, enter something like “Prod_DocuVault@::1” in the command prompt window.

10.

Optional. Specify the name and location of a file to which you want debugging information to be written. Cypress creates the file if it does not already exist.

11.

Enter the import_xml command line at the command prompt.

•

If you choose not to write debugging information to a file, the command line will be in this format:

Cypress\Server\import_xml dv=”<DocuVault name from step 9>” import_file=”<XML file name from step 8>” exist_flag=rename

For example, a valid import_xml command that renames resources without creating a debug file might look like this:

C:\Cypress\Server\import_xml dv=”Prod_DocuVault@127.0.0.1” import_file=”C:\Test\Exports\Test_DocuVault_ren_Roles.XML” exist_flag=rename

•

If you choose to write the debugging information to a file, the command line will be in this format:

Cypress\Server\import_xml dv=”<DocuVault name from step 9>” import_file=”<XML file name from step 8>” exist_flag=rename debug=”<file name from step 10>”

A valid import_xml command that renames resources and creates a debug file for your review might look like this instead:

C:\Cypress\Server\import_xml dv=”.” import_file=”C:\Exports\Prod_DocuVault_ren_Roles.XML” exist_flag=rename debug=”C:\Logs\Exports\Roles.dbg”

See import_xml Parameters for a complete reference to all import_xml parameters.

12.

Once the specified resources have been renamed, be sure to check Cypress to verify that everything has been renamed as you expected. If you created a debug log, read through it to make sure that no unnoticed problems have occurred.

This is an example of a complete, valid file:

<?xml version="1.0" ?>

<docuvault_settings docuvault_name="ABC_DocuVault" database_version="5.0 build 2">

<rename_obj_list>

<inx_template obj_name="DatesEurope" new_name=”MonthsEurope”/>

</rename_obj_list>

</docuvault_settings>

Exporting Cypress Resources

Cypress’s export_xml utility enables you to export Cypress resource data into an XML file. You can then import the XML data into a second DocuVault or modify the data and import it back into the original DocuVault.

Only a member of the Export Role can use the export_xml utility. You can add members to the role using the Administration Tools module’s Role tab.

When you successfully run the export utility, an XML file is created in a directory that you specify. The file is named in the format <DocuVault name>_<resource type>.XML. For example, if you export all devices from the ABC_DocuVault, your XML file will be called:

ABC_DocuVault_Devices.XML

This is a sample XML export file:

<description>Epson Printer</description>

<host>ABC_EPSON</host>

<device_dll>epson</device_dll>

<link_dll><none></link_dll>

<num_of_buffers>3</num_of_buffers>

<block_size>16384</block_size>

<page_queue_limit>6</page_queue_limit>

<format obj_name="<none>" use_auto_format="false" />

<banner obj_name="<none>" always_use_this_banner="false" />

<color>black/white</color>

<orientation>simplex</orientation>

</general>

<input>

<input_tray obj_name="Tray 1" stock="Win Letter" type="cut sheet"

sel_no="0" pri¬ority="50" capacity="0" scan_dim="11" feed_dim="8" />

<input_tray obj_name="Tray 2" stock="Win Legal" type="cut sheet"

sel_no="0" pri¬ority="50" capacity="0" scan_dim="14" feed_dim="8" />

</input>

<output_tray obj_name="Output A" type="stacker" priority="50" capacity="500"

scan_dim="14" feed_dim="8" sel_no="0" page="face down" order="descending" as_default="false" />

</output>

<time>

<job_timeout retain_for="24:00(hr:min)" purge_after="never" />

<device_timeout switch_after="2:00(hr:min)" alt_device="<none>" />

</time>

</security>

</device>

For documents, forms, and images, there is a second file created as a result of exporting. It has the same name with a different extension: DAT (data file). For example, if you export all images from the ABC_DocuVault, your XML file and data file will be called:

ABC_DocuVault_Images.XML

ABC_DocuVault_Images.DAT

After a resource has been exported, you can modify the data in the XML file. For example, if the ABC company has a second printer identical to this one, you can modify the device’s name and description, save the XML file to a different name, and use the import utility to import the second printer into Cypress.

When you modify XML files, ensure that the beginning and ending tags match. If you are unfamiliar with XML structure, consult a book or Web page on the subject before changing your data.

In addition, always back up your data before you make changes.

To export Cypress resource data from a DocuVault

Open a command prompt window.

Determine the type of resource that you wish to export.

This table shows the parameter that corresponds to each type of Cypress resource that can be exported:

Resource Type	Parameter
All available resources except documents, forms, or images	ALL
Banners	BANNER
Batch settings only	IMAGE_PROTOTYPE
Bundles	BUNDLE
CPF Groups	CPF_Group
Databoxes	FORM_DATA_BOX
Devices	DEVICE
Documents	DOCUMENT
Document Template	DOC_TEMPLATE
DocuVault parameters	DV_PARAMETERS
DV Users	DV_USER
Font	FONT
Font substitution	FONT_SUB
Formats	FORMAT
Forms	FORM
Images	IMAGE
Imaging queues and batch settings	IMAGING
Imaging queues only	IMAGE_QUEUE
Indexes	INDEX
RDM groups, reports, and subreports	RDM_GROUP
RDM reports	RDM_REPORT
RDM subreports	RDM_SUBREPORT
Recipients	RECIPIENT
Regions	REGION
Roles	ROLE
Saved Queries	SAVED_QUERIES
Stock substitution tables	STOCK_SUB
Stocks	STOCK

When exporting CPF Groups, specifying an individual Group is not implemented. Exporting is only available for all groups.

When exporting DV Users from another DocuVault, the password is emitted as the hash value in hex preceded by a tilde character.

Specify the name of the object that you wish to export.

•

If you wish to export all resources of the type you specified in step 2. , then you will not need to specify a name.

•

If you wish to specify a particular object, look up its name in the module used to configure it.

If you choose to export a document, you must use the document ID. For example: document obj_id=1234.

You can specify an obj_id when exporting a form, form_data_box, or image to indicate which object is to be exported.

•

If you do not specify the ID for a form or image, Cypress exports the newest one with that name.

•

If you do not specify the ID for a form_data_box, Cypress exports all forms with that name.

In most cases, specifying the correct name will be straightforward. For example, if you want to export Printer 1, then the name will be Printer 1. If, however, you need a particular RDM report, it must be preceded by its group, which is followed by a slash, for example:

RDM GROUP/RDM REPORT

A specific RDM subreport must be preceded by both its group and its report separated by slashes, for example:

RDM GROUP/RDM REPORT/RDM SUBREPORT

A specific sub-bundle must be preceded by its bundle name, for example:

BUNDLE/SUB-BUNDLE

If you chose RDM_REPORT or RDM_SUBREPORT as the resource type, you must specify a specific report or subreport. If you need to see all reports or subreports, use the RDM_GROUP resource type instead.

Although you cannot export a specific databox, you can export all databoxes for a particular form by specifying the form name. You also can export all regions for a particular report group by specifying the name of the report group and all global regions by specifying <global regions>.

When exporting saved queries, the obj_name parameter specifies the Recipient name. If provided, the saved queries for that Recipient are exported. If not specified, all saved queries are exported.

Specify the DocuVault from which you want to export the data.

•

If the DocuVault is on Cypress Server where you are running the export_xml utility, you can enter only a period (.) at the command prompt.

•

If the DocuVault is on a different server than where you are running the export_xml utility, you must enter the full name and IP address of the DocuVault at the command prompt.

For example, enter something like “Prod_DocuVault@127.0.0.1” in the command prompt window.

If your system is running in a Windows Server 2008 environment, enter something like “Prod_DocuVault@::1” in the command prompt window.

Specify the export directory into which the export file will be created.

•

If the directory that you specify does not exist, Cypress will create it.

•

If the folder name is not preceded by a drive, the folder will be created as a subdirectory of the Cypress Server directory.

•

If the folder name is a fully qualified path, including a drive, the folder will be created in that location.

•

If desired, specify the file prefix with the Prefix attribute. If not specified, the DocuVault name will be used as the prefix.

For example, the command Export_xml device dv=. export_dir=d:\temp run against a DocuVault named Prod
will create a file named d:\temp\Prod_devices.xml.
The command Export_xml device dv=. export_dir=d:\temp prefix=Export_2014_0709 will create a file named d:\temp\Export_2014_0709_devices.xml.

Specify the unit of measurement that should be used. All measurements can be exported in units of inches or centimeters.

You can skip this step if you want to use inches, which is the default setting.

•

If you are exporting documents, forms, or images, continue to step 8. .

•

If you are exporting any other resource, go directly to step 11. .

If the items you are exporting contain any special control characters in the data (characters 0x00 thru 0x1F), add the escape_control_chars parameter. This will cause these characters to be escaped so they will be correctly processed by XML. An attribute denoting this will be added to the XML so the Import process will know of their existence.

If you are exporting a document, form, or image and want to export system fonts, enter export_system_font on the command line.

The export_system_font option is used for exporting only documents, forms, and images. It specifies whether to export system fonts. This option is turned off by default. Document-centric fonts (i.e., non-system fonts) are not affected by this option and will always be exported. System fonts are exported only when you enable this option.

Enabling the export_system_font option can increase the size of the exported data file.

If you are exporting a document or a form and want to export embedded forms or images, enter export_embedded_form/image on the command line.

The export_embedded_form/image parameter specifies whether to export embedded forms or images. This option is used to export only documents and forms. This option is turned off by default. You must enable this option in order to export embedded forms and images of a form or document.

10.

If you want to export only a range of pages from the document, enter start_page=<page number> and/or end_page=<page number> on the command line.

The start_page and end_page parameters specify the desired range of pages of a document to be exported. These parameters are used only for document export and, by default, the entire document is exported.

11.

Enter the export_xml command line at the command prompt.

•

If you choose not to specify a particular object, the command line will be in this format:

X:\Cypress\Server\export_xml <parameter from step 2> dv=”<DocuVault name from step 4>”export_dir=”<export directory from step 5>” unit_of_measure=<unit of measurement from step 6> export_system_fonts export_embedded_form/image

The unit_of_measure, export_system_font, and export_embedded_form/image parameters are optional.

12.

Once the export has completed, be sure to check the XML file to verify that everything has been exported as you expected. The XML file name is determined by Cypress and will always be the name of the DocuVault followed by an underscore and the type of resource that was exported. For example, the XML files created in the examples above would be named:

Test_DocuVault_RDM_Groups.xml

Test_DocuVault_Forms.xml

Prod_DocuVault_Address_book.xml

Prod_DocuVault_Document.xml

For documents, forms, and images, there is a second file created as a result of exporting. It has the same name with a different extension: DAT (data file).

•

If you choose to export all available resources, a separate XML file will be created for each type of resource. If, however, you use the IMAGING resource type, which exports both imaging queues and imaging prototypes, only one XML file will be created. This file will be named <DocuVault>_Imaging.xml.

If you wish to use this file with a reporting application such as Crystal Reports, you must convert it to an ADO-compatible schema. Cypress provides the xml_converter utility for this purpose. See Converting Cypress Export XML for further information.

Examples

These are some examples of how you can use the export_xml utility. See export_xml Parameters for a complete reference to all export_xml parameters.

Example 1

Assume that you are exporting all RDM reports and subreports from a test DocuVault. Your command line would look something like this:

C:\Cypress\Server\export_xml RDM_GROUP dv=”.” export_dir=”C:\Exports\RDM Reports” unit_of_measure=inches

Example 2

Assume that you are exporting all forms from a test DocuVault. Your command line would look something like this:

C:\Cypress\Server\export_xml FORM dv=”.” export_dir=”C:\Exports\Forms” export_embedded_form/image

You can export all resources, including forms and images all at once, but only one document at a time.

•

If you choose to specify a particular object other than a document, the command line will be in this format:

X:\Cypress\Server\export_xml <parameter from step 2> obj_name=”<object name from step 3>” dv=”<DocuVault name from step 4>” export_dir=”<export directory from step 5>” unit_of_measure=<unit of measurement from step 6> export_system_fonts export_embedded_form/image

If you choose to specify a particular document, the command line will be in this format:

X:\Cypress\Server\export_xml <parameter from step 2> obj_id=<object id from step 3> dv=”<DocuVault name from step 4>” export_dir=”<export directory from step 5>” unit_of_measure=<unit of measurement from step 6> export_system_fonts export_embedded_form/image start_page=<page number from step 10> end_page=<page number from step 10>

The unit_of_measure, export_system_font, export_embedded_form/image, start_page, and end_page parameters are optional.

Example 3

Assume that you are exporting a single manager’s Address Book information so you can duplicate and modify it for each manager in that department. Your command line might look like this instead:

C:\Cypress\Server\export_xml RECIPIENT obj_name=”LBLewis” dv=”Prod_DocuVault@127.0.0.1”

export_dir=”D:\Exports\Address Book” unit_of_measure=centimeters

Example 4

Assume you are exporting a document, your command line would look something like this:

C:\Cypress\Server\export_xml document obj_id=1234 dv=”.” export_dir=”d:\temp

prefix=Export_2014_0709” export_system_font start_page=3 end_page=5

export_xml Parameters

Use the syntax illustrated in this figure for the export_xml.exe program. The first parameter—object type—must appear first in the command string. The other parameters can appear in any order.

This table describes the export_xml parameters. All the parameters are optional unless otherwise indicated.

Parameter

Description

obj_type

Required. Specifies the object type that you want to export. These are the obj_type parameters:

•

ALL (exports all resources, except documents)

•

BANNER

•

BUNDLE

•

CPF_GROUP

•

DEVICE

•

DOCUMENT

•

DV_PARAMETERS

•

DV_USER

•

FONT

•

FONT_SUB

•

FORM

•

FORM_DATA_BOX

•

FORMAT

•

IMAGE

•

IMAGE_QUEUE

•

IMAGE_PROTOTYPE

•

IMAGING(exports both image queues and image parameters)

•

INDEX

•

RDM_GROUP(exports groups, reports, and subreports)

•

RDM_REPORT

•

RDM_SUBREPORT

•

RECIPIENT

•

REGION

•

ROLE

•

SAVED_QUERIES

•

STOCK

•

STOCK_SUB

obj_name

Required. Specifies the name of the resource that you want to export, with the exception of documents.

•

If the parameter is omitted or is set to a null string, all of the objects of the specified resource type will be exported.

•

If multiple resources of this type share the same name, the one created last will be exported.

In most cases, the object name is straightforward, with these exceptions:

•

You must specify RDM reports in the form RDM Group/RDM Report, and RDM subreports in the form RDM Group/RDM Report/RDM Subreport.

•

You must specify sub-bundles in the form Bundle Name/Sub-Bundle Name.

•

When exporting saved queries, the obj_name parameter specifies the Recipient name.

You can export all databoxes for a particular form by setting obj_name to the name of the form.

•

To export all regions for a particular report group by setting obj_name to the name of the report group.

•

To export all global regions, set obj_name to the literal <global regions>.

These are some examples of specifying the obj_name parameter:

obj_name=”Accounting Reports/Departments/Sales”

obj_name=””

obj_name=”Printer 1”

obj_name=”<global regions>”

obj_id

Required when exporting a document; specifies the ID of the document to be exported.

For example:

export_xml document obj_id=2008 dv=”.” export_dir=”d:\cyp_export” start_page=16 end_page=25 export_embedded_form/image

You can also use this parameter when exporting a form, form_data_box, or image to specify which object is to be exported.

•

If you do not specify the ID for a form or image, Cypress exports the newest one with that name.

•

If you do not specify the ID for a form_data_box, Cypress exports all forms with that name.

Required. Enables you to specify the DocuVault from which you want to export resources. To specify the local DocuVault, you can use a period (.) instead of a DocuVault name. For example:

dv=”.”

dv=”ABCDocuVault@ABCCompany-3”

export_dir

Required. Specifies the folder to which you want the XML file to be written.

•

If the folder name is not preceded by a drive, the folder will be created as a subfolder of the Cypress Server directory.

•

If the folder name is a fully qualified path, including a drive, the folder will be created in that location. For example:

export_dir=”DV_export”

export_dir=”D:\Exports\DV_params”

prefix

Specifies the prefix of the generated file title.

If not specified, the DocuVault name will be used as the prefix.

For example:

The command Export_xml device dv=. export_dir=d:\temp run against a DocuVault named Prod will create a file named d:\temp\Prod_devices.xml.

The command Export_xml device dv=. export_dir=d:\temp prefix=Export_2014_0709 will create a file named d:\temp\Export_2014_0709_devices.xml.

unit_of_measure

Specifies whether measurements should be given in inches or centimeters. For example:

unit_of_measure=inches

unit_of_measure=centimeters

escape_control_chars

Specifies whether special control characters in the export data (characters 0x00 through 0x1F) will be escaped so they can be correctly processed by XML. An attribute denoting this will be added to the XML so the Import process will know of their existence. For example:

export_xml image obj_name=”my_image” dv=”.”

export_dir=”d:\temp” escape_control_chars

export_system_font

Specifies whether system fonts are exported. This option is used only for exporting documents, forms, and images.

•

System fonts are not exported unless specified.

•

Document fonts (i.e., non-system fonts) are not affected by this option and will always be exported. For example:

export_xml image obj_name=”my_image” dv=”.”

export_dir=”d:\temp” export_system_font

export_embedded_form/image

Specifies whether embedded forms and/or images are exported. This option is used only for exporting documents and forms. Embedded forms and images are not exported unless specified. For example:

export_xml form obj_name=”my_form” dv=”.”

export_dir=”d:\temp” export_embedded_form/image

start_page

Specifies the start page of a document that is exported. This option is used only when exporting documents. The document will be exported from the first page unless the start page number is specified. For example:

export_xml document obj_id=2008 dv=”.”

export_dir=”d:\cyp_export” start_page=16

end_page

Specifies the end page of a document that is exported. This option is used only when exporting documents. The document will be exported through the last page unless the end page number is specified. For example:

export_xml document obj_id=2008 dv=”.”

export_dir=”d:\cyp_export” end_page=25

Converting Cypress Export XML

After the export_xml utility creates an XML file, you can use that file immediately with the import_xml utility. You can specify a name and path for the XML file created by the xml_converter utility when converting the file. If you want to use the exported data with a reporting application, however, you also must convert the information to a schema that is readable by Microsoft and other major reporting tools.

To convert Cypress export XML to an XML file that uses a known schema

Open a command prompt window.

Specify the name and path of the XML file that you want to convert.

•

If you have not modified this file since the export_xml utility created it, it will be valid and fully formed.

•

If you have made changes, you should verify their accuracy before you proceed.

To verify that an XML file is valid and fully formed, open it in your Internet browser. If the file contains a formatting error, the browser will display it.

Optional. Specify the name and path of the XML file that you want the xml_converter utility to create.

If you do not wish to specify a custom name, the xml_converter utility will append _converted to the name of the file in step 2.

Enter the xml_converter command line at the command prompt:

•

If you choose not to specify a customized output file name, the command line will look like this:

Cypress\Server\xml_converter input_file=”<XML file name
from step 2>”

•

If you choose to specify a customized output file name, the command line will look like this:

Cypress\Server\xml_converter input_file=”<XML file name
from step 2>” output_file=”<XML file name from step 3>”

For example, assume that you are converting an XML file that contains information about Cypress stocks, and you do not care what the xml_converter utility names the output file. In that case, the command line will look something like this:

C:\Cypress\Server\xml_converter input_file=”c:\Cyp_xml\ABC_DocuVault_stocks.xml”

On the other hand, if you convert the same file but wish to call it “Cypress_stocks_20050708,” your command line will look more like this:

C:\Cypress\Server\xml_converter input_file=”C:\Cyp_xml\ABC_DocuVault_stocks.xml”

output_file=”C:\Cyp_xml\Cypress_stocks_20050708.xml”

Once the conversion completes, look over the new file to verify that all information has been converted as you expected. You can then use this XML file with Microsoft applications and other reporting applications.

This figure illustrates the syntax for the xml_converter parameters.