Chapter 15. Terminal

The ReportServer Terminal is a mighty tool for administrators. You open it with the keyboard shortcut CTRL+ALT+T or using the ''Admin Panel'' system console (Please consider that you need the respective rights; refer to Chapter 3. User and Permission Management).

The ReportServer Terminal follows the shell of a Unix system. It includes a command prompt as well as a history of commands and the respective outputs. Beside general commands, the Terminal provides access to almost all ReportServer objects via the Virtual file system. In addition, the Terminal can be used to enter and execute scripts.

Enter commands at the command prompt and confirm with ENTER. The following command:

reportserver$ hello

will return the reply

> hello user

There are two different types of commands. Simple commands will provide their output directly in the Terminal. This applies for the majority of commands. Beside the simple ones there are also commands requiring further user interaction. After calling up this type of command, the command prompt will change and display a single opening angle bracket. The eliza program represents an example for this command type (originally by Joseph Weizenbaum, and here in an adaptation by Jesper Juul). You close complex commands with CTRL+C, or according to eliza also by entering the leave-taking expression: bye

reportserver$ eliza
**************************
ELIZA
CREATIVE COMPUTING
MORRISTOWN, NEW JERSEY
ADAPTED FOR IBM PC BY
PATRICIA DANIELSON AND PAUL HASHFIELD
Java version February 24th, 1999
By Jesper Juul - jj@pobox.com.
**************************
> Hi, my name is Bob.
HI! I"M ELIZA. WHAT"S YOUR PROBLEM?
I DON"T CARE ABOUT NAMES --PLEASE GO ON.
> I do not know. Isn"t that why I am here?
HOW LONG HAVE YOU BEEN HERE?
> About one minute or so.
WHAT DOES THAT SUGGEST TO YOU?
> I guess you cannot help me after all.
OH, I CANNOT HELP YOU AFTER ALL.
> bye
Good Bye
reportserver$

The -h flag (or -? flag) offers help to a command listing the individual options. When pressing the TAB key, ReportServer attempts to complete the command presently entered. If it fails to do so because there are several options, these will be shown to you by pressing the TAB key again. With the arrow keys UP/DOWN you browse through the history of your commands. To clear the Terminal window, use the clear command.

You can leave the Terminal by entering the exit command.

You will find a command overview including a short description of all available commands in Chapter 19.

ReportServer integrates various objects (reports, datasources, files, etc.) as virtual file systems in the Terminal. Each object tree (e. g. the report section) has here an own root node. When you open the Terminal you first arrive at the top level. Here you find the root nodes of the various virtual file systems. By entering the command ls you can display them.

reportserver$ ls
datasources					Datasource management
reportmanager				Report management
dashboardlib				Dashboard library
fileserver 					File system
tsreport 					TeamSpaces 
usermanager 				User management

Here ls shows the objects in the current directory. By entering the command pwd the current directory will display.

reportserver$ pwd
/

Use the command cd directory to change the directory. Multiple folders will be separated by / (slash). So, by entering

cd "reportmanager/Dynamic Lists/"

you can switch to the folder Dynamic lists in the report management tree. Please observe to set quotation marks when there are objects that include spaces in their name. When you enter mkdir, you can create a new sub-folder.

reportserver$ mkdir newFolder reportserver$ ls -l
12 T_AGG_ORDER - Basis TableReport			TableReport
17 T_AGG_PAYMENT - Basis								TableReport
22 T_AGG_CUSTOMER - Basis								TableReport
26 T_AGG_PRODUCT - Basis								TableReport
33 T_AGG_EMPLOYEE - Basis								TableReport
39 T_AGG_ORDER - Parametrized 					TableReport
49 newFolder 														ReportFolder

This is the output of ls -l which returns name and object as well as ID and type. Now, to move all reports to the new folder, use

reportserver$ mv T_AGG_* newFolder/ 
reportserver$ ls -l newFolder
17 T_AGG_PAYMENT - Basis 						TableReport 
33 T_AGG_EMPLOYEE - Basis 					TableReport 
12 T_AGG_ORDER - Basis 							TableReport
22 T_AGG_CUSTOMER - Basis 					TableReport 
39 T_AGG_ORDER - Parametrized 			TableReport 
26 T_AGG_PRODUCT - Basis 						TableReport

Be aware that the mv command at present expects the second parameter always to be a directory in contrast to the Unix equivalent. This is why it cannot be used to rename objects.

Now we switch to the FileServer and create a temporary directory:

reportserver$ cd /fileserver/
reportserver$ mkdir tmp
reportserver$ cd tmp
reportserver$ pwd
/fileserver/tmp

