Chapter 11. Transports
ReportServer offers a comprehensive transport mechanism that enables secure transportation of objects like reports, datasources, datasinks, and files between different system environments such as development, testing, and production. This mechanism ensures that changes are carried out consistently and in a controlled manner, thereby guaranteeing the integrity and stability of the entire system landscape.
The transport mechanism in ReportServer provides various use cases that allow users to efficiently manage their work and safely transfer changes across different environments:
| Use Case | Transporting reports, datasources, datasinks, and files from a development environment to a testing or production environment. |
| Advantage | Ensures that changes can be tested in a controlled environment before being transferred to production. |
| Use Case | Developers can create regular transports to secure the current state of their work. |
| Advantage | Provides a way to secure work steps as snapshots that can be restored or transferred to another system if needed. This is especially useful when multiple developers are working in parallel or when experimental changes are made that need to be rolled back later. |
| Use Case | Creating copies of existing transports to make changes or use content in other contexts. |
| Advantage | Flexibility in managing transports, as existing transports can be duplicated and reused as open transports. |
| Use Case | Undoing unwanted changes by applying a new transport that restores the original states. |
| Advantage | Allows restoring the original state after an error or misapplication by transporting and applying the corresponding changes again. |
| Use Case | Indirectly reverting changes through manual adjustments or repeated transports, as direct rollbacks are not possible in ReportServer. |
| Advantage | Provides a method to undo applied changes by either relying on backups or performing manual corrections. |
The transport mechanism of ReportServer offers flexible and powerful tools to securely transport changes across different system environments, secure work steps and correct errors when necessary. Through careful planning and application of transports, administrators and developers can ensure the stability and consistency of their systems while remaining flexible in responding to changes.
For the transport mechanism in ReportServer to be used, specific configurations and prerequisites must first be met.
| Unique Keys | All transportable objects, such as reports, datasources, datasinks, and files, require a unique key (per tree) that is automatically generated when the object is created. These keys are necessary to uniquely identify the objects and avoid conflicts during transport. |
This file contains basic settings for importing and applying transports. It specifies, among other things, the remote server from which transports are imported, the target directory for the transports and the user responsible for applying the transports.
Common Errors in transport.cf
| Correctness of the Remote Server Key | The the remote server's key must be correctly specified. An incorrect key will prevent the transports from being retrieved. |
| Directory under target | The directory specified in the target field must exist. If the directory is not present, it is created by ReportServer automatically while retrieving the transports. |
| Reloading the Configuration | After any changes to the transport.cf or other configuration files, the new configuration must be loaded. This is done using the config reload terminal command, which ensures that the changes take effect. |
This file defines the mapping of datasources between the source system and the target system. There are two possible options that determine the priority of the mapping.
| Mapping | If explicit mapping is required between a datasource in the source system and one in the target system, it is defined in the mappings.cf file. This is necessary when the datasources in the systems have different keys. |
| Same-Key | If the datasources in both systems have the same key, explicit mapping can be omitted. ReportServer automatically recognizes that the datasource is identical based on the key and uses it accordingly in the target system. |
| Priority of Options |
|
To exchange transports between different ReportServer instances, the remote server must be configured in the Remote-Servers section. This configuration includes:
| Name | A name to identify the remote server. |
| Key | A unique key for authentication. |
| REST-URL | The URL of the remote server, which can be found in the system console under General Information. |
| Username | The username authorized to access the remote server. |
| API Key | A special key for authenticating API requests between the servers. This API key must be stored as a user property in the user profile. It uses an apikey analogously as in executing reports via URL (see Section 7.11.) for more information on this. |
Transports can only be exchanged and applied if ReportServer version and schema version of both systems are identical. This prerequisite is crucial to avoid compatibility issues and to ensure that the transported objects function correctly in the target system. If there is a version mismatch, data structures or functions might not align correctly, leading to errors during the import or application of the transports.
The transport process in ReportServer involves several steps that must be carefully followed to ensure a successful transfer of objects between systems.
The process begins with the creation of a transport order in the source system (e.g. development). This transport order acts as a container that consolidates the objects and their configurations for transfer between systems.
Objects such as reports and datasources can then be added to the transport via the context menu ''Add to Transport'' in the respective area of ReportServer. It is important to note that the saved state of the object at the time of addition is what is included in the transport. If an object that is already in the transport is added again, the previous version of the object in the transport is overwritten. This ensures that the most current version of the object is always included in the transport.
As long as a transport is still open, the objects within it can be managed. The management of the object list is done via the ''Objects'' tab of the transport. Objects can be added or removed before the transport is finalized.
After all relevant objects have been added to the transport and the object list has been managed, the transport order is closed on the source system. This effectively releases the transport. Additionally, only closed transports can be transferred. A transport must therefore be released and thereby closed before it can be imported into another system.
The next step is to retrieve the released transports from the source system in the target system. This process is initiated in the Transport Management section of ReportServer by pressing the ''Fetch Transports from Remote'' button. When retrieving, all closed transports from the remote system are imported into the target system and stored there. However, the content of the transports is not unpacked or applied at this time.
Before the transport is applied, it should be thoroughly verified. This ensures that all settings and prerequisites are met, particularly that the mappings for the datasources are correctly configured. This guarantees that the objects function properly in the target system.
The following preconditions must be met before a transport can be applied:
| RS_VERSION_CHECK | the ReportServer version of the transport must exactly match the current ReportServer version in the target system. |
| DB_SCHEMA_CHECK | the database schema version of the transport must match the current schema version in the target system. Typically, this precondition is satisfied when the RS_VERSION_CHECK precondition is met. |
| TRANSPORT_CLOSED_CHECK | only closed (released) transports are eligible for application. This precondition verifies that the transport is indeed closed. |
| SUPER_USER_CHECK | only a super user may apply a transport, as transports can alter many parts of the system, which requires superuser privileges. The super user must be specified in the main/transport.cf configuration file and must correspond to an existing super user in the system. This precondition checks that these criteria are met. |
| USER_PERMISSION_CHECK | the current user, i.e., the one applying the transport, must have both read and execute permissions on the transport. This precondition ensures that the user has the necessary permissions. |
| CONFIG_TRANSPORT_EXIST_CHECK | the main/transport.cf configuration file must exist in the target system. This precondition checks for the presence of this file. |
| CONFIG_MAPPINGS_EXIST_CHECK | the main/mappings.cf configuration file must be present. This precondition verifies its existence. |
| LOCAL_MAPPINGS_CHECK | the local keys defined in the mappings within the main/mappings.cf configuration file must correspond to an existing datasource in the current system. Local keys refer to datasource keys from the local system, and thus they must point to an existing data source. |
| TRANSPORT_MAPPINGS_CHECK | All remote keys found in the transport being applied must match a local key that points to an existing local data source. This matching can be done in two ways: either through explicit mappings defined in the mappings file or by identifying a data source in the local system that shares the same key. The LOCAL_MAPPINGS_CHECK precondition ensures that the mappings file correctly links remote keys to local data sources, while this precondition verifies that any keys not explicitly mapped in the mappings file correspond to an existing data source in the local system. Thus, any keys not covered by an explicit mapping in the mappings file must still point directly to an existing data source within the local system. |
A transport can only be applied if all the above preconditions are met. These preconditions can be checked by clicking the ''Check apply preconditions'' button.
The following screenshot illustrates the outcome when some preconditions are met while others are not, indicating that the transport cannot be applied.
The following screenshot depicts a transport that has been imported into the system. The transport can be applied if all preconditions meet as explained above.
When applying a transport in the target system, the contained objects are integrated into the target system using a merge mechanism. The merge process identifies whether the objects are new or modified based on the unique key of the object.
| What happens | If the transport contains a report whose key does not exist in the target system, the report is imported into the target system as a new report. The report is fully transferred and then available in the target system. |
| Result | The new report is inserted into the target system and can be used and further edited like any other report. |
| What happens | If the transport contains a report whose key already exists in the target system, the merge process recognizes it as a modified report. In this case, the existing report in the target system is completely replaced with the changes from the transport. |
| Result | The report in the target system will look exactly like it does in the source system (test system). The original version of the report in the target system will be overwritten. This means that all changes to queries, names, parameters, report properties, and report metadata will be fully transferred to the target system. |
| Note on Variants | Variants of the report that exist in the target system will generally remain intact. However, it is important to note that changes to parameters or the replacement of parameters can affect existing variants. These may become unusable if the new parameters are not compatible with the existing variants or if the structure of the report has been significantly changed. |
The entire transport process, from creation to retrieval and application of the transports, is thoroughly monitored and logged. These logs provide complete traceability and assist in troubleshooting if issues arise during the import or application of the transports.
After a transport has been successfully imported and applied, the associated logs can be directly accessed within the respective transport. These logs contain detailed information about the transport's progress, including all actions taken, any errors and warnings. This allows administrators to precisely track what changes were made and whether the transport was executed correctly.
This logging ensures a high level of transparency and traceability for all transport operations performed within ReportServer.
Transports in ReportServer are packages that contain reports, datasources, datasinks, and files, enabling their secure transfer between different system environments (e.g., development, test, production). They are used to transfer modifications and configurations to other systems in a consistent and controlled way, ensuring a uniform and stable system landscape.
A transport is created in the source system (e.g., development) by creating a transport job. This job serves as a container that aggregates the objects and their configurations for transfer between systems. This is typically done via the context menu ''Add to Transport'' for the respective objects.
The encrypted name of a transport is an automatically generated string composed of a timestamp and a unique identifier, e.g., 2024-08-18T11:10:03-3672330c. This name ensures that each transport can be uniquely identified and prevents conflicts during the management and transfer of transports between systems.
A transport contains fields such as the creation date, creator, the server ID of the source server, the schema version of ReportServer, the import date, importer, import log, and status (e.g., CREATED, CLOSED, IMPORTED). These fields are fixed and cannot be edited after creation to ensure the integrity and traceability of the transport. What can be edited are the objects within an open transport, which can be added or removed before the transport is closed.
Currently, following statuses are defined:
| CREATED | This status is set when a transport is newly created. This can happen through a context menu or a terminal command. |
| CLOSED | This status is set when a transport is released or closed. This means that the transport is no longer editable, as released transports are fixed. |
| IMPORTED | This status will be assigned when fetching transports from an external system e.g. from a test environment. |
| APPLIED | This status is set when an existing transport is applied. This means that the contained objects have been previously integrated into the system using a merge mechanism. |
| ERROR | This status is set when an attempt is made to apply an existing transport and it is found that the transport is not applicable. |
| INVALID | Internal status, currently not used. |
Following a screenshot of an imported transport. This means that the transport has been fetched from an external system.
Transport logs are detailed records that document all steps and events during the transport of an object. They include information about the transport's progress, such as the time of import, actions performed, and any errors or warnings. These logs are structured to provide a clear and traceable overview of the entire transport process.
Elements such as reports and datasources can be added to a transport via the context menu ''Add to Transport'' in the respective areas of ReportServer. It is important to note that the state of the object at the time of addition to the transport is captured.
If the same element is added to a transport multiple times, it is typically stored only once in the transport. The most recently added state of the object overwrites the previous one, ensuring that the transport contains the most current version of the object.
As long as a transport is open, elements can be removed via the ''Objects'' tab in the Transport Management. Once removed, these elements are no longer part of the transport and will not be imported into the target system during transfer.
The elements contained in a transport can be viewed in the Transport Management of ReportServer. Through the ''Objects'' tab, administrators can see and manage a list of all included reports, datasources, datasinks and files.
The following screenshot shows a transport that includes one Jasper report and two dynamic lists. It also contains datasources, which can be viewed by clicking on the ''datasources'' section.
If the original elements are moved or changed after being added to a transport, these changes are not automatically reflected in the transport. The transport captures the state of the object at the time of addition. Any changes require the objects to be re-added to the transport to include the updated version.
Released transports are transferred from the source system (e.g., development) to the target system (e.g., production) by importing them in the Transport Management of the target system using the ''Retrieve Transports from Remote'' button. Here, the transports are stored in the target system but are not yet unpacked or applied.
Application conditions, also known as ''apply preconditions'', are specific requirements that must be met before a transport can be applied in the target system. These include the correct configuration of datasources, the presence of all required dependencies, and compatibility with the schema version of the target system. Transports can only be applied if ReportServer version and schema version of both source and target systems are identical.
A transferred transport can be applied in the target system. ''Apply'' means that the objects in the transport are unpacked and integrated into the target system. The reports, datasources, datasinks, and files are implemented according to the defined configurations and mappings in the target system. When applying a transport, the objects are merged into the target system:
| New Report / New Datasource | If the object is recognized as new (Key does not yet exist in the target system), it is fully imported into the target system. |
| Changed Report / Changed Datasource | If the object is recognized as existing (Key exists in the target system), the existing object is updated with the changes from the transport. |
In the following two subsections you can find some examples for reports.
The report will be fully overwritten in the target system after applying the transport, so it appears exactly as it did in the source system (test system).
Variants of the report remain intact. However, caution is advised as changes to parameters or the exchange of parameters can affect the functionality of these variants. Variants could become unusable if they rely on parameters that have been changed or removed, or if the structure of the report has been significantly altered.
Clicking ''apply'' multiple times will typically result in the transport being applied only once. Reapplying should not cause additional changes since the transport is processed only once. However, errors may occur if the same objects are attempted to be imported again.
Yes, a transport can be recreated at any time, regardless of its current state (open, closed, or already applied), by using the ''Duplicate as Open'' function in the context menu. This feature allows for copying an existing transport and managing it as an open transport. This is particularly useful for efficiently organizing content and making further changes without affecting the original transport.
If a transport cannot be applied due to errors or missing prerequisites, the transport status remains unchanged, and the corresponding errors are documented in the transport's log. The administrator must resolve the reported issues before the transport can be applied again.
Yes, multiple transports can be applied sequentially or simultaneously, provided that the application conditions for each transport are met. It is essential to ensure that the transports do not contain conflicting changes to avoid consistency issues in the target system.
If a transport is interrupted during application (e.g., due to a server crash), some parts of the transport may have been applied while others were not. It is crucial to check the system after such an interruption and, if necessary, reapply the transport or manually intervene to ensure system consistency.
No, transports can only be exchanged and applied between systems with identical ReportServer and schema versions. Systems must be updated to the same version before a transport can be exchanged.
Transports that have not yet been completed or applied should be completed or exported before a system backup. This ensures that they are not lost during a system restoration and can be correctly restored.
The order of transports is not enforced by ReportServer but is the responsibility of the user. It is important to perform transports in the correct order, especially if later transports depend on or contain changes that build on previous ones. The user should ensure that all necessary dependencies are transported in the correct order to avoid consistency issues in the target system.
Applying transports in the wrong order can lead to missing dependencies or inconsistent data being imported into the target system. This may result in reports, datasources, or other objects not functioning correctly or unexpected errors occurring. Therefore, it is crucial to carefully plan and adhere to the order of transports.
Ideally, only final work states should be transported to ensure that the target system receives a stable and consistent version of the objects. Transporting intermediate states can lead to a disorganized system state and increase the risk of errors and inconsistencies. If it is necessary to transport intermediate states, it should be done with special care, and the order and dependencies should be clearly documented.
Transports can be effectively used as backups of work results during development. Developers can regularly create transports to secure the current state of their work. These transports then serve as snapshots that can be restored or transferred to another system if needed. This is especially useful when multiple developers are working in parallel or when experimental changes are made that may need to be rolled back later. To ensure efficient backup, only meaningful work steps should be captured as transports, and these transports should be appropriately named and organized to avoid confusion.
To successfully perform transports in ReportServer, some configurations are necessary:
| Unique Keys | All transportable objects such as reports, datasources, datasinks, and files must have a unique key (Key) that is automatically generated upon creation. |
| Configuration Files |
|
| Remote Server Configuration | In the Remote Servers section, the name, key, REST URL, username, and API key of the remote server must be correctly configured. |
| Version and Schema Version | ReportServer and schema version must be identical in both source and target systems to enable transport. |
These configurations are crucial to ensure that transports are carried out correctly and applied successfully.
Applied transports cannot be directly undone via ReportServer. To revert changes made by an applied transport, you must either restore a previously created system backup or manually reset the objects to their previous state. Another option is to create a new transport that reverts the changes to the desired original state. Therefore, it is important to ensure that all changes are reviewed and correct before applying a transport to avoid unintended consequences.