AWS transform documentation change
Summary
Restructured mainframe modernization workflow documentation by replacing multiple steps with consolidated 'Assess and reimagine job plan', 'Reimagine job plan', and 'Custom job plan' sections. Added detailed content for business function assessment, Neptune connector setup, traceability artifacts, and updated SMF analysis requirements.
Security assessment
The changes reorganize workflow documentation and add technical details about Neptune/S3 connectors, but contain no evidence of addressing security vulnerabilities or weaknesses. Security configurations mentioned (VPC security groups) are standard cloud infrastructure practices without indicating remediation of specific security issues.
Diff
diff --git a/transform/latest/userguide/transform-app-mainframe-workflow.md b/transform/latest/userguide/transform-app-mainframe-workflow.md index cede1f2d3..e3f5c5f5c 100644 --- a//transform/latest/userguide/transform-app-mainframe-workflow.md +++ b//transform/latest/userguide/transform-app-mainframe-workflow.md @@ -7 +7 @@ -Prerequisite: Prepare project inputs in S3Sign-in and create a jobTracking transformation progressSet up a connectorAnalyze codeData analysisActivity metrics analysisGenerate technical documentationExtract business logicDecompositionMigration wave planningReforge codePlan your modernized applications testingGenerate test data collection scriptsTest automation script generationDeployment capabilities in AWS Transform +Prerequisite: Prepare project inputs in S3Sign-in and create a jobTracking transformation progressSet up a connectorAssess and reimagine job planReimagine job planCustom job plan @@ -25 +25 @@ AWS Transform accelerates the transformation of your mainframe modernization app - * Analyze code + * Assess and reimagine job plan @@ -27 +27 @@ AWS Transform accelerates the transformation of your mainframe modernization app - * Data analysis + * Reimagine job plan @@ -29,19 +29 @@ AWS Transform accelerates the transformation of your mainframe modernization app - * Activity metrics analysis - - * Generate technical documentation - - * Extract business logic - - * Decomposition - - * Migration wave planning - - * Reforge code - - * Plan your modernized applications testing - - * Generate test data collection scripts - - * Test automation script generation - - * Deployment capabilities in AWS Transform + * Custom job plan @@ -80,8 +61,0 @@ AWS Transform is capable of handling complex mainframe codebases. To use codebas -**Download modernization tools** - -For a test environment modernizing mainframe applications, beyond the automation necessary to run test cases at scale, AWS Transform makes tools available to achieve specific testing tasks. These tools include Data Migrator, designed to facilitate the migration of database schemas and data from legacy systems, Compare tool, to automate the verification that a modernized application produces the same results as reference data, and Terminals, to provide capabilities to connect to legacy mainframe and midrange screen interfaces to capture scenario scripts and videos, in the context of capturing online test cases. These tools are downloaded in your S3 bucket. - -**Optional configuration of S3 vector bucket.** - -In Regions where S3 vector buckets are available, AWS Transform will store searchable vector encodings of job output in this S3 vector bucket in your account to provide an AI powered search and chat experience. Data is not used outside of this job, and is not used to train models. T o enable this, you must create and provide S3 vector bucket. AWS Transform automatically creates and attaches a role with required permissions to write to this bucket. - @@ -96,2 +69,0 @@ To sign into the AWS Transform web experience, follow all the instructions in th -When setting up your workspace for mainframe transformation, you can optionally 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. Or you can set up the S3 bucket when setting up the connector as well. For more information, see Set up a connector. - @@ -102,2 +73,0 @@ When setting up your workspace for mainframe transformation, you can optionally -When you set up your workspace for mainframe transformation, you must 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. Alternatively, you can set up the S3 bucket when setting up the connector as well. - @@ -123 +93 @@ You can track the progress of the transformation throughout the process in two w -Set up a connector with your Amazon S3 bucket so that AWS Transform can access your resources and perform transformation functions. +AWS Transform uses a connector to access resources in your account that are required for mainframe modernization functions. Your connector is automatically configured with the first job you run in the workspace. Depending on the job plan you choose, AWS Transform guides you to create your connector. @@ -125 +95 @@ Set up a connector with your Amazon S3 bucket so that AWS Transform can access y -This is some of the information that AWS Transform might ask you to provide: +### Mainframe reimagine connector @@ -127 +97 @@ This is some of the information that AWS Transform might ask you to provide: - * AWS account ID for performing mainframe modernization capabilities +The mainframe reimagine connector is for jobs running the assess and reimagine workflow. It uses an S3 bucket to access and store transformation resources, and an Amazon Neptune cluster to store extracted artifacts. The Neptune cluster serves as the unified knowledge graph that stores all extracted artifacts about your job, and the knowledge graph answers all questions in the AWS Transform chat interface. @@ -129 +99 @@ This is some of the information that AWS Transform might ask you to provide: - * Amazon S3 bucket ARN where your transformation resources are stored +You must deploy the Amazon Neptune cluster in a VPC where AWS Transform can create elastic network interfaces (ENIs) in the VPC, load data from S3 into Neptune, and query the graph. Provide the following details when you configure your connector: @@ -131 +101 @@ This is some of the information that AWS Transform might ask you to provide: - * Amazon S3 bucket path for the input resources you want to transform + * **S3 bucket ARN** – The S3 bucket ARN identifies the bucket that stores all transformation resources. @@ -133 +103 @@ This is some of the information that AWS Transform might ask you to provide: - * Whether to enable AWS Transform chat to learn from your job progress (optional) + * **Neptune cluster ARN and resource ID** – We recommend an Amazon Neptune Serverless cluster with scaling from 1–128 NCUs. @@ -134,0 +105 @@ This is some of the information that AWS Transform might ask you to provide: + * **Subnets and security group** – AWS Transform requires a subnet and security group with access to the Neptune cluster and to the internet to reach AWS Transform APIs. @@ -138 +109,8 @@ This is some of the information that AWS Transform might ask you to provide: -Once you have set up your S3 connector and S3 project inputs, and shared an S3 vector bucket for indexed output, you can create a job based on the objective of the mainframe modernization project. Here is the full list of capabilities you can select from with dependencies noted For example, code analysis is required for most steps. + +We recommend using the following CloudFormation template to create the resources required for your mainframe reimagine connector. Use the same S3 bucket that you plan to use for the connector when you run the template. The Outputs tab of the CloudFormation template includes the details you need to configure the connector. + +[Download the CloudFormation template](https://d3lxw3eiclnnkx.cloudfront.net/neptune-kg-setup.yaml). + +### S3 connector + +For jobs with a custom job plan, AWS Transform can use an S3 connector. The S3 connector uses an S3 bucket to access and store transformation resources, and an S3 vector bucket for indexed output. @@ -142 +120,5 @@ Once you have set up your S3 connector and S3 project inputs, and shared an S3 v -Your data is stored and persisted in the AWS Transform's artifact store in your workspace and is used only for running the job. +Your data is stored and persisted in the AWS Transform artifact store in your workspace and is used only for running the job. + +**Optional configuration of S3 vector bucket.** + +In Regions where S3 vector buckets are available, AWS Transform will store searchable vector encodings of job output in this S3 vector bucket in your account to provide an AI powered search and chat experience. Data is not used outside of this job, and is not used to train models. To enable this, you must create and provide S3 vector bucket. AWS Transform automatically creates and attaches a role with required permissions to write to this bucket. @@ -144 +126 @@ Your data is stored and persisted in the AWS Transform's artifact store in your -### S3 bucket CORS permissions +#### S3 bucket CORS permissions @@ -146 +128 @@ Your data is stored and persisted in the AWS Transform's artifact store in your -When setting up your S3 bucket to view artifacts in AWS Transform, you need to add this policy to the S3 bucket's CORS permission. If this policy is not set up correctly, you may not be able to use the inline viewing or file comparison functionalities of AWS Transform. +When setting up your S3 bucket to view artifacts in AWS Transform, you need to add this policy to the S3 bucket's CORS permission. If this policy is not set up correctly, you might not be able to use the inline viewing or file comparison functionalities of AWS Transform. @@ -171 +153,157 @@ When setting up your S3 bucket to view artifacts in AWS Transform, you need to a -## Analyze code +## Assess and reimagine job plan + +The Assess and reimagine job plan is a predefined workflow for modernizing mainframe applications. It guides you through two phases: assessing your codebase to identify business functions, and reimagining the functions you select. To choose individual capabilities instead, use the Custom job plan. + +### Assess + +Mainframe modernization journeys typically start with evaluating the codebase to identify contents and understand relationships and dependencies. After this evaluation, you can start to decompose and select portions of the source code to modernize. The boundaries of decomposition are determined based on business functions. + +The business function catalog decomposes your codebase into discrete business functions, which are built on a foundation of deterministic data paths that map each business function from start to finish. A data path is the route that data takes, starting with a business trigger through to the final write within the mainframe code. Rather than limiting analysis to a single entry point, the system spans batch jobs, CICS transactions, and their shared data stores to identify coherent units of business work. + +A business function is a body of work that starts from a business trigger and ends at a measurable business outcome. AWS Transform provides a catalog of business functions that a line of business can act on, enabling informed decisions about what to modernize first. + +Benefits of assessing your codebase to modernize using business functions: + + * **Full-estate visibility** – Understand how your batch jobs, online transactions, and data stores connect into meaningful functions for your business. + + * **Actionable boundaries** – Each identified business function is a self-contained unit that your line-of-business stakeholders can review and prioritize for modernization effort. + + * **Consistency from code to specification** – The same code blocks that define a business function are used to generate its specifications, with no translation layer and no reconciliation required. + + * **Reduced discovery time** – Automated detection replaces months of manual tribal-knowledge interviews with systematic, repeatable analysis. + + + + +#### Results of assessment provided through the chat + +The results of assessment provided through the chat include a list of business functions, including the number of data paths, what each function spans in terms of batch and CICS transactions, and a business description. You are provided with a link to the artifacts generated in the Amazon S3 bucket, and you can also access them through the chat. Two artifacts are provided: business function details and business function summary. + + * **Business function summary** – Provides a list of the business functions and a natural-language description of what functions the elements within the code are performing. + + * **Business function details** – Provides an interactive graph that depicts the relationships across the source code. + + + + +To interact with the graph, select an element to show additional details about it, or open an element to interrogate its details. Within each page, there is a summary of all elements at that level and a graphical interface to interact with and learn more about each component, including the following: + + * **Business function** – Depicts which business functions are connected to each other and provides an overview of each business function. When you select a business function, the following information is provided: + + * Number of data paths + + * Number of lines of code + + * Business description: an overview of the business function that describes, in natural language, what functions the elements within the code are performing. + + * Interfaces: details how data elements within the business function relate (for example, exchange or write). + + * **Business function details** – Depicts the connections across the data paths within a single business function, allowing you to dive deeper into the composition of the business function. When you select an element, you see how that element connects across the business function, along with the following details: + + * Datastore: writers and readers for the datastore. + + * Other elements: an overview of the related data path that describes, in natural language, the actions and outcomes handled within the data path, a list of programs, and readers and writers. + + * **Data paths** – Depicts the details of one data path and how the elements within the data path relate to each other. + + * Description: an overview of the data path that describes, in natural language, the actions and outcomes handled within the data path. + + * Contents of the data path: + + * Entry point + + * Reads + + * Writes + + * Programs + + + + +Through the chat, you can interrogate the outputs to understand the elements contained within each business function, and explore the boundaries through the business function graph. + +After you identify the boundaries of your modernization, the chat prompts you to select the business functions that you want to reimagine. You can select a single business function or multiple business functions. AWS Transform sends the selected boundaries and the required assessment outputs to the reimagine flow to continue the modernization journey. + +After you complete your first modernization, you can use the chat to select an additional set of business functions to modernize. + +### Reimagine + +In the reimagine phase, you can select one or all of the business functions that assessment identified and prepare them for modernization. This triggers business logic extraction followed by requirement generation for the selected business functions. The generated requirements are the primary input for forward engineering, translating legacy system understanding into a precise specification of what the modernized application must deliver. + +#### Extract business logic + +After you select one or more business functions, AWS Transform begins generating business logic for the selected business functions. After extraction is complete, AWS Transform stores the results in an Amazon S3 bucket in JSON format for downstream use. You can monitor the progress of the extraction and review any issues directly within the AWS Transform console. + +###### To review business logic extraction results + + 1. In the left navigation pane, choose the **Extract business logic** step to expand it. + + 2. View the following from the step details: + + * **S3 bucket link** : The location where the extracted business logic results are stored in JSON format. + + * **Issues** : A list of any issues encountered during the business logic extraction process. + + + + +If any files encountered issues during extraction, the following details are displayed for each affected file: + + * **File name** : The name of the file that encountered an issue. + + * **File type** : The type of the file (for example, COBOL or JCL). + + * **File path** : The location of the file within your application. +