BUSINESS INTELLIGENCE EXTRACTION SERVICE (BIXTRACTOR)

Transcription

1 Department of Army BUSINESS INTELLIGENCE EXTRACTION SERVICE (BIXTRACTOR) Installation Guide VERSION 3.3 OCTOBER 9, 2018

2 1 INTRODUCTION Upgrade and Re-Install Steps Retention of existing Settings Uninstall existing software DOWNLOAD THE BIXTRACTOR FILES Initial BiXtractor Setup Wizard Select Installation Folder Confirm Installation Installation Complete CONFIGURING THE BIXTRACTOR Access the BiXtractor Service Windows Service Status HTTPS Upload Settings ASE Database Servers SQL Script Folders Data Extracts Specify the Output Folder location Create the Daily Default Data Extract Define the PrWebDB Value (Aquiline Database) Start the BiXtractor Service Verify Contents of BiXtractor Folders Manual Extraction SCHEDULED TASK WIZARD Create a Scheduled Task on a Windows Server 2008 R2 System General Tab Triggers Tab Actions Tab Conditions Tab Settings Tab History Tab DOCUMENT HISTORY AND MAINTENANCE REQUEST FOR ASSISTANCE i

3 ii 10/9/2018

4 1 Introduction Welcome to Business Intelligence and the Business Intelligence Extraction Service (BiXtractor). The installation process begins here. The purpose of this document is to provide detailed instructions for downloading, installing, and configuring the Business Intelligence Extraction Service and its components. System Administrators: Must have System Administrator privileges, and must have DoD approved credentials. Before beginning this installation, it is recommended that you close all programs not related to this install process. Software for this installation package is downloadable through the BiXtractor Documentation page. These instructions are written toward using Internet Explorer to download the installation package. Target Machine: Must run continuously - 24 hours a day, 7 days a week. Extractions will not run if machine is powered down, resulting in delayed reporting of PD2 data to VCE. System Requirements: The system requirements vary in relation to other applications or services running on the target machine. The following are general guidelines: Microsoft Windows Server 2008 R2 or Microsoft Windows Server 2012 R2. Scheduled tasks are created using Microsoft Task Scheduler. Network connectivity to the NIPRNET and to target PD² database server(s) from which data will be extracted. 75 MB of available disk space. It is assumed that the BiXtractor Service will be installed using the default location of C:\Program Files\BiXtractor. If you will be installing this program using an alternate drive/location, please allow for this change by substituting your unique destination drive/location, where applicable, throughout this document. To utilize the BiXtractor Service, system administrators must have the following three components installed: BiXtractor (Version 3.3, Build 6704) 32-bit or 64-bit. Microsoft.NET Framework or greater. DoD issued certificate for your machine and installed within the Personal Certificates certificate store. 1 10/9/2018

5 1.1 Upgrade and Re-Install Steps When performing an upgrade or re-install of your BiXtractor software, it is advantageous to retain a copy of the existing settings before upgrading or re-installing the BiXtractor software. The Settings.xml file holds unique BiXtractor settings that are specified during the initial setup/configuration. Reusing the Settings.xml file after an upgrade or re-install can reduce the setup/reconfiguration time of the software installation and the steps needed when performing these procedures. The following changes were implemented in version 3.3. The Settings.xml file, the AutoScripts folder, the Output folder, and the Logs folder are located in the C:\ProgramData\BiXtractor folder as noted below: Settings.xml file location and xml format. C:\ProgramData\BiXtractor\Settings.xml <Settings xmlns= > Base URL used for the HTTPS Upload Settings. DoD issued certificates are now used. SQL Script Folders, Default folder path. C:\ProgramData\BiXtractor\AutoScripts\Default Data Extracts Output Folder location. C:\ProgramData\BiXtractor\Output Data extraction Logs folder location. C:\ProgramData\BiXtractor\Logs Retention of existing Settings Before upgrading or re-installing the BiXtractor software, create a copy of the Settings.xml file that is currently in use. This current Settings.xml will be located in the folder where the BiXtractor software is installed. For example the default install folder location is C:\Program Files\BiXtractor. Locate the Settings.xml and make a copy of the file in an alternate location. 2 10/9/2018

