Setup and configure crystal web service

Both Crystal Quick Reports and Crystal Operational Reports could be previewed and printed from IFS Cloud. The following article describes how you can install and set up the Crystal Report Web Service, which is required for both Crystal Operational Reports and Crystal Quick Reports.

Installing Crystal Web Service

A local system Administrator account should be used for all the below configuration steps.

Prerequisites

Prerequisite	Details
1. CRYSTL component	CRYSTL component must be acquired and included in the build.
2. Microsoft.Net Framework version 4.0 or a later	Microsoft.Net Framework version 4.0 or a later version should be installed. You can download and install this from the Microsoft download site, http://www.microsoft.com/download
3. Microsoft IIS 10 or higher	Microsoft IIS 10 or higher version should be installed.
4. IIS 6 Management Compatibility	IIS 6 Management Compatibility role should be configured“IIS 6 Management Compatibility” role should be configured. Without configuring this properly the Crystal Web Service installation will not run properly. i) From Windows go to Start\Administrative Tools\Server Manager, select the "Add roles and features" option ii) On the "Server Roles" pane, scroll down to "IIS 6 Management Compatibility". Select all the checkboxes underneath the node. iii) Next, select the following Roles under Application Development. You will be prompted to add some other required features in order for ASP.NET to run properly: Web Server / Application Development: -.NET Extensibility 3.5 -.NET Extensibility 4.7 -Application Initialization -ASP -ASP.NET 3.5 -ASP.NET 4.7 -ISAPI Extensions -ISAPI Filters When in a WindowsServer 2012 with .NET 4.5, the ASP.NET v4.5 should be enabled as well. iv) Next select features and select the following under .net Framework 3.5 and .net Framework 4.7: -.Net Framework 3.5 Features - [x] .Net Framework 3.5 -.NET Framework 4.7 Features - [x] .Net Framework 4.7 - [x] ASP.NET 4.7 v) Next select the below server roles under Security - Web Server - Security - Basic Authentication Note: In IIS version 6 the .Net Web Service Extensions are disabled by default. Make sure these Web Service Extensions are enabled in the environment where the Crystal Web Service is installed. In order to enable these extensions, from the IIS Manager, go to Web Service Extensions. From the right-hand side panel, make sure that the Active Server Pages and ASP.NET v.4.0.x Web Service Extensions are enabled. If not, select these two extensions and click the Allow button to (or select Allow from the RMB menu) change the status to Allowed. vi) The final selection will look like the below vii) Click ‘’Next’’ then click "Install" at the "Confirm Installations Selections" pane. viii) After finishing the installation successfully click “Close” to leave the “Add Role Services” wizard. ix) Restart the machine after configuring IIS.
5. Oracle Runtime Client	Oracle Runtime Client should be installed with a certified Oracle version. Additionally, it's crucial to install the 64-bit version of the Oracle Client Runtime to match the 64-bit version of the Crystal.Net runtime version. Using different bit versions can cause issues with database connectivity, so it's important to make sure they match. An Oracle TNS entry should be specified in the tnsname.ora file that points to the database you are going to retrieve data from. This should point to the same database the relevant IFS Application Home is connecting to. Make a note of the tns entry name as you would need it in step 1-iii) in “Install CWS”, (see below) when setting up the Crystal Web Service. i) After installing the Oracle Runtime Client make sure that that line SQLNET.AUTHENTICATION_SERVICES= (NTS) in \network\admin\sqlnet.ora file is commented. # SQLNET.AUTHENTICATION_SERVICES= (NTS)
6. Crystal.Net runtime	The Crystal.Net runtime should be installed on the machine where the Crystal Web Service is going to be installed. The Crystal.Net runtime installation and the Crystal Web Service installation files can be found in the IFS Build Home. Go to the \Build\Home\artifact\crystl folder. Extract ifs-crystal-installers.zip file and copy the extracted files to the machine where the Crystal Web Service is going to be installed and run the CRRuntime_64bit_13_0_*.msi file it to install the Crystal.Net runtime on that machine.

