Configure The Crystal Web Service¶
Both Quick Reports and Operational Reports of type Crystal Reports could be previewed and printed from IFS Cloud Web Client. Yet, there are some configuration parts one would have to carry out before using this feature. The following describes how you can install and setup the Crystal Report Web Service.
Installing and configuring Crystal Web Service¶
Local system Administrator account should be used for all the below configuration steps.¶
- CRYSTL component must be acquired and included in the build.
- Microsoft.Net Framework version 4 or later. You can download and install this from the Microsoft download site, http://www.microsoft.com/download
- Microsoft IIS 10 or higher.
Install “IIS 6 Management Compatibility” Role. Follow the steps given below to install it. Without this the Crystal Web Service installation will not run properly.
- From Windows go to Start\Administrative Tools\Server Manager
- Select the "Add roles and features" option
- On the "Server Roles" pane, scroll down to "IIS 6 Management Compatibility". Select all the check boxes underneath the node.
Next select the following Roles under Application Development. You will be prompt 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.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.
2. Next select Features and select the following under .net Framework 3.5 and .net Framework 4.7:
- .Net Framework 3.5 Features
- .Net Framework 3.5
- .NET Framework 4.7 Features
- .Net Framework 4.7
- ASP.NET 4.7
Next select the below server roles under Security
- Basic authentication
Note: In IIS version 6 the .Net Web Service Extensions are Prohibited by default. Make sure these Web Service Extensions are Allowed in the environment where the Crystal Web Service is installed. To allow 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.xxxxx Web Service Extension status are set to Allowed. If not, select these two extensions and click the Allow button to (or select Allow from the RMB menu) change the status to Allowed. 2. The final selection will look like below 3. Click Next then click "Install" at the "Confirm Installations Selections" pane. 4. After the installation finishes successfully click “Close” to leave the “Add Role Services” wizard. 5. Restart the machine which has the Crystal Web Service installed
- Oracle Runtime Client needs to be installed. The Oracle version should be a certified Oracle version. When installing keep in mind that the Oracle Client Runtime should be 64bit as the Crystal.Net runtime version is 64bit and it's a requirement that both should be in same bit version. Having mixed versions will cause database connection issues. An Oracle TNS entry should be specified in the tnsname.ora file which is pointing 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 2c when setting up the Crystal Web Service.
- After installing the Oracle Runtime Client make sure that that line SQLNET.AUTHENTICATION_SERVICES= (NTS) in <ORACLE_HOME>\network\admin\sqlnet.ora file is commented.
# SQLNET.AUTHENTICATION_SERVICES= (NTS)
- 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.
If all prerequisites are met, follow the steps below to install and configure the Crystal Web Service.
Create a folder in the machine where the Crystal Web Service is going to be installed and copy the Crystal Report files that are need to be in IFS Cloud Web to this folder. This folder will be referred to as the OpenReportPath later on in the installation process. If the reports are Operational Reports make a folder by the ordering language inside the "OpenReportPath" folder and copy the files in to that language folder. For example, if one is are going to order Operational reports with "en" language then create a folder called "en" inside the "OpenReportPath" folder and copy the Operational Report layout of type Crystal in to the "en" folder.
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.)
a. 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.
b. In the Database User Credentials step specify the IFSPRINT and IFSSYS passwords in plan text. The passwords will be encrypted and written in to the configuration file during the installation.
c. 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 6 in the prerequisites section.
d. 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: From IFS Cloud 22R1 onwards the Crystal Report layouts could be directly stored in the database. Report Layout Location field is kept for backward compatibility only
e. Select Next to start the installation.
f. 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
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 its running on ASP.NET v4.0 Application Pool.
Enabling Crystal Web Service logs¶
The Crystal Web Service Instances can be configured to write logs in different levels. The CR_Web_Log.exe which can be found in the Web Service instance folder could be used to configure logs for that particular instance. Once the logs are configured, you should make sure that the Windows security group IIS_IUSR has read, write and modify access the logging folder that you specify under "Log File Location".
Note: From IFS Cloud 22R1 onwards Crystal runtime logs can be accessed and managed through IFS Cloud Web client. It is recommended to use that functionality for accessing Crystal runtime logs. Refer Crystal Web Service logs for more details.
Main Instance Replication¶
When installing a Crystal Web Service, you can specify how many copies of the main instances that 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 takes some considerations in to account.
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.
All replicated copies have the same configurations details so that it points to the same database and use the same database credentials.
When replicating the installer will suffix a number to the main instance virtual directory name when creating and registering the virtual directories in IIS. For example, if the main instance name is IFSCRWebSetup and if 3 copies are requested, then the installer will create and register the copies in, then the installer will create and register the copies in IIS as IFSCRWebSetup_1, IFSCRWebSetup_2 and IFSCRWebSetup_3.
- 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.
How to check if the Crystal Web Service is running correctly?¶
- Open IIS Manager and right click on the Crystal Web Service instance and select Switch to content view.
- Right click on the Ifs_ReportService.asmx file and select Browse.
- This will open the specification of the web service in the browser displaying the list of operations available in the web service.
- Search for the operation called GetSavedReportA. Save a test crystal report with no connection to the database in the Report Layout Location specified in the installer. Provide the name of the sample report, the web user name and set the Secured Report Required parameter as False. 5. When the operation is invoked it should return a binary response. This indicates that the connection between the Crystal Web Service and crystal report works as expected. The next step is to setup IFS Cloud Web to communicate with the Crystal Web Service.
Configuring the System Parameters¶
One needs to configure some System Parameters in order 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 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 guide lines on how to add the CR_WEB_INIT procedure to a layout.
- 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 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 for 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
Crystal Web Service does not authenticate the requests sent to it. Therefore it relies on restrictions set by the infrastructure. So when setting up the Crystal Web Service, you should make sure that you have setup adequate security restrictions to prevent the access of the Crystal Web Service or send requests to the Crystal Web Service from outside and it only serve requests sent from the IFS Application Server that it's configured to handle requests from.
Due to security considerations the Crystal Web Service configuration stored in the ifs-crystal-config.xml file is not split in to two parts and 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:\inetput\wwwroot folder. A file with ifs-crystal-config-
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||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
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.
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.