We’ve developed some resources to help you work effectively from home during COVID-19 Click to learn more

Convert from eJournal 4.x

In this article

    To upgrade from eJournal 4.x on Windows to SuperOffice Customer Service.
    A lot of differently implemented installations exist, and one might need to adapt the installation procedure to the particular installation in these cases. However this document should be a general guide providing enough information to handle most special cases as well. As the upgrade from eJournal 4.x to SuperOffice Customer Service requires several steps and converting a lot of data, we recommend that a test run is done to verify the process, the conversion result and the amount of time it takes.


    The following abbreviations are used throughout the document.

    $ejPath The applications root directory. E.g. c:\SuperOffice\Customer Service
    $wwwPath Web directory. E.g. c:\SuperOffice\Customer Service \www\doc
    $cgibinPath Cgibin directory. E.g. c:\SuperOffice\Customer Service \www\bin
    $ejDomain The DNS name that the application uses. E.g. support.company.com

        
    Prerequisites


    Make sure you have upgraded to the latest eJournal 4.x version.

    – see http://techdoc.superoffice.com/webframe.html?eJournalUpgrade.html

    Make sure there are no simultaneous or read-only users in the eJournal 4.x installation. Either convert them into normal users or remove them.

    Make sure the eJournal 4.x installation is frozen.

    Stop the scheduler for 4.x and disable it.

    If you plan to use the same hostname as the 4.x installation, you should remove the existing eJournal IIS site.

    Install SuperOffice Customer Service – but do not start the scheduler yet. Pay close attention to the section about running ejtermsetup. It is important that ejtermsetup has been run and completed without errors before converter.exe is run!

    Make sure the new SuperOffice Customer Service installation is frozen by adding a new line in the config file found in the “$ejPath" folder with the word frozen

    # eJournal Config file (c) eJournal AS 2006
    # Created by ejsetup on 2010-11-08 11:49:26

    frozen
    dbHost = localhost
    dbUsername = ejournal
    dbPassword = ejournal
    dbDatabase = eJournalDB
    dbType = mssql
    ...

    SuperOffice Sales & Marketing must not be in use when converter is run. Make sure all users are logged out and stay logged out for the duration of the conversion process. In SOAdmin you may turn on "No login" under System Options - System events.

    Make sure the scheduler service for SuperOffice Customer Service is stopped.


    Converting the database to the SuperOffice 7 database schema

    From version 7.0 of SuperOffice Customer Service and SuperOffice Sales & Marketing, both applications are using the same database schema and database upgrade procedures. There are several scenarios:

    1 Upgrading into a freshly created 7.0 database, that does not contain user data. All eJournal 4.x data will be copied to the SuperOffice 7 database.
    2 Upgrading into an existing SuperOffice 7 database containing data that is integrated with the eJournal 4.x database. Integrated customers and companies will get updated with data from eJournal if it’s missing in the new database (e.g. a customer will only get the address from eJournal if it doesn’t have an address in this database). All other data will be copied to the SuperOffice 7 database.
    3 Upgrading into an existing SuperOffice 7 database that is not integrated with eJournal 4.x. All eJournal data will be copied to the new database. Customer and company duplicates may occur, and should be checked for after converting.

    Using converter.exe

    You will find the converter.exe application in the “$ejPath\bin” directory of your new SuperOffice Customer Service installation. This converter application will convert all your eJournal 4.x data to the SuperOffice CRM 7 database schema. This includes changes to the customer and cust_company tables as the application now use the CRM equivalents of those tables – the “person” and “contact” tables.

    If you are converting all the data into an existing SuperOffice CRM 7 database, you should first try to make sure the login names of users in the eJournal 4.x database match the username of the appropriate associates in SuperOffice CRM 7. This is the default behavior for matching users. If you prefer to use another approach, this can be accomplished by modifying the convertscript.txt file. Most likely you will need some help from consultants with such special adaptation of the upgrade and conversion process.

    The database conversion is aware of dbi SuperOffice integrations and should handle it well with regards to person/contact data “merging”. All rows are also run through the ejscript engine. This allows for customized transformation and other special cases and needs. Consulting support is generally necessary in such cases to make the conversion as smooth as possible.

    Before you start the converter, make sure the ODBC DSN associated with your hostname and Customer Service config file now points to the SuperOffice CRM 7 database you will be using. Also make sure that the variables in the “$ejPath\config” file are set to options that are valid for your target database. These variables should normally be correct.

    Here is an example of how the converter.exe is used in the general case:

    1 Start cmd.exe from the Start menu.
    2 Navigate to the “$ejPath\bin” directory.
    3 Run “converter.exe –help” to get a short explanation of parameters.
    In particular, the “--dbiagent” parameter should be used to specify the id of the dbi agent that was used to integrate with an existing SuperOffice CRM database. If there is no such dbi integration, the “--dbiagent” parameter should be omitted.
    4 Run e.g.:
    converter.exe -h localhost -d old_dsn -u ej-db-user -p password -t mssql --dbiagent 1 support.company.com ” . Change parameters according to your database settings and domain name.
    5 The converter.exe will then ask you about some default values etc. and perform the conversion.

    Explanation of parameters:

    -h Hostname. A server name where DSN to the old eJournal database is located. It is recommended to create the DSN to eJournal on the server where you are running converter.exe in which case -h parameter will be localhost 
    -d Source database. Name of the eJournal database 
    -u Source user. Database user which is used to access eJournal database. This user can't have Sysadmin role on SQL server and needs to have dbo set as default schema.
    -p Source password. Password for the database user.
    -t Source db type. Type of the eJournal database server - MySQL, MS SQL or Oracle.
    --dbagent id Dbagent parameter should be used to specify the id of the dbi agent that was used to integrate with an existing SuperOffice CRM database. If there is no such dbi integration, the “--dbiagent” parameter should be omitted.
    --debug Converter.exe will write more debuging information on screen
    --nowrite The conversion process will be tried but nothing will be written to the target database. This is a good way to test if there are no issues in the source database.
    target domain The domain for which the conversion is being done.


    Converter will perform checks and ask if you want to continue if it detects something that may cause problems. The checks are:

    Missing Customer Service licenses in the target system
    Not enough user licenses in the target system compared to users in the source system
    Tables that have more than 1 million rows, that may be skipped

    By default converter.exe logs output to converter.log You can view this file in a text editor that doesn’t lock the file (notepad is ok, but not MS Word) to monitor the conversion progress. The converter app runs several batches at the same time to use the database connections efficiently. The batch commands are written to a separate file before they are executed (tasklist.txt). If a batch fails you can run it again by copying the batch command from tasklist.txt and pasting it in cmd.exe.

    Converting a large database can take several hours, depending on server hardware and the amount of data being converted. As previously mentioned, we recommend a test run is done before the actual upgrade conversion takes place so this aspect of the conversion is well known.

    After conversion, you must check the log file you redirected output to (converter.log by default), to make sure everything was converted ok. The conversion will not stop if an error occurs, so it is important to check this so you can resolve problems or restart tasks that failed. When all the tasks of converter.exe are done without error, your data is converted to the SuperOffice CRM 7 database schema!

    If tables were skipped with the –skipTables parameter, the batch commands for those tables are written to skippedtasks.txt. These batches can be rerun later on, by copying the batch command from skippedtasks.txt and pasting it in cmd.exe

    Finalizing the conversion process

    Copy the attachment and text directory of the old eJournal 4.x installation to the new installation.

    Run “$ejPath\upgrade.exe” and follow the instructions. This will update profiles, screens and searches to the new SuperOffice 7 database schema.

    Restart the Netserver site in IIS. This will ensure that extra tables and extra fields are registered properly in Netserver.

    Verification of the upgrade

    Remove frozen from the “$ejPath\config” file of your new installation. The following checks can be applied to verify that the upgrade was successful.

    1 Go to “http://$ejDomain/scripts/rms.exe?action=about” (note that /scripts/ is the default virtual directory. Your installation might use something else). If the version reported by the link does not match the one prompted by upgrade it is a good indicator that the files have been installed to the wrong folders.
    2 Go to the customer portal and verify that it is correct. If it has changed, the template files have been overwritten. To recover your old files copy the appropriate backup folder “$ejpath\templates.xxxxx”, to “$ejPath\templates”
    3 If at any point an error form is received, this can indicate that the wrong database or domain has been upgraded. Run upgrade again and ensure the values entered are correct
    4 Navigate around and test that everything works as expected, focusing on key functionality, recent data and any adaptations or screens/scripts that are particular to your installation. Some scripts may require small changes to work with SuperOffice 7 and need to be updated manually.
    5 All DBI tasks are disabled when converted, so if any need to run on the new installation, they should be manually re-enabled from the GUI.
    6 Start the ejScheduler, either by running upgrade again and answering yes to that question, or go to services view and click start on “ejScheduler $ejDomain”.
    7 Verify that the application sends and receives email. Send an email to an account that is imported into the application. Verify that this email generates a ticket. Add a reply and verify that the message is recieved by the original sender. If this does not work as anticipated it could be an indication that the ejScheduler service has not been started. If this is the case, start the service and retry. If this still fails examine the log file at “$ejpath\log\warning.[todays date]”. Any recent warning/error here might indicate that the application was installed to the wrong folder, or did not upgrade the correct database. Run the install and upgrade script again if appropriate.