Install External Report Formatters

A default IFS Middleware Server installation, whether clustered or not, will service all types of server calls, for example from interactive users using IFS Enterprise Explorer or IFS Web Client, for report rendering and for integrations. It is possible to use separate middle-tier installations for these three types of calls (Clients, Integration and Reporting) as a means to minimize one type of server call potentially affecting the response time or availability of unrelated functionality. Read more this separation at High Availability and Scalability.

An External Report Formatter is a Report Formatter that runs in a separate application server instance compared to a non External Report Formatter which runs in the central application server instance (i.e. the same application server instance that serves requests from IFS Connect, IFS Web Client, Solution Manager and so on). Formatting reports can be a quite resource (memory and CPU) intensive operation, especially if it's complex reports or if multiple reports needs to be formatted simultaneously. The purpose of using one or several External Report Formatters is to offload the central application server. To get an overview of how the Report Formatters and the use of external ones fit in to the overall Info Services / printing architecture of IFS Applications it's recommended to look at the About IFS Report Formatters section in the concept section of the Foundation1 overview.

There is currently no fully automated support for setting up an External Report Formatter. A couple of manual steps needs to performed after running the installer. Below you'll find a step by step guide on how to set up an External Report Formatter. The External Report Formatter runs inside it's own application server instance and can be set up on a different machine or on the same machine where the central application server is installed. There's no limitation on how many External Report Formatters can be set up (the physical memory of a single server will obviously limit the number of application server instances that can be set up on a machine).

Contents

• 1. Set up / install a new application server instance for the External Report Formatter
• 2. Tune the application server instance
• 3. Configure a Report Formatter template to invoke the new External Report Form
• 4. Configure to use the External Report Formatter when previewing and direct printing
• 5. Restarting the server
• 6. Configure for SSL
• 7. Verify that it works
• 8. Troubleshooting

1. Set up / install a new application server instance for the External Report Formatter

Detailed information about each step in the installer wizard can be found in the normal/full installation guide. That's where you'll find information about how the installation is made on different operation systems, using different application server types. This step by step guide shows how to setup an External Report Formatter on Windows using the IFS Middleware Server.

1. Start the installer from your BUILD_HOME, select to create an IFS HOME and verify the location of your installation.
   
2. Extended Server and the Installer are the only components we want to deploy when setting up an External Report Formatter
   
3. Choose to create a new instance and name it.
   
4. Deploy only the Extended Server
   
5. Enter database host name, service name and IFS system user password.
   
6. Supply the passwords for the internal system users. This is just a matter of supplying the same information as when setting up the main application server instance. This is not the time to change the passwords.
   
7. We do not need to import any at this page. So we need to deselect all checkboxes on this page. A tip is to use the RMB "Deselect All" option.
   
8. Session Properties and Connect server can be ignored for the External Report Formatter. Keep the default values.
9. Specify the ports which this application server instance will be using. Since it's a separate application server instance, it needs to run on a different port that the main one (and any other application server on the same machine). In this scenario the External Report Formatter is being set up on the same machine as the main application server. Specify for instance 60 as the port prefix instead of the standard 58 and see all the ports change accordingly.
   
10. Select the same user authentication method as when the initial/main application server instance was set up, in this case Oracle.
    
11. Keep the default values in section Database Connection Pool Settings.
12. The External Report Formatter should not be included as a cluster member. Make sure it uses different ports from you original server if on the same machine. Specify passwords for the Admin User and the Monitoring User as it's required. You will have to perform a Prerequisite Check to advance forward. This will essentially set up its own little cluster with only one node.

13. Keep the default values in section Java Virtual Machine settings for Admin Server.
14. Add the Custom Java Parameter -Derf=true in order to specify that this application server should be treated as an External Report Formatter. This is a mandatory step in this configuration. This parameter is considered with previewing and direct printing to physical printers through IFS EE client in an External Report Formatter installed environment . You can the Java minimum and maximum memory heap size settings. The minimum size controls how much memory will be allocated, when just starting up the External Report Formatter in this case. In order to avoid allocating a lot of memory even if the External Report Formatter isn't invoked. The maximum size is essentially what limits how large reports or how many simulations reports that can be formatted. All the formatting threads of this application server instance will compete for the same memory resources. This means the number of reports being processed simultaneously will effect the maximum size of reports that can be processed. It's very hard to say exactly how much memory a certain number of pages will require and so on, since it varies from report to report and the data will also affect the memory usage. You can increase the maximum high enough not only to be able to process the most extreme reports, but also to be able to handle simultaneous formatting of multiple large reports. However setting this higher than needed is not recommended since it could cause trouble to the JVM garbage collector when collecting is eventually triggered. It can take quite some time to collect vast amounts of memory.
    
    As a guide, you can expect that the server needs at least 2 Gb of memory and can then render a 30000-page (simple text) report. You will have to increase with about 1 Gb for each extra 15000 pages rendering capacity.
    
    
15. Change the port for the Managed server as well, if on the same machine as your original server. If on a new machine, you have a new IFS HOME and you can use the default ports for both step 12 and 15.
    
16. Use SSL according you your own preferences.
17. Keep the default values in section Web Server Configuration or change as required.
18. Specify SSRS URL, user and password, if you are using SSRS feature of IFS Applications. This step will be available only if you have SSRSOR module included in your build. Further information could be found at SSRS Integration Configuration section.

