Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Transformation of mainframe applications

Focus mode
Transformation of mainframe applications - Amazon Q Developer

Amazon Q Developer accelerates transformation of your mainframe modernization applications from COBOL to Java. The following document guides you through the process of leveraging generative AI and automation of the transformation capabilities of Amazon Q Developer for analyzing codebases, planning transformation, and executing the refactoring in an accelerated manner. All of this while preserving your mission-critical business logic.

Note

The transformation capabilities of Amazon Q Developer are in preview release, and are subject to change.

Step 1: Sign in and onboarding

To sign into the Amazon Q Developer transformation web experience, follow all the instructions in Setting up your workspace section of the documentation.

(Optional) When setting up your workspace for mainframe transformation, set up an Amazon S3 bucket to be used with the S3 connector. After creating the bucket and uploading the desired input files into the bucket, save that S3 bucket ARN for use later.

Step 2: Create and start a job

Follow these steps to start a new job in your workspace.

  1. On your workspace landing page, choose Ask Q to create a job.

  2. Next, choose Perform mainframe modernization (z/OS to AWS) for modernizing your mainframe application.

  3. In the chat window, Q will ask you to confirm the job details, such as, the job name, and what steps you want this job to perform.

    Note

    You can ask Q to perform any combination of the capabilities mentioned in High-level walkthrough.

  4. Once confirmed, choose Create and start job.

Q will then kick off the modernization for your job.

Step 3: Set up a connector

In this step, you set up a connector with your Amazon S3 bucket that allows Amazon Q Developer to access resources, and perform consecutive transformation functions.

  1. Under job plan, expand Kick off modernization, and choose Connect to AWS account.

    Note

    You will directly skip to Specify resource location page if you have already created a connector and added S3 bucket when creating your workspace.

  2. Enter the AWS account ID you would like to use to perform the mainframe modernization capabilities.

  3. Choose Next.

  4. Enter the Amazon S3 bucket ARN from earlier where your resources are stored for transformation of your mainframe applications.

  5. Choose Create connector.

Once you add the Amazon S3 bucket ARN, you will get a verification link. You must share this link with your AWS administrator, and ask them to approve the request in the AWS Management Console. After the request is approved, you will see connection details with Amazon S3 as the connector type.

Note

If you need to create a different connector, you can choose to restart the connection process.

When your connector is set to active, on the Specify asset location page, enter the Amazon S3 bucket path for the input resources you would like to transform for your mainframe applications. Then, choose Approve and send to Q.

Step 4: Tracking transformation progress

You can track the progress of the transformation throughout the process in two ways:

  • Worklog – This provides a detailed log of the actions Q takes, along with human input requests, and your responses to those requests.

  • Dashboard – This provides high-level summary of the mainframe application transformation. It shows metrics on number of jobs transformed, transformation applied, and estimated time to complete the transformation of mainframe applications. If you like, you can also see details of each step including, lines of code by file types, generated documentation by each file type, the decomposed code, migration plan, and the refactored code.

Step 5: Code analysis

After you share the Amazon S3 bucket path with Q, it will analyze the code for each file with details such as file name, file type, lines of code, and their paths.

Under Analyze code in the left navigation pane, choose View code analysis results.

You can view your code analysis results in multiple ways:

  • List view – All files in the Amazon S3 bucket you want to transform for mainframe

  • File type view – All files in the Amazon S3 bucket displayed per file type. For a list of currently supported file types, see Supported files.

  • Folder view – All files in the Amazon S3 bucket displayed in folder structure.

  • Missing files view – Missing files from the mainframe modernization code analysis. These files ideally, should be added as a part of the source input in Amazon S3 bucket for better and cohesive results.

Note

Non-IBM mainframe files are currently not supported for transformation by Q for code analysis.

Step 6: Generate documentation

In this step, you can generate documentation for your mainframe applications undergoing modernization. By analyzing your code, Q can automatically create detailed documentation of your application programs, including descriptions of the business logic, flows, integrations, and dependencies present in your legacy systems. This documentation capability helps bridge the knowledge gap, enabling you to make informed decisions, and preserve the critical business logic as you transition your applications to modern cloud architectures.

