Home
Guides
Sign in

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.