Deployment of the WebHelp With Feedback System

System Requirements

The feedback-enabled WebHelp system of Oxygen XML Editor requires a standard server deployment. You can request this from your server admin and it needs the following system components:

A Web server (such as Apache Web Server)
A MySQL or MariaDB database server
A database admin tool (such as phpMyAdmin)
PHP Version 5.1.6 or later

Oxygen XML WebHelp system supports most of the recent versions of the following browsers: Chrome, Firefox, Internet Explorer, Safari, Opera.

Create WebHelp with Feedback Database

The WebHelp system needs a database to store user details and the actual feedback, and a user added to it with all privileges. After this is created, you should have the following information:

Database name
Username
Password

Exactly how you create the database and user depends on your web host and your particular needs.

For example, the following procedure uses phpMyAdmin to create a MySQL database for the feedback system and a MySQL user with privileges for that database. The feedback system uses these credentials to connect to the database.

Using phpMyAdmin to create a database:

Type localhost in your browser.
In the left area, select: phpMyAdmin.
Click Databases (in the right frame) and then create a database. You can give it any name you want (for example comments).
Create a user with connection privileges for this database.
Under localhost, in the right frame, click Privileges and then at the bottom of the page click the reload the privileges link.

Deploying the WebHelp output

If you have a web server configured with PHP and MySQL, you can deploy the WebHelp output by following these steps:

Connect to your server using an FTP client.
Locate the home directory (from now on, referred to as DOCUMENT_ROOT) of your server.
Copy the transformation output folder into the DOCUMENT_ROOT folder.
Rename it to something relevant, for example, myProductWebHelp.
Open the output folder (for example, http://[YOUR_SERVER]/myProductWebHelp/). You are redirected to the WebHelp installation wizard. Proceed with the installation as follows:
1. Verify that the prerequisites are met.
2. Press Start Installation.
3. Configure the Deployment Settings section. Default values are provided, but you should adjust them as needed.
  Tip: You can change some of the options later. The installation creates a config.php file in [OXYGEN_WEBHELP]/resources/php/config/config.php where all your configuration options are stored.
4. Configure the MySql Database Connection Settings section. Use the information (database name, username, password) from the Create WebHelp with Feedback Database section to fill-in the appropriate text boxes.
  Warning: Checking the Create new database structure option will overwrite any existing data in the selected database, if it already exists. Therefore, it is useful the first time you install the WebHelp with Feedback system, but you do not want to select this option on subsequent deployments.
5. If you are using a domain (such as OpenLDAP or Active Directory) to manage users in your organization, check the Enable LDAP Autehntication option. This will allow you to configure the LDAP server, which will provide information and credentials for users who will access the WebHelp system. Also, this will allow you to choose which of the domain users will have administrator privileges.
6. If the Create new database structure option is checked, the Create WebHelp Administrator Account section becomes available. Here you can set the administrator account data. The administrator is able to moderate new posts and manage WebHelp users.
  The same database can be used to store comments for different WebHelp deployments. If a topic is available in more than one WebHelp deployments and there are comments associated with it, you can choose to display the comments in all deployments that share the database. To do this, enable the Display comments from other products option. In the Display comments from section, a list with the deployments sharing the same database is displayed. Select the deployments allowed to share common feedback.
  Note: You can restrict the displayed comments of a product depending on its version. If you have two products that use the same database and you restrict one of them to display comments starting from a certain version, the comments of the other product are also displayed from the specified version onwards.
7. Press Next Step.
8. Remove the installation folder from your web server.
  Important: When you publish subsequent iterations of your WebHelp system, you will not upload the /install folder in the output, as you only need it uploaded the first time you create the installation. On subsequent uploads, you will just upload the other output files.
9. In your Web browser, go to your WebHelp system main page.

Testing Your WebHelp with Feedback System

To test your system, create a user and post a comment. Check to see if the notification emails are delivered to your email inbox.

Note: To read debug messages generated by the system:

Enable JavaScript logging by doing one of the following:
- Open the log.js file, locate the var log= new Log(Level.NONE); line, and change the logging level to: Level.INFO, Level.DEBUG, Level.WARN, or Level.ERROR.
- Append ?log=true to the WebHelp URL.
Inspect the PHP and Apache server log files.

Documentation Product ID and Version

When you run a WebHelp with Feedback transformation scenario, by default you are prompted for a documentation product ID and version number. This is needed when multiple WebHelp systems are deployed on the same server. Think of your WebHelp output as a product. If you have 3 different WebHelp outputs, you have 3 different products (each with their own unique documentation product ID). This identifier is included in a configuration file so that comments are tied to a particular output (product ID and version number).

Note: The WebHelp with Feedback installation includes a configuration option Display comments from other products that allows you to choose to have comments be visible in other specified products.