Way of Working

Activity: Entity and Requirements Traceability Matrix

01 March 2021 • 4 minutes

Written by Tessa Mylonas

Way of Working title image

Systematically record a divide-and-conquer migration pattern.

The Entity and Requirements Traceability Matrix is used to help systematically record a divide-and-conquer migration pattern. It is possible to create a traceability matrix using a spreadsheet and use the Codebots Platform to assist with the process.

Before you start

The requirements backlog must be up to date. If you do not have a requirements backlog, follow the Activity: Reverse Engineering Requirements activity. You will also need to have access to the legacy database schema(s) and get a list of all the tables.


Level of difficulty




Suggested time

Ideally less than the maximum iteration time (usually 2 weeks)




  1. Access the the Entity and Requirements Traceability Matrix spreadsheet from the Codebots website. Open it up, save a copy and have a look around.
  2. Populate the entities on the ‘entity’ sheet as shown in the image below. The entities are the tables found in the legacy database schema. It is recommended to include all of them to ensure that nothing is missed from the legacy database.

  3. Populate the stories on the ‘requirements’ sheet as shown in the image below. The stories are the requirements and can be reverse engineered from the legacy system.

  4. In the ‘traceability’ sheet, indicate relationships between the different entities and requirements by entering values into the corresponding cell. If done correctly, on either the ‘entities’ sheet, you will be able to see each entity and it’s related requirements, or vice versa on the ‘requirements’ sheet.

  5. Inspect the stats sheet to gain insight on the project and it’s coverage.


Rather than the size, the difficulty with complex legacy migration projects is the systematic approach to how they are migrated over time. There will be a significant amount of effort in establishing what the legacy system actually does, and what parts of the organisation it is used in. The journey of continuous modernisation is to find a software/people fit so that the organisation can be agile and meet change. The traceability matrix presented in this migration kit activity goes a long way to helping the journey.

Before this activity is started, the requirements are reverse engineered from the legacy system. This activity by itself gives a target list of stories. However, for large and complex systems where a big bang or firecracker is not feasible, the project must be broken down into a number of iterations. Our way of working is to group several iterations into a milestone and use scoping iterations (as shown in the figure below). Each iteration will contain stories based on the goals and value that will be delivered. Using the Entity and Requirements Traceability Matrix, it is now possible to work out which entities must be included as part of this iteration. This shines a significant amount of light onto the project and allows a systematic approach to the migration process.


However, there are a few traps to look out for that can arise from this process. What happens when an entity belongs to two requirements that are in different iterations? There are a few ways to work around this. First, does it make sense for the requirements to be shifted into the same iteration? If it does, then shift the requirements so they are in the same iteration. If it does not, you can leave the requirements in separate iterations, but the isolation checker will fail in the divide-and-conquer migration pattern. Recall that the isolation checker is a safe guard that ensures the data integrity of the new application. To make sure the isolation checker is going to function as expected, any releases which include an entity must include all of the requirements that relate to that entity. A nice way to ensure this is to use milestones to group iterations that cover all the requirements for the entities being migrated to the new application.

Furthermore, the Entity and Requirements Traceability Matrix can be used to help decide on the boundaries for the new microservice applications. We have included another approach called the Activity: Bubble context and anti-corruption layer. A different approach is to base the new application suite on the natural boundaries that arise from the matrix. For some legacy systems, the matrix can help reveal a new set of microservices relatively quickly, but for some more complex legacy systems the new set of microservices is not as obvious.

Tessa Mylonas

Written by Tessa Mylonas

Head of Support and Education

If Tessa isn’t busy answering support questions or educating you about the Codebots products, she is typically found putting together flat-pack furniture, playing with her chocolate Labradors or hoarding houseplants.