To generate documentation
  1. In the left navigation pane, under Generate documentation, choose Select files and configure settings.

  2. Select the files in the Amazon S3 bucket that you want to generate documentation for, and configure the settings in the Collaboration tab.

    Note

    Selected files should have same encoding type (that is, all in the same CCSID - UTF8 or ASCII). Otherwise, generated documentation might have empty fields or sections.

  3. Choose the documentation detail level:

    • Summary – Provides a high-level overview of each file in the scope. Also, gives a one-line summary of each file.

    • Detailed functional specification – Provides comprehensive details for each file in the mainframe application transformation scope. Some details include logic and flow, identified business rules, data flow, dependencies, input and output processing, and various transaction details.

    Note
    1. Currently, documentation can be generated only for COBOL, JCL, and Assembler files.

    2. The pricing for generating documentation varies per the detail level. For more information, see Amazon Q Developer pricing.

  4. Choose Send to Q.

  5. Once Q generates documentation, review the documentation results by following the Amazon S3 bucket path in the console, where the results are generated and stored.

Important

Amazon Q Developer will refuse questions from users who don’t have the proper permissions. For example, a contributor cannot cancel a job transformation of mainframe applications or delete a job. Only an administrator can perform those functions.

Step 7: Decomposition

In this step, you decompose your code into domains that accounts for dependencies between programs and components. This helps ensure that related files and programs are appropriately grouped within the same domain. It also helps maintain the integrity of the application logic during the decomposition process.

  1. Expand Decompose code from the left navigation pane.

  2. Choose Decompose into domains.

    Note

    Two domains (unassigned and disconnected) are automatically created initially by the application. Unassigned domain strictly is under decomposition control and can't be edited.

  3. Create a new domain by choosing Create domain from the Q prompt (for first domain only), or from under Actions menu.

  4. Provide domain name, optional description, and mark some files as seeds. Seeds are elements that are labeled with business features or functions for Q to group related components into domains. Seeds act as a semantic link between technical code and business context by providing a connection between the code elements and their corresponding business domains.

    CICS configured files (CSD) and Scheduler configured files (SCL) can be used for automatic seed detection.

    Note

    You can also set one domain only as a common component. The files in this domain are common to multiple domains.

  5. Choose Create.

    Note

    You can create multiple domains with different files as seeds.

  6. After confirming all domains and seeds, choose Decompose.

  7. Q will check the source code files and then decompose into domains with programs and data sets with similar use cases and high programming dependencies.

    Q gives you a tabular and graph view of decomposed domains as dependencies. Graph view has two options:

    • Domain view – Can view how different domains are related to each other in visual format.

    • Dependency view – Can view all files in each domain as a complex dependency graph. If a node that was added to a domain didn't receive information from a seed in the same domain, then this node will either be predicted into unassigned (node didn't receive any information), disconnected (in a sub graph that didn't receive seed information) or into another domain (node received information from at least that domain).

    Repeat these steps to add more domains or to reconfigure your already created domains with a different set of seeds if you don’t like current domain structure.

  8. When completed, choose Approve and send to Q.

Step 8: Migration wave planning

Based on the domains you created in the previous step, Q generates a migration wave plan with recommended modernization order.

  1. To view the planning results, choose Plan Migration Wave, and then choose Review Planning Results.

  2. Review the domain wave plan (either in a table view or a chart view).

  3. You can either choose to go with the recommended migration wave plan generated by Q or add your preference manually by importing a JSON file.

    Note

    You can choose to migrate multiple domains in a single wave.

  4. (Optional) If you decide to manually adjust migration wave plan, Q generates a new migration wave plan per your preference. You can also adjust the domains in each wave as required by choosing Add preference and then, Add and regenerate.

  5. After verifying, choose Approve and send to Q.

If you're satisfied with this migration plan, you can move next step for refactoring the code. If you need to adjust the preference, you can follow these steps again.

Step 9: Refactor code

In this step, Q refactors the code in all or selected domain files into Java code. The goal of this step is to preserve the critical business logic of your application while refactoring it to modernized cloud-optimized Java application.

  1. Navigate to Refactor code in the left navigation pane, and choose Domains to migrate.

  2. Select the domains you want to refactor.

  3. Choose Approve and send to Q. You can track the status of refactoring domains (and files in it) using the worklog. Q will do the transformation of the mainframe code, and generate results without any manual input.

  4. After refactoring completes, it will change the status to Completed in the worklog. You can view the results of refactored code by going to the Amazon S3 bucket where the results are stored. Each domain will provide a status for Transform (with each file), and Generate and will be marked as Done.

You might also see certain domains that have a Done with issues status. Expand those to see files showing a Warning status or an Error status. You can view the issues for the Warning and Error files, and choose to fix them for better refactoring results.

When all the steps are successfully completed, you will see each job task in the left navigation pane completed in green. Your worklog will also reflect this by giving a message that “Q project has completed.”

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.