How to Delete Stale BI4 User Sessions with biUserSessionKillScript
Since the release of BI 4.0 (and going back as far as XI 3.x and XI R2), we’ve had various issues related to stale user sessions. I’m referring to a user session initiated from the BI Launchpad, CMC or other SDK application that should have expired and been deleted by the CMS hours or days ago, but is somehow still listed in the CMC > Sessions page. These open sessions not only consume a license but also take a small bit of CMS resources as long as they’re kept open. BI4.1 SP3 has a nice new feature that brings us one step closer by offering a way to manually drop a session. But this still leaves it up to the Administrator to manually do this periodically. See screenshot below from prereleased copy of SP3:
As you can see above, here’s a session that has been active for almost a week. The new SP3 feature will now allow you to select one or more sessions and click ‘end session’. This is no doubt a step in the right direction. Prior to BI4.1 SP3, you really had two options: 1.) Recycle the CMS or 2.) run an sdk script to do the delete. I think we can do better than this.
I’d love to be able to solve the real issue(s)… which would be for the BI product to always close the session when it expires (or possibly even sooner, for instance when the user is finished with it). But unless we knew the exact workflow a user followed that led to a stale session, we can’t prevent and fix these types of problems in a patch or code correction. If you find a specific workflow that can cause a session to linger for hours or days after it should have expired, please raise an incident with SAP in the BIP-BI-SRV component and we’ll do our best to resolve it. Also, be sure to read kbase# 1862925 – “Session handling and tuning”. Until the workflows are each identified, I’m offering you more of a reactive approach to this problem.
I’ve seen a few scripts on the SCN offering a way to delete user sessions. But I couldn’t find one that offered a way to automate the task, delete it safely and most of all delete a user session based on its age. The script I created can be uploaded to your BI 4.x environment as a Program File and automated via a recurring schedule or it can be run on from a command line manually on or off the BI server. I’ve tested it under various locale and regional settings and it works well on both Windows and Linux installations. As any program, there are probably flaws so please use at your own risk and let me know if you run into problems.
Due to file format restrictions on the SCN, the ‘biUserSessionKillScript’ (.biar, .jar and source code) can be downloaded from:
kbase#: 996692 – How to Automate the Cleanup of Stale BI4 User Sessions
** UPDATE (March 15, 2019) **
I’ve added a new zip file attachment “biUserSessionKillScript_v2_for_BI42.zip” to the kbase article above. It includes a few updates I made to the original script. Version 2 now allows you to override the 60 minute minimum session age as well as pass in a list of excluded user Ids. Be aware, the 60 minute minimum age was originally enforced as a safeguard to prevent unintentional mishaps. I’ve removed it to give admins an easier way to test the script. I’ve also included the .java file (source code) to version 2 in the zip file. Input parameters are passed differently into the application in version 2. See the updated notes below for instructions on how to use the new script. Lastly, the new script is compiled in java 8 and will not work in the lower environments which use the sapjvm 6.
Uploading as a Program File:
There’s two ways to insert the Program File into your BI4 environment. You can either add it via CMC as a Program File or import it via Promotion Management via an .lcmbiar file.
CMC insert method:
- Login to the CMC, Navigate to a folder, click on the ‘Manage’ menu and select: ‘Add’ > ‘Program File’
- Browse to the biUserSessionKillScript.jar file and change the ‘Program Type‘ radio button to ‘Java’.
- Select OK
Promotion Management method:
- Log into the CMC and open the Promotion Management page.
- Choose ‘Import’ > ‘Import File’ and select the attached .lcmbiar file.
- After clicking OK, select the destination dropdown and login to your CMS. Click ‘Create’.
- In the next screen, click ‘Promote’.
Scheduling the Program File:
Scheduling a Program File is very similar to scheduling a report. The only difference is you’ll need to specify a few arguments to tell BI how to run the program.
- Right click on the Program File and click ‘schedule’
- Select the ‘Program Parameters’ option on the left
- The only argument the script needs when run within BI is the Age of a Session in Minutes
- Specify this value in the Arguments textbox. For safety reasons, the value must be >= 60. Anything less and you risk deleting an active user session.
- In the ‘Class to run” textbox, type: biUserSessionKillScript
- From here, you can specify any of the other scheduling settings you need like recurrence, notification, etc. and then click ‘Schedule’ to run the job.
- Regardless if the script succeeds, there will be a text file saved to the Output FRS with the results. Click on the instance title to view the output.
Running the jsp outside of BI
Run manually on the server console via cmd line:
- Copy the ‘biUserSessionKillScript.jar’ into the equivilant folder in your BI4 installation directory:
- C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\java\lib
- If your path is different than above, then you’ll need to also edit the ‘biUserSessionKillScript.bat‘ file so the correct path is referenced.
- Execute the .bat file directly.
- To prevent the cmd window from disappearing at the end ofthe program, open a cmd window first, drag the .bat file into the window and click enter.
- Or you can copy the syntax within the .bat file and paste directly into a cmd window.
Run manually on a non-BI server via cmd line:
The biUserSessionKillScript.jar was compiled without including the BI4 dependency jars. This helps keep the file small and allows for a quick and easy download. Also, when the .jar is scheduled, BI already knows where to find the corresponding dependencies so there is no need to package them. However, if you want to run the script on a pc manually where neither BI4.x nor the client tools are installed, then you will need these depencies inserted into the jar. In this case, follow the steps below.
- On the BI4 Server, open the ‘biUserSessionKillScript.jar’ file with WinRar.
- Navigate to the path ‘C:\Program Files (x86)\SAP BusinessObjects\SAP BusinessObjects Enterprise XI 4.0\java\lib’ and insert all of the files below into the .jar.
- Prior to adding the jar files into biUserSessionKillScript.jar, it will look like:
- After adding the files, it should look like:
- To Execute the file, open a command prompt and run:
- Version 1:
- <path to java.exe> -jar <path to biUserSessionKillScript.jar> <username> <password> <CMS servername> <Auth Type> <session age in minutes>
- Version 2:
- <path to java.exe> -jar <path to biUserSessionKillScript.jar> -user=<username> -password=<password> -cms=<CMS servername> -age=<session age in minutes>
- Version 1:
- age = must be the first argument passed to the application and it must be specified as an integer. Minimum value = 60
- A second parameter that was undocumented was the “-force” switch. It could be passed as a second argument for testing lower values. If this is not specified, and the age value specified is lower than 60, the age which will be used becomes 60 minutes.
- Version 2:
- The arguments below can be used in any order and are not case sensitive (except for the password).
- specify the username to login. Only needed when executed on the cmd line. Do not include if scheduling as a program file..
- password of the user above. Only needed when executed on the cmd line.
- -cms=<cms hostname>
- CMS name to be used during login. Only needed when executed on the cmd line.
- -age=<session age in minutes>
- Session age in minutes. If used with the -force switch, value specified is used. If no -force switch is used, then the value must be greater than 60, otherwise 60 will be used.
- List of user Ids to exclude from possible deletion. The session age is first evaluated, then cross referenced with the exclude list. If the session user ID exists in the exclude list, the session is not deleted. However, it will still be listed in the output as *Excluded*.
- if used, the age value is accepted as-is.
- Example: To purge all sessions including the one you used to run the script, use -force -age=0
- Only intended for testing purposes. Use at your own discretion.