What is so unique in OpenLegacy Screens API?

OpenLegacy is the first open source screens strong type API, which enables you to model your legacy application and treat them as a true API and not a low level screen scraping script.
OpenLegacy screen API provides:

  • Identifying screen buffers to Java strong type classes (See general and identifiers tab in screen entity editor or @ScreenEntity, @ScreenIdentifiers annotations).
  • Java fields and tables mappings to positions on screens (See fields tab in screen entity editor or @ScreenField , @ScreenTable, @ScreenColumn annotations).
  • Enable direct fetching for screens by configuring navigation for each screen entity directly including primary key/s support.
  • Cast from flat screen strings to true data type (Integer, Double, Boolean, Date, List, Enum. See fields tab in screen entity editor or @ScreenNumericField, @ScreenBooleanField, @ScreenDateField, @ScreenListField annotations).
  • Enable special handling for fields with description or values from other screen (See fields tab, add values field and description section in every field properties in screen entity editor or @ScreenDescriptionField, @ScreenFieldValues annotations).
  • Enable separating a screen to smaller data structures using inner classes (See parts creation in fields tab, add screen part in screen entity editor).
  • Enable to define possible actions on a screen entity (See actions tab in screen entity editor or @ScreenActions annotation).
  • Enable to define relationship between a parent screen and its child screens (See child entities tab in screen entity editor).
  • Enable extend screens via abstract screen classes.
  • Provide rich metadata to front end application to enable on the fly UI rendering or design-time UI generation of web and mobile applications.
  • A highly flexible infrastructure which enable highly customized solutions for screen based applications.
  • A connectors API, which provides out of the box support for Mainframe and AS/400 and allows to combine different host protocols or other screen API’s relatively fast.


What are the quick steps to get started with OpenLegacy Screens API?
  • Install OpenLegacy IDE from http://ftp.openlegacy.org/installations/  or add Openlegacy plugin via eclipse market place
  • Create an OpenLegacy project of the desired type.   OpenLegacy-mvc-new is a good default to start from, but you can choose any desired screen project (Java, REST, Integration (web services), MVC)
  • Configure the provider, host address, port and select a theme (if relevant).
  • Run run-emulation.launch (right click, Run as -> run-emulation) to start an emulator, and open your browser to http://localhost:1512
  • Navigate through some sample screen that you want to define in OpenLegacy. A good choice would be a login, 1-2 menu screens, a table screen and a details screen. Click logoff.
  • A trail file is created within your project src/test/resources folder (refresh the folder if needed). You can try to analyze it entirely (right click on the file), or screen by screen.
  • Go through the API and fine tune it.
  • Run the application (run-application.launch), and see the on the fly rendered pages. As you edit the API, the web application will be reflecting the changes (after restart).
  • If you are web or mobile enabling, Generate views and controllers (in Java workspace -> Package Explorer -> right click on an entity -> OpenLegacy -> Generate views/controller) to customize the display (view) or workflow (controller).
How do I create a screen entity API class?

You should create a trail file from your real host application. For practicing purposes you can use demo_session.trail which exists in all OpenLegacy project types.

Once you have created a trail, you can open it with OpenLegacy trail editor, and right click on the relevant screen image in the list (IN screen) and either choose “Generate Screen Model” to let OpenLegacy analyzer to try to identify all elements on the screen image into the API, or “New Screen Model” to create an empty class which is just attached to the image. Add entity name and press OK.


What is a trail file?

A trail file is an XML file that captures emulation screens structure (IN screen), and actions performed when navigating between them (OUT screen). It serves the following purposes:

–        Analysis and creation of new API of screen entities

–        Offline work. Allows to work disconnected from the host, remote development, or troubleshooting. Edit commented section in spring file under src/main/resources/META-INF/spring/applicationContext.xml to use a trail file instead a real host.

A trail is created when running a project via run-application or run-emulation. During development a trail file is created in src/test/resources/trails, when clicking logoff in the web application. Trail is turned on by setting a path in the system property: org.openlegacy.trail.path

NOTE: When requesting OpenLegacy community assistance, please send us your trail file so we can analyze problems you may encounter.

How does a trail file behave vs. the real host application?