Install CWS

If all prerequisites are met, follow the steps below to install and configure the Crystal Web Service.

1. Go to the same folder where you have copied the Crystal Web Service installation files. (Locate the setup.exe file and run it to install the Crystal Web Service.)
   

i) Select Default Web Site as the Site, enter a new name for the Virtual Directory , or leave the default value as it is and select the Application Pool and click Next to start the installation.

ii) In the Database User Credentials step specify the IFSPRINT and IFSSYS passwords in plain text. The passwords will be encrypted and written into the configuration file during the installation.

iii) In the Database Details step specify the TNS Entry Name, Schema Owner, IAL Owner. The TNS Entry Name should match the tns entry that you created in the tnsname.ora in step 5(Oracle runtime client installation) in the prerequisites section.

iv) In the Main Instance Replication & Layout Location step specify the number of copies of the main instance that needs to be replicated and the report layout folder location. This is the folder location that you created in step 1. See section Main Instance Replication for more details on instance replication. Also specify the folder that will be used to store the Crystal Report layouts.

Note: In IFS Cloud current release (22R2 onwards) the Crystal Report layouts could be directly stored in the database. The report Layout Location field is kept for backward compatibility only.

v) Select Next to start the installation.

vi) The following is shown if the installation is successful.

• Browse to <OS folder>\Microsoft.NET\Framework\v4.0.xxxx\CONFIG folder (e.g. C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\CONFIG) and open the machine.config file from a text editor. Under the <configuration>\<system.web> section, comment the following line

<processModel autoConfig="true"/>

and insert the following line:

<processModel enable="true" userName="SYSTEM" password="AutoGenerate" />

• From the IIS, Check the Basic settings for the Virtual Directory, Make sure it's running on ASP.NET v4.0 Application Pool.

Main Instance Replication

Configuring crystal web service instances for the same database is done by main instance replication. When installing a Crystal Web Service, you can specify how many copies of the main instances you need the installer to replicate. This is done in the Main Instance Replication & Layout Location step of the Crystal Web Service installer.

When replicating the installer take some considerations into account.

1. When replicating, the installer will replicate copies to the number of copies specified through the installer in addition to the main instance. For example, if you specify the number of copies as 3, you would get 4 Crystal Web Service instances.

2. All replicated copies have the same configuration details so that it points to the same database and use the same database credentials.

3. The installer will suffix a number to the main instance virtual directory name when creating and registering the virtual directories in IIS while replicating. For example, when the main instance name is IFSCRWebSetup and 3 copies are requested, then the installer will create and register the copies in IIS as IFSCRWebSetup_1, IFSCRWebSetup_2, and IFSCRWebSetup_3.

1. The replication instance details are maintained in the main instance. In the main instance a file named Instance.list will include the names of the replications of the current main instance. This file is only found in main instances. Do not add/remove items from this file. If you want to remove instances, then use the Windows Uninstaller to uninstall the full installation, including the main and the replications.

Multiple Instance Replication

One or more Crystal Web Service instances can be configured against the same or different application servers. In fact, all the configured instances could be redirected to either one database, or to different databases, upon the requirement. Configuring multiple web service instances will introduce the load balancing functionality for the Crystal Web Service which enhances the performance and bypass some limitations in multithreaded usage of Crystal Runtime. This guide explains how to configure multiple IFS Crystal Web Service instances in both approaches.
Disclaimer: Some screenshots and examples are with respect to Windows 2008 and IIS 7. The exact configuration depends on the specific environment.

Configuring CWS instances for different databases

The process of configuring the Crystal Web Service instances into different databases has a few manual steps when compared to installing copies to the same database. One should also note that in a different database approach, there is a risk of retrieving irrelevant and incorrect data in reports if all of those instances are configured to one application server. But this approach is useful when different Crystal Web Service instances should be used for different application servers in the same machine.
Follow the steps below,

