HELP DESK MANUAL INSTALLATION GUIDE

Transcription

1 Help Desk 6.5 Manual Installation Guide HELP DESK MANUAL INSTALLATION GUIDE Version 6.5 MS SQL (SQL Server), My SQL, and MS Access Help Desk 6.5 Page 1 Valid as of: 1/15/2008

2 Help Desk 6.5 Manual Installation Guide Table of Contents: Installation by Expinion.net... 3 Installing Help Desk Yourself Write Permissions on Database, and on the Upload (Export) folders: Unzip the downloaded file to any folder on your computer In Notepad, open the file called config.asp to make the following changes 'Create Your SQL Database Set Your Database Connection Save Your Config.asp and Upload Your Help Desk Folder: Verify Write Permissions on Database (Access), and on the export (Upload) folders: Initializing Help Desk via Administration: Login to Admin: Help Desk Settings: Agents Tab: Categories Tab: Security Levels: Agents Tab (Update Screen ) Add Issues: Customize Messages: Language Translations: Customizing the Header & Footer: Link Your Site: Optional Config.asp Settings: Trouble Shooting Guide Incorrect Server Path: Component: Common Installation Error Messages Other questions? Help Desk 6.5 Page 2 Valid as of: 1/15/2008

3 Help Desk 6.5 Manual Installation Guide Welcome to the manual installation guide for Help Desk 6.5 by Expinion.net, released January 18 th Please note that this installation guide is compatible only with version 6.5 and not with any previous versions. If you intend on using the automated installation utility, please use the Automatic Installation Guide instead of this one. (The manual installation guide can be found in the same download zip as you found this guide.) Installation by Expinion.net Expinion.net offers installation free of charge with any purchase; if you are interested please fill out the following form on our web site. Once we receive your request, it usually takes us between 24 and 48 hours to do the installation. You will be notified once we are finished. Note: After installation by Expinion.net, you should still go to the section below called Initializing Help Desk via Administration. (To change your password and to verify that messages are appropriate for your business, etc.) Expinion does not customize Help Desk to include your headers, nor does it add links to Help Desk from other pages on your site. For more information on adding custom headers etc. to your Help Desk, please visit our support area here. Help Desk 6.5 Page 3 Valid as of: 1/15/2008

4 Installing Help Desk Yourself If you can set write permissions on your server s help desk folder, then you don t have to do this install manually. You can probably use the Automatic Installation Utility. (See the Automatic Installation Guide that was also included in the download zip.) To continue with the manual installation, please read the next few steps. 1. Write Permissions on Database, and on the Upload (Export) folders: In step 7 below, you will be asked to verify write permissions on two folders. If you re using MS Access, the database folder must be both read and write enabled for internet users this is critical to the operation of your Help Desk. Your server may provide a control panel for this purpose. If not, and you are remotely hosted, you will need to ask your host to have these folders write enabled. Or to tell you which folders are write enabled. (You may wish to begin this process now, while you are working.) 2. Unzip the downloaded file to any folder on your computer. Open your editor of choice, or if you don t have one, open Windows Notepad application. Please note, that you should not use editors such as MS Front Page, which replaces certain characters and can corrupt the configuration file. 3. In Notepad, open the file called config.asp to make the following changes. The config.asp file is located in the main program folder (Help Desk 6.5), root directory. Notes: Please ensure that all variables containing text (characters or commas, etc.) have both quotes when you have finished editing. Note the comments (text beginning with a single ) above each setting, which contain helpful information. Ensure that all paths are changed to match your domain (virtual) and server (physical) paths. PURCHASE_ID Replace the text in the quotes with the purchase ID given to you by Expinion.net. This purchase ID can be found in the that contains the download links for this application. If you have lost this information you can try to find it with this utility: PURCHASE_ID = Your Purchase ID Here SET_BASE_PATH This variable expects a virtual path to the location where Help Desk is installed. Please make sure to include a back slash on the end of the path. (Quotes are required.) Ex: SET_BASE_PATH = Help Desk 6.5 Page 4 Valid as of: 1/15/2008

