1. Home
  2. Knowledge Base
  3. MDWorkflow
  4. MDWorkflow Installation Guide

MDWorkflow Installation Guide

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:

  1. Download the SAVF for Tomcat from the MD Customer Area
  2. 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
  3. Use command MDCMS to go into the MDCMS menu
  4. Use F21 to get to a command line
  5. 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

  1. Download the SAVF version of MDWorkflow from the MD Customer Area
  2. Extract the Save File from the ZIP file and copy to either IFS or a library on the partition where the application server resides
  3. Use command MDCMS to go into the MDCMS menu
  4. Use F21 to get to a command line
  5. 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:

  1. 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
  2. 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:

  1. parent folder – this folder must exist directly under folder …/co. The name of the folder must match the value for property corporateIdentity
  2. 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
  3. 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.
  4. 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.

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#
#iref# will be replaced with the value of the reference field in the task screen and the link will be followed when the user left-clicks on the reference field from a Task or Subtask page.

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.

Related Articles