How to Create a Program File in BI4

I’ve written a bit of jsp, vbscript, and java based applications in the past and lately I’ve really enjoyed writing simple java apps that can be run as a Program File (.jar) within the BI 4.x environment.  A couple examples of these Program Files were shared earlier this year called the ‘biUserSessionKillScript’ and ‘DisableInactiveUsers’.

How to Delete Stale BI4 User Sessions with biUserSessionKillScript

How to Auto-Disable Inactive Users in BI4

In BI 4.x, Program Files can be in the form of a batch file, vbscript, javascript, shell script, or a jar file.  The examples above were compiled as .jar files and below I’ll explain what it takes to create your own java Program File.  I’ve created a template that can be imported into Eclipse to help get you started.  The source code is attached to a Kbase which can be downloaded separately here:

SAP Note 2099941

In this example, its assumed you know how to import a java project into Eclipse and how to export it to a jar file.

The What and Why:

Developing a BI4 Program File has many benefits.

• For one, your application will be executed by the AdaptiveJobServer which means it will look to the BI4 java classpath used by the AJS.  There’s no need to package all the extra dependent jar’s as you would a standalone application.  Your import statements will automatically look for and find these libraries in the “C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\java\lib” directory assuming you are only using the BI SDK based libraries.
• Second, a Program File offers all the benefits of historical instances.  But instead of having a Webi or CR report as your scheduled instance, a .txt file is generated in the Output FRS location with all of the System.out.println() information within your program.  This can be beneficial for both debugging your application as well as giving a historical look at whatever your application did when it was scheduled.
• Lastly, since the program is stored, executed and managed within the BI system, the security for running the application can be set just as any other infoobject.

Attached at the bottom of this article is an Eclipse project template for creating a new BI4 program file.  Feel free to use this as a starting point for creating your own Program File.  Below is an explanation and breakdown of how this application template works.

How it works:

In the top portion of the example you’ll find the class definition and main method.  The difficulty in writing a new program file is the application needs to be able to run standalone in order for you to develop it, alter it and debug it within Eclipse.  When the application is run as a program file within BI, the standalone portion of this application will never be executed.  In other words, the main() method is never actually called.  Instead, the Adaptive Job Server calls the run() method directly.

The example starts off with the class definition and the main() method.  The class implements the IProgramBase interface.  This is a requirement for all BI4 program file applications because of how the program job server service calls the run() method directly.

The majority of the main() method code does nothing more than create an enterprise session and pass it to the run() method.  Be careful of what you include in your main() method as this will only be executed when your application is run outside of BI (within Eclipse, via command line or any other means).  All code you want executed when the application runs within BI must be inside the run() method or in another method called from this point down.  Again, think of the run() method as your starting point.

In order to run the application from the command line in standalone mode, you will need to create an enterprise session.  This requires 4 command line parameters passed to your application.  The code below first ensures that 4 values were entered.  It compensates for a 5th value in case something else needs to be passed, but this isn’t necessary for the code below to work.

There’s not much going on here in the run() method.  In this example, its assigning the username within the enterprise session to a variable and then writing it to the console.  However, every time you output text to console via System.out.println() the Adaptive Job Server will write this to the text file created in the Output FRS when the program file is scheduled.  There’s no need for additional code to output your information to a text file.  This is all built into BI and automatically done at schedule time.

Although this really doesn’t do much, keep in mind its just an example.  The program will run as-is and output to console the user name held in the enterprise session.  To test this within the Eclipse IDE, you will need to create a Run Configuration.

1. To do this, right click on the project name within the Package Explorer, choose Run-As > Run Configurations.
2. Highlight Java Application on the left and click the ‘new launch configuration‘ button.
3. Under the Main tab:
   • The project name should be auto filled in if you had right clicked on the correct package within the Package Explorer.  If its not, then browse for it and select the project.
   • You’ll need to search and select the main class in the 2nd box.  Click the Search button to do this and select the ProgramObjectTemplate classname.
4. Under the Arguments tab:
   • Add the 4 command line arguments separated by a space.
   • The values specified in the main() method are:  <username> <password> <cms name> <auth type>
5. Once the Run Configuration is created and saved, you can run the application within the Eclipse IDE and test it.  Once tested, then you’ll be ready to export it to jar and import the jar into the Central Management Console.

Import the Program File into the CMC

To import the Program File into the CMC, you’ll need to follow these steps:

1. Log into the CMC
2. Navigate to a folder where you want to import the file. Right click on the folder, choose Add > Program File
3. Choose Browse and select the .jar file you exported from Eclipse
   
4. Select the Java radio button and click OK
5. You will now see the new Program File within the folder.
6. Before you can schedule it, you’ll need to set the default Program Parameters.  To do this, right click on the Program File, and select Default Settings > Program Parameters
7. In the Class to Run box, type the name of the class – ProgramObjectTemplate.
8. If there were any additional command line parameters after the first 4 we created (user, password, cmsname and authtype), you would set these in the Arguments box. The BI4 Java SDK will automatically create a user session at schedule time based on the user that schedules the program file.  So passing these here isn’t required.  The only arguments you would need in the Arguments box are the additional command line parameters passed beyond these 4.  See either of the examples mentioned at the beginning of this blog as both use an additional command line argument.