MDWorkflow Installation Instructions
These instructions provide the customer with the necessary information to install and configure the MDCMS Workflow Web Application.
General Information
MDWorkflow is a web application that runs on an application server. The web application connects with a MDCMS database repository on an IBM i system, where the data and business logic for the application resides. Both the web application and MDCMS must be correctly installed before MDWorkflow can be used from the web.
(version 8.x)
Installation of core IBM i Libraries
Prerequisites
- An IBM i (AS/400, iSeries) system with IBM i OS version V7R2M0 or higher
- A valid MDCMS License
- A valid MDWorkflow + WebApp License
The Installation Steps
Use the MDINSSAVF command (see the MDCMS Installation Instructions for full details) and keep parameter “Incl. MDREP for Open/Workflow” (REP) set to *YES. The MDREP library is only necessary for the partition that the Web Application will connect to (unless MDOpen is also in use). However, the version of MDCMS on the other partitions should be the same as the repository partition.
Installation of Web Application directly on IBM i
Prerequisites
- A minimum JDK version of 8
- A minimum OS/400 version of V7R2M0
Install Apache Tomcat
If the preferred application server isn’t already installed on the IBM i, Midrange Dynamics provides version of Apache Tomcat that is pre-configured for use directly on IBM i. To install it, use the following steps:
- Download the SAVF for Tomcat from the MD Customer Area
- Extract the Save File from the ZIP file and copy to either IFS or a library on the partition where the server should be installed
- Use command MDCMS to go into the MDCMS menu
- Use F21 to get to a command line
- Enter command MDINSTOM and press F4
The Install Tomcat Server (MDINSTOM) command provides the ability to restore a Tomcat Application Server to IFS that is ready for use directly from the IBM i.
The included port and java parameters are automatically inserted into the configuration files for the server during installation.
If the IFS folder to contain Tomcat already exists, and REPL(*YES) is specified, the prior contents of the folder will be replaced with the contents for the save file.
If replacing a server, make certain that the prior server has ended before installing this server. Also make certain that the selected port numbers aren’t used by another process.
MDINSTOM has the following parameters:
| Parameter | Text | Description |
| PATH | Server Root Path | The IFS Path, including the root, to contain the Tomcat server |
| REPL | Replace Existing Directory | Specifies if the directory specified on the PATH parameter should be replaced if it already exists. |
| LTYP | Save File Location Type | Specifies if the Tomcat save file is in an IFS folder or in a library. |
| SAVP | IFS-Path containing Save File | Specifies the IFS path containing the save file used to install Tomcat. |
| SAVL | Library containing Save File | Specifies the Library containing the save file used to install the Tomcat Server. |
| SAVF | Save File name | Specifies the name of the save file containing the Tomcat Server. |
| JDKV | Java Version | Specifies the QOPENSYS version of Java to be used by the Tomcat Server. The version must be at least 8.0 and include the 32bit or 64bit subfolder. Use WRKLNK ‘/QOpenSys/QIBM/ProdData/JavaVM’ to see the installed JDKs on the system. The version can be changed in the future manually by editing file <tomcat>/bin/setclasspath.sh |
| HTPP | Tomcat HTTP Port | Specifies the port number that tomcat will listen on for HTTP requests. The port numbers can be changed in the future manually by editing file <tomcat>/conf/server.xml |
| AJPP | Tomcat AJP/1.3 Port | Specifies the port number that tomcat will listen on for requests forwarded by a web server. |
| REDP | Tomcat Redirect Port | Specifies the port number that tomcat will push requests to once they’ve arrived by HTTP or AJP. |
| SDNP | Tomcat Shutdown Port | Specifies the port number that tomcat will listen to for the request to shut down the server. |
Starting/Stopping Tomcat on the IBM i
The command to start tomcat is QSH CMD(‘<Server Root Path>/bin/startup.sh’)
The command to stop tomcat is QSH CMD(‘<Server Root Path>/bin/shutdown.sh’)
It is recommended to place the commands into scheduled jobs for automatic starting and stopping on a daily or weekly basis and/or placing the start command in the QSTRUP program for restart after an IPL.
Troubleshooting Tomcat
Tomcat writes log entries to files in folder <Server Root Path>/logs’)
Install MDWorkflow Web App
- Download the SAVF version of MDWorkflow from the MD Customer Area
- Extract the Save File from the ZIP file and copy to either IFS or a library on the partition where the application server resides
- Use command MDCMS to go into the MDCMS menu
- Use F21 to get to a command line
- Enter command MDINSWF and press F4
The Install MDWorkflow (MDINSWF) command provides the ability to restore the MDWorkflow web app directly to an application server on the IBM i.
If the IFS folder to contain the web app already exists, and REPL(*YES) is specified, the prior contents of the folder will be replaced with the contents for the save file.
Make certain that the server has ended before installing this web app.
MDINSWF has the following parameters:
| Parameter | Text | Description |
| PATH | Server Root Path | The IFS Path, including the root, where the MDWorkflow Web app should be located. |
| APP | Web App Name | The Name of the Web App. A directory with this name will be created in the webapps directory specified in parameter PATH and the contents of the save file will be restored to it. Also, this is the name that will be used in the URL to access MDWorkflow. For example:
http://myserver:4901/mdworkflow |
| REPL | Replace Existing Directory | Specifies if the directory specified on the APP parameter should be replaced if it already exists. |
| LTYP | Save File Location Type | Specifies if the save file is in an IFS folder or in a library. |
| SAVP | IFS-Path containing Save File | Specifies the IFS path containing the save file used to install MDWorkflow |
| SAVL | Library containing Save File | Specifies the Library containing the save file used to Install MDWorkflow. |
| SAVF | Save File name | Specifies the name of the save file containing MDWorkflow. |
Run as Worker from Apache Web Server
If you would like to take advantage of standard URLs without port numbers as well as SSL connections, http requests can be forwarded to the Apache Tomcat application server from the native Apache Web Server. To do this, the following steps must be taken within the Web Server configuration:
- A workers.properties file must be added to the web server instance in folder /www/<instance>/conf and the file must contain the following text:# workers definition file for MDWorkflow worker.list=wf worker.wf.type=ajp13 worker.wf.host=localhost worker.wf.port=<nnnn> Whereby <nnnn> is the AJP port number specified in …tomcat\conf\server.xml
- Edit /www/<instance>/conf/httpd.conf and add the following line at the beginning (or immediately after any existing LoadModule lines): LoadModule jk_module /QSYS.LIB/QHTTPSVR.LIB/QZTCJK.SRVPGM and add the following lines at the very end of the file: JkMount /mdworkflow wf JkMount /mdworkflow/* wf JkWorkersFile /www/workflow/conf/workers.properties JkLogFile /www/<instance>/logs/jk.log JkLogLevel Error Whereby <instance> is the Apache Web Server instance
Installation of Web Application Anywhere
Prerequisites
- Java JDK 8 or newer
- Application Server
The web application has been tested on the Apache Tomcat Application Server version 9.0.82.
The Installation Steps
Download the WAR version of the MDWorkflow web application from the MD Customer Area.
Extract the WAR file from the ZIP file.
Depending on the Application Server, you can use a browser-based management console to deploy the WAR file or you can copy the WAR file to a folder within the Application Server and the Server will deploy it automatically.
If your server permits you to modify the files in a Web App after deployment, then you can make the configuration changes after deployment and then restart the Server. If modifications are not permitted, then you will need to open the WAR with extraction software such as 7-Zip or WinRAR and make the changes prior to deployment.
Configuration of Web Application
All configuration properties are stored in file (mdworkflow)/WEB-INF/conf-faces-config.xml
If MDWorkflow is installed directly on the IBM i, and MDOpen is used, the property values can be edited, permanently stored and published directly within MDOpen from MDWorkflow->WebApp Config xml. When upgrading to a new version, the values can simply be republished.
If MDOpen is not installed, the file can be edited directly. In this case, it is best to make a copy of the file prior to upgrading to a new version of MDWorkflow, since the values will otherwise be lost.
WARNING: it is highly recommended to avoid the use of special language characters (such as ü or é, etc.) in the property values as they can cause an issue in loading the xml properties at server startup.
Store Properties at Server Level
If using Glassfish, It is also possible to set just one property in the xml file and manage all other property values at the server level. This allows for simple upgrading of the Workflow app when the server isn’t directly on the IBM i.
| Property | Default | Description |
| appPropPrefix | md. | The prefix for the system properties set at the server level that override the property variables in file conf-faces-config.xml Any property not found at the server level will be obtained from conf-faces-config.xml. Example: Setting system property ‘md.env’ to a value of myPROD will cause MDWorkflow to use value myPROD instead of the value stored in the env property in file conf-faces-config.xml |
Connect MDWorkflow to MDCMS Repository
MDCMS, including library MDREP(instance) must be installed on at least 1 IBM i partition to use MDWorkflow. DDM is used to connect from that partition to all other IBM i partitions or systems in the corporate infrastructure.
| Property | Default | Description |
| aspGroup | empty, system ASP |
The ASP device name that MDCMS is installed in, when not installed in the system ASP. Example: IASP1 |
| host | None, Mandatory | Host address of the IBM i repository to connect to Example: ‘my.system.com’ When installed directly on an IBM i partition, set host to localhost |
| hostAttachments | empty | Specify the host address of the IBM i partition to contain any IFS attachments for projects and tasks. Leave empty if same partition as for the MDWorkflow connection. A system user and password must be provided in the properties when connecting to a remote partition. Specify localhost when the host is a remote partition and the attachment host is the same partition as the instance of the MDWorkflow web app that is running. |
| hostEnv | empty, standard instance without suffix | MDCMS instance on the IBM i. Example: DEMO, to use MDCMSDEMO instance |
Setup User Authentication via IBM i User Profile
This is the default authentication. Each MDWorkflow user must have a valid User Profile and Password on the partition that MDWorkflow connects to. The user is presented with a Login screen when a new MDWorkflow session is started.
The user must also be registered in MDSEC with at least general authorization to MDCMS.
| Property | Description |
| userType | iseries |
Setup User Authentication via MDSEC User Profile
This authentication setting allows users and passwords to be defined directly in MDSEC, so that an IBM i profile is not necessary for each user. This can be relevant for Management or certain Business Users who do not require any other access to the IBM i partition. If the entered user id exists as an IBM i user profile, MDWorkflow will automatically use that profile for the authentication instead of MDSEC.
| Property | Description |
| userType | mdsec |
| systemUser | the technical user id used by MDWorkflow to authenticate the provided User ID in MDSEC, and to carry out the MDWorkflow processes, if the provided user id profile does not exist as a user profile. The technical user id does not require special rights – it merely needs to be enabled with a valid password. Example: MDWFUSER |
| systemPw | the password of the technical user id in base64 encryption format a java encryption tool EncryptPassword.jar is provided with MDWorkflow in folder ../tools Example: nlgJ8U1bSKDg+EqTWw== |
Setup User Authentication via LDAP
Each MDWorkflow user must be registered in MDSEC with at least general authorization to MDCMS. In order to link the network user id to the internal user profile, the value (case-sensitive) of each network user id must be entered in MDSEC. This value is placed in field External User ID and may be up to 20 characters in length.
| Property | Description |
| ldapserver | address of LDAP server Example: ldap://subdomain.company.com:389 |
| ldappassword | password for LDAP server for user lookup in base64 encryption format Example: nlgJ8U1bSKDg+EqTWw== |
| ldapsearchbase | the directory partition and suffix filters for the distinguished name of a container object Example: OU=Production,DC=company,DC=com |
| ldapconverttocn | Convert Network ID to Common Name true/false Example: true |
| ldapDomainController | The prefix name of the ldapDomainController Important: only prefix without the .com or .ch etc. Example: midrangedynamics |
| ldapprinciple | the domains and organizational units within the forest for identifying the principle Example: CN=s_ReadADTree, OU=ServiceAccounts, OU=Production, DC=company, DC=com |
| networkUserProviderClass | a custom NetworkUserProvider java class can be used to retrieve the NetworkUserId and NetworkUserName Example: com.company.base.MyNetworkUserProvider |
| userType | external |
| systemUser | the technical user id used by MDWorkflow to authenticate the provided Network User ID in MDSEC. If the provided user id does not exist as a profile on the partition, the technical user id will also be used to carry out the MDWorkflow processes. The technical user id does not require special rights – it merely needs to be enabled with a valid password. Example: MDWFUSER |
| systemPw | the password of the technical user id in base64 encryption format a java encryption tool EncryptPassword.jar is provided with MDWorkflow in folder ../tools Example: nlgJ8U1bSKDg+EqTWw== |
Customize Page Information
| Property | Default | Description |
| environment | empty | The Description of your environment. This text will be shown at the upper left of the browser so that the user will know in which environment they are working. |
| locationForTS | empty | The name of a location placed to the right of the time at the upper right of the browser. Example: Zurich |
| gmtOffsetForTS | empty, GMT | An offset to the current GMT time displayed at the upper right of the browser. An offset to GMT may be set here. Format is DHHMM where D -> direction, with + = add time to GMT and – = subtract time HH -> number of hours difference MM -> number of minutes difference Example: +0200 for Central European Time, -0400 for Eastern Time |
| dateFormat | DD.MM.YYYY | The format that dates should be displayed. Valid Date elements: YYYY -> year MM -> month DD -> day Valid date separators: / – . or , |
| firstDayOfWeek | Monday | The first day of week shown in the calendar view and in the date picker. Value may be Monday (default) or Sunday Example: Sunday |
| contactLabel | empty | If you would like your users to contact you in case of questions or issues, you can place the label text here, which will be shown at the bottom left of the browser. Example: Contact Us |
| contactPhone | empty | A phone number that the users can call in case of questions or issues. The number will be shown at the bottom left of the browser. Example: 1 800 800 8000 |
| contactLink | empty | A link the user can click on (mailto or http) in case of questions or issues. The link will be shown at the bottom left of the browser. Example: http://www.midrangedynamics.com/contact.php |
Provide Own Corporate Identity
The banner, fonts and colors can be customized to provide your own Corporate Identity for the MDWorkflow browser client.
| Property | Default | Description |
| corporateIdentity | empty (md) | The name of the folder within the web application root/co directory which contains the necessary elements. Example: : myCompany |
MDWorkflow is delivered with 2 sets of corporate identity layouts. The first is the default layout, which is located in folder …/co/md
The second is a working example layout which is located in folder …/co/example
There are 4 mandatory components for a functional corporate identity layout:
- parent folder – this folder must exist directly under folder …/co. The name of the folder must match the value for property corporateIdentity
- xhtml – this folder must contain file main.xhtml. The file does not need additional information beyond what is shown in the example, unless special image handling is required
- css – this folder contains the main.css style sheet. The example comes with 3 base color (blue, green, red) style sheets which can be renamed to main.css. The style sheet sets the fonts and names the locations of the necessary images.
- images – this folder contains image workflow (for the banner), logo, bg_paper and bg_paper_shadow (for background). The image files can be replaced with your own banner, logo and background images or your image files can remain named as they are and the css file can be edited to use your own images.
Set Reference Title and Link for another Product
If you are using another tool for tracking tasks, incidents, change requests, etc…, you can reference the ID of those entities from MDWorkflow Tasks and, if the other product supports variable hyperlinking, direct links to those entities..
| Property | Default | Description |
| iref | Ref | The Title of the Task field containing external reference information Example: Incident Number |
| ireflink | empty | The URL link syntax to the reference entity in another product Example: http://otherproduct.context.com/incidents/#iref# |
Configuration of email Client on the IBM i
MDWorkflow can send emails to recipients if the MDMAIL service has been configured on the partition that MDWorkflow connects to. See the MDCMS User Manual for information about setting up the MDMAIL service.