TIBCO NimbusTM Office Integration Server Software Release 9.5.2 October 2015
Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright law s and treaties. No part of this document may be reproduced in any form w ithout the w ritten authorization of TIBCO Softw are Inc. TIBCO, Tw o-second Advantage and TIBCO Nimbus are either registered trademarks or trademarks of TIBCO Softw are Inc. in the United States and/or other countries. All other product and company names and marks mentioned in this document are the property of their respective ow ners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE RELEASE NOTE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright 1997-2015 TIBCO Softw are Inc. ALL RIGHTS RESERVED. TIBCO Softw are Inc. Confidential Information
Contents 3 Table of Contents... 4 About the Office Integration Server Configuring the OIS... 5 Logging the OIS... 7 Testing the OIS... 9... 10 Running the OIS in Desktop Mode... 12 Running the OIS in Service Mode
4 About the Office Integration Server About the Office Integration Server The Office Integration Server facilitates the communication between TIBCO Nimbus and Microsoft Excel. Excel data is used to update metric links in the Web Server and Business Intelligence Server, and to generate Excel-based (.mht) scorecards in the Web Server. There are two modes that the Office Integration can work in; Service Mode and Desktop Mode. The Service Mode is a Windows-based service that can be managed by the TIBCO Nimbus Service Installer tool (supplied on the CD). The Desktop Mode is a user-interface that provides a visual tool for monitoring and troubleshooting the Office Integration Service, as well as allowing the configuration settings of the OIS to be easily modified. Scorecards in Mozilla Firefox To view MHT-based scorecards in Mozilla Firefox, users will require the UnMHT addon. This can be downloaded from the following location: https://addons.mozilla.org/en-us/firefox/addon/unmht/ Note: The UnMHT addon does not fully support MHT-based scorecards in Mozilla Firefox. You may notice incorrect formatting and some embedded images may not be present.
Configuring the OIS 5 Configuring the OIS Both the Desktop Mode and Service Mode are controlled by a single configuration file, CtrlOffSvr.ini. This configuration file can be modified in both the Desktop Mode, and by manually editing CtrlOffSvr.ini in Notepad. The configuration file, CtrlOffSvr.ini, is stored in the following location: \TIBCO Nimbus\Action Server The Office Integration Server (Desktop Mode) can be run from the Start menu: Programs>>TIBCO Nimbus>>Action Server>>Office Integration Server (Desktop Mode). Then, from the File menu choose Configuration. Desktop Mode CtrlOffSvr.ini Description Port Port The listening port for the application. The permitted range is 1024-65535, default is 51001. Note: The value must be the same as the port values specified in the TIBCO Nimbus Web Server and Business Intelligence Server configuration files. Monitor timeout MonitorTimeout The time, in milliseconds, that the OIS should wait for a response from Excel. Default is 15000 milliseconds (15 seconds). Terminate timeout Terminate Timeout The time, in milliseconds, that the OIS should wait for Excel to shutdown. Default is 15000 milliseconds (15 seconds). Use interactive desktop Interactive Desktop Allows Excel warning messages to appear on the desktop of the user who is logged on directly to the operating system (Service mode only). Note: This option cannot be enabled in Windows Vista and Windows Server 2008. Maximum history records MaxHistoryCount The maximum number of request history records that will be stored in memory in Desktop Mode. The default is 20000 and once this value is been reached, the oldest record will be deleted for every new record generated. Logging level LoggingLevel The detail of logging generated (see Logging the OIS for more information). File rollover size LogRolloverSize The maximum size permitted (kilobytes for Desktop Mode, bytes for Service Mode) for any one log file. When a log file reaches the size specified, a new log file will be created. Maximum rollover LogMaxRollover files The maximum number of rollover files permitted. When this number is reached the oldest log file will be deleted for every new log file that is created. If this value is set to '0' then only a single file will be used, which is not limited by size. Table: Descriptions of the configuration parameters in both the Desktop Mode and the CtrlOffSvr.ini file.
Configuring the OIS 6 Windows Server 2008, Vista and later For Windows Server 2008, Windows Vista and later versions, a dual process is required to run the OIS service. The main account for the service to run under should be left as the default Local System account. Additionally, a secondary account should be specified for the worker process. Note that the worker process does not inherit any security rights from the Local System, therefore posing no security risks. Worker Process Credentials (SecondaryIdentity) This account should be a Control specific service account, which only needs to be a normal domain user account, and this is set in the OIS Desktop Mode (in the OIS Desktop Mode, from the File menu choose Configuration). The worker process account requires the following: DCOM rights to launch Excel; it must also have previously run Excel and the Visual Basic Editor on the local machine. Log on as a service rights; this is usually granted when the account is specified in the properties for a service. If the account has never been used on the PC as a service account, it will need to be added by either: Temporarily setting the account as the account for the Office Integration Server service, so that Windows automatically grants this right. OR Adding the account to the Log on as a service list using the Local Security Settings policy editor. Note that on earlier versions of Windows the OIS service will run as a single process using a normal domain user account. Path Mappings The path mappings to UNC path names can be configured, thereby allowing users to define an Excel spreadsheet in a mapped drive in the client, and define a UNC path in the Web Server. For example, the source path might be H:\Documents, but in the Web Server you might want to substitute this with \\[server1] \public\documents. Multiple mappings can be defined if needed. In Desktop Mode click the Path Mappings tab (in the Configuration window), or see the [PathMapping] section in the CtrlOffSvr.ini file. Source path (SourcePathn) is the mapped drive path to be substituted by the Web Server. Destination path (DestPathn) is the UNC path to use instead of the mapped drive path.
Logging the OIS 7 Logging the OIS The Office Integration Service offers Log4D logging capabilities, which allows the debugging of any issues that arise in the OIS. Log File The same log file, ControlOIS.log, is used for both the Desktop and Service modes. This log file is stored in: C:\TIBCO Nimbus\Action Server\Logs\OIS Note: The current log file can also be viewed in the Log File tab in the Desktop Mode. Configuring OIS Logging The logging configuration settings are defined in the CtrlOffSvr.ini file. This log file is stored in: C:\TIBCO Nimbus\Action Server Both the Desktop and Service modes share the same configuration settings file, so any changes to the logging level will be reflected in both modes. The logging settings can be defined in either the CtrlOffSvr.ini file (through a text editor such as Notepad) or through the Desktop Mode. Configuring OIS logging in Desktop Mode: 1. Run Office Integration Server (Desktop Mode) from the Start menu. 2. From the File menu choose Configuration. 3. In the Log file panel on the General tab, modify the following options, as required: Logging level is the detail of logging that is generated (see table below) File rollover size is the maximum size permitted, in kilobytes, for any one log file (when the current log file reaches the size specified, a new log file will be created). Maximum rollover files is the maximum number of rollover files permitted (when this number is reached, the oldest log file will be deleted for every new log file that is created). If this value is set to '0' then only a single file will is used, which is not limited by size.
Logging the OIS 8 Logging Level Desktop Mode CtrlOffSvr.ini None Detail of log entries 0 No logging. Low 1 Date and time when the service is started Date and time when the service is stopped Medium 2 Date and time when the service is started Date and time when the service is stopped Any errors that are encountered High 3 Date and time when the service is started Date and time when the service is stopped Any errors that are encountered All handled requests Table: Available logging levels. Configuring OIS logging in the configuration file: 1. Open the configuration file CtrlOffSvr.ini, which is stored in:...\tibco Nimbus\Action Server\ 2. In the [Options] settings, modify any of the following logging parameters: LoggingLevel is the detail of logging that is generated (see table above) LogRolloverSize is the maximum size permitted, in bytes, for any one log file. When a file reaches the size specified, a new log file will be created. LogMaxRollover is the maximum number of rollover files permitted. When this number is reached, the oldest log file will be deleted for every new log file that is created. If this value is set to '0' then only a single file will is used, which is not limited by size. 3. Save and exit CtrlOffSvr.ini.
Testing the OIS 9 Testing the OIS The Office Integration Server can be tested to ensure it is working correctly. When a self test is run, several requests are sent to the local computer on the port specified in the configuration settings. The following tests are run: Metric with no macro Metric with macro Scorecard Testing the Office Integration Server (Desktop Mode): Note: The OIS service must not be running. 1. Run Office Integration Server (Desktop Mode) from the Start menu. 2. Click Start request processing. 3. Click Self test. Testing the Office Integration Server (Service Mode): Note: The OIS service must be running. 1. Run Office Integration Server (Desktop Mode) from the Start menu. 2. Click Self test.
Running the OIS in Desktop Mode 10 Running the OIS in Desktop Mode The Office Integration Server Desktop Mode allows administrators to visually monitor the status of the OIS and view the list of handled requests; this assists in troubleshooting any problems that arise. The Office Integration Server (Desktop Mode) can be run from the Start menu: Programs>>TIBCO Nimbus>Action Server The Desktop Mode is split into three tabs: Current Status This tab provides a summary of the number of processed requests and the number of failed requests for the current history record, since the application started. You can also start and stop the processing of requests. To start processing, click Start request processing. To stop processing, click Stop request processing. Request History This tab displays all requests handled since the Desktop Mode started, subject to the limit set for the 'Maximum history records' parameter. It does not show the requests handled by the Service Mode. To reset the history, click Clear History. Request records can be copied to the clipboard and then pasted into an Email if support is required. Highlight the text that you want to copy, then press Ctrl+C to copy the data to the clipboard. Grouping Columns Group any column by clicking and dragging the column header onto the grey space above the columns. Sorting Columns Sort the data within a column by clicking the column header (click it twice to reverse the order). Filtering Columns Filter a particular column by selecting a filter value from the associated drop-down arrow on the column header. Displaying/hiding Columns Display or hide certain columns by clicking to display the Column Selector. The Column Selector lists the columns that are not currently being displayed. To add a column to the report, click and drag the column from the Column Selector to the desired position on the column headers. When the green arrows appear, release the mouse button to drop the column into place. To remove a column from the report, simply click and drag the column header into the Column Selector.
Running the OIS in Desktop Mode 11 Log File This tab displays the current log file for the Office Integration Server. Note: This is the same log file that is used by the OIS Service Mode. Reload log file when a change is detected will refresh the log file whenever a change is detected. If this option is disabled then click Reload Log to refresh the view.
12 Running the OIS in Service Mode Running the OIS in Service Mode The Office Integration Server service can be managed using the TIBCO Nimbus Service Installer; the service can be started/stopped, uninstalled, toggled between automatic and manual startup, and a suffix can be added to the service name. The TIBCO Nimbus Service Installer, ServiceInstaller.exe, is found in the Utilities folder on the installation CD. For more information, see Managing TIBCO Nimbus Services under Maintenance in the TIBCO Nimbus Administration Guide (found in the Admin Guide folder on the installation CD).