MDCMS Connectivity Troubleshooting

from Midrange Dynamics

for Version 8.6

Published April 7, 2024

Use this knowledge guide to understand and troubleshoot inbound and outbound connectivity issues between the MDCMS server, for various DevOps functions(Azure, Jenkins, Gitlab, JIRA....) or the MDOpen VSCode extension and the MDCMS server.

Architecture Overview

MDCMS uses the HTTP REST API protocol as its primary communication protocol.

There are both inbound and outbound connections being triggered between MDCMS and various clients/servers.

Some requests are triggered by events. For example:

An RFP being installed, which triggers an Azure pipeline to run(via a REST request from MDCMS),
A GIT commit to an Github repo which sends information from GitHub to the MDCMS GitHub webhook REST API,
An issue added or updated in JIRA, which triggers a webhook request to the MDCMS REST API server, to update the appropriate MDCMS Project/Task.

Some communication requests are triggered by scheduled services on the IBM i, by the pre-started MDCMS services batch jobs. For example, pushing all task updates to JIRA every 30 seconds.

DevOps and MDCMS Server Connectivity

Remote DevOps functions such as:

Pipelines(Jenkins, Azure, Gitlab, Bamboo etc),
GIT webhooks(GITHUB, GITLAB, BitBucket...),
Issues/Projects (JIRA, ServiceNow, Azure...) communicate with the MDCMS server via REST APIs (inbound) and REST Consumers(outbound).

The diagram below shows a schematic of the REST API connectivity architecture, used by MDCMS to communicate in realtime with remote DevOps applications.

MDCMS TEST API Connectivity Architecture

MDOpen-VSCode Extension Connectivity

The diagram below shows a schematic of the connectivity architecture used by the VSCode MDOpen extension to communicate the MDCMS on IBM i.

MDOpen-VSCode Connectivity Architecture

Info

The primary communication mechanism between MDOpen in VSCode(PC/Mac Installation) and MDCMS, is via MDCMS REST API's. The other two connectivity protocols used by MDOpen in VSCode(PC/Mac Installation), are only used for specific functionality in the MDOpen client.

MDOpen VSCode Connectivity Description

Functionality	Description
ALL MDCMS Functionality	All MDCMS functionality is handled by MDCMS REST API connectivity. The HTTP instance installed from MDCMS for the REST API's, is used to expose the MDWSOPEN and MDWSUSER Rest APIs on the IBM i. There are a set of pooled/shared connections (CGI jobs) that run under this HTTP instance. These CGi jobs are stateless, and reused by multiple sessions and users from multiple locations, and are NOT related to the job number that appears in the MDOpen VSCode UI connection node. When the user signs in to MDOpen in VSCode, a batch job is started under the MDCMS subsystem. This batch job number appears in the MDOpen VSCode UI connection node. In the MDCMS subsystem this job number has an "MDRP" prefix added to it. This MDRP999999 job controls the user client session stateful information and data.
Source Editing	Uses the SSH protocol to connect to the SSHD TCP server on the IBM i. The source code editing in the MDOPEN VSCode extension, is controlled by features from the IBM i Development Pack VSCode extension. This extension must be installed before the MDOpen VSCode extension.
SQL & CL Commands	Uses JDBC-JTOPEN to connect to the HOST servers on the IBM i. The Db2 for IBM i is part of the IBM i Development Pack. It allows users to write and execute SQL and CL commands from a VSCODE view. HOST servers must be started on the IBM i to use these features.

Troubleshooting Connectivity

Info

90% of connectivity issues are caused by problems in the HTTP REST API server setup. Validating this configuration in sequence, is a base line for troubleshooting any connectivity issue.

Warning

In the tests below "MDCMS" is used by default as it assumes the default instance is being used. With the exception of starting MDCMS from a command line in a 5250 screen, "MDCMS" can be replaced with "MDCMS" concatenated with the instance name. For example "MDCMST86"

