Home
Guides
Sign in
Start typing to search…

No-Code Integration Setup for OpenLegacy H3270 Screens API


This no-code API exposes REST endpoints for mainframe 3270 screen-based applications generated from an OpenLegacy Hub H3270 Screens project, running as a Spring Boot service.

This README provides instructions to set up the No-Code Integration solution using the provided JAR and batch files.

Prerequisites

Before you begin, ensure that you have:

  • Java 17 (OpenJDK or a compatible distribution such as Amazon Corretto or Temurin) installed and available on your PATH.
  • Docker installed and running if you plan to build and run the Docker image.
  • Access to an OpenLegacy Hub environment, including a valid Hub URL and API key, and an existing project with at least one published version.
  • Access to the target mainframe 3270 environment and an H3270-compatible terminal emulator JAR as required by the OpenLegacy screens runtime.

Step 1: Download Required Files

Please download the required JAR and batch files to proceed with the setup:

https://ol-nocode-artifacts.s3.eu-central-1.amazonaws.com/nocode-apps/<OPENLEGACY HUB VERSION>/mainframe-screens-spring-java-rest/mainframe-screens-spring-java-rest-nocode-all.jar

Replace <OPENLEGACY HUB VERSION> with the appropriate version number.

Step 2: Running the JAR File

To run the JAR file directly, follow these steps:

  1. Open a terminal in the directory where you downloaded the JAR file.
  2. Add the following required environment variables:

When running the application with OpenLegacy Hub as the source provider, ensure to set the following environment variables:

  export OL_FLOW_TYPE=SCREENS
  export OL_SOURCE_PROVIDER=HUB
  export OL_HUB_PROJECT_NAME=<OL HUB PROJECT NAME>
  export OL_HUB_PROJECT_VERSION=<OL HUB PROJECT VERSION>
  export OL_HUB_API_KEY=<OL HUB API KEY>
  export OL_HUB_URL=<OL HUB URL>
  export OL_LICENSE_KEY=<OL LICENSE KEY>
  set OL_FLOW_TYPE=SCREENS
  set OL_SOURCE_PROVIDER=HUB
  set OL_HUB_PROJECT_NAME=<OL HUB PROJECT NAME>
  set OL_HUB_PROJECT_VERSION=<OL HUB PROJECT VERSION>
  set OL_HUB_API_KEY=<OL HUB API KEY>
  set OL_HUB_URL=<OL HUB URL>
  set OL_LICENSE_KEY=<OL LICENSE KEY>
  $env:OL_FLOW_TYPE=SCREENS
  $env:OL_SOURCE_PROVIDER=HUB
  $env:OL_HUB_PROJECT_NAME=<OL HUB PROJECT NAME>
  $env:OL_HUB_PROJECT_VERSION=<OL HUB PROJECT VERSION>
  $env:OL_HUB_API_KEY=<OL HUB API KEY>
  $env:OL_HUB_URL=<OL HUB URL>
  $env:OL_LICENSE_KEY=<OL LICENSE KEY>

When running the application with OpenLegacy Project ZIP as the source provider, ensure to set the following environment variables:

  export OL_FLOW_TYPE=SCREENS
  export OL_SOURCE_PROVIDER=OL_PROJECT_ZIP
  export OL_PROJECT_ZIP_PATH=file:<PATH TO OPZ FILE>
  export OL_LICENSE_KEY=<OL LICENSE KEY>
  set OL_FLOW_TYPE=SCREENS
  set OL_SOURCE_PROVIDER=OL_PROJECT_ZIP
  set OL_PROJECT_ZIP_PATH=file:<PATH TO OPZ FILE>
  set OL_LICENSE_KEY=<OL LICENSE KEY>
  $env:OL_FLOW_TYPE=SCREENS
  $env:OL_SOURCE_PROVIDER=OL_PROJECT_ZIP
  $env:OL_PROJECT_ZIP_PATH=file:<PATH TO OPZ FILE>
  $env:OL_LICENSE_KEY=<OL LICENSE KEY>

Note For Windows users: export should be replaced with set (cmd) or $env:VAR=... (PowerShell)

  1. Copy the H3270 JAR to the lib folder.
  2. Run the following command to start the application:
java -cp <PATH TO JAR DIRECTORY>/mainframe-screens-spring-java-rest-nocode-all.jar -Dloader.path=<PATH TO JAR DIRECTORY>/lib org.springframework.boot.loader.launch.PropertiesLauncher

Step 3: Building a Docker Image

If you prefer to build a Docker image with the JAR file, follow these instructions:

  1. Create a Dockerfile in the same directory as the JAR file.
FROM amazoncorretto:17
COPY mainframe-screens-spring-java-rest-nocode-all.jar /app/mainframe-screens-spring-java-rest-nocode-all.jar
COPY lib/ /app/lib/
WORKDIR /app
ENTRYPOINT ["java", "-cp", "mainframe-screens-spring-java-rest-nocode-all.jar" , "-Dloader.path=lib", "org.springframework.boot.loader.launch.PropertiesLauncher"]
  1. Build the Docker image using the following command:
docker build -t mainframe-screens-spring-java-rest-nocode:latest .
  1. Run the Docker container with environment variables specified directly: Run with OpenLegacy Hub as the source provider:
docker run -p 8080:8080 \
  -e OL_FLOW_TYPE=SCREENS \
  -e OL_SOURCE_PROVIDER=HUB \
  -e OL_HUB_PROJECT_NAME=<OL HUB PROJECT NAME> \
  -e OL_HUB_PROJECT_VERSION=<OL HUB PROJECT VERSION> \
  -e OL_HUB_API_KEY=<OL HUB API KEY> \
  -e OL_HUB_URL=<OL HUB URL> \
  -e OL_LICENSE_KEY=<OL LICENSE KEY> \
mainframe-screens-spring-java-rest-nocode:latest

Run with the OpenLegacy Project ZIP as the source provider:

docker run -p 8080:8080 \
  -v </path/to/your/opzfile.opz>:/app/ol.opz \
  -e OL_FLOW_TYPE=SCREENS \
  -e OL_SOURCE_PROVIDER=OL_PROJECT_ZIP \
  -e OL_PROJECT_ZIP_PATH=file:/app/ol.opz \
  -e OL_LICENSE_KEY=<OL LICENSE KEY> \
mainframe-screens-spring-java-rest-nocode:latest

Step 4: Verify the API

After starting the application (either by running the JAR directly or via Docker), verify that the API is up and the OpenAPI definition is exposed:

  1. Open a browser or an HTTP client (such as curl or Postman).

  2. Navigate to the OpenAPI endpoint:

    • URL: http://localhost:8080/openapi

  3. Confirm that you receive a valid OpenAPI document (typically in JSON or YAML format). If the endpoint is not reachable, review the container logs or application logs and validate your environment variables and network connectivity.

Updated 1 day ago