/tags/v4.9.2/ Recent content in v4.9.2 on Hugo -- gohugo.io /sicsdocs/technical/server/api_server/installation_guide/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/ /sicsdocs/technical/misc/memory_settings/introduction/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/introduction/ This document describes how you may change the memory settings of SICS. For most installations of SICS the standard settings are appropriate. Although the memory settings are carefully tailored to suite the memory usage of SICS, you may need to change them to fit a given SICS installation. Conditions that affect memory usage are data volumes, system settings and the functions and modules of SICS in use. /sicsdocs/technical/server/api_server/server_security/introduction/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/introduction/ SICS API Server is a software component in the SICS product suite. SICS API Server implements the Web Services that allows external applications to call/invoke SICS functions. This document describes the Security features that SICS API Server supports. What this document covers # Security feature Description Authentication How to get SICS API Server to authenticate the sender of Web Services calls. Authorization How to get SICS API Server to check whether a user has the authority (Access Rights) to invoke a web service, and to perform the business logic that is re-used from the SICS on-line system. /sicsdocs/technical/server/api_server/technical_paper/introduction/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/technical_paper/introduction/ SICS API Server is a non-mandatory component in the SICS software package. SICS API Server is a “headless” component that implements Web Services to common SICS functions, allowing other applications, components or front-ends to call SICS business processes directly or via a Services-oriented Architecture (SOA) implementation. This document describes the design of SICS API Server. It explains the basic architecture and important properties. For a full description of the supported Web Services, including WSDL/XSD files and sample SOAP messages, please refer to the documentation that is available after installing SICS API Server. /sicsdocs/technical/server/api_server/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/ /sicsdocs/technical/misc/hw_and_sw_requirements/sics_hardware_requirements/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/hw_and_sw_requirements/sics_hardware_requirements/ End-User PC # The requirements described here, are valid for an end-user who performs normal online (GUI) related tasks and who has SICS Workstation and/or System Administration Utility installed on his own PC. For centralized operation, please see the section on Remote Desktop Operation. For heavy processing, please see the section on SICS Batch Server. For interfacing via the SOAP/XML-based API, please see the section on SICS API Server. /sicsdocs/technical/misc/memory_settings/background/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/background/ SICS is programmed in Java. The SICS programs are compiled into so-called Java byte code format. The SICS Java byte codes are grouped into a number of compressed files called jars. These jars constitute the main part of a SICS installation. In order to run SICS, one must start a Java Virtual Machine (JVM), a computer program in its own right, and tell it where the Java byte code for SICS is stored, i. /sicsdocs/technical/server/api_server/technical_paper/concepts/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/technical_paper/concepts/ Overall description # SICS API Server provides access to SICS functionality through Web Services. Web Services is an industry accepted standard for application interoperability. SICS API Server enables the use of SICS as server component in a number of scenarios: Calling SICS functions from other applications, e.g. to request information from the SICS database (for example retrieving information for a business); perform an operation using SICS logic (for example exchanging a monetary amount using SICS’s exchange rates and rules, create a business or renew a business). /sicsdocs/technical/server/api_server/server_security/security_parameters/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/security_parameters/ Three parameters determine ‘Secure’ and ‘Non-Secure’ Modes of SICS API Server Start-up. The parameters act as overall switches for the authentication and authorization security functions. The parameters are found in the web.xml file. If SICS API Server is installed as described in SICS API Server - Installation Guide, this file can be found (for Tomcat 10.x) in: %CATALINA_HOME%/webapps/SicsServer/WEB-INF/web.xml. The parameters are: Parameter name Valid values Default Purpose web.xml ApplyServerSecurity true/false false Indicates whether SICS API Server is running in secure mode or not. /sicsdocs/technical/server/api_server/server_security/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/ /sicsdocs/technical/misc/hw_and_sw_requirements/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/hw_and_sw_requirements/ /sicsdocs/technical/server/api_server/server_security/authentication/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/authentication/ If SICS API Server is started in secure mode, all normal Web Services calls must include an authentication token. The caller must obtain this token by sending an initial “login” message to SICS API Server. The Login service # Sample SOAP Request and Response # The SOAP request (input message) for the login service must follow one of these formats (see discussion on OS AUTHENTICATION and <sicsUserId> further down): <SOAP-ENV:Envelope . /sicsdocs/technical/server/api_server/installation_guide/configure_api_server_for_tomcat_deployment/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/configure_api_server_for_tomcat_deployment/ SICS API Server is delivered as a web application. Web applications are packaged as files with extension .war. The war file is in fact a zipped archive file. The contents may be viewed with a zip application such as WinZip. Any configuration setting done prior to deploying SICS API Server, must therefore be done in the war file. For instance, WinZip allows the user to edit text files from the archive with Notepad or another external editor. /sicsdocs/technical/misc/memory_settings/determine_java_version/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/determine_java_version/ The Java version being used can be determined as follows: In Help->About SICS, go to System Info. Select the Java tab The properties java.version and java.runtime.version specifies the Java version. The property sun.arch.data.model specifies if the SICS is 64 or 32 bit. Note that this version of SICS requires 64-bit Java 21+. /sicsdocs/technical/server/api_server/technical_paper/features/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/technical_paper/features/ Stateless # SICS API Server is designed to operate in a stateless manner. In other words, each SOAP call must contain the data that is necessary for SICS API Server to fully process the SICS business function. Parts of the data may consist of references to data that already exist in the SICS operational database. Commit / Rollback / Unit of Work # Each SOAP call to the SICS API Server will either succeed 100% or fail completely. /sicsdocs/technical/misc/memory_settings/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/ /sicsdocs/technical/server/api_server/technical_paper/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/technical_paper/ /sicsdocs/technical/server/api_server/server_security/authorization/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/authorization/ Authorization is the process of ensuring that the caller invokes services that the caller is allowed to execute, according to the caller’s SICS user profile. When receiving a service call request, SICS API Server verifies whether the SICS user identified by the “User ID” (present in the Authentication Token) has Access Rights to execute the service, according to the (existing) security set-up defined via the SICS System Administration utility. See also SICS API Server - Installation Guide, on how to set up your own authorization policy. /sicsdocs/technical/server/api_server/installation_guide/configure_tomcat_for_api_server_deployment/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/configure_tomcat_for_api_server_deployment/ Memory Setting # SICS API Server is a memory intensive application and the standard Java VM settings are not sufficient. To avoid out of memory error messages like: java.lang.OutOfMemoryError. Do the following: Ensure Tomcat is not running Start (double-click) the %CATALINA_HOME%\bin\tomcat9w.exe program You will then see a window like this: Figure 1 - Apache Tomcat Windows Service Properties Go to the “Java” tab and at the bottom at the “Java Options:” field and add the following parameters: Set the Initial memory pool 512 MB and Maximum memory pool 1024 MB. /sicsdocs/technical/server/api_server/technical_paper/deployment/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/technical_paper/deployment/ This section briefly explains the hardware and software required for installing and running the SICS API Server component. It is assumed that there already exists a SICS database that the SICS API Server will work against. Hardware Requirements # The SICS API Server component runs inside a Java servlet container. Such containers are available for many operating systems. One instance of SICS API Server requires at least 1 GB of memory running on a 64-bit operating system. /sicsdocs/technical/misc/memory_settings/standard_settings/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/standard_settings/ The use of SICS functions obviously varies from user to user and from one SICS session to another. Likewise, the amount of data being processed varies from user to user and from one SICS session to another. Therefore, it is not possible to pre-set the heap memory size in such a way that, the JVM never runs out of memory, and there is no gross over-allocation of memory. The best one can do, is to pre-set the memory limits such that /sicsdocs/technical/server/api_server/installation_guide/deploy_api_server_to_java_servlet_container/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/deploy_api_server_to_java_servlet_container/ The way to deploy war files differ from the various Java Servlet Containers. The following describe how to do it on Apache Tomcat 10.1.40. https://tomcat.apache.org/tomcat-10.1-doc/index.html Ensure Tomcat is running Open the Tomcat Web Application Manager in a browser. If you have installed it locally on port 8080 the address is: http://localhost:8080/manager/html (or click on the link Tomcat Manager in the Tomcat start page (http://localhost:8080): (You must log in with the username and password set when installed Tomcat) /sicsdocs/technical/server/api_server/server_security/enable_api_server_module/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/enable_api_server_module/ To enable the API Server module, check the API Server module in use checkbox in System Parameter Maintenance -> Module Key. Figure 1 - Module Keys System Parameter /sicsdocs/technical/misc/memory_settings/identifying_memory_problems/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/identifying_memory_problems/ If SICS terminates (abends) with an error message and one of the first lines of the walkback file is: ... java.lang.OutOfMemoryError: Java heap space ... then you have a heap memory problem. Examples of situations when such an error can occur are: Batch processing Long running task, e.g. accounting orders and periodic functions Reading large amounts of data from the SICS database, for instance, asking the Business Partner Ledger to return more than a few thousand balances. /sicsdocs/technical/misc/memory_settings/changing_memory_settings/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/misc/memory_settings/changing_memory_settings/ If you identified a memory problem as described in section 4, you may solve the problem by increasing the appropriate maximum memory size parameter. If you use the standard SICS setup, the Java command line parameters are located in the command files: run_sics_workstation.bat and run_sics_sysadmin.bat. Edit the relevant file and increase the -Xmx value. If you use the SICS Launcher setup the JRE command line parameters are located in the SICSJavaLauncher. /sicsdocs/technical/server/api_server/installation_guide/configure_api_server_environment/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/configure_api_server_environment/ Required knowledge # Most SICS API Server configuration is specified using XML files. You should be familiar with syntax rules for well formed XML, and be able to comment and uncomment XML fragments. Suggested configuration order # Configure logging Configure security Configure system pool size Configure queue sizes Configure caching of data Configure xml files Configure HTTP return codes Configure logging # Turn on/off Separate Logging of SOAP Messages # The default installation of SICS API Server logs SOAP messages to a separate log. /sicsdocs/technical/server/api_server/server_security/web_services_use_cases/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/server_security/web_services_use_cases/ Use Case security # Each Web Service is defined as a “Use Case” in the SICS Security module. This means that it is possible to “switch off” each of the Web Services that your company do not use, by simply removing the unused Use Cases from the security profiles. Naming convention # All Web Services Use Cases are named with the “API” (Application Programming Interface) prefix, to easily separate them from the normal SICS Workstation Use Cases. /sicsdocs/technical/server/api_server/installation_guide/verify/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/verify/ Verify SICS API Server startup using the SICS API Server Management console # SICS API Server comes with a rudimentary management console which can be found at: http://<Tomcat-installation:port>/SicsServer/SicsServerManagementConsole and looks like this: When SICS API Server is ready to process SOAP messages the status will be “Running and ready since date/time and the flag will be green: Figure 9 - SICS API Server Management Console Green Status Verify SICS API Server startup by inspecting the log files # SICS API Server writes important startup messages to the SicsServer. /sicsdocs/technical/server/api_server/installation_guide/monitoring_sics_server/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/monitoring_sics_server/ SICS API Server can process multiple messages concurrently. The SICS API Server management console is extended to show information of the SICS System pool: Figure 22 - SICS API Server Management Console Figure 23 - SICS API Server Management Console Status /sicsdocs/technical/server/api_server/installation_guide/multiple_instances/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/multiple_instances/ SICS API Server runs as a web application inside a Java Servlet Container (Tomcat, Websphere etc). How to scale SICS API Server capacity depends on the Java Servlet Container and other infrastructure constraints/possibilities. For different alternatives and guidelines on how to set this up, please refer to the Java Servlet Container provider documentation. For testing purposes, DXC has defined a setup using Tomcat and Apache. The description of this setup is provided below for information purposes, as an example of how Load Balancing can be achieved. /sicsdocs/technical/server/api_server/installation_guide/additional_information/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/additional_information/ Application managed database connection # Complete the following steps to set up application managed connections to the database. Define and test a database connection in the file sics-database-sources.xml used by SICS workstation. On success, copy the connection entry to file %CATALINA_HOME%/webapps/SicsServer/WEB-INF/classes/sics-database-sources.xml Copy the required JDBC jar(s) into %CATALINA_HOME%/webapps/SicsServer/WEB-INF/lib (similar to the same step for 3.1 “Configure database connection”) Uncomment and specify the following servlet init-parameters in %CATALINA_HOME%/webapps/SicsServer/WEB-INF/web.xml: Parameter Description Required DATABASE The name attribute of the connection specified in %CATALINA_HOME%/webapps/SicsServer/WEB-INF/classes/sics-database-sources. /sicsdocs/technical/server/api_server/installation_guide/appendix_a/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/appendix_a/ Required knowledge # This is not an introduction to IBM WebSphere Liberty administration, the user must as a minimum know how to: Open and log into the Admin Center. Create a JDBC data source and install JDBC drivers Create JDBC login credentials Install an Enterprise Application Refer to official IBM WebSphere Liberty documentation and support for assistance. WAS Liberty Memory Parameters # Default JVM memory parameters must be changed. This can be done by creating a file named jvm. /sicsdocs/technical/server/api_server/installation_guide/appendix_b/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/appendix_b/ Two-level login is supported when using ‘application managed’ database connection. This is how it works: The user name and password for the first-level ’technical user’ is provided in a configuration text file which is read by SICS SICS will connect to the database using the technical user name and password SICS reads the corresponding SICS User Object from the CNU_USER table SICS detects that the SICS User Object contains a second-level name and password SICS disconnects from the database SICS connects (once more) to the database using the second-level name and password from the SICS User Object This connection is used for all later access and updates to the database In other words, when using application managed login, the db connection is under control by the application, i. /sicsdocs/technical/server/api_server/installation_guide/appendix_c/ Mon, 01 Jan 0001 00:00:00 +0000 /sicsdocs/technical/server/api_server/installation_guide/appendix_c/ It is possible to run Tomcat without installing it as a Windows service. This section briefly explains a few differences from the ‘Tomcat installed as a Windows service’ procedure described above. Download and Unzip Tomcat # Download the Tomcat zip file and unzip to some folder. Hereafter, the alias TOMCAT refers to the folder where Tomcat is unzipped. Java setup # Install the 64-bit Java Development Kit 21 (JDK 21) or later as described above.