Importing and Exporting Dialogs and Dialog Survey Reports

This chapter provides an overview of the Online Marketing Dialog Mover and Dialog Response Export, and discusses how to:

• Export dialogs

• Import dialogs

• Export dialog security results.

Understanding Dialog Mover

When running Online Marketing as a standalone application, developing and deploying an Online Marketing dialog in a single location is a viable option, but customers running integrated applications that need to access other CRM data need to be able to develop the dialog in one location and then move it to their production environment once it has been completed and tested.

The Dialog Mover allows you to develop a dialog and then export it to an XML file, which you can then import to another location. It consists of two utilities:

• Dialog Export, which copies the dialog and saves it to a file that can be transferred between the two systems.

• Dialog Import, which reads the file and translates it back into the form of an Online Marketing dialog.

What Dialog Mover Moves

Dialog Mover moves the following dialog components:

• Web documents.

• Email documents.

• Dialog flow.

What Dialog Mover Does Not Move

Dialog Mover does not move shared objects, such as:

• Business units.

• SetIDs.

• Profiles.

• Audiences.

• Templates.

• Mailboxes.

• Custom extensions.

These items will need to be moved manually from the original system to the target before the dialog is exported. If these items are not in place prior to the export, Dialog Mover displays an error message and the dialog will not be moved.

Furthermore, Dialog Mover does not update dialogs in any way.

How Dialog Mover Works

Because the source and target databases in some cases are not accessible at the same time due to firewalls, security issues, or other reasons, Dialog Mover is split into two steps for moving dialogs and other related objects. The first step, Dialog Export, translates the dialog's components into an XML document that is portable from one machine to another. The second step, Dialog Import, translates the XML document back to a dialog format (provided that its attendant shared components have already been manually moved to the new machine first).

Dialog Mover does not require that dialog components (such as web and email documents) retain the same ID numbers across systems. Since there is no way to know whether the IDs are in use by other objects on the target system, Dialog Mover ensures that the links are synced up correctly across each system by matching on object name rather than ID number. Shared objects are referenced primarily by name, but can also be referenced by other properties such as type or status.

Imported dialogs are created in the new system in an In Design state. They must be activated before they can be ready for production. Users can use an In Test state to verify the imported dialog before moving it to a Live state.

Only users with Dialog Administrator permission can use the Dialog Mover to import and export documents. Only one dialog can be exported at a time.

Note. Dialog Mover will only support moving dialogs between databases that have the same A. You cannot use Dialog Mover to move a dialog from a source database with one base language to a target database with a different base language.

Dialog Mover Memory Allocation

When moving large dialogs, Dialog Mover can experience errors if sufficient memory is not allocated to it in both the host and the target systems. It is recommended that the maximum heap size be set to at least 500 megabytes if you will be moving large dialogs.

Exporting Dialogs

Dialog export consists of five steps, some of which are optional:

1. Select a dialog to export.

2. Run Dialog Check (optional).

3. Run the Dialog Dependency Report (optional).

4. Export the select Dialog and Save the export file.

5. View any messages about the export.

Pages Used to Export Dialogs

Selecting a Dialog to Export

Access the Dialog Export page (Marketing, Dialog Mover, Dialog Export).

Only the current In Design version can be accessed; if the dialog has both a Live and In Design version, you may want to select Revert to Live in the In Design version so that the In Design and Live versions are the same.

Running Dialog Check

Access the Dialog Check page (Click the Check Dialog button on the Dialog Export page).

This step is optional; it is not necessary to run Dialog Check before exporting a dialog. The Dialog Check page is described in the documentation on creating a dialog.

Click the Return link to return to the Dialog Export page.

See Designing Online Dialogs.

Running the Dialog Dependency Report

Access the Dialog Dependency Report (Click the Dialog Dependency Report button on the Dialog Export page).

The Dialog Dependency Report lists all the profile fields, audiences, mailboxes, custom extensions, templates, and so forth used within the documents. You must make sure that all of these items exist on the target database before you can import this dialog (after the export file is generated), or the import operation will fail.

You can save the Dialog Dependency Report to a file by clicking the Download icon.

Saving the Export File

After you have verified that all necessary shared objects exist on the target system, click the Export to File button on the Dialog Export page. If you haven't selected a dialog, an error message will appear asking you to select one before exporting.

Note. You should disable any pop-up blockers prior to clicking the Export to File button, or the file download window might not appear.

Dialog Mover prompts you to open the file or to choose a location in which to save it. Click Save and save the file to your local machine. The default name for the file is dialog_<original dialog id>.xml (for example, a dialog with the Dialog ID of 20001in the source system will be saved as dialog_20001.xml), but you can change this name. The default save location is the browser's default.