5 SET_ _COMP This variable allows you to select from supported pre-programmed components. The following are supported components and their corresponding SET_FROM_COMP value: 2 = Persits (ASP ) 3 = SMTPsvg 4 = CDONTS 5 = CDOSYS 1 6 = JMail 7 = Dundas 8 = CODSYS 2 - Windows 2003 Server 9 = CODSYS 3 - Windows 2003 Server 10= CODSYS 4 Windows 2003 Server, Exchange Server The following example enables CDONTS component. (No quotes.) SET_ _COMP = 4 As you have probably noticed we have 3 different values for CDOSYS component. This is done because the Windows 2003 might require a little different syntax. Please try value 8 or 9 at first when using Windows 2003 server. 1 Having trouble with your component? See the footnote below. DB_TO_USE Set this variable according to what database you will be using, if you will be using the MS Access database, then remove the from the line that is set to value 1; remove the from the line set to value 2, if MS SQL will be used. DB_TO_USE = 1 Don t leave the config.asp file yet, there s one more thing to do. Set the database connection. 1 If you aren t sure which component to choose, skip this step for now (leave it as the default component number 8.) You can modify this portion of the config.asp file when you ve had an opportunity to test whether or not the setting works! (The setting will affect s but will not prevent you from completing the rest of the settings.) You can view which types of components your server supports from your administration area, Tools tab, Help Desk Settings link. This form will show you a list of available features and components on your server, including components and paths. Once you see which components your server supports, you can go back to the config.asp file and change this setting. If you re having trouble receiving s, or are getting errors submitting an issue but can add an agent or category, see the troubleshooting portion of this document. Help Desk 6.5 Page 5 Valid as of: 1/15/2008

6 4. 'Create Your SQL Database You only need to read this step if you are using MS SQL database, if you are using MS Access please skip this step. (Proceed to step 5, below.) Before you can access your installation of Help Desk you need to create the necessary database structure on your SQL server. To do so please open the DB folder and open the file called MSSQL.sql. This file contains an SQL script that will create the necessary tables etc. for you. Simply run it against your database using the SQL Query Analyzer and make sure you have not received any errors. NOTE: This MS SQL script will NOT create a new database for you due to the fact that many hosts allow only one database per account and this database might already be created. So if you do not have a database yet create one now then run the MS SQL script, which will create the necessary structure on an existing database. 5 Set Your Database Connection This is the final and most important setting for your config.asp file. First, you have to identify which type of database you are using, and in the case of MS ACCESS whether or not you are accessing it from a DSN connection (which you have already set up), or you can simply point to the database included with your download. Please note that if you are using MS SQL database, you will need to create the database structure using the SQL script located in the DB folder. Please read step 4. Locate procedure OPEN_DB, remove the at the beginning of the two lines you will be using (the line beginning with '// is just instructional text and shouldn t have the removed). Then correct the paths to point to your domain. A copy of this portion of config.asp text is on the following page, with more details. The database connection area of your config.asp file will look similar to the clipping below the line. (Although they may not be in the same order.) Note the color-coding assigned to each database type, in this install guide only. Each database connection option begins with these characters // // PATH TO DATABASE Access Option 1 Set MyConn = Server.CreateObject("ADODB.Connection") MyConn.Open "PROVIDER=Microsoft.Jet.OLEDB.4.0;DATA SOURCE=E:\your_host_info\your_site.com\db\HD60.mdb" '// SAMPLE MapPath CONNECTION Access Option 2 'Set MyConn = Server.CreateObject("ADODB.Connection") 'MyConn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" & Server.MapPath("\path\db\HD60.mdb") & ";Persist Security Info=False" '// DSN CONNECTION ACCESS Access Option 3 'Set MyConn = Server.CreateObject("ADODB.Connection") 'MyConn.open = "DSN=helpdesk" Help Desk 6.5 Page 6 Valid as of: 1/15/2008

