In order to propose a new microService, you must perform the following steps:

1. Ensure that no other microService already exists that will meet your needs, or that can be extended to meet your needs.

2. Setup repository for the Domain Model

3. Perform Domain-Driven Design analysis to the point where you can identify the bounded contexts, and be able to justify your microService(s)

4. Adhere to Standards for Naming and API Design

5. Complete the MicroService Questionnaire for each microService.

6. Create MicroService Catalog entries ("Proposed" status)

7. Create and review the Cross-Tower MicroService Questionnaire

8. Receive approval to proceed

All microServices (mS) are registered in a central catalog, no matter what their current state (proposed, in-development, deployed, etc).  The catalog contains a great deal of information about each microService and provides access to the documentation about each microService. 

Before you propose a new mS , you must check the catalog to make sure that...

...there is not already a mS that does essentially the same thing your proposal does, and

...there is not already a mS that could be easily extended to accommodate your needs

To check the mS catalog, proceed to the   Catalog wiki page and access the appropriate catalog .

The domain model for the microService(s) should be retained and used over the life of the microService(s) just as if it was part of the source code.  The domain model created using Domain-Driven Design is a living model that will be initially created to identify the bounded contexts, then refined over the course of the microServices lifetimes.  The domain model is, for all practical purposes, another "source" artifact that needs to be managed as part of the domain. See Domain-Driven Design for more information as to what the model entails.

Since CDP requires the use of Git repositories for all source code that it builds and manages as part of the microService(s), one possible solution would be to create a CodeCloud project and repository for your domain model.  The model should be protected and recoverable in the event of a failure.  The actual storage of the domain model needs to protect your investment in the domain model.  This can be accomplished using Git or tSpace.

In either case, you will need to decide where and how you want to store, manage, and disseminate model information.  Most modeling tools provide the ability to create reports or extracts from the model for dissemination to external parties that do not have the modeling tool.  Enterprise Architect (by Sparx Systems, Ltd) also has the ability to export the model as a "web site" that can be "zipped" and distributed to members of the team.  The web archive allows the user to navigate the model in much the same way as using the tool, except that it is read-only.

If you already have a CodeCloud project, CDP can use that project and create repositories in it for each microService.  You can also create a repository in that project for the domain model and all DDD artifacts if so desired.  If you do not have a CodeCloud project and you want to set up one now for the DDD modeling effort, then see the page "Using Git With MicroServices". 

If you have your CodeCloud project (or you have created one) and you wish to setup a repository for the domain model, you can manually create the Git repository through the Arcade On Demand (AOD) dashboard.  If you are using a modeling tool such as Enterprise Architect, it may support Git directly and have the ability to push and pull the model automatically.  However, if you are using a tool that does not support Git, or you are sing a manual organization of design materials, you will need to configure a Git client on your workstation so that you can push and pull design artifacts yourself.  See "Using Git With MicroServices" for information on setting up a Git client on your workstation.

Perform enough Domain-Driven Design to identify the likely bounded contexts and high-level operations that will be required.  This will identify the needed microServices and provide enough insight into the domain to be able to proceed.  There are a lot of resources available to you to help perform the Domain-Driven Design process.  This does not mean you need, or even want to, create the complete design at this point.  You just need enough to be able to identify the bounded contexts that you are going to propose.  That does not mean that you may find other bounded contexts later (if you do, they will need to be proposed and approved using this same process).  It also does not mean that you cant change a proposed microService later by adding more operations, or changing some of the proposed operations.  If you do, you will need to update the microService catalog to reflect those changes.

A "taxonomy" is a systematic classification of the business into discrete functional areas.  The One ATT Taxonomy is defined by the TAM.  This classification assigns every business activity to some place in the hierarchy.

All microServices must be named using a namespace that is defined by the TAM.

 Every classification in the hierarchy has a long name, a short name, and a taxonomy ID (numeric).  For example, look at the fragment of the TAM below:

 

The root level categories are aligned to the left, and can be opened to show the entire classification under that category.  If we expand the "Sales & Marketing" category, we see numerous lower levels of classification.  For example,

Solution Design is part of Solution Management which is part of Sales & Marketing.  Every level in the hierarchy has a long name (descriptive name) and a short name.  The short name is shown in parenthesis.  The taxonomy id for "Solution Design" is 20.04.01.01.

When creating a microService for a business domain, the microService MUST be named with a namespace that is comprised from the taxonomy short names.  For example, a microService that provides functionality for "Solution Design" would have a namespace of "com.att.salesmarketing.soma.sode". 

The official TAM classifications are maintained on the MOTS site.

A Job Aid has been created to help explain how to use the TAM when naming your microServices.

The API exposed by all microServices must conform to the AT&T standards.  If your microService uses a RESTful API, then the RESTful Web Services Standards apply.  If they are SOAP-based, then the SOAP Web Services Standards apply.  In all cases, the API Platform Standards apply.

• • RESTful Web Services Standards
  • SOAP Web Services Standards
  • API Platform Standards

 

All microservices must conform  to the AT&T standards for their design and construction.  These standards also include standardized patterns that can be utilized to solve common problems. 

• • Microservice Standards

Complete the mS Questionnaire to document the intended purpose of your microServices, the domain they operate within, and the major operations that they will expose.  In order to complete this questionnaire, it is very helpful to have performed some of the Domain-Driven Design process.  The questionnaire is called the "MicroServices Maturity Model"and is used to gauge your level of maturity in your microService design and intended implementation.

After you have completed the maturity model assessment, you will need to upload it to tSpace and use that location in your catalog entries.  The maturity model assessment must be linked to the catalog entries for the review process.  See the page "Uploading and Linking mS Maturity Score" for more information and how to perform this step.

The microService Catalog is documented in its own wiki site.  Within that site, there are several pages that may be of interest.  See this page for information on the microService catalog, how to create entries, and what the entries must contain.

The cross-tower microService questionnaire form is a document that must be filled out and submitted when the review is scheduled.  The form is available on the cross-tower tSpace site.  The cross-tower CIO review team should be contacted to schedule the reciew and to assist you in completing and uploading the document.

When the mS questionnaire is reviewed by the cross-tower team, they will be looking for several things.  This includes sufficient evidence that you understand your domain, that the microServices that you are proposing are actually needed and will provide benefits to the organization, and that speed, costs, and quality will be improved.  In particular, they are going to look for the minimum artifacts to demonstrate this level of understanding. 

When you receive approval to proceed, you will continue to complete the domain-driven design, proceeding to detailed design, and start the project.  At this point, you will need to start finalizing the design and getting a much better feel for the capacity and demand for the microService.  This is input to the next step.

{width="8" height="8"} image2018-2-9 15:30:33.png (image/png)