Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
712:configure_stages [2025/11/10 11:02] – [AI Feature Configuration: How to create Azure OpenAI services] Linz, Andreas712:configure_stages [2026/02/13 14:11] (current) – Prinz, Patrick
Line 60: Line 60:
 | ''$STAGES_CONF/log4j-customer.xml'' | Customisation of logging |  **✘**  | | ''$STAGES_CONF/log4j-customer.xml'' | Customisation of logging |  **✘**  |
 | [[#Licenses|Stages license files]] ||| | [[#Licenses|Stages license files]] |||
-| ''$STAGES_CONF/license.xml'' |  |  **✘**  | +| ''$STAGES_CONF/license.xml'' |   |  **✘**  | 
-| ''$STAGES_CONF/signature.xml''  |  |  **✘**  | +| ''$STAGES_CONF/signature.xml''  |   |  **✘**  | 
-| ''$STAGES_CONF/licences'' |  |  **✘**  |+| ''$STAGES_CONF/licences'' |   |  **✘**  |
 | [[#configuring-tlsssl-certificate|Certificates]] ||| | [[#configuring-tlsssl-certificate|Certificates]] |||
-| ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |  |  **✘**  |+| ''$STAGES_CONF/*.crt'' \\ ''$STAGES_CONF/*.p12'' \\ ''$STAGES_CONF/*.jks'' |   |  **✘**  |
 | [[kerberos_autologin|Kerberos SSO]] ||| | [[kerberos_autologin|Kerberos SSO]] |||
-| ''$STAGES_CONF/jaas.conf'' |  |  **✘**  | +| ''$STAGES_CONF/jaas.conf'' |   |  **✘**  | 
-| ''$STAGES_CONF/*.keytab'' |  |  **✘**  |+| ''$STAGES_CONF/*.keytab'' |   |  **✘**  |
 | ''$STAGES_CONF/krb5.conf'' |   |  **✔**  | | ''$STAGES_CONF/krb5.conf'' |   |  **✔**  |
 | Metamodels and customisations ||| | Metamodels and customisations |||
Line 82: Line 82:
 **Windows:** **Windows:**
  
-<code>+<code ->
 net stop stages net stop stages
 $STAGES_ROOT\bin\update.bat $STAGES_ROOT\bin\update.bat
Line 89: Line 89:
  
 **Linux:** **Linux:**
-<code>+ 
 +<code ->
 stages reload stages reload
 </code> </code>
Line 140: Line 141:
     <property name="name.of.property" value="value.of.property"/>     <property name="name.of.property" value="value.of.property"/>
 </properties> </properties>
- 
 </code> </code>
  
Line 150: Line 150:
  
   * Windows:   * Windows:
-      * Open file "$STAGES_ROOT\config.bat" +    * Open file "$STAGES_ROOT\config.bat" 
-      * Modify the setting: //set TOMCAT_OPTS=–JvmMx=<RAM in MB>// +    * Modify the setting: //set TOMCAT_OPTS=–JvmMx=<RAM in MB>// 
-      * Open a cmd with administrative permissions and navigate to folder "$STAGES_ROOT\stages\bin" +    * Open a cmd with administrative permissions and navigate to folder "$STAGES_ROOT\stages\bin" 
-      * Reinstall the Stages service: **reinstallService.bat** +    * Reinstall the Stages service: **reinstallService.bat** 
-      * Restart Stages service: **net start stages**+    * Restart Stages service: **net start stages**
   * Linux:   * Linux:
-      * Open file "$STAGES_ROOT/bin/rc.conf" +    * Open file "$STAGES_ROOT/bin/rc.conf" 
-      * Modify the value: //CONF_TOMCAT_OPTS="-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow"// +    * Modify the value: //CONF_TOMCAT_OPTS="-Xmx<RAM in MB>m -XX:+UseG1GC -XX_-OmitStackTraceInFastThrow"// 
-      * Restart the Stages service:** stages restart**+    * Restart the Stages service:** stages restart**
  
 You can configure additional Java start parameter for Stages that are listed below: You can configure additional Java start parameter for Stages that are listed below:
Line 164: Line 164:
   * -Xmx (Max memory pool): 4048 MB   * -Xmx (Max memory pool): 4048 MB
   * -Xms (Initial memory pool): 4048 MB   * -Xms (Initial memory pool): 4048 MB
- +
 ==== Java Garbage Collection Strategies ==== ==== Java Garbage Collection Strategies ====
  
Line 171: Line 171:
 ==== Configuring the TCP Ports ==== ==== Configuring the TCP Ports ====
  
-Stages comes with HTTPS configured by default. +Stages comes with HTTPS configured by default. The server.xml for new installations looks as follows: [[server.xml]]
-The server.xml for new installations looks as follows: [[server.xml]]+
  
 Stages is started on TCP/IP port 80, 443 and 8085 and enforces usage of HTTPS by default. Thus, it can be accessed via the URL [[https://<servername>|https://<servername>]]. To use a different port or [[#configuration-for-usage-with-reverse-proxy|delegate HTTPS termination to a reverse proxy]] like Apache HTTP server or Nginx, change the respective lines in the Tomcat configuration file named ''$STAGES_CONF/server.xml''. Stages is started on TCP/IP port 80, 443 and 8085 and enforces usage of HTTPS by default. Thus, it can be accessed via the URL [[https://<servername>|https://<servername>]]. To use a different port or [[#configuration-for-usage-with-reverse-proxy|delegate HTTPS termination to a reverse proxy]] like Apache HTTP server or Nginx, change the respective lines in the Tomcat configuration file named ''$STAGES_CONF/server.xml''.
Line 231: Line 230:
  
 Please configure the Stages hostname as it is used by the end users in ''$STAGES_CONF/config.properties'' as ''general.external.hostname'', e.g. Please configure the Stages hostname as it is used by the end users in ''$STAGES_CONF/config.properties'' as ''general.external.hostname'', e.g.
 +
 <code properties> <code properties>
 general.external.hostname = stages.example.com general.external.hostname = stages.example.com
Line 242: Line 242:
  
 Stages comes with a self signed certificate for [[https://stages.localhost]]. Of course this needs to be replaced by your own certificate for production use. Stages comes with a self signed certificate for [[https://stages.localhost]]. Of course this needs to be replaced by your own certificate for production use.
 +
   * Register a DNS alias for the server, e.g. “stages.company.com”   * Register a DNS alias for the server, e.g. “stages.company.com”
-  * Apply for a TLS/SSL certificate for the server which refers to the above alias. Depending on your local procedures, this might require creating a certificate request (e.g. see https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm for more info).+  * Apply for a TLS/SSL certificate for the server which refers to the above alias. Depending on your local procedures, this might require creating a certificate request (e.g. see [[https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm]] for more info).
   * Store your PKCS#12 (requires JDK 8u301 or newer) or JKS keystore file in ''$STAGES_CONF'' directory and adapt the following configuration properties accordingly:   * Store your PKCS#12 (requires JDK 8u301 or newer) or JKS keystore file in ''$STAGES_CONF'' directory and adapt the following configuration properties accordingly:
  
 ''$STAGES_CONF/config.properties'' ''$STAGES_CONF/config.properties''
 +
 <code properties> <code properties>
 general.external.hostname = stages.example.com general.external.hostname = stages.example.com
 general.keystore.path = conf/stages-self-signed-keystore.p12 general.keystore.path = conf/stages-self-signed-keystore.p12
 </code> </code>
 +
 ''$STAGES_CONF/secret.properties'' ''$STAGES_CONF/secret.properties''
 +
 <code properties> <code properties>
 general.keystore.keyAlias = stages general.keystore.keyAlias = stages
Line 258: Line 262:
  
 [[#apply-configuration-changes|Apply the configuration changes]] [[#apply-configuration-changes|Apply the configuration changes]]
 +
 ==== Configuration for usage with Reverse Proxy ==== ==== Configuration for usage with Reverse Proxy ====
  
Line 263: Line 268:
  
 E.g. E.g.
 +
 <code xml> <code xml>
 <Connector port="8081" <Connector port="8081"
Line 284: Line 290:
     </Connector>     </Connector>
 </code> </code>
 +
 or for AJP or for AJP
 +
 <code xml> <code xml>
 <Connector protocol="AJP/1.3" <Connector protocol="AJP/1.3"
Line 293: Line 301:
                />                />
 </code> </code>
-In case the reverse proxy runs on a separate machine replace the address attribute by ''address="0.0.0.0"'' or ''address="::"'' and additionally apply IP filters on operation system level to ensure the port is only reachable from the reverse proxy.  + 
-Please also make sure websocket connections (''ws:'') are forwarded by your reverse proxy.+In case the reverse proxy runs on a separate machine replace the address attribute by ''address="0.0.0.0"'' or ''address="::"'' and additionally apply IP filters on operation system level to ensure the port is only reachable from the reverse proxy.  Please also make sure websocket connections (''ws:'') are forwarded by your reverse proxy.
  
 Here is an example for Apache HTTP server configuration using an HTTP connector for Stages on port 8081: Here is an example for Apache HTTP server configuration using an HTTP connector for Stages on port 8081:
-<code>+ 
 +<code ->
 <VirtualHost *:443> <VirtualHost *:443>
 ServerName {{ general_external_hostname }} ServerName {{ general_external_hostname }}
Line 326: Line 335:
  
 Please ensure the following properties are configured in ''$STAGES_ROOT\config.bat'' Please ensure the following properties are configured in ''$STAGES_ROOT\config.bat''
-<code>+ 
 +<code ->
 set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL set JAVA_OPTS=[...] -Djavax.net.ssl.trustStoreType=Windows-ROOT -Djavax.net.ssl.trustStore=NUL
 </code> </code>
 +
 This is the default for new installations of Stages 7.10.5.0 or newer. This is the default for new installations of Stages 7.10.5.0 or newer.
  
Line 334: Line 345:
  
 Please ensure to use the proper ''update-ca-trust'' or respective script of your distribution, that should ensure to copy the certificates to the system and the JAVA truststore. Please ensure to use the proper ''update-ca-trust'' or respective script of your distribution, that should ensure to copy the certificates to the system and the JAVA truststore.
- 
  
 ===== Licenses ===== ===== Licenses =====
Line 346: Line 356:
   * An email with all the necessary information will be opening    * An email with all the necessary information will be opening 
   * Send the email to the Stages Customer Care team   * Send the email to the Stages Customer Care team
- 
  
 ===== Local Message Customization ===== ===== Local Message Customization =====
Line 377: Line 386:
  
 ===== AI Feature Configuration: Chatbot Assistant and Content Generation ===== ===== AI Feature Configuration: Chatbot Assistant and Content Generation =====
 +
 To activate the AI chatbot and the content generation feature in Stages, the following steps are required. **The content generation feature needs to be configured to use the chatbot feature. The chatbot feature configuration is arbitrary - the content generation feature can be used without the chatbot feature.** To activate the AI chatbot and the content generation feature in Stages, the following steps are required. **The content generation feature needs to be configured to use the chatbot feature. The chatbot feature configuration is arbitrary - the content generation feature can be used without the chatbot feature.**
 +
 ==== Stages version ==== ==== Stages version ====
 +
 The chatbot will only work with Stages v7.12 or higher. The content generation feature works with Stages v7.11 or higher. The chatbot will only work with Stages v7.12 or higher. The content generation feature works with Stages v7.11 or higher.
- 
- 
  
 ==== Metamodel ==== ==== Metamodel ====
  
-A new unified configuration metamodel for Stages v7.12 / v.7.11 is required to support the AI features. Please contact [[stages-support@ul.com]] for further metamodel update instructions - depending on your Stages version and server operating system. If you use a customized metamodel, please contact your Stages product consultant to extend your metamodel. +A new unified configuration metamodel for Stages v7.12 / v.7.11 is required to support the AI features. Please contact [[stages-support@ul.com]] for further metamodel update instructions - depending on your Stages version and server operating system. If you use a customized metamodel, please contact your Stages product consultant to extend your metamodel.
  
 ==== User permissions ==== ==== User permissions ====
 +
 Depending on the activities performed by the Stages user with the chatbot assistant - the following user permissions are required: Depending on the activities performed by the Stages user with the chatbot assistant - the following user permissions are required:
 +
   * Use chatbot assistant:    * Use chatbot assistant: 
-      * Permission Domain Chatbot > Permission: Read +    * Permission Domain Chatbot > Permission: Read 
-      * Permission Domain Workspace > Permission Read+    * Permission Domain Workspace > Permission Read
   * Configure chatbot assistant:   * Configure chatbot assistant:
-      * Permission Domain AI Administration > Permissions: RCMD +    * Permission Domain AI Administration > Permissions: RCMD 
-      * Permission Domain Workspace > Permission: Read+    * Permission Domain Workspace > Permission: Read
  
 ==== Modify config.xml settings ==== ==== Modify config.xml settings ====
 +
 Please add the following section to your file config.xml. Please add the following section to your file config.xml.
 +
   * Default file path on windows server: /methodpark/stages/conf/config.xml   * Default file path on windows server: /methodpark/stages/conf/config.xml
   * Default file path on linux server: /opt/stages/conf/config.xml   * Default file path on linux server: /opt/stages/conf/config.xml
 +
 AI Chatbot Assistant feature: AI Chatbot Assistant feature:
 +
 <code xml> <code xml>
 <chatbot> <chatbot>
Line 468: Line 484:
 </chatbot> </chatbot>
 </code> </code>
 +
 AI Content Generation feature: AI Content Generation feature:
 +
 <code xml> <code xml>
 <cg> <cg>
Line 505: Line 523:
             <cg-property name="isEmbeddingModel" value="true"/>             <cg-property name="isEmbeddingModel" value="true"/>
         </cg-host>         </cg-host>
 +    </cg-type>
 +</cg>
 +</code>
 +
 +AI translate feature configuration:
 +
 +**Version**
 +
 +The API of the AI Translator has the version 3.0 and will be set like following: <cg-property name="version" value="3.0"/>
 +
 +**Request Type**
 +
 +The request type differs depending on the type of connection you’re using to the service.
 +
 +__For globally accessible services the configuration is:__ ''<cg-property name="request_type" value="translate"/>''
 +
 +__For virtual network access (mind the v in front of 3.0):__ ''<cg-property name="request_type" value="translator/text/v3.0/translate"/>''
 +
 +**Region**
 +
 +The region is an optional header. If the region property is not set, the translate service requests a translation from the closest available data centre. As we provide our services in Europe and USA only, there are just a few possible combinations for our configuration. ''<cg-property name="region" value="eastus"/>''
 +
 +<code ->
 +<cg>
 +    <cg-type name="other_systems_go_here">
     </cg-type>     </cg-type>
     <cg-type name="microsoftTranslateService">     <cg-type name="microsoftTranslateService">
Line 513: Line 556:
             <cg-property name="version" value="3.0"/>             <cg-property name="version" value="3.0"/>
             <cg-property name="request_type" value="translate"/>             <cg-property name="request_type" value="translate"/>
 +            <!-- if using a virtual network configuration the request type has to be like following -->
 +            <!-- <cg-property name="request_type" value="translator/text/v3.0/translate"/> -->
         </cg-host>         </cg-host>
     </cg-type>     </cg-type>
 </cg> </cg>
 </code> </code>
- 
  
 ==== Modify secret.properties settings ==== ==== Modify secret.properties settings ====
-Please add the following section to your secret.properties file and replace the url and key values with your personal Azure AI subscription data. Details on the subscriptions required can be found here: [[712:ai_privacy|]] + 
 +Please add the following section to your secret.properties file and replace the url and key values with your personal Azure AI subscription data. Details on the subscriptions required can be found here: [[712:ai_privacy]] 
   * Default file path on windows server: /methodpark/stages/conf/secret.properties   * Default file path on windows server: /methodpark/stages/conf/secret.properties
   * Default file path on linux server: /opt/stages/conf/secret.properties   * Default file path on linux server: /opt/stages/conf/secret.properties
Line 530: Line 576:
   ai.translateservice.url = [azure_translate_service_url]   ai.translateservice.url = [azure_translate_service_url]
   ai.translateservice.key = [azure_translate_service_key]   ai.translateservice.key = [azure_translate_service_key]
-  +
 If you use Stages as managed service and you don't have an own AI subscription, please contact UL for an subscription offer. If you use Stages as managed service and you don't have an own AI subscription, please contact UL for an subscription offer.
  
-     
-     
 ==== Restart Stages service ==== ==== Restart Stages service ====
 +
 To make all above changes take effect - finally please restart the Stages service. To make all above changes take effect - finally please restart the Stages service.
- 
  
 ===== AI Feature Configuration: How to create Azure OpenAI services ===== ===== AI Feature Configuration: How to create Azure OpenAI services =====
-1. Login to Azure-Management-Portal and navigate to "Azure OpenAI" service:\\ \\  + 
-{{ :712:create_azure_openai_services_01.jpg?direct&400 |}}\\  +1. Login to Azure-Management-Portal and navigate to "Azure OpenAI" service:\\ \\  {{ :712:create_azure_openai_services_01.jpg?400&direct }}\\  2. Create a new service within the OpenAI service:\\ \\  {{ :712:create_azure_openai_services_02.jpg?400&direct }}\\  3. Define basic information for the resource - e.g. select region:\\ \\  {{ :712:create_azure_openai_services_03.jpg?400&direct }}\\  4. Create resource: click "Create":\\ \\  {{ :712:create_azure_openai_services_04.jpg?400&direct }}\\  5. Select resource and navigate to "AI Foundry portal". Required AI models need to be configured here:\\ \\  {{ :712:create_azure_openai_services_05.jpg?400&direct }}\\  6. Within "AI foundry portal" these three models need to be deployed:\\ \\  {{ :712:create_azure_openai_services_06.jpg?400&direct }}\\  {{ :712:create_azure_openai_services_07.jpg?400&direct }}\\  7. Within the resource navigate to "Keys and Endpoints":\\ \\  {{ :712:create_azure_openai_services_08.jpg?200&direct }}\\  8. Here the required access data for Stages can be exported (URL, Key):\\ \\  {{ :712:create_azure_openai_services_09.jpg?400&direct }}\\  9. Afterwards create another resource for the translator-services:\\ \\  {{ :712:create_azure_openai_services_10.jpg?400&direct }}\\  {{ :712:create_azure_openai_services_11.jpg?400&direct }}\\  10. Define name and region:\\ \\  {{ :712:create_azure_openai_services_12.jpg?400&direct }}\\  11. Leave system-identitiy-switch turned "off":\\ \\  {{ :712:create_azure_openai_services_13.jpg?400&direct }}\\  12. Create resource: click "Create":\\ \\  {{ :712:create_azure_openai_services_14.jpg?400&direct }}\\  13. Export Stages access data (Key, Endpoint):\\ \\  {{ :712:create_azure_openai_services_15.jpg?400&direct }}\\  How to test if given credentials work? Please execute the command below in a command shell on the server that Stages is installed on: 
-2. Create a new service within the OpenAI service: + 
-{{ :712:create_azure_openai_services_02.jpg?direct&400 |}} +  curl -X POST 'https://openai-methodpark-prod-msc-plc.openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview' -H 'Content-Type: application/json' -H 'api-key: xxxxxxx' -d '{ "messages": [ { "role": "user", "content": "Hello" } ], "max_tokens": 1 }' 
-3. Define basic information for the resource - e.g. select region: + 
-{{ :712:create_azure_openai_services_03.jpg?direct&400 |}} +===== AI Feature Proxy Configuration: How to use HTTP proxies with AI Ressources ===== 
-4. Create resource: click "Create": + 
-{{ :712:create_azure_openai_services_04.jpg?direct&400 |}} +To use a proxy for connecting to ai ressources, the following configuration has to be added to the conf/config.xml file 
-5. Select resource and navigate to "AI Foundry portal". Required AI models need to be configured here: + 
-{{ :712:create_azure_openai_services_05.jpg?direct&400 |}} +>__! This has been introduced with Stages 7.12.4.1 !__ 
-6. Within "AI foundry portal" these three models need to be deployed: + 
-{{ :712:create_azure_openai_services_06.jpg?direct&400 |}} +<code -> 
-{{ :712:create_azure_openai_services_07.jpg?direct&400 |}} +<proxies> 
-7. Within the resource navigate to "Keys and Endpoints": +  <proxy-host ident="<proxy_ident>" hostName="<proxy_host>" port="<the_port_the_proxy_listens_on>"> 
-{{ :712:create_azure_openai_services_08.jpg?direct&200 |}} +  <!-- if required by the proxy, username and password can be provided --> 
-8. Here the required access data for Stages can be exported (URL, Key): +    <proxy-property name="username" value="<username>"/> 
-{{ :712:create_azure_openai_services_09.jpg?direct&400 |}} +    <proxy-property name="password" value="<password>"/> 
-9. Afterwards create another resource for the translator-services: +  </proxy-host> 
-{{ :712:create_azure_openai_services_10.jpg?direct&400 |}} +</proxies> 
-{{ :712:create_azure_openai_services_11.jpg?direct&400 |}} +</code> 
-10. Define name and region: + 
-{{ :712:create_azure_openai_services_12.jpg?direct&400 |}} +To use the proxy configuration with the Stages AI configuration the proxy property has to be added to the cg-hosts like following: 
-11. Leave system-identitiy-switch turned "off": + 
-{{ :712:create_azure_openai_services_13.jpg?direct&400 |}} +<code -> 
-12. Create resource: click "Create": +<cg-host ident="chatModel" url="${ai.model.url}" displayName="dummy_display_name"> 
-{{ :712:create_azure_openai_services_14.jpg?direct&400 |}} +  <cg-property name="user" ... /> 
-13. Export Stages access data (Key, Endpoint): +  <cg-property name="key" .../> 
-{{ :712:create_azure_openai_services_15.jpg?direct&400 |}}+  <cg-property name="deployment_name" ... /> 
 +   
 +  <cg-property name="proxy" value="<proxy_ident>" /> 
 +<cg-host/> 
 +</code> 
 +