Unlike typical file systems, ReportServer allows two objects having the same name in one folder. For example, two reports with identical names will be in the same report section. We can simulate this by creating two folders with the same name:

reportserver$ mkdir test
reportserver$ mkdir test
reportserver$ ls -l
124 		test		FileServerFolder
125 		test 		FileServerFolder

Now, what will happen if we change to the test folder by entering cd test?

reportserver$ cd test
reportserver$ pwd
/fileserver/tmp/test

We have switched to the test folder. But to which one did we switch? Internally, ReportServer saves paths not via their names, but via the ID of objects which are unique in the individual virtual file systems. By entering pwd -i they will display.

reportserver$ pwd -i
/fileserver/id:123/id:124

As you see, we changed to the first test folder with the ID 124. To get to the second one with the ID 125, use the internal path:

reportserver$ cd ../id:125
reportserver$ pwd
/fileserver/tmp/test
reportserver$ pwd -i
/fileserver/id:123/id:125

In FileServer (i.e. in the virtual file system which represents ReportServer FileServer) we can use the commands createTextFile and editTextFile to create or edit text files.

reportserver$ createTextFile text.txt
file created

By entering cp now we can copy this text to other folders.

reportserver$ cp text.txt ..
reportserver$ cd ..
reportserver$ ls -l
124			test 				FileServerFolder
125 		test				FileServerFolder
127 		text.txt 		FileServerFile

To delete objects, use the rm command. Here wildcards can be used.

reportserver$ rm tes*
/fileserver/tmp/test has children

Here, ReportServer stated that the folder to delete still holds objects. To include them in the deletion, use rm -r.

reportserver$ rm -r tes* 
reportserver$ ls -l
127 		text.txt 		FileServerFile

For some recurring commands it might be useful to define shortcuts (aliases). To do this, use the configuration file etc/terminal/alias.cf (You will find it in the ReportServer File system, from the Terminal you will access it by entering /fileserver/etc/terminal/). If the file does not exist, create the respective directories by entering mkdir and the file with createTextFile.

The file is structured as follows

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<cmdaliases>
		<entry>
			<alias>ll</alias>
			<command>ls -l</command> 
		</entry>
   	</cmdaliases>
</configuration>

Here, alias ll was assigned to the command ls -l. To reload the aliases, use:

reportserver$ config reload
configuration reloaded

Thus, the cache which stores all configuration files will be reloaded by entering the command above. As an alternative, you can restart your ReportServer for reloading config files.

A main task of the Terminal is to manage and execute scripts. In ReportServer scripts can be used for various purposes. Firstly, they can be used to create dynamic or complex reports. As they have access to the Java runtime environment and with this to the available metadata, scripts are perfectly suited for reports analyzing the system status. An example for a script report is the documentation report (for further information on script reports refer to Section 7.9.). In addition, scripts can also be used for administrative tasks, or even to expand the functionality of ReportServer. Within the scope of this Administrator manual, we will give you some insight into the world of ReportServer scripts in the following section. You will find a detailed treatment including examples and concepts in our script guide.

Warning: The right to write scripts allows a user to execute arbitrary code. This right should thus only be granted to trusted system administrator's.

The following describes how to locate entities. Entities are stored objects such as reports, users or TeamSpaces. You can find entities by searching for classes annotated with @Entity. You can also find a list of all entities in our ReportServer SourceForge project https://sourceforge.net/projects/dw-rs/. Download the latest apidocs file from the src directory for this. Further, you can also find all entities for the current ReportServer version here: https://reportserver.net/api/latest/entities.html.

Many terminal commands provide you with an object resolver to find a specific entity or a group of entitities. Currently, there are three object resolvers:

ID Resolver	Allows you to locate an entity by its entity ID.
Path Resolver	Allows you to find an entity by its Virtual File System path.
HQL Resolver	Allows you to find entities by a HQL (Hibernate Query Language) query.

We will illustrate these object resolvers by using the locate command. Any other command supporting object resolvers works analogously to the examples provided below.

The locate command allows you, as its name suggests, to locate entities by using an object resolver query. Refer to the locate command documentation for more information on this.

The ID object resolver uses an entity ID for locating an entity. Since entity IDs are unique, the query resolves to zero or one entity. The syntax is: id:EntityType:entityId where EntityType is the specific entity class, e.g. TableReport. Refer to the entity list mentioned above for the specific entity types. entityId is the specific entity ID. E.g.:

reportserver$ locate id:TableReport:123
Report Root/Dynamic Lists/myReport (Reportmanager)