1. Due to concept changes in the new track, the Crystal Web Service configuration file ifs-crystal-config.xml is not generated at the time of creating the IFS_HOME. It is only created when you install a Crystal Web Service after providing the necessary details. Due to this reason, one needs to do a dummy installation to get the correct configuration file. To do this, on a different machine, you need to do a dummy installation of the Crystal Web Service to get the required instance copy by providing the relevant details as you would normally install a Crystal Web Service. When installing you can leave the number of main installation replication copies blank or you can specify the number of copies you require. After backing up the copy/copies, you can uninstall the dummy installation.

2. Now copy the backed-up copy/copies of the Crystal Web Service to the "C:\Inetpub\wwwroot\" folder of the machine you want to configure the Crystal Web Service instances in. If you have got only one copy and wish to have multiple instances, then you need to duplicate the copy you have and provide unique names for the other replications. For example, if the copy name is IFSCRWebSetup, and you wish to have another instance, then it can be IFSCRWebSetup_B. This will be referred to as the Alias later in IIS.
   
   

   1. In IIS, select the Default Web Site connection listed under SERVER > Sites. RMB on it, and select "Add Application". (If IIS is already listing your newly created folder under "Default Web Site", then RMB on that and select "Convert to Application").

      
      
      

   2. In the appeared dialog, give an appropriate Alias (a name for the instance). Select the Application pool and then select the Physical path of the newly created folder IFSCRWebSetup_B and then click OK.
      

   
   
   

   ​

   1. Repeat steps 3 and 4 for all instance copies.

   2. In IIS, select “Default Web Site” and restart the site.

   ​

Configuring the System Parameters

One needs to configure some System Parameters for IFS to communicate with the Crystal Web Service. Namely these System Parameters are,

System Parameter Name	Description	Example
The machine name where the Crystal Web Service is installed	The machine name to be used when accessing Crystal Web Service is installed. The default value is *.	CMBGSEAPP4
The protocol of the Web Server where the Crystal Web Service is running	The protocol to be used when accessing the Crystal Web Service. Normally this is the IIS default protocol. The default value is HTTP.	http
The IIS port for the above mentioned Web Server	The port to be used when accessing the Crystal Web Service. Normally this is the IIS default port. The default value is 80.	80
The Virtual Directory name given to the Crystal Web Service in IIS	The Virtual Directory name be used when accessing the Crystal Web Service. This is the name one would specify when installing the Crystal Web Service. The default value is IFSCRWebSetup. Check here to find out how to define multiple web service instances.	IFSCRWebSetup
Specify if web database access security check is required	Specify if web database access security check is required when previewing/printing Quick Reports. The default value is 'NO'.	NO

Note: If you set YES to the web database access security system parameter then it's mandatory that you add the CR_WEB_INIT procedure in the CRYSTAL_WEB_UTIL_API package to your Crystal layout. Check the developer guidelines on how to [add the CR_WEB_INIT procedure to a layout.

Defining virtual directory for multiple web service instances

Update the System Parameter Virtual Directory names given to the Crystal Web Service instances in IIS, with adding the newly created instance alias, separated by a comma.

Once a report request is made, the request will be directed to the first web service instance in this list which is considered as the default web service (e.g. IFSCRWebSetup in the example), and if that instance failed to return a successive PDF, the request will be handed over to the next web service instance in this list. This functionality will be iterating until the report formatter gains a successful PDF.

Adhering to Network Policy

From IFS Cloud 23R1 onwards, network policies are enabled by default. Therefore you need to add the crystal web service machine IP address which needs to be included in the cloud values yaml file (ifscore.networkpolicy.crystalhost).

Known limitations