6 1.1.2 Uninstall existing software All previous versions of the BiXtractor software must be uninstalled first before upgrading or re-installing. Uninstall software using the Programs and Features option from the Windows Control Panel. Figure 1 Uninstall BiXtractor Screen. After software has been uninstalled, including removal of BiXtractor folder and original contents from C:\Program Files (or an alternate location, if used), proceed to Section 2 Download the BiXtractor Files to continue the BiXtractor installation process. 2 Download the BiXtractor Files. To access the BiXtractor Documentation page, please use the following URL: After navigating to the BiXtractor Documentation page, scroll to the Download section and select the appropriate version of BiXtractor: BiXtractor v3.3 Build bit Install BiXtractor v3.3 Build bit Install For installing on a Windows 64-bit operating system. For installing on a Windows 32-bit operating system. 3 10/9/2018

7 The.zip selection force authentication through EAMS-A. After successfully authentication a download message will be generated from vce.army.mil, similar to the one below. Figure 2 File Download Screen. Select Open to begin the download of the BiXtractor bit.zip (3.91 MB) or the BiXtractor bit.zip (3.95 MB) file. Afterwards extract the contents of the.zip file onto your local machine and open the extracted.msi file. Figure 3 Zip file contents. NOTE: If.NET Framework Version or later cannot be found, the option to install will automatically be made available to you. Follow the screen prompts to extract and install the components of the.net Framework. After the.net Framework installation is complete, return to Section 2 Download the BiXtractor Files to resume the BiXtractor installation process. NOTE: If MDAC Version 2.7 or greater cannot be found, the option to install will automatically be made available to you. Follow the screen prompts to extract and install the MDAC components. After the MDAC installation is complete, return to Section 2 Download the BiXtractor Files to resume the BiXtractor installation process. 4 10/9/2018

8 2.1 Initial BiXtractor Setup Wizard Figure 4 Initial BiXtractor Setup Wizard Screen Click: Next. 5 10/9/2018

9 2.2 Select Installation Folder Figure 5 Select Installation Folder Screen. Specify Install Folder: C:\Program Files\BiXtractor or alternate location Select Install Option: Everyone (for all BiXtractor users) Click: Next. NOTE: From the Select Installation Folder screen, specify the location where the BiXtractor service is to be installed. If your site will be installing the BiXtractor service in the default folder location of C:\Program Files\BiXtractor, no change needs to be made. However, if your site will be installing the BiXtractor service in an alternate location, please specify that folder location at this time. 6 10/9/2018

10 2.3 Confirm Installation. Figure 6 Confirm Installation Screen. Click: Next. Click: OK when you see the message, The service is installed! 7 10/9/2018

11 Figure 7 Install in Progress. NOTE: Be aware that the window showing that the service has been installed might appear in the background behind the window showing the installation progress. Please check your Windows taskbar to confirm the service installation window is present. The window can be brought to the foreground by selecting it from the taskbar. Cancelling the installation at this point can put the software installation and service in an inoperable state, resulting in the need to uninstall the service. 8 10/9/2018

12 2.4 Installation Complete Click: Close. Figure 8 Installation Complete Screen. 9 10/9/2018

13 NOTE: Attempts to reinstall over the current program is not possible. If you need to reinstall the BiXtractor software, first remove the current version by selecting the Remove option from the Repair/Remove window or use the Control Panel to remove a previously installed version of the Business Intelligence Extraction Service (BiXtractor). Figure 9 Remove/Repair Screen 10 10/9/2018

14 3 Configuring the BiXtractor The Settings.xml file holds unique BiXtractor settings that are specified during the initial setup/configuration. After completing the configuration of the BiXtractor service, it is strongly recommended that you save a copy of the Settings.xml in a safe place. The Settings.xml file can be copied back to its original location, which may reduce setup/reconfiguration time if a reinstall is needed at your site. If you are performing an upgrade or reinstall, locate your copy of the Settings.xml file and copy the file into its new destination, C:\ProgramData\BiXtractor. Modify the Settings.xml file by opening it using Windows Notepad or WordPad. Edit the <Settings> tag that appears on the second line, so that it reads: <Settings xmlns= > Do NOT edit the end tag </Settings> tag that appears on the last line of the Settings.xml file. Save and close the file after editing. 3.1 Access the BiXtractor Service. Go to: C:\Program Files\BiXtractor\bixconfig.exe Or go to: Start BiXtractor\BIXtractor 3 Configuration 11 10/9/2018

