Running Birst Connect from the Command Line

The recommended way of running Birst Connect is from the command line. This allows you to add drivers that are not distributed by Birst, run unattended, and schedule the running via Windows and Linux schedulers.

Certain data connectors, like SAP ERP, require third-party libraries that Birst is not licensed to redistribute via Birst Connect. In order to use these types of connectors, you download the required libraries, save them to a folder on a local machine, and launch the Birst Connect UI from the command line.

You can launch the UI from the command line or run the program from the command line without the UI. Running in command mode is useful for automating tasks.

Implementation and Usage Notes
Start the UI from the command line
Start in command mode without the UI

Implementation and Usage Notes

You must have the Birst Connect product installed. See Checking Which Products Are Installed.
Java JDK 8 or greater is required to run Birst Connect. Birst supports both OpenJDK and Oracle Java SDK.
Birst distributes a subset of the drivers for the connectors.
No modifications are necessary to any JNLP files when adding non-distributed drivers. Running Birst Connect from the command line only looks at the JNLP file for space identification and authentication purposes. The JNLP file needs to be copied into the same directory where the batch files execute.

Birst Connect Memory Allocation

When running Birst Connect from the command line it may be necessary to increase the amount of memory allocated to Birst Connect. Memory issues will be logged in the Java Console for Birst Connect and will look similar to the error below:

Exception in thread "Thread-12" java.lang.OutOfMemoryError: Java heap space

By default, memory is set at 256 MB. To allocate more memory to Birst Connect, find the BirstConnect.xml file in the root directory where Birst Connect is installed. If out of memory issues arise increase the value of Xmx, for example:

Important: Changes to the BirstConnect.xml file require you to restart Birst Connect. If Birst Connect runs as a service, restart the service.

To run the Birst Connect UI from the command line

Download BirstConnect.zip. Go to Admin - Define Sources - Birst Connect and click Download (BirstConnect.zip). If your browser prompts you to open or save the file, select to save the file.
Create a new HOME directory folder, for example:
C:\BirstConnect
and extract BirstConnect.zip into it.
Go to Admin - Define Sources - Birst Connect.
In the Configurations list, click Launch. A SpaceId.jnlp file downloads.
Tip: You can have multiple Birst Connect configurations for multiple tasks.
Copy the SpaceId.jnlp file to the HOME directory.
Open the HOME\commandline\cmdUI.bat file in a text editor and update the following settings per your environment:

Set JAVA_HOME to the path of the JDK or JRE on your machine, for example:
JAVA_HOME=C:\Program Files\Java\jdk1.8.0_x

Set BirstConnect_Home to the path of the folder to which you extracted the content of BirstConnect.zip, for example:
BirstConnect_Home=C:\BirstConnect

In the -Djnlp.file="%BirstConnect_Home%\BirstConnect.jnlp" line, replace BirstConnect.jnlp with the SpaceId.jnlp from the JNLP file you saved to the HOME directory. This parameter enables Birst Connect to read the properties from the JNLP file.

Example cmdUI.bat:
set JAVA_HOME=C:\Program Files\Java\jre1.8.65
set BirstConnect_Home=C:\BirstConnect

"%JAVA_HOME%\bin\java" -cp "%BirstConnect_Home%\dist\*;%BirstConnect_Home%\dist\lib\*"
-Djnlp.file="%BirstConnect_Home%\SpaceId.jnlp" -Xmx1024m com.birst.dataconductor.DataConductorApp

If you are using a proxy server to connect to the internet, add the proxyHost and proxyPort to the command:
"%JAVA_HOME%\bin\java" -cp "%BirstConnect_Home%\dist\*;%BirstConnect_Home%\dist\lib\*" -Djnlp.file="%BirstConnect_Home%\SpaceId.jnlp" -Dhttp.proxyHost=ProxyHostName -Dhttp.proxyPort=ProxyPort -Xmx1024m com.birst.dataconductor.DataConductorApp

Birst Connect can resolve script-based proxies that are configured on the same machine that is running Birst Connect. In this case, the proxyHost and proxyPort parameters are not required.
If Birst Connect is using a server that uses https instead of http, supply the parameters as follows:
-Dhttp.proxyHost=ProxyHostName -Dhttp.proxyPort=ProxyPort

To extract data from Application Connectors using Birst Connect commands see Extracting Application Connector Data Using Birst Connect Commands.
Save the required third-party resource files to the \dist\lib folder.

Tip: For information on downloading SAP library files see Downloading SAP Library Files.
To launch the Birst Connect user interface, open a command prompt and run cmdUI.bat:
C:\BirstConnect\commandline\cmdui.bat

The Birst Connect GUI application launches.
Once Birst Connect is set up to run from the command line, copy the jar file(s) to the dist\lib folder, located where Birst Connect was installed on your local machine.

To run Birst Connect in command mode without the UI

The steps and notes are essentially the same as running the UI.

Follow the previous steps 1-5.
For step 6, edit cmdNoUI.bat. This file calls DataConductorCommandLine and takes Birst Connect tasks and/or Live Access connections as arguments.
set JAVA_HOME=C:\Program Files\Java\jre1.8.65
set BirstConnect_Home=C:\BirstConnect

"%JAVA_HOME%\bin\java" -cp "%BirstConnect_Home%\dist\*;%BirstConnect_Home%\dist\lib\*" -Djnlp.file="%BirstConnect_Home%\SpaceId.jnlp" -Xmx1024m com.birst.dataconductor.DataConductorCommandLine -tasks MyTaskName1, MyTask Name2 -liveaccess

The -tasks flag can take multiple task names as arguments. Task names can have spaces.

The -liveaccess flag runs all Live Access connections configured in Birst Connect. It does not have any arguments.
Open a command prompt and run cmdNoUI.bat:
C:\BirstConnect\commandline\cmdNoUi.bat

Note: Birst Connect Tasks that contain 'process' in the name of the task process fine via the Birst Connect UI but if the same task is run via the command line, the task will upload data and process the data even though the desired outcome is upload only. The work around is to rename the Birst Connect Task so that it does not contain 'process' in the name.

For automating when tasks are run, See Running Birst Connect Tasks Using an OS Scheduler.