• If you perform multiple report requests to the same crystal web service simultaneously, you can get the Error in retrieving the saved PDF report from the Crystal Web Service exception. This limitation is due to an error in Crystal Runtime. This has been reported to the crystal runtime vendor. The issue is addressed by the LCS bug 104424.
• Users may identify a performance issue with delaying a report from rendering through the Crystal Web Service when it has some active long-running requests. This occurs since the Crystal runtime is limited to 3 CPLs (Concurrent Processing License) where it limits only three report requests to be processed at once, and a Maximum of 75 Jobs where each of the integrated resources in the report like the main reports, sub reports, and in-session report objects (e.g.; drill down, paging, searching, and more.) consumes a "crystal job". In a production environment, the above limitations could rarely happen.
  Related knowledge-based articles: CPLs, Job Processing Limit

Security Considerations

• Due to security considerations, the Crystal Web Service configuration stored in the ifs-crystal-config.xml file is split into two parts and is saved in two different locations.

The ifs-crystal-config.xml located in the Crystal Web Service instance folder will only contain the logging configuration details and the path to the other configuration file.

The rest of the configuration is saved in the IFS-CWS-Config-Dir folder which is located under C:\inetpub\wwwroot folder. A file with ifs-crystal-config-.xml (e.g. ifs-crystal-config-IFSCRWebSetup.xml) will hold the rest of the Crystal Web Service configuration details.

Command Line Installation

You You can install the Crystal Web Service through command line and install it through a script. The below table provides details on the parameters that needs to be passed as command line augments.

msiexec.exe /I IFSCRWebSetup.msi /l* IFSCRWebSetup.log
IFSPRINT=printpw
IFSSYS=syspw
TNS=GHDEPCMB
APPOWNER=IFSAPP
IALOWNER=IFSINFO
TARGETVDIR=IFSCRWebSetup
NUMVDIR=3
LAYOUTLOC=C:\ReportLayouts
LOGS=TRUE
LOGLEVEL=HIGH
LOGFILENAME=C:\test.log
FROMSCRIPT=TRUE /quiet

Parameter	Description
IFSPRINT	The IFSPRINT user password in plain text. It will be encrypted when written to the configuration file.
IFSSYS	The IFSSYS user password in plain text. It will be encrypted when written to the configuration file.
TNS	The Oracle TNS entry name specified in the tnsnames.ora file pointing to the database which the Crystal Web Service connects to.
APPOWNER	Application Owner User.
IALOWNDER	IAL Owner User .
TARGETVDIR	The main Crystal Web Service instance name. Some special considerations are made if the FROMSCRIPT is TRUE. This will be taken as the virtual directory in IIS.
NUMVDIR	The number of instances to be replicated of the main instance. Some special considerations are made if the FROMSCRIPT is TRUE.
LAYOUTLOC	The Crystal Report layout location .
LOGS	Enable logs. Values: TRUE or FALSE
LOGLEVEL	Log level. Values: LOW, MEDIUM or HIGH
LOGFILENAME	The log file name and path where the logs are to be written in to.
FROMSCRIPT	This parameter is used to manipulate the number of copies and the instance names in special installation scenarios. Values: TRUE or FALSE FALSE: No special considerations, the number of copies and the instance names will be as the same as you have would install them from the wizard. TRUE: Expects and assumes that you specify the main instance name with a "_1" suffix. e.g. IFSCRWebSetup_1. this will be treated as the main instance name. The number of copies will be counted as main instance plus extra copies. e.g. if number of copies are set to 3, you would end up with 3 instances and not 4 as you would get when this parameter is set to FALSE. For example, if you specify the TARGETVDIR as IFSCRWebSetup_1 and NUMVDIR as 3, then you will get 3 instances as IFSCRWebSetup_1, IFSCRWebSetup_2 and IFSCRWebSetup_3 where as IFSCRWebSetup_1 is the main instance and IFSCRWebSetup_2 and IFSCRWebSetup_3 are copies of the main instacne.