I. PREREQUISITES - MUST READ:
The first prerequisite is you must know IIS to be able to install this application on a web server. If you do not know IIS, stop right here; this is not something you can do. This is not something we (Jeff-Net) can help you do either. This is one of the very few areas we "draw the line" on our wonderful, friendly support. IIS is a specialty. Get with your IIS administrator to install the application. Once installed, anyone that is familiar with Crystal Reports will understand how to configure the reports for Web Portal. Also note, we DO support Web Portal once it is installed on your server. We will help you configure the portal itself and get your reports running.
You can install Web Portal on Windows Server 2003, 2008, 2012, 2016, or later. We do not support installing or running Web Portal on a desktop PC. This defeats the purpose of running a server application.
Web Portal is not an overly complicated application, but it is important you use this installation guide and follow each step. DO NOT SKIP AROUND. DO NOT SKIM READ. There are a lot of parts that work together beautifully, but each piece must be there. There is more to do than simply run the installers and type in a URL. It is a licensing and support requirement to read this documentation. If you are not willing to read this documentation to understand Web Portal, we do not want you to license it. We will not give support to anyone that has not read this documentation. We sell Web Portal at a very cost-effective price. We can only do that requiring you to read and follow this documentation.
Do the following FIRST, before installing Web Portal:
II. UPGRADING FROM 2013.1? Read First!
- Backup your entire Web Portal install files and directories in C:\inetpub\www\YourWebPortalDirectory
- What's changed since 2013.1? Active Directory support added (optional), additional user-based parameter value options (3 total plus login ID), group support added (you now assign users to groups, and groups to reports), Upgraded ADMIN interface (no more tiny icons to click), standard web templates can now be created from ADMIN interface (no need for Report Runner Batch), 150+ free category icons now included, and even more and easier customization (including footers and widgets); Read full release notes here...
- With these new features, you will not lose any previous reports and users settings, BUT you must edit each report from ADMIN interface, verify parameters, and re-assign any user-based settings. You must also edit your users, assign them to groups, and then assign reports to groups. It is quick and easy to assign reports to a group, including "select all" type functionality.
- If you are going to utilize the new Active Directory integration, see notes towards end of this documentation discussing the configuration of the web.config file.
- If you installed/tested the application before but never did anything with it (ie. it's not in production), we recommend deleting the entire directory from c:\inetpub\www. This will allow the application to do a fresh, 100% new install.
- If you installed the application to production, but you've never customized anything other than your logo and/or the background, please manually delete the file WebPortalDictionary.xml from the JNAdmin folder in your installation. This file contains all text/phrases within the application. It's better if this file can be re-installed. If you do not delete this file, you will be prompted during the install whether to write over it or not.
- You can safely install on top of a previous install if necessary, with the previous warnings noted. And as long as you have a backup as noted first, we can restore/fix anything the Web Portal installer overwrites.
- If you have any additional concerns or questions, we are happy to schedule a remote session with you when you get ready to update, and do the upgrade with you.
- Lastly, when you view the site, due to the CSS changes, you (and your users) may need to do a Ctrl-F5 in their browser on each page the first time the application is accessed. Browsers, by default, store old cached pages and you must force them to refresh. You do this in a browser by pressing Ctrl and F5 at the same time.
III. UPGRADING FROM 2013.2 OR LATER?
- Backup your entire Web Portal install files and directories in C:\inetpub\www\YourWebPortalDirectory; if you've made custom CSS changes, those will normally need to be re-done. If you have any issues re-doing your CSS changes, if you have a backup, we can help you merge old settings with new settings.
- As of 2013.5 and later, the base color changes of Web Portal are much easier (so even if you have to re-do custom color and logo changes, it's super quick and easy).
Important! If you are a network administrator installing Web Portal for someone else in your company who will be administrating it, it is HIGHLY recommended they sit with you while you install the application. There are NUMEROUS directories that the Web Portal administrator needs to know about and USE. These directories must be written down so the Web Portal administrator knows where to find them later.
Installation of Report Runner Web Portal is simple and straightforward. Following is a list of steps, one-by-one, that will take you from beginning to end:
1) Download the software via the link sent to you in email (it's not publicly posted on our website)
2) Run the setup executable name Report_Runner_Web_Portal_Setup.exe
Note: If running in an environment where your machine is "locked down", you will need to use the "Run As Administrator" function or if on a Terminal Server (RDP), use "Install Terminal Server Application" from the Control Panel.
3) This is the first window you will see (after initialization process)
4) Next, read the Happiness Disclaimer, and click Next
5) Enter your IIS website directory (do not use spaces within this folder), and click Next
6) Enter your short-cut folder (default should normally be used), and click Next
7) Enter your Jeff-Net data folder (default should normally be used), and click Next
Note: This directory MUST ALREADY EXIST. You will not be able to continue. It's required that you've already installed Report Runner Batch and Report Runner Event Server previously. Within the existing Report Runner Batch AppData and Event Server directory, this installer will add a Web Templates directory. This is where your Web Templates will need to be moved/saved from Report Runner Batch. These Batch XML templates are used to configure your web reports.
Note: Reread previous note (the most common question we get is "Where do I put my web templates?")
8) Select the version of Event Server you are running. Normally, you will stay with the default of 2011 or higher. We have a few customer still running the legacy version of Event Server, though.
9) Configure your mail settings. In the user-facing application, the user can change their login password. These mail settings are used to send these emails. Note, the Web Portal report emails are sent using Report Runner Batch mail settings.
10) You are ready to INSTALL; this is your final confirmation before files start being copied; click >>INSTALL>> to begin
11) Once the installation is complete (after the main files are copied), you will see a message about setting and configuring IIS. The application should be set up as an ASP.Net v4 application (previous to 2013 it was a .Net v2 application).
NOTE: The jnAdmin folder (which has all the ASP pages for creating/editing reports and users) is not protected in any way. You will want to create some kind of Windows authentication protection for those pages or only allow them to be run internally (or not available via the external internet). This external article gives a good overview of setting the authentication in IIS7:
12) Installation is complete, and click Finish
Note: Write down the Picklist and Web Templates directories listed below.
Note: Write down the Picklist and Web Templates directories listed below.
Note: Write down the Picklist and Web Templates directories listed below.
The Web Portal Administrator needs to know where these directories are located.
V. IMPORTANT DIRECTORIES TO BE AWARE OF:
1) Free category icons directory. We've made over 150 free category icons available. You can create custom report categories and select any of these perfectly designed and matching icons.
2) Picklists directory. This directory is where you place any custom picklists you create to assign to parameters. The Web Portal is unable to load the SQL-based dynamic parameters directly your Crystal Reports, so we allow you to create picklists external to Web Portal and assign them to parameters (and as of 2013.191 of Report Runner --- SQL-based picklists are now defineable, and static parameter values stored in RPT file are now extracted to auto-create picklists). Web Portal even supports cascading parameters. It can fully duplicate all of the functionality within Crystal Reports parameters. There are a number of pre-defined picklists in this directory, and you'll figure out the syntax of these picklists quickly. Also note, the beginning names of the picklists matter, too. Those names are used to determine how Web Portal reads the picklist format. This text-based picklist technique is simple and elegant all-in-one. Picklist configuration is discussed more below in the "Configuring Web Portal" section.
3) Report templates directory. This directory is where you can place all reports that you want to run in the Web Portal. This will allow you to browse to these reports when you're ready to add a new report. Please note, alternatively, you can also "throw" all RPT files in the Input queue of Event Server, and Event Server will automatically create Web Portal templates for each report. The login ID/password assigned to the reports in this process will be the Global ID/password from Report Runner Batch. If your reports do not require an ID/password, you can either leave the Global ID/Password blank or literally set them both to "jnnothing" (without quotes). Any other kind of custom login information will require you editing the XML files (Web Templates) manually from Report Runner Batch.
VI. MODIFYING WEB.CONFIG SETTINGS:
All of your Web Portal-specific settings are stored in the web.config file, found in c:\inetpub\www\YourWebPortalDirectory. Towards the top, you will see various paths defined, which the installer takes care of setting. There are some additional settings that you can toggle features on or off by editing the web.config file manually. Most of the settings in web.config have comments/notes above them that explain how to modify them. Here are a few examples of modifications for key features:
1) Turn on Active Directory support (optionally). Simply change the 0 to a 1 to enable. Set your LDAP/AD directory or you can comment out that line to tell Web Portal to use default AD directory. Turning on AD support will DISABLE the Groups and Users tabs within the ADMIN interface. Your report groups will now list your AD groups, and you can assign them to the reports. And of course, when your end users log in to the application, they will use their AD credentials.
2) Modify the parameter date format (optionally). Do not change this just for the fun of it, to see it displayed a different way. Change it only if the date format we are passing to the report needs to be formatted another way.
3) Modify mail settings. When you ran the installer, you entered your mail settings for sending password notifications. The installer created these settings in web.config. If you need to change these settings later, you can change them here.
VII. OTHER NOTEWORTHY OPTIONAL WEB.CONFIG SETTINGS:
Note: These settings are normally NOT modified or changed from their default settings. We are simply explaining how to use them if you choose to.
1) ShowPasswordInBrowseList - By default, password settings are hidden in the ADMIN interface. Use this setting to show them.
2) InstanceNamingFormat - Use this setting to set the default instance naming format
3) UseWPLoginForDatabaseLogin - By default, report login information for database access is stored in the Web Portal (Batch) XML template. Enable this setting to use the same Web Portal login ID and password for report database access, too.
4) WebPortalURL - If you plan on using the command line feature of Web Portal (calling URLs to run reports without user interaction), there is a key called "webportalurl" that you need to set. We do not automatically set it, because you may want to use a different URL for external display. When you generate a command line to call a report, this URL will be used.
VIII. STARTING AND VERIFYING YOUR WEB PORTAL INSTALLATION:
1) Start ADMIN interface:
Note: Sample ADMIN interface: http://admin.reportrunner.com
2) Start END USER interface:
Note: Sample END USER interface: http://reports.reportrunner.com
IX. SIX (6) MOST COMMON INSTALLATION ISSUES (AND SETTINGS TO VERIFY DURING INSTALLATION --- DO NOT SKIP):
1) Permissions: The application you installed or any extra files you copied into the Web Portal directory after installing need permissions assigned or re-assigned. If you are having permissions issues, you might see a message like the one below or the application may simply appear to not work.
To fix this, you will need to set FULL CONTROL permissions on your Web Portal directory (the c:\inetpub\www\YourWebPortalDirectory) for IIS_WPG (you also need to set them for ASPNET, IUSER_YourServerName, and/or IWAM_YourServerName). Make sure you propogate these settings throughout the entire directory (including files and sub-directories). See following screenshots:
Here are some useful permissions links:
2) Application Pool Incorrect: The application needs to be run in a .Net 4 application pool. When you add an application to IIS, it will not automatically assign it to a .Net 4 application pool. You will need to verify it. If you do not see .Net 4 as an option for your application pool, you need to register .Net to IIS (help links below). If you are having application pool issues, you will probably see a message like this:
Here are some useful .Net 4 registration and application pool links:
3) Older browsers: The end user interface runs fine in most any browser. The ADMIN interface needs a fairly up-to-date browser (IE 9 or 10, current Chrome, current Firefox). If you use an older browser with the ADMIN interface, you will be unable to delete anything (it will look as if the DELETE feature doesn't work --- it will do nothing). You will also see issues with scrolling within the various pop-up windows (they will not scroll properly).
4) Reports don't finish or do finish and show an error: See this KB article...
5) Compiler errors: Make sure users have proper permissions. For example, the following compiler error can be fixed by giving IIS_IUSRS full access to C:\Windows\Temp. This is just an example. Your configuration may differ.
Server Error in '/Jeff-NetReportRunnerWebPortal' Application.
Description: An error occurred during the compilation of a resource required to service this request. Please review the following specific error details and modify your source code appropriately.
Compiler Error Message: BC31007: Unable to open module file 'C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files\jeff-netreportrunnerwebportal\637ef227\e96b22d7\App_Code.vl8ltcud.0.vb': System Error &Hc0000005& (Visual Basic internal compiler error)
6) Command line URL is wrong: Go back and review Section VII, #4.
--- USER MANUAL BEGINS HERE ---
X. QUICK CUSTOMIZATION OF WEB PORTAL:
Customizing Web Portal is super easy. From your ADMIN interface, click on SETTINGS. You can change the upper right logo and background easily (see screenshots below). You can also easily make CSS changes to modify colors and fonts. The footer displayed on the END USER interface can be modified to show your company name and important links. This footer will show on all forms after the user logs in. Want to change text or messages displayed on the a form? You can do that by editing the data dictionary. All columns are sortable. It's easiest to sort the definitions and look for the string you want to change. Just EDIT, UPDATE, and click the orange REFRESH button to reload the dictionary into memory. Please note, in some browsers, you may need to do a Ctrl-F5 to reload cached text in browsers and/or CSS changes. Lastly, we've added a simple Widget setting to allow for implementing the left or right "floating" prompts that you can generate with various web-based helpdesk and feedback applications like Zendesk or UserVoice, or GetSatisfaction, just to name a few.
XI. CONFIGURING WEB PORTAL AND SETTING UP REPORTS:
Once installed and customized, using and configuring Web Portal is really straightforward. There are two types of interfaces. The ADMIN interface and the END USER interface (start-up links given previously). Start the ADMIN interface. You have 5 tabs to choose from, which you can use to configure 99% of everything in Web Portal. We recommend configuring in the following order:
- Configure base SETTINGS: As discussed in prior topic, you can customize the look-and-feel of the END USER interface here. You can do this at any time, but we recommend doing it first.
- Configure base CATEGORIES: Set up names and icons for all of report categories. We've installed over 150 32x32 sized icons to use within the application. When you add a report, you will have a list of your categories to choose from to assign the report to. End users only see categories for reports they have been assigned. If you have a Management category and an end user has no Management reports assigned to them, they will not see this category. So, set up an unlimited number of categories. We've created a number of default ones for you.
- Configure GROUPS: If you are using the Active Directory integration, their is nothing to do here (all groups would be loaded from Active Directory). Otherwise, set up your user groups here. You can be as specific as creating groups like Sales, Support, Administrative, Employees, Customers, etc... or as generic as Everyone (which we include by default). If you have already created some users or reports, you can assign these items here, too. Reports are assigned to groups, not users. Users are assigned to groups. Users can be assigned to multiple groups. Note, we have a unique feature where, if you do not want to create specific user IDs for everyone, you can give them the group ID and password, and they can simply log in as a group.
- Configure USERS: If you are using the Active Directory integration, their is nothing to do here (all users would be loaded from Active Directory). Otherwise, set up your user users here. A user can be anything from an in-house employee to an external customer. One of the neatest features in Web Portal is the ability to assign up to three (3) *hidden*, user-based, parameter values. Why is this neat? This allows you to use one report for everyone, and everyone sees something different because of these values. The end user does not see these hidden values, but you, the administrator, can assign them as "answers" to parameter prompts (and hide the parameter prompts). For example, you may have a sales report that has a salesman ID parameter. You could set up the report to use parameter value one. The salesmen would never see the prompt; it would simply filter the data in the report based on their hidden user value. You could do the same with customer invoices. You could post an invoice report, assign to all customers, and have a parameter that filters the report based on a hidden customer ID. The customers never see this parameter. They simply enter their invoice number and it allows them to see it, because the record selection also filters based on this hidden customer value. The "wrong" customer would never see another customers invoice, because they would have different user values assigned. Note, you could always make the user ID the same as the customers actual account ID (or for salesmen, their actual salesman ID), because one other option for parameters is to assign the "login ID" to the parameter value, too.
- Configure REPORTS: Lastly, you create your reports. You have two types of Web Portal reports (really three)... 1) Live 2) Static Crystal Reports (pre-run reports using Report Runner Batch) 3) Static URLs (http-based links to pages and/or documents). We're going to discuss live Crystal Reports-based reports first.
Web Portal depends on an XML "config" file to be created for every live report. These XML config files are the exact same format as a Report Runner Batch XML file with one batch job in it. Previous to 2013 of Web Portal, you had to manually create these single-job XML files using Report Runner Batch. In 2013, this is no longer necessary. While you can still do this manually in Report Runner Batch, you have two other options. One, you can place all of your RPT files that you want to create XML templates for into the INPUT directory of Event Server (this KB assumes you know what Event Server is). Event Server will AUTOMATICALLY process the RPT files (and also auto-create your static picklists from values stored in RPT files), creating one XML template per RPT file (using same name as report), and placing that new XML template into the Event Server's Web Templates directory (this is the same directory used in previous version of Web Portal). Since these XML templates are now in the Web Templates directory, when you go to add a new report, your XML templates will load and show for all of these reports. There is no limit to the number of reports you place in the INPUT queue either. You can place 10, 50, 100, or 500. It will create the web templates for each one. Alternatively, your second option is to place all of your RPT files into the Web Portal directory called "NewRPTFilesDirectory". This will allow you to (from the new report interface), browse to that directory and pick the RPT file. Once you select the RPT file, Event Server will process the RPT file on-the-fly, and create a new web template for you. Some users may prefer doing reports one-at-a-time like this so they don't have to choose from a large number of XML templates in the drop-down. Note, this automated web template creation process will assign the Global ID and Password from Report Runner Batch to be used to run Web Portal reports. If you need to configure some other ID/password, you will need to edit the XML web template manually using Report Runner Batch and configure the data connection information.
Ok, so you've selected your web template. Next, name your reports, assign a category, configure your output options (PDF only or allow user to choose), configure usage of report instances, and configure your parameters.
Report instances allow Web Portal to retain previously run reports. This allows users to easily access a report they ran previously. You determine how many to keep, and Web Portal does the rest. The biggest benefit of report instances is it saves report processing time on the server, because users aren't re-running the same report over-and-over. For example, a salesman might run a report every morning at 8am. Let's say it take 5 minutes to run. If he wants to look at that same data later in the say, he doesn't need to rerun the report and wait 5 minutes; he can click the previous report instance and it opens immediately.
You have numerous options to configure parameters and picklists. You can change parameter prompting text (uses Crystal Reports prompt by default), assign a picklist, enter a default value, assign a user-based value, allow for manual values, and show/hide (display) the parameter. Most of this falls right-in-line with how you would expect the report to work. Assuming you know Crystal Reports, configuring the parameters should make sense and work as you would expect it to work.
Picklists are text files stored in the PicklistDirectory (the directory you noted in Section V, #2 during installation). These picklist text files have multiple ways to be configured, and we use text files so you can configure them with a text editor like Notepad. Picklists can be static (values listed per line in text file) or dynamic (values are fetched when report is run by executing a SQL Select query). Picklists can also be cascading (choosing one value shows another limited set of values to choose from). Cascading picklists are only static at this time (you can't create cascading picklists with a SQL Select query). Cascading picklist files MUST start with the words "CascadingPicklist". All other picklists MUST start with "Picklist". The rest of the filename can be anything, but we recommend being as descriptive as possible.
Static Picklists: We have a number of default static picklists already defined in the PicklistDirectory folder. You can manually create a picklist simply by adding values to a text file, one line at a time. If you need to show one value, but assign a different value, add the pipe symbol "|" between each value. Click here to see a sample static picklist. In this sample, Yes or No is picked by user, but 1 or 0 is assigned to the parameter.
Auto-Created Picklists: As of 2013.191 of Report Runner, when your RPT is processed via Event Server, static parameter values stored in your RPT file will be extracted to auto-create static picklist files for you. These auto-created picklists are stored in your Event Server data folder (where your WebTemplates directory is located --- installation step #12) in a folder called AutoPicklists. The picklists are named vased on the report name and the parameter name, so you know what it should be assigned to. You will need to MOVE any auto-created picklists from the Event Server AutoPicklists folder to the PicklistDirectory folder in Web Portal. We do not automatically store all picklists in the PicklistDirectory folder, because a number of reports (can) utilize the same picklist, and it's better to use one picklist for maintenance purposes. If you need to add a code to a picklist, and the picklist is used by 100 reports, it's much easier to add a code to one file than 100 files. Make sense?
Dynamic SQL-based Picklists: As of Web Portal 2013.5g, dynamic, SQL-based picklists are now available. It's as simple as configuring a connection string and writing a select statement. The SQL-based picklists can be a direct connection to SQL Server or, for any other datasource type, be based on a DSN. Click here for an example of a SQL Server connection. Click here for an example of a DSN connection. Note, the format of the file must be as shown. The *SQL* at the top is a keyword to tell Web Portal this is a SQL-based picklist. The number 1 you see on the second line can be a 1 or a 2. 1 indicates one value is being returned. 2 indicates two values are being returned. If two values are returned, the 1st value is shown to use in picklist, and based on users choice, the 2nd value is assigned to the parameter.
Cascading Picklists: Cascading picklists must be configured manually or you can create formulas in a Crystal Reports template and export values from a database to text using Report Runner Batch. Click here for an example of our cascading picklist format. The greater than sign is used to indicate a cascading value. Use the Header line to assign cascading headers/descriptions, too. In this example, users can pick a state in the US, then a region, then a city, and via the pipe symbol "|", a city code is passed instead of the city name.
For the 2nd and 3rd types of Web Portal reports, static reports, you need to check the "Static" option. This will change the form to allow you to browse and select a static report (from the StaticReports directory) or enter a specific URL. The specific URL option makes sense to most users, but we do get the question of why the static Crystal Reports option? This allows you to pre-run long running reports (imagine large sales or accounting reports that take an hour or longer to run) using Report Runner Batch. You could refresh these static reports at whatever interval you like and any time the user selects this type of report, it opens it immediately. There iss, of course, no need to set up parameters or output options, because they are already run and saved to a specific format.
The final thing you will do is assign the report to the groups that are allowed to access it. You can assign a report to more than one group. Users only see reports their groups have been assigned. If you have 1000 reports created, but a user group has access to 20 of them, those users see ONLY those 20 reports, not all 1000.
XII. FINAL QUESTIONS:
Q: How many users can access Web Portal?
A: It's unlimited. You can set up an unlimited number of named users. They can all access the Web Portal at once. We do not limit users in any way.
Q: How many users can be logged in at one time running reports?
A: It's unlimited. Live reports will run in the order the reports were submitted. Event Server processes report requests in the background. You can configure Event Server to run up to twenty (20) reports at a time. How many you set this to depends completely on your server power and configuration. End users will never get a messages stating "too many report requests" or "licenses exceeded". We simply queue up the reports and run them one-by-one.
Q: Are static-type report requests or instances "queued up" in the order received?
A: No, they are processed/opened immediately. Event Server does not need to do anything with these types of requests. They are already processed.
Q: The reports seem to be running, but they are not displaying afterwards. What's the problem?
A: You have pop-ups blocked. You must instruct any users to enable pop-ups in their browser. Please note, many browsers have a pop-up blocker AND many devices have additional pop-up blocking software. If the report is not displaying after running, it is your pop-up blocker.
Q: What about mobile devices? Can I run a Crystal Reports RPT on my iPhone, iPad, or Windows phone?
A: Yes! Anything with a browser can access Web Portal and run live Crystal Reports. Note, for Windows phone users, since it doesn't really support pop-ups, we've configured Web Portal to automatically use the same browser window to show the report. When you are finished viewing the report, simply press you back arrow twice to return to Reports window. Windows phone users are accustomed to this browser usage technique.
Q: Popup windows are tiny and can't be resized. How can I fix this?
A: This is generally an issue in IE. For that, go into your Internet Options, Tabs, select the option to Always Open Popups In A New Tab.
Q: Reports will not finish (the gears just keep turning) or I get an error message. How can I fix this?
Q: Where's the User Manual? I can't figure how to use Web Portal.
A: THIS DOCUMENT IS THE MANUAL. Scroll back up to Sections X and XI. Those two sections really do explain all you need to know to get started and do most anything with Web Portal.
PLEASE NOTE: If you are trying to run Web Portal and it appears to "not work" ... CHECK PERMISSIONS. Go back up to "IX. Four Most Common Installation Issues" and perform steps #1 and #2 even if you do not see the exact error messages we give as examples. 99.9% of all Web Portal "errors" come down to permissions not being correct.
XIII. COMPLEMENTARY FREE TOOLS FOR WEB PORTAL (USEFUL FOR WEB PORTAL END USERS):
1) PDF VIEWER: http://get.adobe.com/reader/ (be sure and uncheck McAfee Security option)
2) WORD VIEWER: http://www.microsoft.com/en-us/download/details.aspx?id=4
3) EXCEL VIEWER: http://www.microsoft.com/en-us/download/details.aspx?id=10
That's it! Please let us know if you have any additional questions. We are always here to help!