15 3.1.1 Windows Service Status The Windows Service Status screen is the first screen of the configuration utility. This screen will show you the status of two important Windows services needed for the extraction service to perform. The first pane, Windows Service, shows the status of the BiXtractor service. At this time, you should see a red light and the word Stopped. We will start the BiXtractor service in a later step. The second pane, Schedule Service, shows the status of the Windows Task Scheduler. At this time, you should see a green light and the word Running. If a "Stopped" message is accompanied by a red stoplight on the Schedule Service screen, a Start button will be available to turn on the service. However, the user cannot stop the scheduler from inside the BiXtractor. Figure 10 Windows Service Status. NOTE: To verify that both the Task Scheduler and the Business Intelligence Extraction Service are set to automatic startup, go to: Start Control Panel System and Maintenance Administrative Tools Services, and check each service. From the General tab, ensure the Startup type is set to Automatic on both services. This will allow for an automatic restart of the task(s) after a system reboot is performed. If there is a need to manually stop a service, the Startup type can be set to Disabled /9/2018

16 3.1.2 HTTPS Upload Settings Figure 11 Base URL for HTTPS Upload. Select: Enter Base URL: Proxy Address/Port: Certificate: Click: Test button. HTTPS Upload Settings (on the left). If your site uses a proxy, enter the proxy address:port (e.g; :8080). If your site does not use a proxy, please leave this field blank. Select the DoD issued certificate that is installed on your machine. If your certificate is not listed, see below NOTE for additional information. NOTE: If the connection is successful, you will receive a Test Passed message. If the Test Passed message is not received, please verify that the base URL information has been entered correctly. Ensure you have the proper certificate installed and selected, as connectivity will not be possible if a DoD certificate is not used. Follow the steps in the Certificate Check Procedures to check your system for certificates. These procedures can be downloaded from the BiXtractor Documentation page. Also, have your site s network operations support staff confirm that HTTPS connectivity to is open for both incoming and outgoing traffic on Port 443. If you need assistance, please submit a Help Desk ticket to VCE Tier 2 support, through the AESD website along with any additional information for example contents of screen messages that can assist in troubleshooting. Refer to the end of these procedures for details on submitting a Help Desk ticket /9/2018

17 3.1.3 ASE Database Servers If you are performing an upgrade or reinstall, your ASE Database Servers should appear in the right portion of the window. This information is retrieved from the Settings.xml file. At the time of the upgrade or reinstall, please verify that information in each field is current. All necessary revisions should be applied at this time. Otherwise, perform the following steps to add your ASE database servers. Figure 12 ASE Database Servers. Select: ASE Database Servers (on the left) Select: Add ASE Database Server... (on the right). NOTE: The PD 2 Database Name and Password fields are case sensitive. Please use caution to enter upper and lower case characters exactly. Figure 13 Add ASE Database Server. Enter: Site Identifier (unique Id provided by VCE Operations Support) Enter: Server Address, Port, PD 2 Database Name, User Name, and Password information for the server /9/2018

18 Click: Test Connectivity button. A successful connection to the database server will display a Connected successfully. message. Figure 14 ASE Database Server Connectivity Check. Click: OK (to close message box) Click: OK (to continue setup) NOTE: Your database server item should now be displayed on the ASE Database Servers screen. Any future change to the ASE database server information, such as a Server Address, Port number, PD 2 Database Name, or Password change, will also need to be changed in the BiXtractor service using this screen. After a change is entered, please perform a Stop and Start of the BiXtractor (Windows Service) to refresh the configuration settings. NOTE: If the Connected successfully message is not received, please verify the site information again. If you need assistance, please submit a Help Desk ticket to VCE Tier 2 support, through the AESD website along with any additional information for example contents of screen messages that can assist in troubleshooting. Refer to the end of these procedures for details on submitting a Help Desk ticket /9/2018

