Running Birst Connect as a Windows Service

The Birst Connect Service is the Windows Service version of Birst Connect that enables it to run in a non-interactive mode (batch mode) as a Windows service. Using the Birst Connect Service is recommended when Live Access connections need to remain active.

The Birst Connect Service should not be installed for the purpose of scheduling data extracts. Use an existing scheduler on your computer to schedule regular extracts, for example, Cron for Unix or Linux and Task Scheduler for Windows. See RunningBirst Connect Tasks using an External Scheduler.

Running Birst Connect Service does not require an active user session and can therefore run when users are not logged on to the machine. You can also install and run multiple Birst Connect Services on the same client for single or multiple spaces.

Prior to installing the Birst Connect Service

Before beginning the installation obtain the BirstConnect.zip file. To download BirstConnect.zip:

Go to Admin - Define Sources - Birst Connect.

Click the Download (BirstConnect.zip) link at the bottom of the page.

To install and run the Birst Connect Service

Create a new folder (such as C:\BirstConnect) and extract BirstConnect.zip into it. This folder will be referred to as the HOME directory.

Open BirstConnect.xml in a text editor and modify the properties to suit to your environment:

ID and Name: Not required for running a single instance of Birst Connect Service. If running multiple instances, the ID and name of each instance must be unique in order to install the service.

Description: Change it to suit to your requirement. This will appear as service description.

Logpath: The path where Service Wrapper, StandardOutput (birstconnect.out.log) and StandardError (birstconnect.err.log) logs will go. You can specify this path as HOME\logs, for example: C:\BirstConnect\logs.

Logmode: Do not change this.

Env Name="CLASSPATH": Do not change this.

Env Name="JAVA_HOME": Set this parameter to your local Java installation, the path to jdk/jre, for example: C:\Program Files\Java\jre1.8.65".

Executable: Do not change this.

<argument>-Xmx256m</argument>: The maximum size of the memory allocation pool. Use caution if changing this. In situations when Live Access appears to run out of memory this value may be increased - for example, to 1024m. Make sure that your system can handle the increased value. Do not set this value higher than 1024m when using 32-bit Java. If you change this setting and save it, restart Birst Connect.

<argument>-Xrs</argument>: Do not change this.

<argument>-cp %CLASSPATH%</argument>: Do not change this.

env name="BirstConnect_Home": This value should be same as HOME, for example: C:\BirstConnect.

<argument>-Djnlp.file="%BirstConnect_Home%\LiveAccess.jnlp"</argument>: Launch Birst Connect from the Define Sources tab of Infor Admin (for the configuration for which the service is to be installed) and save the <spaceID>.jnlp file to the HOME directory and then replace LiveAccess in the above argument with <spaceID>. This parameter will enable Birst Connect to read the properties from the .jnlp file and launch Birst Connect using the same.

<argument>-Djnlp.log4j.Override="%BirstConnect_Home%\log4j.xml"</argument>: Do not modify this parameter unless you would like to use custom log4j.xml or log4j.properties other than supplied by Birst for logging purposes.

<argument>-DBirstConnect.logs.path=%BirstConnect_Home%\logs\</argument>: This parameter is consumed by log4j.xml (or log4j.properties) supplied by Birst in order to specify the path where the daily log file should be generated. This path is usually the same as logpath where the other logs go.

<argument>-Djnlp.headless=true</argument>: This argument is mandatory and should not be modified when running Birst Connect as a Service. If you change the value of this parameter, Birst Connect service may become unresponsive.

<argument>com.birst.dataconductor.DataConductorApp</argument>: Do not change this.

To install the Birst Connect Service, do the following:

Open a command prompt and change the directory to HOME.

At the command prompt enter:
BirstConnect install

If this command does not show any errors on console, the Birst Connect Service installed successfully and you can see it in the list of services at Windows Control Panel - Administrative Tools - Services or Windows 7 Control Panel - System and Security - Administrative Tools - Services.

To start the installed Birst Connect Service, do one of the following:

At the command prompt, navigate to HOME and enter:
BirstConnect start

At the command prompt enter:
net start <serviceID>

From the Services list, select the service and click Start.

You should see the log files generated inside the HOME\logs directory, or where the logpath and -DBirstConnect.logs.path are set to divert logs.

Tips:

Make sure that the Startup Type for this service is set to Automatic, otherwise it will not start after a system reboot.

To check the status of data being uploaded by Birst Connect, look at the log that by default is installed at C:\BirstConnect\logs.

To stop the Birst Connect Service, do one of the following:

At the command prompt, navigate to HOME and enter:
BirstConnect stop

At the command prompt enter:
net stop <serviceID>.

From the services list, select the service and click Stop.

To uninstall the Birst Connect Service, open the command prompt, change the directory to HOME, and enter:
BirstConnect uninstall

Do not delete files from the HOME directory when the Birst Connect Service is installed or running. This can orphan the service making it difficult to stop or uninstall.

If not enough memory is allocated to the Java process, a java.lang.OutOfMemoryError message may appear in the error or output logs. See the Xmx argument.