A trail file mimics the real host application as close as possible. When the API requests a specific API class instance (e.g. Items), the trail is located at the next matching image to Items. When performing any terminal action, the trail usually advances to the next screen in the trail, no matter what the input is.

What is the difference between working with the editor and using the Java editor?

In short, it is the same. The editor provides editing abilities for the API for non-Java developers and for Java developers who want to use the API, and wish learn it more easily.

The editor saves the API to a Java file, and can be edited back and forth between entity editor and standard Java editor. All of the editor forms have matching annotation properties that can be edited using eclipse auto complete within the Java editor as well.

The document describes annotation properties as written in the editor (e.g. “Display Name”, but all properties are available in OpenLegacy annotation via Java standard naming convention (e.g. displayName)

How does OpenLegacy create screen entities API automatically?

OpenLegacy uses the Drools rule engine (http://drools.jboss.org/) to analyze recorded screens and find patterns and relations within them. The rule engine uses a set of predefined and default rules provided by OpenLegacy that produce metadata definitions. The definitions are generated to Java API’s that stores the metadata within the API annotations.

How can I customize the screens analyzer?

To customize the screens analyzer, you should right click on your OpenLegacy project, and select OpenLegacy -> Customize Design-Time Context. This will add the file openlegacy-designtime-context.xml that defines all the screens rules and their parameters.

Each rule can be enabled/disabled by setting “p:enabled” to false. Each rule has its own parameters, mainly regular expressions to find patterns on the screens.

Rules can viewed in GitHub under:


Or by exploring Maven dependencies -> openlegacy-designtime-<version>.jar/rules/default

Please read the Drools manual to get familiar with the Drools rules language:

http://docs.jboss.org/drools/release/latest/drools-docs/html/  Each rule relies on OpenLegacy TerminalSnapshot instances as input, and ScreenEntityDefinition as output.

It is also possible to write a custom rule, and add it. See sample.drl, and commented definition in openlegacy-designtime-context.xml

What should I check when “preview” pops-up after generating a model?

The following is recommended when analyzing a full trail, or “Generate Screen Model” is performed on one or more selected screens.

For each analyzed screen, you should check:

  • Does the “Entity name” field make sense? This will be the entity class name. Use Java class naming convention (e.g “ItemDetails”)
  • Are the recognized fields are correct and points to dynamic data fields, and their names make sense. Edit their name if needed. Use Java field naming convention (e.g. itemNumber).
  • Delete fields that points to static labels on the screen
  • Verify that the identifiers refer to meaningful static content on the screen (e.g. screen title, etc.)

The “preview current” does not support adding new fields, display tables and actions.

It is recommended to open the generated entity in the entity editor after generation to review the full mapping has been performed.

Why do I not see the screen/RPC preview when I open an entity?

Make sure you are using OpenLegacy perspective. Choose Window -> Reset Perspective if you still do not see it. If you prefer to use another perspective, then open the screen preview from: Window -> Show View -> Other… -> OpenLegacy -> Screen preview

OpenLegacy Screen Preview

How do I split entities into more than one package?

When creating a new project, a default package is set. If you wish to split entity classes into more than one package, edit src/main/resources/META-INF/spring/applicationContext.xml and applicationContext-test.xml and add another package value to the bean definition with id “screensRegistry” or “rpcRegistry”.

How do I define a screen field with a description next to it? (e.g. Status: 2 – Open)

OpenLegacy provides special handling for such fields. For each field in the editor there is a Description section which you need to define the column of the description (e.g. “Open”). You can optionally define row and end column.

In the API it will generate a @ScreenDescriptionField.

The API will generate automatically an additional java field named <fieldname>Description, and the MVC web application will render this field as < field – description > automatically.

How do I create a login entity and page?

OpenLegacy enables you to create a login screen entity that automatically will be shown as the login page. When the login page is shown, the session is still disconnected, and only after login submission, is a session created. This allows OpenLegacy to optionally check credentials and configuration for the entered user, and only then will open a connection to the host application.

To configure a login screen entity:

–        In General tab, configure the screen as type “LoginEntity”.

–        In fields tab configure the user field as Field type: “UserField”

–        In fields tab configure the password field as Field type: “PasswordField”

–        In fields tab configure the error message field as Field type: “ErrorField”


Once there is one login entity, Openlegacy will display a login page within the web application.

The API exposes a simple login API using:


How do I change a data type of a field?

Currently it is possible only from Java code. Open the entity in Java editor (Open with -> Java Editor) and change the code accordingly. When changing a String field to Boolean/Number/Date you should define additional properties for the typed field via the screen entity editor. Close the editor and reopen to pick up the changes.

How do I use API’s in more than one project (e.g. web and web services projects)?

You should create an OpenLegacy Java API project, and place/generate the entities inside this project. In the other project (web, REST, ws) pom.xml, add a dependency to the Java API project according to the Maven artifact.

By default its group id: <project name, artifact id: <project name>, version: 0.1

Why is navigation not generated when generating a single screen?

Whengenerating a single screen entity, @ScreenNavigation is not generated and needs to be created manually

How can I control the layout of a page?

There are a few ways to control the layout of fields in the MVC web project.

–        By default, OpenLegacy finds “neighbor” fields and group them in a panel (aka pagePart). Single fields (without neighbors) are rendered in absolute positioning.

–        Create screen parts. If you define screen parts, and move the relevant fields inside the part, they are auto created as a single panel

–        Generate view (right click on the entity class, and select OpenLegacy -> Generate view). A file named <entity name>.jspx is generated under:



When you generate a view, the page is generated with OpenLegacy tags which allows to generate organize the entity fields.

OpenLegacy field tag and table tag knows to extract by default all the metadata from the API and use them to generate a leading label, widget type, table columns and much more. So all it takes to draw a field is <ol:field id=”[field name]” />

The tags allows to override the API defaults (e.g. label, type, maxlength) and CSS settings (width, style,cssClass).

The current entity model is also available in the page context and it is possible to access the model properties as ${<entityName>.<fieldName>} or ${<entityName>.<pagePartName>.<fieldName>}.

Also the page is a standard JSP page (well formed) and can use HTML, CSS, JavaScript, and other tag libraries such as JSTL and Spring to manipulate the page.

What is the HTML preview tab?

The HTML preview tab allow you to see the basic layout of the entity before running it in the front end application. We provide a basic template based on Freemarker template language (http://freemarker.org/) to render a preview of the page.

How can I customize OpenLegacy generated code?

OpenLegacy allows you to customize all the code it is generating (as long as you are aware of what you are doing).

To customize generation of the API, web or other code, right click on the project and select OpenLegacy -> Customize Code Templates. A folder named “templates” is generated with all the default templates OpenLegacy uses. You can delete the all of the files you do not intend to change (OpenLegacy will use the default file).

The template files are using Freemarker template language (http://freemarker.org/) to render generate any code produced by OpenLegacy.

Why there are no getters and setters method for each field?

OpenLegacy saves the burden of generating getters and setters and does that behind the scene automatically. When working on OpenLegacy API, a hidden aspect file is generated which adds the necessary getters and setters automatically. If you wish to work without it, just uncheck “Generate Aspect” when generating API classes.

How do I navigate to a screen directly?

This is one of the most important features in OpenLegacy. It treats screens as data sources, no matter where the session is currently located, and greatly simplifies API/web/mobile client development.

Screen entities in OpenLegacy should have a @ScreenNavigation configuration, if accessing them is done without logical conditions or restrictions (typically menu “leaf” screens).

Open the relevant entity and configure @ScreenNavigation (general tab or class level) and select in “Accessed from” the screen entity which it’s accessible from. ENTER is the default terminal action between the source screen entity and the current.

There are several navigation types:

–        If the action is different than ENTER, you may select it from the dropdown.

–        If typing field values in the “Accessed From” screen is required, than define them in “Assigned fields” table. Assigned fields supports ‘hardcoded’ values. You cannot use entity fields or keys. See drill down.

–        If the current screen has primary key/s, then at least one field in this screen should be set as “Is key”. OpenLegacy has built in support for drill down, and you should configure “Drilldown value” for the row selection option (e.g. X, 1, etc.). The “Accessed from” screen entity should have a table configured with at least one column configured as “Is selection field” and “Is editable”. And at least one column configured as “Is key”. The table column key in the “Accessed from” must match the key in the current screen.

Note that it is possible to write custom navigation via the TerminalAction interface (can be an inner class of the same Java file of the entity) and use it within the new Terminal action.

It is also recommended to configure how to exit this screen via Exit key field. Default is F3.


One the navigation is properly configure, it is possible to access the API easily. E.g:

Items items = terminalSession.getEntity(Items.class);

Or via URL when using an MVC web project:


Or via REST API when using a REST project:

GET: http://demo.openlegacy.org/openlegacy-rest-sample/Items

Content-Type: application/json ; Accept: application/json

Navigation with primary key/s

If the screen has primary key/s, at least one field in this screen should be set as “Is key”. Openlegacy has built in support for drill down, and you should configure “Drilldown value” for the row selection option (e.g. X, 1, etc.). The accessed from screen entity should have a table configured with at least one column configured as “Is selection field” and “Is editable”.

Note that it’s possible to write a custom navigation via TerminalAction interface (can be an inner class of the same Java file of the entity) and use it within the new Terminal action

One the navigation is properly configure, it is possible to access the API easily. E.g:

ItemDetails itemDetails = terminalSession.getEntity(ItemDetails.class,2000);

Or via URL when using an MVC web project:


Or via REST API when using a REST project:

HTTP GET: http://demo.openlegacy.org/openlegacy-rest-sample/Items

Content-Type: application/json ; Accept: application/json

Navigation is not working. How can I trace what is wrong?

During development, all screens are printed to the Eclipse console, and for each performed telnet action, before and after screens is printed.

If action (e.g. enter, pf1) is printed on top of the before screen, and modified fields are marked with “*”. It is recommend to clear the Eclipse console, if you want to trace a specific action, before performing it.

It is recommend to reproduce an issue in OpenLegacy HTML emulation or external emulation to see if a certain action is not performed on the API.

NOTE that OpenLegacy logger (src/main/resources/log4j.properties) should be configured to DEBUG mode:

log4j.logger.org.openlegacy=DEBUG, defaultLog

or more specifically (for just the screens logger):


When deploying to production it is highly recommended to switch DEBUG to INFO

How can I write custom code for navigation?

When a screen can be accessed from multiple source screens, or requires custom script for navigation, you should implement a custom navigation action. Write a class which extends org.openlegacy.terminal.actions.TerminalAction (recommended as inner class within the entity, and use the custom class in @ScreenNavigation, terminalAction property as follows:

How do I create tabs in my page?

To create tabs you need define child entities in the “Child Entities” editor tab.

The child entity should be referred from the main entity, which is displayed as the 1st tab. The child entity should have a @ScreenNavigation definition which defines how it is accessed from the main entity. The child entity should be marked as “Is child” in General tab in the screen entity editor or @ScreenEntity(isChild=”true”) annotation. After you define the child screen as child, define in the main screen’s screen entity editor -> child entities tab -> add child screen or in add to the screen class the child screen as a private member (e.g. private SomeScreenEntity;) .

How do I match actions to a screen entity?

Host applications typically mix navigation actions and logical actions, all into F keys.

OpenLegacy distinguishes between the two and recommends handling them as follows:

  • Navigation actions such as “exit” are defined within @ScreenNavigation, exit action. This enables you to click anywhere and the action is performed in the server side automatically
  • Navigation to other screens should be configured in many cases as child entities, shown as tabs.
  • Only real logical actions (save, delete, etc.) should be configured as screen actions

Actions are exposed as part of the API as getActions() auto generated aspect method, and drawn as a toolbar in OpenLegacy web projects.

Actions are also exposed in the REST API.

How do I configure logical actions?

Sometimes screen actions are not available on the host application due to various reasons (permissions, certain logical condition, etc.), and we need to be able to remove these actions from the API.

To define a conditional action, map it to an action text on the screen (F5=SAVE), using Row, Column, Length and When (regex). Only when the text in “Row”, “Column” in the specified “Length” matches the “When” regex, will the action be available.

Why are function keys are not available in designed pages?

OpenLegacy philosophy is to re-build the host application using the new web standards.

This means no menu screens, no F keys, no selection field, and no host application patterns.

F keys are also a legacy pattern, and therefore we have eliminated it.

F keys are fully functional in the HTML emulation, which show when the current screen has no API class.
On the other hand, designed pages support enter, page up and page down, if applicable, as they are also common in web applications.

During development I want to stay on emulation, and not switch back to designed pages on each action. How can I do that?

Change the application URL to /emulation?stick=true to stay on emulation. To turn it off, Change the application URL to /emulation?stick=false, and perform an action which should show a designed page.

I have not generated any web page code. How is OpenLegacy showing a designed page automatically?

OpenLegacy has a default view named generic.jspx, which is shown when no specific view exists for the current entity. generic.jspx is using the current entity metadata to render a default view.

How do I create a conditional view?

OpenLegacy provides a way to map field only on certain conditions. If the condition is not met, the field will be null. To create a conditional field, you need to configure “when” property as a regular expression. If the field value does not match the “when” regular expression, it is set to null.

Same for “unless”, which sets the field to null unless it matches the defined “unless” regular expression.

How do I refer to field properties (editable, color, background color, etc.)?

By default OpenLegacy maps Java entities to field content only, but enables mappings to additional properties. For example, if a screen field has different color in different situations, you may want the color information in the API.
To map a property different than content, you need to set @ScreenField, Field attribute enum to the matching property. When using color, the field type should be org.openlegacy.terminal.Color

Why does a newly created screen not appear in the side menu?

Make sure the screen @ScreenNavigation has “Accessed from” property configured, and that the accessed from entity is of type “MenuEntity”.

OpenLegacy will automatically create a menu tree from all menus, sub menus, and their first leafs.

In the OpenLegacy web project, the menus can be rendered as drawers (default), or tree menu.

To switch to tree menu, configure application.properties, set:  openLegacyWebProperties.treeMenu=true

How do I configure a popup window with possible values for a field?

OpenLegacy web application has built in support for popups. To associate a popup screen to a specific field, you need to configure a field as “Values Field”. To accomplish this, configure a window screen and define “Source screen entity” and check “As window”. You should configure navigation to the window screen.

When the field is rendered, it is rendered with a glass icon, which opens the popup.

The next step is to define a table on the window screen. One of the table columns should be a key field, and optionally a “Main display field”, in the case that the “Values Field” is a description field. This way when clicking on a row in the popup, the key (and description) value is returned to the opening page.

How do I filter empty table rows?

To filter empty rows, you should define one of the screen table columns or the RPC field within a list as “Is Key”. When a row has an empty key it is not created in the entity.

How do I control the template of the pages?

OpenLegacy web applications uses Apache tiles (https://tiles.apache.org/) and JSPX pages for template of the web application.

The following include files (under src/main/webapp/WEB-INF/web/template) are available for customizing the pages HTML structure:

  • jspx – the general page structure
  • jspx – for rendering navigation bar
  • jspx – for rendering toolbar
  • jspx – for rendering side menu
  • jspx – page footer
  • jspx – for rendering a tab inner page
  • jspx – for rendering a popup window

All views are defined in src/main/webapp/WEB-INF/web/views/views.xml, and a few default pages layouts are available (src/main/webapp/WEB-INF/web/template/layouts.xml). Each view typically extends a certain layout to define it’s structure.

Each layout defines what jspx file it should include.

When generating a view file, OpenLegacy generates a default layout according to the API characteristics (composite, window, child, menu, login etc.).

The default layouts are:

  • template – the default layout for 1 to 1 pages
  • emulation – the layout for HTML emulation
  • menu – layout for menu pages
  • compositeTemplate – a template for an entity with child entities
  • view – a template for inner page within a tab
  • public – a template for disconnected pages (login, logoff, error)
  • window – a template for popup pages
After I press a certain action a host window screen may appear, and I want it to be shown as popup. How can I do that?

The OpenLegacy web application will perform standard form submit and page reload on every action. To enable actions to be performed in the background, an action can be configured as Type=LOGICAL. For such a type action is performed in Ajax and a popup will be opened if the resulting screen is configured as “window” (General tab or @ScreenEntity)

How do I open a popup window?

To enable an action to open a popup window, you should configure the action as Type=WINDOW, and the target entity class to open. The target entity should have @ScreenNavigation properly configured from the opening entity.

The host screen shows a table with records spread over more than one row. How can I map them?

To enable a table record that shows  more than one row, the second, third, etc. row fields should be configured with “Rows offset” (1 for second row, 2 for third row, etc).

This way each record is available as one record in the API, even it is displayed over more than one row.

In the web application, OpenLegacy knows to render the rows, with multiple rows for each record accordingly.

One of the fields was not created properly. How do I create a field manually?

Open the entity in the entity editor on fields tab, double click or mark the area on the screen preview, and click “Add” (or choose Add with type in the drop down).

Alternatively, you can use  the Java editor to add a Java field marked with @ScreenField annotation which refers to the location on the screen.

When do I have to restart the web server to show reflect changes to in the project?

Any change to a Java file requires server restart (when not activating JRebel).

Changes made to properties file or XML files, can use “/reload” URL or “Reload application” link if using OpenLegacy web app, to reload changes without restart.

Changes to HTML, JSP, CSS and JavaScript files does not require restart.

How do I avoid restarts every time I make changes to the API?

JRebel. OpenLegacy IDE comes built in with JRebel plugin. You can activate an evaluation from “JRebel Config Center” perspective, or purchase a yearly license (few hundreds $)

Once JRebel is activated, and JRebel is activate via the run-application launcher configuration (JRebel tab), changes to API are reloaded every few seconds into memory (using an OpenLegacy JRebel plugin) and reflect into the front end application.

In general it is highly recommend to write tests during development. When writing tests you code API scenarios which can later on be be tested automatically. Running the test after a code change is much faster than restarting the web server and manually clicking through the screens.

How do I deploy an OpenLegacy application?

Each web/REST/web service project comes with build-war.launch which package the project as a WAR file, which can be deployed in general to any J2EE container.

The WAR is created under the project “target” folder.

OpenLegacy is tested on Tomcat 6.0 and 7.0 and these are the recommended platforms.

A commercial version of OpenLegacy server (based on Tomcat) is available as well, which includes management, security and simple deployment and setup capabilities.

How do I write API tests?

When generating screen entities, a test skeleton is generated by default into src/test/java folder. You may customize and write a set of API calls to go through the screen and verify navigation is correct, including access to screen by keys, values are received and sent properly using test assertion. Once the API is well tested, it simplifies web/REST/WS development as screens are treated as a data source, and the front end just consumes and send data.

When writing multiple tests, it is recommended to use a new session for each test.

See MvcSampleTest.java in openlegacy-mvc-sample project:


RPC doesn’t support generation of testing currently, but you can write it manually (recommended).

How do I automate testing, packaging, and deployment of the developed app?

An OpenLegacy project is a standard Maven project. It can be compiled, packaged, tested deployed using standard tools. We recommend using Jenkins or Hudson continuous integration server, to run continuous or nightly tests, package and deploy in a single click to test/production.

How do I customize CSS of the project?

OpenLegacy comes with predefined themes.  A  theme  is selected when you start your project. But you certainly may want to customize the look and feel of the theme.

To allow you to do that, each web project comes with src/main/webapp/css/project.css.

You can add or override the default CSS settings. We recommend using Chrome developer tools to fine tune the CSS classes, and then copy the changes to project.css.

What source files OpenLegacy can parse?
OpenLegacy supports parsing of various source files.
Files with the following extensions are supported via right click in OpenLegacy IDE (OpenLegacy -> Generate Model)
The files should be copied into the project in OpenLegacy IDE.
AS/400: Cobol (*.cbl), CopyBook (*.cpy), RPG (*.rpg), PCML (*.pcml).
PCML is the recomended format (XML based) as it can be produce via AS/400 command line.
MainFrame: Cobol (*.cbl), CopyBook (*.cpy)
Databases: SQL (*.sql)
Web services: WSDL (*.wsdl)
Natural sub-programs and parameter data areas (PDA) generated through either the SYSTRANS or SYSOBJH utilities