7 '// MS SQL CONNECTION 'Set MyConn = Server.CreateObject("ADODB.Connection") 'MyConn.Open "Provider=sqloledb;Network Library=DBMSSOCN;Data Source=server.example.com,1433;Initial Catalog=DB_NAME;User ID=USERNAME;Password=PASSWORD;" // MySQL Connection Set MyConn = Server.CreateObject("ADODB.Connection") MyConn.Open " Driver={MySQL ODBC 3.51 Driver}; Server=YOUR.MySQL.SERVER; uid=username; pwd=password; database=database_name; option=3; port=3306;" In all cases above, replace the text shown in red with that appropriate for your server. More details are provided below. Help Desk 6.5 Page 7 Valid as of: 1/15/2008

8 For MS SQL: 1. Locate the portion of your config.asp file, which is shown on the previous page in orange. 2. Remove the from the two lines below the title //MS SQL CONNECTION. The before the words Set and MyConn.Open, should not have a. Add any missing s. to the lines above, for the default Access database. 3. Change the SQL particulars to match your server s. That s it. (If you completed step 3 (Create your SQL database, above.) For MS ACCESS: Access connections can be made by selecting any one of the three remaining MS ACCESS connections (not the MS SQL one) shown above, depending on how you prefer to reach the database which is included. (Any of the first three color options, shown here as blue, red or green.) After choosing the single option, ensure that all other options have a at the front of the line (to rem out that line, as being information only). Change the portion shown in bright red to the path in your server. Descriptions of setting up each possible option, can be found on the next page. Where s my database? Your download folder already contains the database entitled HD60.mdb. It can be found in the program/db folder. (When uploading the files later, ensure that the database can be write enabled, but copy protected in this location if you plan to leave it here.) If your server will not allow write permissions to be set with the database located here, you will have to move it and change the path accordingly. For sites with Front Page extensions enabled, this is usually a folder named FPDB. What s my server path? To determine the correct server path, try uploading the setup.asp utility located in the download folder, next. Then call it in your browser from its new location on your site, to see some of your current server settings. (Read about using this utility here.) Or, contact your host for more information. Help Desk 6.5 Page 8 Valid as of: 1/15/2008

9 MS ACCESS: This is the simplest option for MS ACCESS, and can be used without setting up any DSN connection. To use this option: 1. Locate the portion of your config.asp file that is shown here in red. 2. Remove the from the two lines below the title //PATH TO DATABASE. (The before the words Set and MyConn.Open, should not have a.) 3. At this portion: SOURCE=E:\your_host_info\your_site.com\db\HD58.mdb;" change the path in red, to that of your server. This is the default location of the mdb file, but it may need to be moved if you can t set write permissions to it here. 4. Ensure that both characters ; are still at the end of the file changed in number 3 above. 5. If your server is unable to provide you with the physical path required in line 3 above, try using the setup.asp utility included with this application, and described here: MS ACCESS: This is another option for MS ACCESS that can be used, without setting up a DSN connection. To use this option: 1. Locate the portion of your config.asp file, which is shown here in green. 2. Remove the from the two lines below the title //PATH TO DATABASE. (The before the words Set and MyConn.Open, should not have a.) 3. At this portion: Server.MapPath("\path_to_HD_Folder\db\HD58.mdb;") Change the path in red, to that of your server. The db folder is the default location of the mdb file, but it may need to be moved if you can t set write permissions to it here. 4. Ensure that the ; is still at the end of the file changed in number 3 above. MS ACCESS: A third MS ACCESS option can be used if you already have a DSN connection. To use this option: 1. Locate the portion of your config.asp file, which is shown here in blue. 2. Remove the from the two lines below the title //PATH TO DATABASE. (The before the words Set and MyConn.Open, should not have a.) 3. At this portion: 'MyConn.open = "DSN=helpdesk" Change the DSN name to the one assigned in your DNS connection. 4. Ensure that the is still at the end of the file changed in number 3 above. Optionally you can add your own connection while reming (leave at the beginning of the line) the default four sample connections. When adding your own custom connection string, please make sure that the object variable is called MyConn. For MySQL Change the information in this connection string as required. Remove the at the beginning of the following line, and ensure that each line in all of the other MS Access (and MS SQL) path strings begin with. (MS Access is usually our default setting, and may have the removed by default.) Set MyConn = Server.CreateObject("ADODB.Connection") MyConn.Open " Driver={MySQL ODBC 3.51 Driver}; Server=YOUR.MySQL.SERVER; uid=username; pwd=password; database=database_name; option=3; port=3306;" Help Desk 6.5 Page 9 Valid as of: 1/15/2008

