Integrate Stonebranch Universal Controller with AWS Mainframe Modernization - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resourcesAdditional information

Integrate Stonebranch Universal Controller with AWS Mainframe Modernization

Created by Vaidy Sankaran (AWS), Robert Lemieux (Stonebranch), Huseyin Gomleksizoglu (Stonebranch), and Pablo Alonso Prieto (AWS)

Code repository: aws-mainframe-modernization-stonebranch-integration

Environment: PoC or pilot

Technologies: Mainframe; DevOps; Modernization; Operations; SaaS

Workload: Open-source; Microsoft

AWS services: AWS Mainframe Modernization; Amazon RDS; Amazon S3

Summary

This pattern explains how to integrate Stonebranch Universal Automation Center (UAC) workload orchestration with Amazon Web Services (AWS) Mainframe Modernization service. AWS Mainframe Modernization service migrates and modernizes mainframe applications to the AWS Cloud. It offers two patterns: AWS Mainframe Modernization Replatform with Micro Focus Enterprise Technology and AWS Mainframe Modernization Automated Refactor with AWS Blu Age.  

Stonebranch UAC is a real-time IT automation and orchestration platform. UAC is designed to automate and orchestrate jobs, activities, and workflows across hybrid IT systems, from on-premises to AWS. Enterprise clients using mainframe systems are transitioning to cloud-centric modernized infrastructures and applications. Stonebranch’s tools and professional services facilitate the migration of existing schedulers and automation capabilities to the AWS Cloud.

When you migrate or modernize your mainframe programs to the AWS Cloud using AWS Mainframe Modernization service, you can use this integration to automate batch scheduling, increase agility, improve maintenance, and decrease costs.

This pattern provides instructions for integrating Stonebranch scheduler with mainframe applications migrated to the AWS Mainframe Modernization service Micro Focus Enterprise runtime. This pattern is for solutions architects, developers, consultants, migration specialists, and others working in migrations, modernizations, operations, or DevOps.

Targeted outcome

This pattern focuses on providing the following target outcomes:

  • The ability to schedule, automate, and run mainframe batch jobs running in AWS Mainframe Modernization service (Microfocus runtime) from Stonebranch Universal Controller.

  • Monitor the application’s batch processes from the Stonebranch Universal Controller.

  • Start/Restart/Rerun/Stop batch processes automatically or manually from the Stonebranch Universal Controller.

  • Retrieve the results of the AWS Mainframe Modernization batch processes.

  • Capture the AWS CloudWatch logs of the batch jobs in Stonebranch Universal Controller.

Prerequisites and limitations

Prerequisites

Limitations

  • The product and solution has been tested and compatibility validated only with OpenJDK 8 and 11.

  • The aws-mainframe-modernization-stonebranch-integration task scheduling template will work only with AWS Mainframe Modernization service.

  • This task scheduling template will work on only a Unix, Linux, or Windows edition of Stonebranch agents.

Architecture

Target state architecture

The following diagram shows the example AWS environment that is required for this pilot.

  1. Stonebranch Universal Automation Center (UAC) includes two main components: Universal Controller and Universal Agents. Stonebranch OMS is used as a message bus between the controller and individual agents.

  2. Stonebranch UAC Database is used by Universal Controller. The database can be MySQL, Microsoft SQL Server, Oracle, or Aurora MySQL–Compatible.

  3. AWS Mainframe Modernization service – Micro Focus runtime environment with the BankDemo application deployed. The BankDemo application files will be stored in an S3 bucket. This bucket also contains the mainframe JCL files.

  4. Stonebranch UAC can run the following functions for the batch run:

    1. Start a batch job using the JCL file name that exists in the S3 bucket linked to the AWS mainframe modernization service.

    2. Get the status of the batch job run.

    3. Wait until the batch job run is completed.

    4. Fetch logs of the batch job run.

    5. Rerun the failed batch jobs.

    6. Cancel the batch job while the job is running.

  5. Stonebranch UAC can run the following functions for the application:

    1. Start Application

    2. Get Status of the Application

    3. Wait until the Application is started or stopped

    4. Stop Application

    5. Fetch Logs of Application operation