The path resolver requires a Virtual File System path for locating the specific entity. Note that the path requires quotation marks if it contains spaces. E.g.:

reportserver$ locate "/reportmanager/Dynamic Lists/myReport"
Report Root/Dynamic Lists/myReport (Reportmanager)

You can also insert a relative path to the current location, e.g.:

reportserver$ locate myReport
Report Root/Dynamic Lists/myReport (Reportmanager)

Further, you can use an HQL query (Hibernate Query Language) for locating the needed entity or group of entities. Refer to https://docs.jboss.org/hibernate/orm/5.0/userguide/en-US/html/ch13.html for the HQL documentation. The syntax is: hql:query where the query is a valid select HQL query. Since HQL queries have blank spaces, quotation marks are needed. E.g.:

reportserver$ locate "hql:from TableReport where id=123"
Report Root/Dynamic Lists/myReport (Reportmanager)

You can also search for entity attributes, e.g.:

reportserver$ locate "hql:from TableReport where name like '
Report Root/Dynamic Lists/myReport (Reportmanager)
Report Root/myReport2 (Reportmanager)

Following you can find a list of some important entity types, which can be used with the object resolvers described above. The complete list can be found here: https://reportserver.net/api/latest/entities.html

Report entities:

• Report General report entity. Example: locate id:Report:123
• TableReport Dynamic list. Example: locate id:TableReport:123
• BirtReport BIRT report. Example: locate id:BirtReport:123
• CrystalReport Crystal report. Example: locate id:CrystalReport:123
• GridEditorReport Grid editor report. Example: locate id:GridEditorReport:123
• JasperReport Jasper report. Example locate id:JasperReport:123
• JxlsReport JXLS report. Example locate id:JxlsReport:123
• SaikuReport Saiku report. Example: locate id:SaikuReport:123
• ScriptReport Script report. Example: locate id:ScriptReport:123
• ReportFolder Report folder. Example: locate id:ReportFolder:123

User entities:

• User User. Example: locate id:User:123
• Group Group. Example: locate id:Group:123
• OrganisationalUnit Organisational unit. Example: locate id:OrganisationalUnit:123

Datasource entities:

• DatasourceDefinition General datasource definition entity. Example: locate id:DatasourceDefinition:123
• DatabaseDatasource Relational database. Example: locate id:DatabaseDatasource:123
• CsvDatasource CSV datasource. Example: locate id:CsvDatasource:123
• MondrianDatasource Mondrian datasource. Example: locate id:MondrianDatasource:123
• BirtReportDatasourceDefinition BIRT report datasource. Example: locate id:BirtReportDatasourceDefinition:123
• ScriptDatasource Script datasource. Example: locate id:ScriptDatasource:123
• DatabaseBundle Database bundle. Example: locate id:DatabaseBundle:123
• DatasourceFolder Datasource folder. Example: locate id:DatasourceFolder:123

Datasink entities:

• DatasinkDefinition General datasink definition entity. Can always be used instead of a specific datasink entity below. Example: locate id:DatasinkDefinition:123
• AmazonS3Datasink Amazon S3 datasink. Example: locate id:AmazonS3Datasink:123
• BoxDatasink Box datasink. Example: locate id:BoxDatasink:123
• DropboxDatasink Dropbox datasink. Example: locate id:DropboxDatasink:123
• EmailDatasink Email - SMTP datasink. Example: locate id:EmailDatasink:123
• FtpDatasink FTPS datasink. Example: locate id:FtpDatasink:123
• FtpsDatasink FTPS datasink. Example: locate id:FtpsDatasink:123
• GoogleDriveDatasink Google Drive datasink. Example: locate id:GoogleDriveDatasink:123
• LocalFileSystemDatasink Local filesystem datasink. Example: locate id:LocalFileSystemDatasink:123
• OneDriveDatasink OneDrive - SharePoint (O365) datasink. Example: locate id:OneDriveDatasink:123
• PrinterDatasink Printer datasink. Example: locate id:PrinterDatasink:123
• SambaDatasink Samba - SMB/CIFS datasink. Example: locate id:SambaDatasink:123
• ScpDatasink SCP datasink. Example: locate id:ScpDatasink:123
• ScriptDatasink Script datasink. Example: locate id:ScriptDatasink:123
• SftpDatasink SFTP datasink. Example: locate id:SftpDatasink:123
• TableDatasink Table datasink. Example: locate id:TableDatasink:123
• DatasinkFolder Datasink folder. Example: locate id:DatasinkFolder:123

Filesystem entities:

• FileServerFile File. Example: locate id:FileServerFile:123
• FileServerFolder Folder. Example: locate id:FileServerFolder:123