10 You can read more about the connection string here: If you are using MySQL database, you can find the SQL script, which creates the necessary database structure in the DB folder. An explanation about executing the SQL script, can be found here: Only one connection can be enabled at the time, ensure that all other connections in the config.asp file are commented (rem ed) out. 6. Save Your Config.asp and Upload Your Help Desk Folder: You re now finished with the config.asp file. Save it, close your editor, and if you are using a remote server, upload the entire contents of the Help Desk program folder (with the changed config.asp file) to your website using your FTP utility. (You don t have to name the folder program.) Note: There are also optional config.asp settings. These don t require any action from you at this time, but may prove valuable in the future. 7. Verify Write Permissions on Database (Access), and on the export (Upload) folders: This is critical. Your server may provide a control panel for this purpose. If not, and you are remotely hosted, you will need to ask your host to have these folders write enabled. Or to tell you which folders are write enabled. (If you need to move your MS Access database, then you will have to go back and change your database path accordingly.) Initializing Help Desk via Administration: In order for the Help Desk to work correctly, you will need to add categories, agents and other items that are necessary for its successful operation. Please read the following carefully as it might save you some headaches. Login to Admin: When you first install your copy of Help Desk, an agent profile is added already by default. You will need to use this profile in order to set-up your own personalized profile. The typical login area is: The default username and password are both: admin. (not case sensitive.) Login with the username and password mentioned above, then follow the instructions below. Help Desk Settings: Click on the Tools Tab, then on Help Desk Settings to access some additional settings, which will be used to customize your Help Desk. From here you can add optional fields to your issues (ticket) submission, add, edit and view areas, what the upload paths will be (for use with the Upload Manager tools on both the public and admin sides), whether files are checked for duplicate filenames (also for Upload Manager), what the client s default username and password Help Desk 6.5 Page 10 Valid as of: 1/15/2008

11 will be set to (for issues submitted internally), and whether the glossary is active and set to show each word/definition combination once only or for each occurrence. None of the settings here are essential to getting started, unless you really need one of the optional fields, and the upload manager immediately. *Once more, the folder that you want to use for uploading files (admin & public sides) will need to be write enabled before they can be used.* Hints: Since this is a new install, start with the [setting suggestions ] text link. The recommended settings will be pre-filled for you, and HD will attempt to discern your upload paths, etc. Use the Other Variables report at the bottom of the page to help determine server variables and paths. Part of the actual path for your server, will mostly be shown near the bottom of the page. You can copy this and add the correct (write enabled) folder name to the end of the path. Use the icons to see short online help text associated with each area. Agents Tab: Change the password and address of the default profile. Be sure to change the default admin agent password (or add a new agent and delete the old) because the default username and password is admin for every copy installed! (Avoid others fraudulently logging into your system.) Log out of the Help Desk administration (logout button on bottom of all pages) and log back in using your newly set-up profile. Categories Tab: The next thing you will need to do is add appropriate categories to your system. (Categories are used to sort issues/questions. Example Categories: Computers, Software, Games, Business ) At least one category must be added (Add New Categories button) in order for the Help Desk to function properly. (Note: Category names can be edited later, and further categories added; there is no need for the names to be perfect on the first try!) Security Levels: If all the agents should not have access to all features of Help Desk, you may want to establish some additional security levels with some restrictions. (Example: Can t delete any issues.) To do this: 1. Click on the Tools Tab, then on Security Levels; then on Add New Security Level. 2. Name the security level either after a group of agents who will use the security, or a feature of the security. Examples: Accounting or Fred or Junior Agent. 3. Select which features this agent should be able to perform. (Note: Access to tabs only, is for view only rights.) 4. Select the order. (This is the order in which security levels will be displayed in your multiple-choice menu.) 5. Click Add Level button. * Be sure to leave at least one agent with administrator access rights. (Rights to all activities.) Help Desk 6.5 Page 11 Valid as of: 1/15/2008