index.md/#the-mdcms-rest-api-server

HTTP REST API Connectivity

Problem	Tests	Solution
Is the MDCMS REST API server installed?	From a 5250 screen command line: `MDCMS` `1=MDCMS Setup Menu` `10=Interface Settings` `9=MDCMS REST API and Diagramming Server` `2=Generate Server` If there is a value in "Server Name" (MDCMS for example) then the HTTP server instance has been installed. An optional secondary check can be used. Command `WRKLNK '/www/mdcms/conf/'` should list a file httpd.conf*	Install the REST API server instance.
Is the MDCMS REST API server running?	Test 1: From a 5250 screen command line: `MDCMS` `1=MDCMS Setup Menu` `10=Interface Settings` `9=MDCMS REST API and Diagramming Server` `1=Set/Change URL` Click (or copy and paste into your web browser) the link in the Example API URL field. If the server is running, the following JSON should return to the browser: `{"id":"MDTKNIN","text":"No authorization token received","statement":64,"severity":30}`. Test 2: From a 5250 command line, type the following command: `WRKACTJOB JOB(MDCMS)`. If the HTTP REST API server is running, it should display at least four active jobs:	Start the HTTP Rest API server instance using command: `STRTCPSVR SERVER(*HTTP) HTTPSVR(MDCMS)` Repeat tests 1 and 2.
HTTPS Connection to IBM i is not working in MDOpen VSCode.	Check that HTTPS - SSL/TLS is configured correctly in MDCMS HTTP REST API Instance. If HTTPS on IBM i server is controlled using the `APACHEDFT` instance (and ReverseProxy), check if the APACHEDFT HTTP instance is running: `WRKACTJOB JOB(APACHEDFT)`. Also check if the `ReverseProxy` settings for the HTTP MDCMS REST API server are correct in the APACHEDFT httpd.conf file.	Enable HTTPS for MDCMS REST API Server Start the APACHEDFT server (if appropriate). Correct APACHEDFT `reverseProxy` settings for MDCMS HTTP REST API instance. (if appropriate)

SSH Connectivity

Problem	Tests	Solution
*Error: A connection to the IBMi could not be established. Please check the ssh port for IBM i connection and try again.* When trying to open a source member from IBM i in MDOpen VSCode.	Test if the SSHD TCP server is running. From an IBM i command line: `NETSTAT *CNN` From the list of connections, select F15 to filter the list. In the `Local Port Range: Lower value` input `22` and press enter. In the updated display, at least one record should be displayed with the Local Port column = `22` or `SSH`	Use command : `STRTCPSVR SERVER(SSHD)` to start the SSHD server. Recheck if the server is started using the `NETSTAT CNN` command again, and if it is running, retry opening the source member from MDOpen VSCode extension UI.
SSHD TCP server wont start.	Check if OpenSSH is installed.	This article from Seiden Group describes how to install, setup and configure SSH on IBM i: HOW TO CONFIGURE AND USE SSH ON IBM i
SSH server is started on IBM i, and still cannot open source files from MDOpen VSCode.	Check the connection settings for MDOpen VSCode connection you are using. Check your local firewall allows port 22 communications. Check your network security allows port 22 communications to the IBM i.	Specify the correct SSH port number in the MDOpen VSCode settings. Open port 22 on local firewall and/or network to IBM i.

Note

If the SSH server is configured on a different port than the default of 22, ensure all of the above is amended and tested using the custom port number.

SQL JDBC-JTOPEN Connectivity

Problem	Tests	Solution
Query Data option times out from MDOpen VSCode	Check of DB2 for IBM i connection job exists.	Open DB2 for i view in VSCode and manage SQL connection job.
Cannot start SQL server job	Check if HOST servers are started	Start Host servers on IBM i. Use command: `STRHOSTSVR *ALL` For more details refer to the IBM Support page for managing Host Servers on IBM i.