Introduction

This document covers the installation process of the Wands for Oracle R12.1 Oracle systems.

The Wands for Oracle comprises a suite of products. The installation process set out below will install all the products although only those that are licensed will be active.

The installation process is executed entirely on the Oracle server. The application is accessed via the normal Oracle logon URL, but from a new Responsibility that is created during the installation process. No Wands software is required to be installed on the client machine.

If you need assistance during the installation process, please contact our support team at e4asupport@insightsoftware.com. 

Prerequisites

By installing the software into your system you acknowledge that you accept the terms of the Software License and Maintenance Agreement.

In order to run this version of Wands, the following prerequisites must be met: NB Check the Customer Support Community (https://help.insightsoftware.com/s/) for any updates since publishing.

Server Requirements

* We do not currently support Java Access Bridge and require this feature to be disabled. See Oracle Documentation.

Client Requirements

* We recommend the latest updates for all Excel versions.

Upgrade Previous Versions

Upgrading from Version 4

There is no upgrade process from version 4 as the new architecture is completely different from the previous version. This version can be installed independently of version 4 and both can co-exist on an Oracle server during the transition.

Workbooks created in version 4 will need to be upgraded when they are first opened in this version. There is a menu option under the Wand (Oracle) tab to execute this process.

The version 4 key will not work on this version.

Upgrading from 5.4.x

There is no upgrade option from 5.4. You can run the full installation process under section Installation on the Server “Installation on the Server”.

Upgrading from 5.5.x and higher

Follow these steps to perform an upgrade.

1. Confirm that both the Excel4apps and Excel4apps Reports Wand applications have been registered on you system.

   1. Log on to the Oracle system and select a responsibility like System Administrator that has permission to register an application.

   2. Navigate to the following menu: Application > Register.

   3. Query the values that start with Excel4apps% and confirm that the two required applications exist.

   4. If they do not both exist, follow just the instructions in section Setup the Excel4apps custom applicationsSetup the Excel4apps custom applications and then return here to continue the upgrade process.

2. Locate the Wands for Oracle install file. This is the complete zip file that was downloaded from our web site (which contained this installation guide). FTP it to the server as the applications user.

3. Unzip the Wands for Oracle install file.

4. Navigate to the Wands install folder that will have been created by the unzip process.

5. For UNIX systems, change permissions on the file “install.sh” to allow it to be executed.

6. Run the Wands for Oracle Installer using the UPGRADE option.

UNIX:

./install.sh UPGRADE

Windows:

C:\>install.cmd UPGRADE

7. If the APPL_TOP is not shared, repeat the process for the remaining nodes.

8. For shared APPL_TOP installations no further action is required.

9. If you are upgrading from a release prior to 5.13, bounce the Apache and JVM (OC4J) server for each applications node.

Upgrading from 5/6.x.x to 6.2.x and higher

Due to the change in Wands Launcher technology Autoconfig is required to be run for an upgrade to release 6.2.x.

Follow all steps outlined in section 3.3 Upgrading from 5.5.x and higher

Before step 9, please follow to these additional two steps.

1. Run AutoConfig on the applications tier.

2. Bounce the applications tier.

Installation on the Server

Pre-Install Steps

Follow these instructions in order to prepare the system for the installation and to deploy the install files:

1. Locate the Wands for Oracle install file. This is the complete zip file that was downloaded from our web site (which contained this installation guide). FTP it to the server as the applications user.

2. Unzip the Wands for Oracle install file.

Setup the Excel4apps custom applications

The Excel4apps custom applications are created via the Oracle forms as follows:

1. Log on to the Oracle system and select a responsibility like System Administrator that has permission to register an application.

2. Navigate to the following menu: Application > Register.

3. Create a new application as follows:

Install

This step involves running the Wands for Oracle Installer which will deploy the Wands files on the server, configure the Wands applet, load the Wands OAF home page and load the required application components e.g. the menu and responsibility.

Note: An option to install custom database tables has been included in the installer. Please see the Custom Database Objects section of this guide to understand the implications.

1. As the Applications node technology stack owner (applmgr), navigate to the folder on the server where you unzipped the install file.

2. Navigate to the Wands for Oracle install folder that will have been created by the unzip process earlier.

3. For UNIX systems, change permissions on the file “install.sh” to allow it to be executed.

4. Run the Wands for Oracle Installer

UNIX:

./install.sh

Windows:

C:\>install.cmd

5. Below is an example of the output that the installer will generate.

[applmgr@oracle12 wands_oracle21.1.0.0]$ ./install.sh  

Installer Mode: DB_AND_APPS_TIER

Wands for Oracle Installer Started

Enter the APPS username [APPS]:

Enter the APPS password:

Database Connection Details from Environment Context File:

/oracle12/VIS/inst/apps/VIS_oracle12/appl/admin/VIS_oracle12.xml

==========================================================

Server: oracle12

Port: 1522

Sid: VIS

Enter Y to use the following connection settings [Y]: Y

Enter Y to create custom tables in the APPS schema [N]: Y

Database Connection Details used for this installation: oracle12:1522:VIS

Servlet Configured Successfully

Files Deployed Successfully

OAF Pages Loaded Successfully

APPS Components Created Successfully

Customer Tables Created Successfully

Installer Completed Successfully

Program Exit Status=0

[applmgr@oracle12 wands_oracle21.1.0.0]$

Installation – AutoConfig

Once the install script has completed, proceed as follows:

1. Run AutoConfig on the applications tier.

2. Bounce the applications tier.

Installation – Multiple Application Tier Servers

1. If the APPL_TOP is not shared, repeat the install on the remaining Application nodes. Please note that when running the Wands for Oracle Installer on additional nodes you should use the APPS_TIER option. This will ensure that only the application tier components are deployed and the database components are not redeployed with each run.

2. Run the Wands for Oracle Installer with the APPS_TIER option.

UNIX:

./install.sh APPS_TIER

Windows:

C:\>install.cmd APPS_TIER

3. Below is an example of the output that the installer will generate

[applmgr@oracle12 wands_oracle21.1.0.0]$ ./install.sh APPS_TIER

Installer Mode: APPS_TIER

Wands for Oracle Installer Started

Servlet Configured Successfully

Files Deployed Successfully

Installer completed successfully

Program Exit Status=0

[applmgr@oracle12 wands_oracle.21.1.0.0]$

4. For shared APPL_TOP installations, simply run AutoConfig for the remaining nodes.

Log on for the first time

1. The installation process would have created the special Wands for Oracle responsibility. Log on to Oracle and assign the Wands for Oracle Responsibility to your Oracle user.

2. Log out of Oracle and close all browser windows.

3. Log on to Oracle in a fresh browser session using the user that you assigned the Wands for Oracle Responsibility to.

4. Launch the Wands for Oracle application. You will be requested to install a browser dependent plugin. Please see the Wands Launcher section of the online user guide for all supported browser plugin instructions. The launch process will load the Wands for Oracle toolbar into Microsoft Excel.

5. Request or enter a license key.

   • You may be prompted to request a license key or enter one received previously.

   • Additional details on requesting and entering license keys can be found in the Administrator section of the online user guide under the “System Administrator Options” section guide (accessible via the product or logging on to the customer community).

6. Configure system administrator options.

   • Required settings: The first time you log on you must flag one (or more) Oracle user as a Wands for Oracle system administrator(s). Once the license key is entered and saved, only this user(s) will have permissions to administer the installation, change options and set permissions for other users.

7. Proceed to the product specific installation steps set out below.

Product Specific Installation Steps

There are some steps that need to be performed to enable functionality in specific products. These are set out below.

Shared Templates Drive

The System Administrator Configuration Options section of the online user guide (accessible via the product or logging on to the customer community) includes settings that affect the Shared Templates Drive functionality. If you wish to use the EBS Database option as your preferred Drive type, you will be required to execute a SQL script, please see the Shared Templates Drive Type section of the online user guide for complete configuration instructions.

GL Wand

There is not much that needs to be done specifically for the GL Wand product. You should just review the default options to ensure that they are appropriate for your users. These options can be set on the System Administrator options dialog. Please see the user guide (accessible via the product or logging on to the customer community) and navigate to the System Administrator Options section under the Wands (Oracle) menu and specifically review the System Administrator User Options which include a number of items that affect GL Wand functionality.

Report Distribution Manager (RDM)

The System Administrator User Options section of the online user guide (accessible via the product or logging on to the customer community) includes settings for configuring your email which will allow you to send RDM published workbooks via email.

Budget Wand

The System Administrator User Options section of the online user guide (accessible via the product or logging on to the customer community) includes settings that affect the Budget Wand functionality. In addition, should you wish to use the automatic posting feature for budget journals, you must complete the necessary setup of the AutoPost criteria set in Oracle. The details can be found in the user guide under the Budget Wand section.

Reports Wand

The Reports Wand product will work without any further configuration steps and you can create your own queries and reports. However, if you have the Reports Wand insights feature installed, you will need to enable it. The insights section of the of the online user guide include all instructions required for installing Reports Wand insights and generating all relevant content. Additional Reports Wand configuration options are detailed in the System Administrator User Options section of the online user guide.

Journal Wand

The System Administrator User Options section of the online user guide (accessible via the product or logging on to the customer community) includes settings that affect the Journal Wand functionality. In addition, should you wish to use the automatic posting feature for journals, you must complete the necessary setup of the AutoPost criteria set in Oracle. The details can be found in the user guide under the Journal Wand section.

Java Runtime Image

The Wands applications are still a Java based application; however, it runs on a Java Runtime Image which is a stripped down version of the OpenJDK and embedded into our codebase. This allows us to ship an Wands version of Java with a release and removes the prerequisite of having Java installed on a client machine. This image is built from the latest version of OpenJDK to incorporate all the latest security fixes.

After logging into Oracle E-Business Suite, users can navigate to the Wands for Oracle launch page causing the Wands Launcher plugin to kick off some commands, ensuring that the user has the latest copy of the Wands client code. If the user does not have the latest, then they will be notified that the files are being updated. This downloads a new Java Runtime Image from the EBS server. This file is about 25mb and can impact the product launch on slower network speeds.

Wands Launcher Plugin

The Wands applications can be launched from a variety of supported browsers. Please see the Wands Launcher section of the online user guide for all supported browser plugin instructions.

Custom Database Objects

The following features are dependent on custom database objects. The installer allows for the custom database objects to be automatically created in the APPS schema with default database settings.

The installer will prompt the user to install the custom database objects:

Enter Y to create custom tables in the APPS schema [N]: Y

The follow options are valid:

1. Y – will only create database objects if they do not already exist.

2. N – will not create any of the custom database objects.

3. F – will remove existing database objects and recreate as new. This option will delete any data in the database tables.

It is important that you understand your current Oracle license agreement and whether custom database objects are permitted. The custom database objects can be installed after the installation should you not wish to install them at this point. All scripts for creation of the custom database objects are available in the online user guide under the relevant feature section.

Server Test Page

If required, you can test the server installation by loading the test page. The automated installation process will execute this step, but if you need to load the test page manually for any reason, proceed as follows:

1. Open a browser.

2. Enter the URL for your Oracle system followed by /OA_HTML/excel4apps e.g. http://server.domain.com:8000/OA_HTML/excel4apps.

3. The test page should display similar to the image below.
   

Installation on the Client

Installation on the client is currently dependent on the browser used to launch Wands for Oracle. Additionally, the client only needs a supported browser and Microsoft Excel. Full instructions for each browser plugin are available in the Wands Launcher section of the online user guide.

Chrome

On initial launch of this version, the user will be instructed to install a Wands launcher plugin from the Chrome App Store.

Firefox

On initial launch of this version, if using Firefox, users will be requested to download our Firefox specific add-on which is installed in the browser.

Internet Explorer

On initial launch of this version, the user will be instructed to download and install the Wands Launcher. This will allow Wands to be launched from Internet Explorer.

Edge

Instruction will be published soon.

Installation Troubleshooting

You can validate your Wands for Oracle installation at any time by executing the installer in VALIDATE mode. The installer will confirm if the required application components have been deployed and the necessary system configuration performed.

Run the Wands for Oracle Installer with the VALIDATE option:

UNIX:

./install.sh VALIDATE

Windows:

C:\>install.cmd VALIDATE

Below is an example of the output that the validation routine will generate:

[applmgr@oracle122 wands_oracle21.1.0.0]$ ./install.sh VALIDATE

Installer Mode: VALIDATE

Wands for Oracle Installer Started

Enter the APPS username [APPS]:

Enter the APPS password:

Database Connection Details from Environment Context File:

/home/ebs122/oracle/VIS/fs2/inst/apps/VIS_oracle122/appl/admin/VIS_oracle122.xml

==========================================================

Server: oracle122

Port: 1525

Sid: VIS

Enter Y to use the following connection settings [Y]:

Enter Y to create custom tables in the APPS schema [N]:

Servlet Configuration: PASSED

Application File Deployment: PASSED

OAF Artifacts: PASSED

AOL Objects: PASSED

Call Servlet Test Page: PASSED

Installer Completed Successfully

Program Exit Status=0

[applmgr@oracle122 wands_oracle21.1.0.0]$

If the installer validation routine fails, please contact Wands support by emailing the validation log file to e4asupport@insightsoftware.com.

Uninstall Steps

The following instructions can be used to uninstall the Wands for Oracle software on Oracle E-Business Suite 12.1:

1. Shutdown all the application tier services.

2. Remove the following folders on all Application Tier nodes where the installation was performed:

   1. $JAVA_TOP/com/excel4apps

   2. $APPL_TOP/xxe4a

   3. $APPL_TOP/xxe4arw

3. Remove Excel4apps Wands Servlet Entries:

   1. Oracle EBS R12.1: remove the following lines from the bottom of the custom OACORE web.xml template file, $FND_TOP/admin/template/custom/orion_web_xml_1013.tmp:

<!-- Excel4apps Wands 5 Alias -->

<servlet>

<servlet-name>excel4apps</servlet-name>

<servlet-class>com.excel4apps.servlet.wand.oracle.Servlet</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>excel4apps</servlet-name>

<url-pattern>/excel4apps</url-pattern>

</servlet-mapping>

4. End Date the Wands for Oracle Responsibility: Wands for Oracle

5. Run AutoConfig and restart the Application Tier services.

Note: The Oracle E-Business Suite system does not allow for the complete removal of all custom configuration e.g. Custom Applications and is thus not covered by this procedure.

Other Topics and Performance Optimization

Please see the “Installation Guide - Other Topics” for details on customizing the launch configuration, downgrading to an older release, removing GL Wand 4, creating the Shared Templates Drive database table and more.

See the “Installation Guide - Performance Optimization” for our performance tuning tips.