12 Agents Tab (Update Screen ) All agents assigned to a category will each receive notification when a new issue has been submitted to that category. (To ensure that at least one agent is assigned to a category, the agent who adds a category is automatically assigned as the supervisor. If no other agent is assigned, the supervisor will receive the notifications.) If you are the only agent for Help Desk, you will need to assign yourself to every category using Update Agent screen. Add other agents as required. Add Issues: You may wish to add some issues to get your Knowledge Base started. (See your Admin Guide for detailed instructions.) If you can t add an issue, but can add a category or agent, there may be a problem with your component. See the troubleshooting area at the end of this document. Customize Messages: You can get started populating your messages by clicking on the Apply Default System Templates button near the bottom of the page. These messages should then be customized to your preferences. You should also verify your URL where contained in the message. (You may have to use the scrollbar to see the entire message.) If you set the config.asp file to use HTML messages, you may use HTML tags to customize your message. An example is shown in this KB issue. Hint: Test your messages and your component installation at the same time by going to the public area and submitting an issue. You should get an as an issue submitter, and the agent(s) assigned to this category should receive an notification. Your application installation and set up is done! Once you are satisfied, you will want to implement the Help Desk by completing these last two items. Language Translations: Help Desk has been designed with the majority of visible text contained in one file for the public side, and one file for the admin side. Read KB issue for more about translating your help desk. Customizing the Header & Footer: Help Desk 6.5 is designed with one header and one footer file for the entire public side. So, you can include your site s menu by simply adding one include statement into each of these files (if your menus are also designed to be in a separate file). Otherwise you ll need to paste the code into the top of each of these two files. Read KB issue for more info. From the help desk root folder, look for these two files: inc_header.asp and inc_footer.asp. Help Desk 6.5 Page 12 Valid as of: 1/15/2008

13 Link Your Site: Once you successfully go through the above, you can put a link on your site to your new Help Desk! Then you can add issues that you anticipate, and/or receive support issues/questions from your visitors. (Note: Use the [Submit an Issue] button for faster KB populating, being sure to select Public in the Availability field.) Print or save a copy of the Admin Guide onto your PC. This will answer most questions you may have as an administrator of Help Desk 6.5. This version also has a brief End User Guide that you can modify slightly for your clients use. Optional Config.asp Settings: The following settings are not critical to the operation of Help Desk, and are therefore placed at the bottom of the config.asp file where they are set to a recommended default. You do not need to change these settings at this time, or ever. However, once you re familiar with your new Help Desk, you may find that changing one or more of these settings is desirable. COLLECT_ISSUE_HISTORY When set to 1, a history of events related to an issue will be kept. When set to 0, the log will not be kept. The recommended setting is 1. COLLECT_ISSUE_HISTORY = 1 blsend_internal When issues are being added by other agents (example, initially adding knowledgebase issues), it isn t usually desirable to have all agents that are assigned to that category get an for each new addition. To turn internally added issue s off, set this to False. If you wish all agents to receive an for even internally added issues, set this to True. blsend_internal = False BACK_TO_BACK_RELATIONS This setting affects program behavior when marking an issue as being related to another issue. When set to True, both issues will be marked as related to each other. When set to False, the one issue that you are working on will be marked as being related to the second issue, but the second issue will not be marked as being related to the first. BACK_TO_BACK_RELATIONS = True bluse_mms This setting is optional when Help Desk will be used together with Expinion Member Management System versions 3.5 and higher. When set to True, the HD will not require the username and password when submitting an issue, if the user is a logged in member. If not logged in, the submitter will need to enter the username and password. bluse_mms = False Help Desk 6.5 Page 13 Valid as of: 1/15/2008

