Introduction

AWS Transform for mainframe is a powerful service that accelerate and simplify the modernization of mainframe applications and code with an Agentic AI experience. It orchestrates the analysis of mainframe codebases, generate documentation, extract business logic, decompose monolithic structures, transform legacy code, and manage the overall journey with human inputs (HITL) when needed.

In this article we will focus on how to set up the AWS Transform and generate the BRE documentation for mainframe COBOL application.

You may also refer to the article to learn about details of the outputs generated in BRE.

---

1. Setup AWS Transform and user access:

User access for AWS transform is controlled via AWS IAM Identity Center. Follow the steps here to enable the IAM Identity Center on your AWS account. Next, create the IAM Identity users following the steps here. To manage the users as part of a group you may also create IAM Identity Group and add the users into the group.

Enable AWS Transform

By default. AWS Transform is not enabled in AWS Account. To enable AWS Transform -

• Sign in to the AWS Management Console and in the search bar at the top of the console, search for "AWS Transform". Select AWS Transform from the search results.

• On the AWS Transform homepage, choose Get started.

• Select the Encryption Key and click Enable AWS Transform.

• Click on View Profile or Settings on left menu. This will display Web application URL - The URL for accessing the AWS Transform web application.

• Click Users on left menu to add IAM Identity Users or Groups to AWS Transform.

• Use Add and assign new users to add a new User directly, or use Assign existing users and groups to assign previously created IAM Identity users or groups to AWS Transform. Refer here for details around user management.

Note: Note the 'Web application URL' from setting page to access the AWS Transform application Console later.

---

2. Upload mainframe code to S3:

All the mainframe artifacts like COBOL, COPYBOOK, JCL, PROC, PARM, CSD, LISTCAT, DCLGEN, DBD, PSB, etc. should be downloaded from mainframe, packaged into a single zip file and uploaded to a S3 bucket in the same region as where AWS Transform is enabled.

In this article we are going to use the open-source CardDemo mainframe CICS application. Only the mainframe artifacts present in the app folder is zipped and uploaded to S3 bucket.

---

3. Create AWS Transform Workspace:

• Copy the Web application URL from AWS Transform settings page, open a new browser tab and paste the link. The Sign In page will appear. Provide the User name and Password. If multi-factor authentication is enabled, you will have to use MFA selected by your organization. Once signed in the application tab will show the Applications enabled for the user. Click AWS Transform image to open.

• If this is first-time login to AWS Transform a empty workspace is shown on the page. Click on the workspace to enter or click Create a workspace to create a new one.

• Inside the workspace there will be 2 split windows. Left hand side it shows the option to create job by clicking the button. Right hand side has the agentic chatbot with whom you can converse in natural language. On top middle you will see the Settings dropdown with various actions for the workspace and also a + sign which allows you to add invite other users to the workspace.

Note that AWS Transform is already added as a member of your team in workspace. This is the AI Agent. Refer to documentation for understanding different roles.

---

4. Create a mainframe Job:

• In the chat window click Perform mainframe modernization (IBM z/OS to AWS) radio button to start a mainframe workflow.

• Currently AWS Transform supports the following features - Analyze code, Generate technical documentation, Extract business logic, Decompose code, Plan Migration sequence and Transform code to Java. Here we are interested in business logic documentation, so lets type in 2 or Analyze code, Extract business logic in the chat window.

• Next, the chat will present proposed Job Name and Objective. If satisfied click on Create job, if not you can chat further to modify the Job name or Objectives.

• In the new window it will show the selected workflow steps on left panel. The window will show that its Awaiting for human input on top right.

• You can invite other users to the job by selecting Add Collaborators. Then type the IAM Identity User name or email in the search textbox.

• Click on Connect to AWS account to add the AWS account to connect the S3 bucket. Type in or paste the AWS Account id and click next.

• On next page provide the S3 Bucket ARN where the zip file with downloaded mainframe codes is uploaded. Click Create connector.

• This will create a verification link that needs to be shared with your AWS administrator for approval.

• Administrator can reach the approval page via the link shared or Connectors menu of AWS Transform console page.

• Once administrator approves the request click on Send to AWS Transform to proceed.

• The Worklog tab shows the logs from different tasks. On left pane you will see a new line item - Specify resource location appearing. Click on the link.

• Provide the S3 URI of the zip file from S3 bucket and click Send to AWS Transform to start the code analysis.

---

5. Mainframe Code Analysis:

• Once the analysis is complete click on View code analysis results. This will show the results on right hand window. Use the View by dropdown option to see the results in multiple ways. More details on the viewing options and actions available for code analysis is available in the documentation. Once satisfied with the result click Send to AWS Transform to proceed.

If you're having issues with inline viewer or file comparison make sure that the S3 bucket is set up correctly. For more information on S3 bucket's CORS policy, see S3 bucket CORS permissions.

• On Dashboard tab you can view the Code analysis metrics in graphical view. You can use the download link to download the results.

---

6. Submit BRE task:

• Click on Configure settings to open the BRE configuration page. In the Collaboration tab select how you want to extract business logic: Application level: Generates business documents for all business functions, transactions, batch jobs, and files. This selects all of the files in the application. File level: Generates business documents only for files you select from the file table.

Note

• For either option you can select Include detailed functional specification so that AWS Transform includes control flow and comprehensive business rules for the selected files.
• Selected files should have the same encoding type (that is, all in the same CCSID - UTF8 or ASCII). Otherwise, generated documentation might have empty fields or sections.
• Documentation can be generated only for COBOL and JCL files.
• For application level, programs used by CICS transactions and batch jobs are grouped together, while all other programs are categorized as Unassigned.

• After selection click Continue button to proceed. This might take a while, check the Worklog tab for progress.

---

7. View BRE Results:

• Once the BRE task completes click Review business logic extraction results on left pane to see the the results. For this workflow I had selected Application Level BRE. On the right hand pane it shows all the business domains identified. Select an element by clicking on the radio button and then click View results to view the BRE details.

• It shows the extracted business logics details. Scroll down to see different sections. Refer to the article to see all the comprehensive output generated in BRE.

You can drag the middle white line left or right to adjust the split window size.

---

8. Download the BRE HTML files:

• The extracted BRE details as seen in the AWS Transform UI are also saved as HTML files in the S3 bucket for offline viewing. The Business Rules are stored in a JSON file. The location of the S3 object containing the HTML and JSON files is provided on top of the Results page.

---

Tips:

1. The extracted business logic details are generated by AI and sometime it can make mistake in expanding the acronyms due to non-availability of the relevant context. Adding relevant user information into the documentation with user’s glossary file an significantly improve the quality of the output.

ARTIFACT_ID.zip
└── app/
    ├── File1.CBL
    ├── File2.JCL
    ├── subFolder/
    │   └ File3.CBL
└── glossary.csv   
└ ...

glossary.csv file: You can choose to provide and upload an optional glossary in the zip file in the source S3 bucket. Save the glossary as a CSV file named glossary.csv. The glossary helps creating documentation with relevant descriptions using the customer's vocabulary. A sample glossary.csv file looks like:

LOL,Laugh out loud
ASAP,As soon as possible
WIP,Work in progress
SWOT,"Strengths, Weaknesses, Opportunities and Threats"

2. If you need to stop the job, restart or even delete the job use the buttons at the top of the page. To bring up the chat window click on the AWS Transform icon at the bottom of the page.

3. Refer to the different quotas set for AWS Transform.

---

References:

[1] BRE Output explained

[2] AWS Transform for mainframe

[3] Skill Builder - AWS Transform for mainframe Fundamentals