19. If you have the DOCMAN and DOCVUE included in your build, you will be asked to configure these at the end of your installation. You can use the same parameters as in the original server or just type nonsense paths and names since this functionality will never be used in the External Report Formatter.
20. Last step. Click install, see the installation complete and you're done (with this part).
    

2. Tune the application server instance

In the first step we basically just set up a standard application server instance. Even if we excluded some stuff from the installation, the newly created instance still contains too much. The instance will work as a External Report Formatter, but if we tune it by removing some unnecessary stuff we can free up resources (mainly memory) that can be used to process reports instead (i.e. shutting down the External Report Formatter's Admin Server)

3. Configure a Report Formatter template to invoke the new External Report Formatter

Detailed information on how to configure Report Formatters can be found in the configuration guide. This page shows a typical setup, rather than discussing all options and aspects in detail. The Report Formatters and the settings that are setup below are used when a print job is printed to a logical printer.

In order to make it as flexible as possible to control the number of simulations formatting requests a Report Formatter should be able to process, it's recommended to run each Report Formatter template in it's own queue. This since the Execution Mode is set on the queue and not on the template itself. Therefore we start by creating a new queue (BATCH3) for this Report Formatter.

1. To create a new queue, start Solution Manager, go to Integration > IFS Connect > Setup IFS Connect > Messages Queues. Create a new queue by duplicating BATCH1 or BATCH2 (duplicate button in upper right corner). Change the name and description. This is also the place to control how many print jobs this Report Formatter should be able to process simultaneously. You do this by selecting the Execution Mode. You can set this to "InParallel", "InOrder" or "InSequence" depending on your requirement. Each mode has it's own way of processing the jobs. Have a look at Configure Message Queue for more details.

Setting the  Execution Mode to "InOrder" or "InSequence" will make print jobs be processed one at a time. A job that that is printed to one of the logical printers handed by this formatter which takes a long time to process will delay small jobs to the same Report Formatter. On the other hand setting it to this mode will ensure that all available memory can be used to format the report (i.e. you're less likely to run into memory issues). Setting the Execution Mode to "InParallel" will make the job process faster as more then one job is executed at once. Yet, you might have to be cautious about the resource used.

2. Next step is to create the actual Report Formatter template. This is done using Solution Manager as well, go to Reporting > Operational Reporting > Report Formatter feature. Either you create a new Report Formatter template, or you can change an existing one to invoke the new External Report Formatter. There's no limitation in the number of Report Formatter templates that can be active at the same time. Note that with the new Batch Processor the status of the template is irrelevant. There for there is no start/stop RMB option. The status will be set to "Suspended" all the time, this is just a template for the Batch Processor to to know which Report Formatter it should handover the job to. The handing over is done depending on the mapped logical printers in the Report Formatter, which is discuss later on in this guide.
    

In order to create a new Report Formatter template, select "Duplicate" from the dropdown menu or simple press F6.

3. The Report Formatter Interface type should be set to ExternalPrintAgent. This is a mandatory step in setting up a Report Formatter which directs to an External Report Formatter. Then set the External Report Formatter URL parameter to the URL of the application server instance we just setup above. (the ERF01 instance running at port 60080). You should be aware that if these two values are not specified all jobs will default to the main application server and will not invoke the External Report Formatter. Change the Queue if required (we use the newly created BATCH3 queue).

You can also, add logical printers which this Report Formatter template should handle and if required you can specify a Locale for this Report Formatter template as well. The Locale is blank by default and you can leave it as it is. Leaving the locale blank or not will affect the data and number formatting of reports which are printed to the logical printers configured to this Report Formatter template.

4. Configure to use the External Report Formatter when previewing and direct printing

The step 3 in above section setup the External Report Formatter to handle the print jobs when a report is printed to a logical printer. You need to specify the redirect URL in order to direct the request to the External Report Formatter when previewing or when direct printing to a physical printer (i.e. the users Windows default printer). If you don't specify this all preview and direct physical printer print requests will still be handled by the main application server. Go to Solution Manager > System Parameters and specify the External Report Formatter host and port under the system parameter named External Report Formatter Connect String. Note that you don't have to specify the protocol (i.e. http://) as this will be added by the framework when directing the request.

5. Restarting the servers

In order to make the changes we did above affective, we need to restart both the main application server and the External Report Formatter server. This is a mandatory step in this setup process.

6. Configure for SSL

You need to specify the External Report Formatter's SSL URL under External Report Formatter URL parameter when configuring a Report Formatter template for an SSL installation of the Report Formatter. There is no change in the system parameter External Report Formatter Connect String as we only specify the host and the port.

7. Verify that it works

Create a print job bound for a logical printer served by the External Report Formatter to verify that it works as intended and you get a printout on the physical printer that you have mapped to the logical printer. If you're doing this for a production environment or any other type of environment where a Print Agent is handling the actual printing/spooling of the PDF documents created by the Report Formatter, then it's the physical printer mapping in the Print Agent configuration that is used. The logical printer still needs to be listed in the Report Formatter template in order for the job to be picked up from the print queue.

8. Troubleshooting

After Apps 9 Update 1, you can enable IFS Application logging to check if the requests are correctly redirected to the External Report Formatter server from the main server. To do this set the global logging level of IFS Application logging to DEBUG level. Have a look at the Middleware Server Troubleshooting section for more information. Once the logging is enabled you will see "REPORTING ERFInvokeManager:" prefixed log lines in the ifsapplog-<ManagedServerName>.X.log file.