19 3.1.4 SQL Script Folders Figure 15 SQL Script Folders. Select: SQL Script Folders (on the left) Click: Synchronize All Script Folders button (upper right) Click: Yes when prompted with, Do you wish to continue? Double Click: Default folder. Check the Path to ensure that it is set to C:\ProgramData\BiXtractor\AutoScripts\Default Use the Browse button to select the correct path /9/2018

20 Figure 16 AutoScripts (Default) Script Folder Path. NOTE: This will automatically download the necessary SQL scripts from our servers and place them into the Default folder. The Default folder should now be visible in the lower right windowpane. If the synchronization fails, have your site s network operations support staff confirm that HTTPS connectivity to is open for both incoming and outgoing traffic on Port 443. If you need assistance, please submit a Help Desk ticket to VCE Tier 2 support, through the AESD website along with any additional information for example contents of screen messages that can assist in troubleshooting. Refer to the end of these procedures for details on submitting a Help Desk ticket. If updated scripts are available for your site, the updates are automatically sent at the beginning of an extraction attempt. NOTE: If an extraction appears to be hanging on a particular script, performing the manual script synchronization may help eliminate the problem. To refresh your script folders at any time, simply perform a manual Synchronize All Script Folders. This will refresh the current group of scripts being used by your site /9/2018

21 3.1.5 Data Extracts. Figure 17 Data Extracts Specify the Output Folder location Select: Data Extracts (on the left) Click: Browse button (upper right pane) Output Folder: C:\ProgramData\BiXtractor\Output Click: OK NOTE: If performing an initial upgrade to version 3.3, the Output Folder may not be set correctly. Use the Browse button to select the correct folder /9/2018

22 Create the Daily Default Data Extract Each PD 2 database is assigned a unique site identifier. Although most sites have only one ASE database server for the BiXtractor, consolidated database server locations support multiple sites/databases. For multiple ASE database servers, only one server may be selected at a time. The Extract Name will be entered automatically for the server that is selected, and should reflect the Site number that is assigned to that particular ASE Database Server (Example: Default.222). Select: Access: Select: Access: Select: Pickup Date: End Date: Click: Click: Figure 18 Data Extract Properties Screen. Add Data Extract... (lower right pane). drop-down list for SQL Script Folder (fourth item) Default from drop-down menu. drop-down list for ASE Database Server (fifth item) The ASE Database Server for your Site Identifier number. The Initial Pickup Date is assigned by VCE and issued by Operations Support. Pickup date can be set to the current date for a one-day test. Pickup date automatically advances for subsequent daily extractions. If an extraction generates an error, the date will not advance until the error is corrected, which prevents data from being missed. Leave blank (grayed-out). Current date/time will be used automatically. Test Database button OK (if connected successfully) 19 10/9/2018

23 Define the PrWebDB Value (Aquiline Database). You will be required to enter a value for the PrWebDB. If your site does NOT have an Aquiline database, you must enter the letter N in place of the Aquiline database name. If your site DOES have an Aquiline database, this value will be the name of your Aquiline database and usually begins with an ACQ_. Do NOT enter your DoDAAC. Reference the User Defined Variables section at the bottom of the Data Extract screen, shown in the above Data Extract Properties screen. Enter the name of your PrWebDB (Aquiline) in the Value box. Click: OK (to continue). NOTE: If the PrWebDB/Aquiline Value field is left blank, the following error message will display, The extract cannot be saved if all of the User defined variables are not populated. If your site does NOT use an Aquiline database, enter the letter N in the value field. Figure 19 User Defined Variable Error. The Create Task screen will display. Please note the execution path. It will be needed in the task scheduler portion of this process. The default run path is: C:\Program Files\BiXtractor\bixde.exe e Default.{site id} Click: OK to continue. Figure 20 Create Task Screen /9/2018 8