Stonebranch jobs conversion

The following diagram represents Stonebranch’s job conversion process during the modernization journey. It describes how the job schedules and tasks definitions are converted into a compatible format that can run AWS Mainframe Modernization batch tasks.

  1. For the conversion process, the job definitions are exported from the existing mainframe system.

  2. JCL files can be uploaded to the S3 bucket for the Mainframe Modernization application so that these JCL files can be deployed by the AWS Mainframe Modernization service.

  3. The conversion tool converts the exported job definitions to UAC tasks.

  4. After all the task definitions and job schedules are created, these objects will be imported to the Universal Controller. The converted tasks then run the processes in the AWS Mainframe Modernization service instead of running them on the mainframe.

Stonebranch UAC architecture

The following architecture diagram represents an active-active-passive model of high availability (HA) Universal Controller. Stonebranch UAC is deployed in multiple Availability Zones to provide high availability and support disaster recovery (DR).

Universal Controller

Two Linux servers are provisioned as Universal Controllers. Both connect to the same database endpoint. Each server houses a Universal Controller application and OMS. The most recent version of Universal Controller is used at the time it is provisioned.

The Universal Controllers are deployed in the Tomcat webapp as the document ROOT and are served on port 80. This deployment eases the configuration of the frontend load balancer.

HTTP over TLS or HTTPS is enabled using the Stonebranch wildcard certificate (for example, https://customer.stonebranch.cloud). This secures communication between the browser and the application.

OMS

A Universal Agent and OMS (Opswise Message Service) reside on each Universal Controller server. All deployed Universal Agents from the customer end are set up to connect to both OMS services. OMS acts as a common messaging service between the Universal Agents and the Universal Controller.

Amazon EFS mounts a spool directory on each server. OMS uses this shared spool directory to keep the connection and task information from controllers and agents. OMS works in a high-availability mode. If the active OMS goes down, the passive OMS has access to all the data, and it resumes active operations automatically. Universal Agents detect this change and automatically connect to the new active OMS.

Database

Amazon Relational Database Service (Amazon RDS) houses the UAC database, with Amazon Aurora MySQL–Compatible as its engine. Amazon RDS is helps in managing and offering scheduled backups at regular intervals. Both Universal Controller instances connect to the same database endpoint.

Load balancer

An Application Load Balancer is set-up for each instance. The load balancer directs traffic to the active controller at any given moment. Your instance domain names point to the respective load balancer endpoints.

URLs

Each of your instances has a URL, as shown in the following example.

Environment

Instance

Production

customer.stonebranch.cloud

Development (non-production)

customerdev.stonebranch.cloud

Testing (non-production)

customertest.stonebranch.cloud

 Note: Non-production instance names can be set based on your needs.

High availability

High availability (HA) is the ability of a system to operate continuously without failure for a designated period of time. Such failures include, but are not limited to, storage, server communication response delays caused by CPU or memory issues, and networking connectivity.

To meet HA requirements:

  • All EC2 instances, databases, and other configurations are mirrored across two separate Availability Zones within the same AWS Region.

  • The controller is provisioned through an Amazon Machine Image (AMI) on two Linux servers in the two Availability Zones. For example, if you are provisioned in the Europe eu-west-1 Region, you have a Universal Controller in Availability Zone eu-west-1a and Availability Zone eu-west-1c.

  • No jobs are allowed to run directly on the application servers and no data is allowed to be stored on these servers.

  • The Application Load Balancer runs health checks on each Universal Controller to identify the active one and direct traffic to it. In the event that one server incurs issues, the load balancer automatically promotes the passive Universal Controller to an active state. The load balancer then identifies the new active Universal Controller instance from the health checks and starts directing traffic. The failover happens within four minutes with no job loss, and the frontend URL remains the same.

  • The Aurora MySQL–Compatible database service stores Universal Controller data. For production environments, a database cluster is built with two database instances in two different Availability Zones within a single AWS Region. Both Universal Controllers use a Java Database Connectivity (JDBC) interface that points to a single database cluster endpoint. In the event that one database instance incurs issues, the database cluster endpoint dynamically points to the healthy instance. No manual intervention is required.

Backup and purge

Stonebranch Universal Controller is set to back up and purge old data following the schedule shown in the table.

Type

Schedule

Activity

7 days

Audit

90 days

History

60 days

Backup data older than the dates shown is exported to .xml format and stored in the file system. After the backup process is complete, older data is purged from the database and archived in an S3 bucket for up to one year for production instances.

You can adjust this schedule in your Universal Controller interface. However, increasing these time-frames might cause a longer downtime during maintenance.

Tools

AWS services

Stonebranch

  • Universal Automation Center (UAC) is a system of enterprise workload automation products. This pattern uses the following UAC components:

    • Universal Controller, a Java web application running in a Tomcat web container, is the enterprise job scheduler and workload automation broker solution of Universal Automation Center. The Controller presents a user interface for creating, monitoring, and configuring Controller information; handles the scheduling logic; processes all messages to and from Universal Agents; and synchronizes much of the high availability operation of Universal Automation Center.

    • Universal Agent is a vendor-independent scheduling agent that collaborates with existing job scheduler on all major computing platforms, both legacy and distributed. All schedulers that run on z/Series, i/Series, Unix, Linux, or Windows are supported.

  • Universal Agent is a vendor-independent scheduling agent that collaborates with existing job scheduler on all major computing platforms, both legacy and distributed. All schedulers that run on z/Series, i/Series, Unix, Linux, or Windows are supported.

  • Stonebranch aws-mainframe-modernization-stonebranch-integration AWS Mainframe Modernization Universal Extension is the integration template to run, monitor and rerun batch jobs in AWS Mainframe Modernization platform.

Code

The code for this pattern is available in the aws-mainframe-modernization-stonebranch-integration GitHub repository.

Epics

TaskDescriptionSkills required

Download the installation files.

Download the installation from Stonebranch servers. To get the installation files, contact with Stonebranch.

Cloud architect

Launch the EC2 instance.

You will need about 3 GB of extra space for the Universal Controller and Universal Agent installations. So provide at least 30 GB of disk space for the instance.

Add port 8080 to the security group so that it’s accessible.

Cloud architect

Check prerequisites.

Before the installation, do the following:

  1. Install Java as described in Downloading Java Runtime Environment.

    $ sudo yum -y update
$ sudo yum install java-11-amazon-corretto

    Be sure to use one of the supported JAVA versions. The previous command should install java-11. Check the Java version and be sure you are using version 11 before continuing.

  2. As described in Installing Apache Tomcat document, run the following commands.

    $ sudo yum install tomcat tomcat-admin-webapps
$ sudo systemctl enable tomcat
$ sudo systemctl start tomcat

  3. Create an Amazon Aurora database as described in Creating an Aurora MySQL DB cluster and connecting to it. Use Amazon Aurora MySQL-Compatible Edition.

    Choose a Master username and Master password. Keep the default values for the rest of the settings.

Cloud administrator, Linux administrator

Install Universal Controller.

  1. Upload the universal-controller-7.2.0.0.tar installation file to the EC2 instance.

  2. Unarchive the installation files to a temp folder.

    $ tar -xvf universal-controller-7.2.0.0.tar

  3. Give the installation script run permission.

    $ chmod a+x install-controller.sh

  4. Install the controller. This example uses the following command to install Universal Controller under /usr/share/tomcat. Use the Amazon Aurora database that you created in the previous steps.

    $ sudo ./install-controller.sh --tomcat-dir /usr/share/tomcat/ --controller-file universal-controller-7.2.0.0-build.145.war --dbuser admin --dbpass “****” --dbname uc --rdbms mysql --dburl jdbc:mysql://database-2-instance-1.cih63miincgy.us-east-1.rds.amazonaws.com:3306/

    The last line of the output of the script should be “Installation complete.”

  5. Navigate to the following URL in the EC2 instance.

    http://<public_ip>:8080/uc

  6. On the login screen, enter ops.admin in the Username section, and keep the Password field empty.

  7. Set a new password for the ops.admin user.

Cloud architect, Linux administrator

Install Universal Agent.

  1. Upload the sb-7.2.0.1-linux-3.10-x86_64.tar.Z installation file to the EC2 instance.

  2. Log in to the EC2 instance.

  3. Unarchive the Universal Agent installation package.

    $ zcat sb-7.2.0.1-linux-3.10-x86_64.tar.Z | tar xvf –

  4. Run the following command.

    $ sudo ./unvinst --oms_servers 7878@localhost --oms_autostart yes --python yes

  5. Create a PAM file.

    $ cp /etc/pam.d/login /etc/pam.d/ucmd

  6. Enable Autostart for Universal Agent.

    $ /sbin/restorecon -v /etc/rc.d/init.d/ubrokerd
Cloud administrator, Linux administrator

Add OMS to Universal Controller.

  1. Log in to Universal Controller with the ops.admin user.

  2. Choose the Services menu at the top left corner of the screen, and then choose the OMS Servers menu in the System

  3. In the OMS Server Address field, type localhost, and then save.

  4. You will see the status of the OMS server as Connected and the Session Status as Operational.

Universal Controller administrator
TaskDescriptionSkills required

Import Integration Template.

For this step, you need the AWS Mainframe Modernization Universal Extension. Ensure the latest released version of the .zip file is downloaded.

  1. Log in to the Universal Controller with the ops.admin user.

  2. Navigate to Services, Import Integration Template.

  3. Select the Integration Template .zip file (aws_mainframe_modernization_stonebranch_extension.zip), and choose Import.

After the Integration Template is imported, you will see AWS Mainframe Modernization Tasks under Available Services.

Universal Controller administrator

Enable resolvable credentials.

  1. Navigate to Services, AWS Mainframe Modernization Tasks.

  2. On the right panel, fill in the required fields:

    • Name: New Mainframe Modernization Task

    • Agent: Select the only agent (AGNT0001).

    Under AWS Mainframe Modernization Details:

    • Action: List Environments

    • AWS Credentials: If you have an AWS Identity and Access Management (IAM) role added to the EC2 instance, you can keep this field empty. If you will use AWSAccessKeyID and AWSSecretKey, choose the icon () next to the field.

    In the Credential Details window that opens, enter the following information and then save.

    • Name: AWS Mainframe Modernization Credentials

    • Runtime User: Write the AWS access key ID in this field.

    • Runtime Password: Write the AWS secret key in this field.

    • End Point: Be sure that the endpoint has the correct AWS Region. The default is https://m2.us-east-1.amazonaws.com.

    • Region: Enter the Region of the AWS Mainframe Modernization service. The default is us-east-1.

  3. Keep the default values in the rest of the fields, and save the task.

Universal Controller administrator

Launch the task.

  1. At the top of the right panel, choose Launch Task.

  2. In the Confirm window, choose Launch. After that, the Universal Controller Console will display a message similar to the following message.

    2022-08-24 10:11:49 AM

    Successfully launched the Universal task "New Mainframe Modernization Task" with task instance sys_id 1661291493634146313NC8E38DB8OZJY.

  3. Navigate to the Instances If you don’t see the Instances tab, choose the right arrow to scroll right.

  4. Open the context (right-click) menu for the task instance in the list, choose Retrieve Output, and then choose Submit in the Retrieve Output

  5. In the Retrieve Output window, you will see the list of environments in STDOUT.

Universal Controller administrator
TaskDescriptionSkills required

Create a task for the batch job.

  1. Navigate to Services, AWS Mainframe Modernization Tasks.

  2. On the right panel, fill in the required fields:

    • Name: New Mainframe Modernization Task

    • Agent: Select the only agent (AGNT0001).

    Under AWS Mainframe Modernization Details:

    • Action: Start Batch (or Start Batch and Wait to run the batch job and wait until the task completes in AWS)

    • AWS Credentials: If you have an IAM role added to the EC2 instance, you can keep this field empty. If you will use AWSAccessKeyID and AWSSecretKey, choose the icon () next to the field.

    • End Point: Be sure that the endpoint has the correct AWS Region. The default is https://m2.us-east-1.amazonaws.com.

    • Region: Enter the Region of the AWS Mainframe Modernization service. The default is us-east-1.

    • Application: Choose the icon next to the field (), and choose Submit in the Refresh Application Choices. This will connect to the AWS Mainframe Modernization service and return the list of applications. Now you can select the application from the dropdown list. Select the application you want to run the batch job.

    • JCL File Name: RUNHELLO.jcl

    • Wait for Success or Failure: If this option is selected, the task will wait until the status of the batch job is success or failure.

    • Polling Interval: This is the amount of time between each polling.

    • Fetch Execution Logs: If selected, logs will be fetched automatically when the batch job has completed.

    • Log Format: This is the format of the logs to be printed out. It can be Text or JSON format.

  3. Keep the default values in the rest of the fields, and save the task.

Universal Controller administrator

Launch the task.

  1. At the top of the right panel, choose Launch Task.

  2. In the Confirm window, choose Launch. After that, the Universal Controller Console will display a message similar to the following message.

    2022-08-24 11:11:59 AM

    Successfully launched the Universal task "Mainframe Modernization Start Batch" with task instance sys_id <sys id>.

  3. Navigate to the Instances If you don’t see the Instances tab, choose the right arrow to scroll right.

  4. Open the context (right-click) menu for the task instance in the list, choose Retrieve Output, and then choose Submit in the Retrieve Output

  5. In the Retrieve Output window, you will see the list of environments in STDOUT.

Universal Controller administrator
TaskDescriptionSkills required

Copy the tasks.

  1. Open the context (right click) menu for the task that you want to create copies of, and choose Copy.

  2. In the Copy AWS Mainframe Modernization Task window enter the following new name for the new task: Mainframe Modernization Start Batch - RUNAWS2.

  3. Copy the task again, using the following name: Mainframe Modernization Start Batch - RUNAWS3.

  4. Copy with the task again, using the following name: Mainframe Modernization Start Batch - RUNAWS4.

  5. Copy the task a final time, using the following name: Mainframe Modernization Start Batch - FOOBAR.

Universal Controller administrator

Update tasks.

  1. Open (double-click) the Mainframe Modernization Start Batch - RUNAWS2 task, change the JCL File Name field to RUNAWS2.jcl, and save.

  2. Open (double-click) the Mainframe Modernization Start Batch - RUNAWS3 task, change the JCL File Name field to RUNAWS3.jcl, and save.

  3. Open (double-click) the Mainframe Modernization Start Batch - RUNAWS4 task, change the JCL File Name field to RUNAWS4.jcl, and save.

  4. Open (double-click) the Mainframe Modernization Start Batch - FOOBAR task, change the JCL File Name field to MISSING.jcl, and save. This task will fail because the JCL File Name value is incorrect.

Universal Controller administrator

Create a workflow.

  1. Navigate to Services, Workflows.

  2. On the right panel, enter Mainframe Modernization Workflow in the Name field, and save.

  3. In the right panel, choose Edit Workflow.

  4. On the Workflow Editor Tab, the Add Task button (+).

  5. In the Task Find window, choose Search to see all the tasks in the Universal Controller.

  6. Click the icon next to Mainframe Modernization Start Batch Task, and drag the icon into an empty place in the Workflow Editor.

  7. Repeat the same action for the other Mainframe Modernization tasks and place them as shown in the Additional information section.

  8. Choose the Connect button (), and connect the tasks together. To connect a task with another, click in the middle of a task, and drag it to the target task.

  9. Connect the tasks as shown in the Additional information section, and save the workflow.

  10. Right-click an empty place in the Workflow Editor, choose Launch Workflow, and then choose OK.

Universal Controller administrator

Check the status of the workflow.

  1. On the left menu, choose the Activity

  2. In the middle of the window, choose Start.

    You will see the list of task instances in the list.

  3. Open (double-click) Mainframe Modernization Workflow in the list, or open the context (right-click) menu and choose Workflow Task Commands, View Workflow.

    You will see the tasks as shown in the Additional information section. The second task was expected to fail because you used a missing JCL file.

Univeral Controller administrator
TaskDescriptionSkills required

Fix the failed task and rerun.

  1. Open (double-click) the failed task to see the error for the task.

  2. You have two options for fixing the failed task.

    • Fix the JCL file name, and set it to FOOBAR.jcl.

    • Add the correct JCL file name to the JCL File Name (Temp). This field will overwrite the JCL File Name field.

    For this pilot, choose the second option, and save the task instance.

  3. In the Workflow Monitor, open the context (right-click) menu for the failed task, and choose Commands, Re-run.

  4. After that, all the tasks will complete successfully.

Universal Controller administrator
TaskDescriptionSkills required

Create the Start Application action.

  1. Navigate to Services, AWS Mainframe Modernization Tasks.

  2. On the right panel, fill in the required fields.

    • Name: Mainframe Modernization Start Application

    • Agent: Select the only agent (AGNT0001)

    Under AWS Mainframe Modernization Details:

    • Action: Start Application

    • AWS Credentials: If you have an IAM role added to the EC2 instance, you can keep this field empty. If you will use AWSAccessKeyID and AWSSecretKey, select the credential that you created before.

    • End Point: Be sure that the endpoint has the correct Region. The default is https://m2.us-east-1.amazonaws.com.

    • Region: Enter the Region of the AWS Mainframe Modernization service. The default is us-east-1.

    • Application: Choose the icon next to the field (), and choose Submit in the Refresh Application Choices. This will connect to the AWS Mainframe Modernization service and return the list of applications. Now you can select the application from the dropdown list. Select the application you want to run the batch job.

    • Wait for Success or Failure: If this option is selected, the task will wait until the status of the batch job is success or failure.

    • Polling Interval: This is the amount of time between each polling.

    • Fetch Execution Logs: If selected, logs will be fetched automatically when the batch job has completed.

    • Log Format: This is the format of the logs to be printed out. It can be Text or JSON format.

  3. Keep the default values in the rest of the fields, and save the task.

  4. Now copy this task and create a task for Stop Application. Change the name to Mainframe Moderinization Stop Application, and change the action to Stop Application.

Universal Controller administrator
TaskDescriptionSkills required

Create the Cancel Batch action.

  1. Navigate to Services, AWS Mainframe Modernization Tasks.

  2. On the right panel, fill in the required fields.

    • Name: Mainframe Modernization Cancel Batch Execution

    • Agent: Select the only agent (AGNT0001)

    Under AWS Mainframe Modernization Details:

    • Action: Cancel Batch Execution

    • AWS Credentials: If you have an IAM role added to the EC2 instance, you can keep this field empty. If you will use AWSAccessKeyID and AWSSecretKey, select the credential that you created before.

    • End Point: Be sure that the endpoint has the correct Region. The default is https://m2.us-east-1.amazonaws.com.

    • Region: Enter the Region of the AWS Mainframe Modernization service. The default is us-east-1.

    • Application: Choose the icon next to the field (), and choose Submit in the Refresh Application Choices. This will connect to the AWS Mainframe Modernization service and return the list of applications. Now you can select the application from the dropdown list. Select the application you want to run the batch job.

    • Wait for Success or Failure: If this option is selected, the task will wait until the status of the batch job is success or failure.

    • Polling Interval: This is the amount of time between each polling.

    • Fetch Execution Logs: If selected, logs will be fetched automatically when the batch job has completed.

    • Log Format: This is the format of the logs to be printed out. It can be Text or JSON format.

  3. Keep the default values in the rest of the fields, and save the task.

Related resources

Additional information

Icons in the Workflow Editor

Tasks arranged with RUNHELLO on top, FOOBAR in the middle, and the remaining tasks at the third level.

All tasks connected

RUNHELLO connects to FOOBAR, which connects to the three remaining tasks.

Workflow status

FOOBAR task fails and the remaining three tasks are waiting.