Note. The Dialog ID will likely be different in the target system (following the dialog's import).

Warning! If you do not click Save, then the file is not saved to your machine, but Dialog Export will still treat the export as having completed successfully (assuming that it could be generated).

Viewing Dialog Export Status

You can view the status of the dialog export using the Control Center's Dialog Mover Status Report page.

See Viewing Dialog Mover Status.

Importing Dialogs

This section provides an overview of the Dialog Import process and discusses how to:

• Select an XML file to import.

• Check for version and name conflicts.

• Check dialog dependencies.

• Check the dialog.

• Confirm and import the dialog.

• View status.

Understanding Dialog Import

Dialog import creates a new dialog on the target system, using the data from a source XML file generated during the dialog export process. The new dialog is always saved in the In Design state, and it is not necessary that the dialog be in a state that will pass Dialog Check in order to allow the import.

After the dialog has been successfully exported, you must physically transfer the XML file to the target system (or a location that it can access) and then run the import process. Only Dialog Administrators have permission to run the import—users who do not have this permission will not see the Dialog Mover and Dialog Import links.

Warning! Modifying the XML file between the time it is exported and the time it is transferred to the target system is not supported and can cause errors in the import process and unexpected or unwanted behavior by the imported dialog. Further, you should not use Dialog Mover for upgrade purposes.

Pages Used to Import Dialogs

Selecting an XML File to Import

Access the Select Import File page (Marketing, Dialog Mover, Dialog Import).

Select File	Click to display a File Upload page, where you can select an XML file to import.
Process Overview	Click to display a page showing an overview of the steps in the dialog import process.

After you have selected an XML file and clicked Next Step, Dialog Mover validates the file. If the file is corrupt or otherwise invalid, the process stops and an error message appears; otherwise, continue to the next step.

Checking for Version and Name Conflicts

Access the Version and Name Check page (click the Next Step button on the Dialog Import Wizard Step 1: Select Import File page).

This page displays the environment version and duplicate names. If the source and target environments are different in the following respects, the differences are shown:

• CRM release version

• Database type

• Database version

• PeopleTools version

Note. Importing dialogs when source and target versions are inconsistent is not supported and can cause Dialog Import to behave unexpectedly. However, you can still continue the process if you want.

If a dialog or document with the same name exists in the target database, or if the dialog or document had been imported before, the currently-imported dialog and documents are given new names and created as an entirely new dialog for the conflicts. The renaming convention is the same as that for clone dialogs: a space and a numeric suffix are appended to the name. If the name already ends in a space and a number, then the number is increased incrementally. For example:

Only the old names of conflicting dialogs and documents are shown on the Name and Version Check page; the new names will be shown at the end of the dialog import process.

The following names might be changed during the import process:

• Dialog

• Document

• VCObject

• Merge Content - Document Field

• Merge Content - WebLink

• Merge Content - Dynamic Content

• Dynamic Content sections

• Custom Extension

• Temporary Link

Checking Dialog Dependencies

Access the Dialog Import Wizard Step 3: Dialog Dependency Report page (click the Next Step button on the Dialog Import Wizard Step 2: Version and Name Check page).

The following table shows all of the dependencies that must be in place before the import can proceed.

Note. All name checks are case-sensitive.

If any of the dependencies are missing or mismatched, Dialog Import will display an error message and will not continue. Only if all the required dependencies are in the target system will the import process continue. In addition, a Relink warning message will appear for missing dialogs referenced by cross-dialog links; in this case, the cross-dialog link will still appear but it will not point to a dialog.

Regardless of whether the dependencies are missing, the Dependency Report will show the overall status and a list of missing, matched, or both dependencies. By default, the list is sorted by status. You can save this page to a file for reference by clicking the Download icon in the grid. Note that the Next Step button will not be accessible if any dependencies are missing or mismatched.

Checking the Dialog

Access the Dialog Import Wizard Step 4: Dialog Checklist page (click the Next Step button on the Dialog Import Wizard Step 3: Dialog Dependency Report page).

The Dialog Checklist displays information about the steps that you might need to perform following the import. For example, you might have to complete:

• Cross-dialog links: If the dialog contains a link to another dialog, then the cross-dialog link will search (via Dialog Name and Action Name) for the other dialog to link to. If the other dialog action exists, then the link will point to it. If the target action does not exist, the link will point to nothing, and this will be noted on the Dialog Checklist.

• External links in variable content: If the dialog contains any external links, they will be listed in the Dialog Checklist so you can check the URLs and verify that they are still valid.

• Audiences: A list of all the audiences used in the dialog will appear along with a note reminding you to check them and verify whether they need to be regenerated or whether their queries must be changed.

• Templates: You might need to modify the URLs of any web templates used in the dialog.

• Mailboxes: You might need to modify the values of the mailboxes used with the dialog.

• Submit button: If the Submit button is pointing to an image, you might need to verify that the image URL is still correct.

You can save the Dialog Checklist to a file for reference by clicking the Download icon.

Confirming and Importing the Dialog

Access the Step 5: Confirmation page (click the Next Step button on the Dialog Import Wizard Step 4: Dialog Checklist page).

Verify the selected Dialog and click the Import button to start the dialog import.

Viewing Status

When the import process finishes, Dialog Mover displays the Dialog Import Wizard: Dialog Import Status page.

If any objects (dialogs or documents) were renamed during the import process, the old and new names appear on this page. You can save the page for reference by clicking the Download icon.

Click the Dialog Mover Status Report link to display the Dialog Mover Status page in the Control Center. On this page, you can view the status of the import as it runs.

Exporting Dialog Responses

In addition to viewing CRM Online Marketing survey information using the delivered Individual Response Report functionality, you can also export the data into an XML format so that users can easily extract it into a Microsoft Excel spreadsheet or any other data analysis software.

Setting Up Dialog Response Export

Before you can use Dialog Response Export, the administrator must perform some setup tasks. These include ensuring that:

• The PS_FILEDIR environment variable is set on the server where Process Scheduler is running.

• SMTP is configured to get email from the Process Scheduler.

• The export FTP server is available.

• The setup URL points to the FTP server.

Setting the PS_FILEDIR Environment Variable

The administrator must set the PS_FILEDIR environment variable on the server where the Process Scheduler is running. This variable is usually set to PS_HOME\appserv\prcs\<db_name>\files\. This is required in order to be able to write files to the application server/process scheduler server.

Refer to your operating system documentation for information about how to set environment variables.

Configuring SMTP

The Process Scheduler must be running with Report Node configured and must have proper SMTP settings in order to receive an email confirmation upon execution of the Dialog Response Export process.

See Enterprise PeopleTools 8.50 PeopleBook: PeopleSoft Process Scheduler, “Using Report Manager”

Setting Up the URL

To set up the URL to point to the proper FTP server where the exported file will be attached, use the URL Maintenance page (PeopleTools, Utilities, Administration, URLs).

Open the URL definition RY_DRE and replace the delivered URL with the a valid URL pointing to the FTP server where you want the export file to be located.

Exporting Dialog Responses

To export dialog responses, you use the Dialog Response Export page (Marketing, Operational Reports, Document Responses, Dialog Response Export).

Click Add a new value and enter a new report ID, then click Add.

Export Considerations

You should be aware of the following considerations when exporting dialog information:

• The dialog must be live.

• Only completed responses are exported.

• Only the following types of questions can be exported:

  • Profile Field

  • Text

  • Single Choice

  • Choose One with Rating

  • Yes/No

  • Multiple Choice

  • Date

  • Number

  • Comment

Export Validation

The following validations are performed when a dialog is exported:

• The Export ID should contain only letters and numbers without any spaces.

• If they are included, the Through Date value should be later than the Response From Date value.

• The dialog prompt should be secured based on the dialog's security, and users and roles should be authorized for both Individual and Aggregate reports.

• The audience prompt should be secured based on the audience's security and on the users' and roles' authorization for the audience.

Exporting the Dialog

After you enter the correct information and click the Export button, the system starts a batch process to perform the export. A message is displayed informing you that the export is in process. The Dialog Response Export page displays the process instance and the run status; you can click the Refresh Status button to view the current status of the export. You can also click the Process Monitor link if you want to display more detail about the process.

If an email address is associated with the User ID that ran the process, then an email message is sent to that address when the export is complete. Because the exported file is large, the email will not contain the file itself; rather, the email is a confirmation that the process has been completed. The user must log in to the application to download the exported file.

Saving the XML File

When the export is complete, the system creates a zipped XML file, which it stores in the FTP location specified on the URL Maintenance page. To use the file, open it by clicking the Download Export Results link and save it to your computer.

Importing the XML File to Excel

To import the XML file to an Excel spreadsheet:

1. Unzip the zipped file.

2. Open Excel.

3. Select Data, Import External Data.

4. Select the XML file from the local directory where you have stored it.

5. Click Open.

6. Click OK to let Excel auto-create the schema.

7. Highlight the cell where you want the data to be imported.

8. Click OK.

Dialog Responses in the Spreadsheet

When the XML file has been imported into Excel, it looks similar to the following illustration.

• The First Name, Last Name, Gender, Phone, Email, City, State, Country, Response Date, Question, Response, Score, and Comments values are shown as columns.

• Questions show up as rows.

• If the dialog documents are not of type Survey, the Score column will contain no data.

• The data format (font, color, and so on) can vary, and you will need to define it in Excel.

• If the dialog was set up for anonymous responses, the First Name and Last Name columns will display “Anonymous.”