24 3.2 Start the BiXtractor Service. Return to the Window Services Status screen and click Start to start the BiXtractor service. When all services are running, the Windows Service (BiXtractor service) and the Schedule Service (Task Scheduler service) will both display a Green light and the word Running. If not, click on the appropriate Start button to start each service. Figure 21 Start BiXtractor Service /9/2018 8

25 3.3 Verify Contents of BiXtractor Folders. Using Windows Explorer, navigate to the C:\ProgramData\BiXtractor\ folder and verify the contents of the BiXtractor folder. The following folders should be seen: AutoScripts: Output: Logs: SQL scripts used by the extraction service. Briefly holds.xml result files until extracted data is sent to the VCE. The output folder should be automatically created during the install process. Version 3.3(Build 6704) will zip the xml result files before moving from the temp folder to the output folder. If files do not get released from the output folder, test the HTTP Upload Settings and perform a Stop and Start of the BiXtractor service to refresh the BI configuration. Results of the latest extraction attempt is recorded in the bixde.default.{site id}.debug.txt file and placed in the logs folder. The debug file will be overwritten with each new extraction attempt. This is a good place to check for the status of an extraction and for troubleshooting a failed extraction. The following fourteen (14) files should also be seen under C:\Program Files\BiXtractor\ Acbis.Security.dll bixconfig.exe bixconfig.exe.config bixde.exe bixde.exe.config bixlib.dll BiXtractor.exe BiXtractor.exe.config Bixtractor.InstallState ICSharpCode.SharpZLib.dll install_service.bat InstallUtil.exe Settings.xsd Sybase.AdoNet4.AseClient.dll 22 10/9/2018 8

26 Figure 22 BiXtractor Folder and Files. 3.4 Manual Extraction. For some sites, running a manual extraction during peak login periods may slow down the system for all users and may cause the extraction to hang, abort, or error out. Please take this into consideration before running manual extractions at your site. If you choose to run your extraction manually from inside the BiXtractor service: Select: Select: Click: Manual Extraction (on the left) Default.{site_id} from the drop-down list Run When the hourglass disappears: Click: Click: Send Now. Yes to Upload Files Now /9/2018 8

27 4 Scheduled Task Wizard. 4.1 Create a Scheduled Task on a Windows Server 2008 R2 System. Access the Scheduled Task Wizard: Start Control Panel System and Security/Maintenance Administrative Tools Task Scheduler Select Action: Create Task (from Actions list on right) Figure 23 Windows Task Scheduler (Windows Server 2008) 24 10/9/2018 8

28 4.1.1 General Tab Select: Name: Description: Click: Select: Select: Configure for: Select: General tab name of Data Extract (i.e., Default.911) brief description of the task OK Run whether user is logged on or not Run with highest privileges Windows 7 or Windows Server 2008 R2 Triggers tab (at the top of the screen) to proceed. If the message, You must enter a task name and at least one action is displayed, click OK and then select the Triggers tab (at the top of the screen). Figure 24 Create Task (General Tab) 25 10/9/2018 8