14 Note: MMS can be used to also protect the entire KB from being accessed by non-members. This would require the protection code as described in the MMS/Example folder to be pasted into the Help Desk root s inc_header.asp file. ING_MODE Set this variable to either 1 or 2, when set to 1 all out going s will be formatted in plain text, while when set to 2 the out going s will be formatted as HTM, giving you more freedom over the messages style. ING_MODE = 2 USE_DEBUG Set this variable to true in order for Help Desk to handle any errors that might occur, set to False to see any errors that might occur in their natural state. (No quotes are required.) USE_DEBUG = True USE_SHORT_FORM Remove the from the line set to the value of 1 - if you'd like the public issue submit form to be a 1 step process. Remove the from the line set to the value of 2 - to have a 3 steps process, which queries the database for similar issues as the one being submitted, thus saving on the number of duplicate issues submitted. (No quotes should be around the number 1 or 2.) (This selection will show issue submitters a list of possible solutions to their issue.) USE_SHORT_FORM = 2 SEARCH_ALL Setting this variable affect the way public search is done. Set to 0 to search on issue titles only, this is recommended only if you have lots of issues in your public KB. Set to 1 to search on all available fields. 1 is the default setting. SEARCH_ALL = 0 TURN_OFF_LANGUAGE_OPT Set this to True to not give the user the option of changing the user interface language on the public side. Set to False to allow multi language user interface. TURN_OFF_LANGUAGE_OPT = True Help Desk 6.5 Page 14 Valid as of: 1/15/2008

15 Trouble Shooting Guide Incorrect Server Path: To determine the correct server path, try uploading the setup.asp utility; then call it in your browser from its new location on your site, to see some of your current server settings. You can find the setup.asp file in the unzipped download file, Guides folder. Or, contact your host for more information. Component: After completing your installation test your component by submitting an issue. If set incorrectly, the issue submitter and agent won t receive their s! Also, you ll get errors when adding an issue from either the public or admin areas, because you server is called from here. Here are some options to help determine what the correct component setting should be. a. Ask your host (or intranet administration) for the correct component b. Your server may also have this information stored in a control panel. c. Using your browser, login to the administration area. * Click on the Tools Tab found at the top of all pages. * Click on the Help Desk Settings tab. * Look near the bottom of the page to see if your Help Desk can determine the correct component for you. (Please note, this utility may not include the last two components on the list, for Windows 2003 servers. If no components are shown here, try using 9, then 8.) d. Or, simply try setting a different component number in your config.asp file, and test it. Notes: Admin login area can be found here: Default Username: admin, Default Password: admin Public area (test submissions) can be found here: If it doesn t work, try the next component. Common Installation Error Messages Microsoft OLE DB Provider for ODBC Drivers error ' ' [Microsoft][ODBC Microsoft Access Driver] Operation must use an updateable query. Solution: Make sure that you have set read and write attributes to the database, or that you have rights as a user to write to the database. To set read/write permissions for the database on a localhost, please do the following: Help Desk 6.5 Page 15 Valid as of: 1/15/2008

16 - Right click on the DB, select properties - Click on Security Tab, click on Add... button - Select IUSR_MACHINENAME account click on Add and OK - Click OK one more time. Microsoft OLE DB Provider for SQL Server error '80040e14' The name '#XX' is not permitted in this context. Only constants, expressions, or variables allowed here. Column names are not permitted. Solution: Make sure that you have correctly set the DB_TO_USE variable in the config.asp file to 2 for MS SQL or to 1 for MS Access database. Server object error 'ASP 0177 : f3' Server.CreateObject Failed Solution: Make sure that the variable SET_ _COMP is set to an component that is installed on your server. If you are using a component that is not supported by default, please contact us at service@expinion.net and we will provide support for it free of charge. Disallowed Parent Path /path/to/file.asp, line number The Include file '../config.asp' cannot contain '..' to indicate the parent directory. Solution: This is an error caused by the server settings. Some servers don t allow include files to be referenced by their virtual path, but rather must be referenced by direct path taken from the root. For example: A reference like this: <!--#include file="../config.asp"--> change to a reference like this: <!--#include virtual="/path_to/helpdesk/config.asp"--> If you need to replace the include statements throughout your helpdesk, you may wish to use a find/replace utility such as this: (available for free). We have provided a version of the Help Desk 6.5 for you already prepared for server with parent path disabled. See the Other folder. Please note that this version must be installed in a folder called HelpDesk placed in the root of your web site. Other questions? If your question has not been answered here, please check your Admin (Users) Guide, which is also included with the download. If you still have questions, please check our support area here: Help Desk 6.5 Page 16 Valid as of: 1/15/2008