29 4.1.2 Triggers Tab Select: Triggers tab Click: New Begin task: On a schedule Select: Daily Enter: Start date and time: (use current date) Recur every: 1 days Checkmark: Stop task if it runs longer than: (choose anything less than 23 hours) Checkmark: Enabled Click: OK Figure 25 Create Task (Trigger Tab Scheduling Details) NOTE: To edit triggers, select the Triggers tab and click on the Edit button. Under Advanced Settings we recommend adjusting the runtime specifications. Stop task if it runs longer than (specify a time 23 hours or less to ensure that a stalled extraction ends before the next daily extraction attempt occurs. If running extractions for multiple sites, use this option to help manage runtimes and prevent more than one extraction from running at the same time /9/2018 8

30 4.1.3 Actions Tab Select: Actions tab Click: New Set Action: Start a program. Enter Program/script: C:\Program Files\BiXtractor\bixde.exe (must include quotation marks) Add argument: -e Default.{site id} (i.e., Default.222) Start in (optional): C:\Program Files\BiXtractor Click: OK (or specify alternate location where BiXtractor is installed) Figure 26 Create Task (Action Tab Define Action) 27 10/9/2018 8

31 4.1.4 Conditions Tab The Conditions tab can be used to specify additional conditions for a particular task. However, the BiXtractor does not require any of these conditions to be flagged Settings Tab Suggested settings for the BiXtractor task receive a checkmark : Allow task to be run on demand Stop the task if it runs longer than: (specify a time 23 hours or less to ensure that a stalled extraction ends before the next daily extraction attempt occures. If running extractions for mulple sites, use this option to help manage runtime and prevent more than one extraction from running at the same time. If the running task does not end when requested, force it to stop If the task is already running, then the following rule applies: Do not start a new instance. Click: OK to complete the creation of the scheduled task. Figure 27 Setting Tab Suggested Settings 28 10/9/2018 8

32 To view the newly created task, return to the main Task Scheduler screen: Select: Task Scheduler Library (on the left) Select: Refresh (to display newly created task History Tab Use the History tab to monitor the results of a scheduled task. Figure 28 History Tab Task Performance 29 10/9/2018 8

33 5 Document History and Maintenance. Version Description of Version Date Completed 01 Initial BiXtractor (Version 1.0) Installation Guide 4/2/03 02 BiXtractor (Version 2.0) Installation Guide with Uninstall 1.0 Steps 9/30/03 03 BiXtractor (Version 2.1) Installation Guide 11/24/03 04 BiXtractor Upgrade (Version 3.0) Installation Guide 8/3/04 05 Revised BiXtractor (Version 3.0) Installation Guide, supersedes previous version, dated 8/3/ Revised BiXtractor (Version 3.1) Installation Guide, supersedes previous version, dated 10/15/ Updated references to ACBAS website address, BiXtractor webpage, and building address. 08 BiXtractor Upgrade (Version 3.1.1) Installation Guide includes Windows Server 2008, Windows 7, and Vista compatibility. 09 BiXtractor Upgrade (Version 3.1 Build 4588) for Windows Server 2008 (32- bit and 64-bit) 10 BiXtractor Upgrade (Version 3.1.2) Installation Guide, supersedes previous versions, dated 04/30/ BiXtractor Upgrade (Version 3.1.3) Installation Guide, supersedes previous versions, dated 04/30/2013. Windows Server 2003, Vista, and XP are no longer supported. 10/15/06 8/21/2007 7/14/2010 5/25/2011 4/30/ /18/2014 4/3/ BiXtractor Upgrade (Version 3.2 Build 5968) Installation Guide, supersedes previous versions dated 04/03/2015. This version requires certificates. 13 BiXtractor Upgrade (Version 3.2 Build 6192) Installation Guide, supersedes previous versions dated 10/07/2016. New build to correct Send Now deficiency and AESD Help Desk support url change. 14 BiXtractor Upgrade (Version 3.3 Build 6704) Installation Guide, supersedes previous versions dated 12/05/2016. New build to upgrade.net Framework to v4.6.2 and changing domain names from acbisdata.army.mil to vcedata.army.mil. 10/7/ /5/ /9/ /9/2018

34 6 Request for Assistance. Please contact the Army Enterprise Help Desk (AESD) with any questions, concerns, problems, or comments regarding the BiXtractor installation. Follow the below steps to create a Help Desk ticket to VCE Tier 2. Go to the AESD Website: Enter your contact information. Subject: VCE Tier 2: Site #- BiXtractor (i.e., Site BiXtractor). Question: Enter a brief problem description or need for assistance. Product: VCE The BiXtractor website ( also contains a Frequently Asked Questions section as well as a BiXtractor User s Guide to assist you You have completed the installation and setup of the Business Intelligence Extraction Service (Version 3.3 Build 6704) and the setup of the Task Scheduler for the daily Default extraction. Please notify our office via the AESD Help Desk when the BiXtractor installation is complete. We will monitor and confirm the arrival of your initial PD 2 data extraction. Report any downtime that you have scheduled for your system, through the AESD Help Desk, so that VCE Tier 2 is aware of any possible delays in the arrival of your PD 2 data extractions /9/2018