3.2 Defining the Project in the Project Scope

You start the definition and design process within the project scope. In this scope, you assess what the system should achieve, the system's requirements (both business and technical), and the applications and services that will be needed to satisfy those requirements. At the end of this phase, you develop a solution specification that details the findings in this phase, and provides the necessary information to design and implement the individual applications in the application scope.

When designing the solution definition for the project, you take the following steps:

Create a service portfolio plan.

While technically part of the enterprise scope, the service portfolio plan is a collection of all services an enterprise currently has or will need. Creating and then maintaining this portfolio allows an enterprise to reuse existing services, thus reducing software and data redundancy. For more information, see Section 3.2.1, "Creating a Service Portfolio Plan".
Set business and system objectives.

When setting business objectives, you determine what the end result should be, without any regard to what may already exist. Your focus is on the solution of a business problem. Once set, these goals are used to drive requirements. For more information, see Section 3.2.2, "Determining Business and System Objectives".
Determine key business and operational requirements

While best practices for gathering requirements for an SOA project are the same as for any type of application or application integration project, there are some additional steps necessary to ensure that SOA benefits are fully realized. For example, the requirements for each service or piece of functionality in the project must take into account all parts of the project, and even services outside the project scope, and not just the service itself.

To achieve this, you design use cases for SOBAs (service-oriented business applications), which are large-grained use cases that encompass a specific business process. For example, a registration process might be considered a SOBA. Once you define a SOBA use case, you then focus on the use cases for each step within the SOBA's process, and the services each step uses. For more information, see Section 3.2.3, "Determining Business and Operational Requirements".
Conduct a discovery phase

This phase first includes analysis of the requirements in the previous step to determine a high-level design of the solution, without identifying any actual products or services that might be part of the solution. It then includes actual service discovery, where it is determined what existing services might provide needed functionality, what existing services might need to be modified, and what services will need to be created. For more information, see Section 3.2.4, "Conducting a Discovery Phase".
Define the business process orchestration layer and the services it invokes.

Once you have determined the business flows and services that need to be implemented, you begin defining how they will integrate. In the previous steps, the focus was on the high-level business needs. In this step, the focus shifts to technical needs. For example, in this step you define the business process model logic, process variable definitions, and more detailed exception handling. For services, you define the responsibilities of the services, along with their needed granularity. This definition provides a more precise understanding of the requirements and provides details on the internal workings of the system. For more information, see Section 3.2.5, "Defining the Project".
Create a solution specification that can then be used in the application scope of the project. For more information, see Section 3.2.6, "Creating a Solution Specification".

3.2.1 Creating a Service Portfolio Plan

You create a service portfolio plan in order to rationalize acquiring or developing new software applications. By creating and maintaining this plan, you ensure that existing services and applications are reused or repurposed whenever possible. This plan also reduces the time spent in creating needed functionality.

To create a service portfolio plan:

Conduct a top-down analysis of needed functionality (both existing and planned) for the enterprise.

To do this, execute you domain decomposition by restating the enterprise in terms of high-level business domains. Then you define services and their operations within each domain.

For example, Global Company sells electronics to consumers. In the past, they've conducted business through mail-order. Customers called into customer service representatives, who then entered customer and order information into the system. Much of the order process, such as credit validation and determining whether an order needed management approval, required swivel-chair (or manual) tasks. Global Company now wants their customers to be able to purchase products directly, using a web-based application. This means that many of the swivel-chair tasks must now be automated. In addition, Global Company would like to share the automated order booking functionality between the web system and the system used by the internal representatives.

To achieve this, Global Company performs a domain decomposition, as shown in Figure 3-1. This figure shows some of the high-level business domains, including Products, Operations, Order Booking, and Customers. For the Order Booking domain, it is determined that there are a number of services required to place an order, including procuring goods, validating credit, approving orders, order management, and shipping orders. It is further determined that the order management service might contain operations for getting and setting order information, and getting and setting status.

Figure 3-1 Partial Domain Decomposition for Global Company

The listing of services for each domain becomes the first version of the service portfolio.

Conduct a bottom-up analysis of existing applications and services.

To do this, you review all existing data and functionality currently in use, then aggregate them into groups that provide functionality for a specific task, and assign service descriptions to the aggregates. Typically, when this step is performed, you'll find additional services that were not captured in the top-down analysis.

For example, Figure 3-2 shows a partial listing of the existing aggregated services before Global Company created the SOA Order Booking application:

Figure 3-2 Partial Bottom-Up Analysis of Global Company

Bottom up analysis goes from functionality to services

Note that the Credit Validation service was discovered in this analysis. Very often, processes that involve systems external to the company are overlooked during the top-down analysis, and then discovered in the bottom-up analysis.

Tip:

Be sure to include in the portfolio any services necessary to communicate with applications external to the company. For example, the Order Booking project requires communication with a credit validation that is external to Global Company. This service should be included in Global Company's portfolio.

Conduct a business process tracing.

In this step, you note the business processes currently in place or needed within the enterprise. To do this, you trace a high-level business process to identify interactions within the environment that the process executes. You then collect the key events that this business process generates, and the responses that it expects to receive from the environment because of those events. These responses form the basis of operations that some service must provide.

For example, Figure 3-3 shows the business process for shopping in the web-based portal, and the associated operations that some services must provide. In order to create an order, the user must register. The user can then browse through the products, view details of the products, add any product to an order, and then place the order. This order process requires specific services to provide the needed functionality. Note that services contained in one domain are often not used in the same processes.

Figure 3-3 Business Process Tracking for Creating an Order

During this tracking process, it's discovered that cart functionality is needed. That functionality is added to the portfolio as a conceptual service.
Iterate over steps 1, 2, and 3, refining the list of services. Note which services currently exist, and which will be needed to complete the portfolio.

The portfolio plan should be revisited each time any project is completed, to ensure that all functionality created during a project is present in the portfolio.

3.2.2 Determining Business and System Objectives

Project objectives, when realized, solve a business problem. Well-defined objectives are measurable and often relate directly to business processes and deliverables. For example, a partial list of Global Company's business objectives might be to:

Allow 80% of customers to create their own orders using a web site
Reduce by 50%, the amount of time customer service employees spend entering orders
Raise customer service response time by 75% by allowing them to view real-time order status

In an SOA project, the focus should be on business benefits. Because of this, system objectives (those that are not based on functionality) should be defined only where they deliver business benefits by supporting one or more business goals. For example, Global Company might have the following system goals that support the goal of a self-service web site:

The system should be available to users 24 hours a day, 7 days a week.
System response times should not delay users during customer interactions.
All data that has been entered should be retrievable at any later date.

In order to realize specific business and system objectives, you often need to start by identifying higher-level objectives, continually refining until specific objectives are determined.

To determine objectives:

Identify high-level objectives.

Objectives are often very general, and nonquantifiable. For example, Global Company might have the following high-level objectives:
- To allow customers to order products through a web site
- To reuse the existing system where possible
- To replace current manual processes with automated processes
Make the objectives more specific.

In order for objectives to be specific, they must be measurable, achievable, realistic, and timely. Additionally, by making the objectives measurable, it will be easy to determine if the completed project meets the objectives.

For example, Global Company's high-level objectives might be refined to these more specific objectives:
- To allow 80% of customers to create their own orders using a web site
- To reuse 50% of existing functionality
- To automate 50% of existing manual tasks
Determine system objectives.

Some business objectives will lead to system objectives. These objectives should be handled in the same manner as business objectives. That is, they should be specific, measurable, achievable, realistic, and timely.
Prioritize objectives.

Prioritizing ensures that when project development begins, the focus is on those items that help to achieve the objectives with the highest priorities. For example, you might use the following categories to help prioritize:
- Must have: Critical to the project's success
- Should have: Not critical, but should be considered mandatory
- Could have: Desirable, but the project will still succeed without them
- Won't have: Deferred goals for a future project due to constraints

3.2.3 Determining Business and Operational Requirements

To help determine business and operational requirements, you build a use case model. When building the model, focus on addressing the defined business objectives. In a use case, you define who or what (the actor) interacts with the system, and the goals of that interaction. The use case results in a business interaction diagram used in the discovery phase, where you determine the needed services to fulfill the use case, and further identify those services that exist and those that will need to be developed.

To create a use case model:

Determine the actors that will interact with the system.

Actors represent users and other systems that will interact with the project's system. For Global Company's Order Booking application, the following actors might be defined:
- Customer: The person registering, placing orders, and reviewing past orders on the web site
- Customer Service Representatives: The internal employee accessing the system to place and review orders on behalf of a customer
- Manager: The internal employee approving order
- CRM application: The existing application that stores customer information
- Credit verification system: The system that verifies customer credit information
- Rapid Manufacturer: The company supplying prices and products for orders
- Select Manufacturer: The Company supplying prices and products for orders
Define use case packages for each actor.

Use case packages are high-level use cases for each actor.

For example, Figure 3-4 shows the high-level use cases for some of Global Company's actors. While the customer and customer service representative both need to place orders and register, the manager needs to review customer analytics and approve orders.

Figure 3-4 High-Level Use Cases in an SOA Project
Examine each use case package, and determine whether any can actually be a SOBA.

SOBAs are use case packages that encompass a specific business process. The Place Order package can actually be defined as two separate SOBAs. One would be for shopping for the products and creating the order, while the other might be the order fulfillment process.

For example, Global Company may determine that the following SOBAs are needed:
- Manage customers
- Shop for products and create order
- Book orders
- Review orders
In the next step, you'll decompose the high-level use case packages, or SOBAs, into more detailed use cases. This will allow you to begin to identify the services that will be exposed by each SOBA.
Define use cases for each SOBA.

The use cases provide a lower-level view of the steps for each SOBA. For example, the Order Booking SOBA might contain use cases for submitting an order, validating credit, approving an order, determining the supplier, and notifying the customer, as shown in Figure 3-5:

Figure 3-5 Use Cases
For each use case, define any preconditions and post-condition guarantees.

Preconditions are requirements that must be satisfied before the use case can begin. Post-condition guarantees are what will happen when the use case is successfully completed.

For example, for the Validate Credit use case, a precondition might be that the customer's credit card type and number must be known. A post-condition guarantee might be that the external validation system returns a validation message.
For each use case, describe the main success scenario.

This scenario includes the steps needed to satisfy the use case. For example, the Validate Credit use case might have the following steps:
1. Obtain credit card information.
  
  Tip:
  At this point, you do not identify where this information comes from or how it will be retrieved.
2. Send the card information out for validation.
3. Receive validation from the credit company.
For each step in the scenario, identify failure conditions and extensions.

Failure conditions are places where something can happen that jeopardizes the success of the use case. Note that some failures can be avoided by determining whether the use case can follow an alternate path to success. These alternate paths are referred to as extensions. In an SOA project, exceptions and extensions need to take into account all actors (including secondary systems) involved in the use case.

For example, a failure condition might be identified for step 2 in the Credit Validation use case, for when the credit card does not pass validation.
Define the recovery steps for each failure condition.

These recovery steps should be treated as small use cases. That is, the steps should be a success scenario, with associated failure conditions noted. Continue in this fashion until all failure conditions are discovered.

For example, the recovery steps for a validation failure might be:
1. Set the order status to canceled.
2. Send an email to the customer explaining why the order was canceled.
The second step in this recovery scenario might also have a failure condition for when the email is returned undeliverable.
Add any supplementary requirements.

There may be additional requirements that are not fully surfaced in a use case. For example, reuse and automation are two business objectives for Global Company. Because of this, a supplemental requirement for the Credit Validation use case might be that the process of communicating with the credit company be fully automated, and that both the customer and the internal representative be able to use the same process.

Additionally, because there is now a supplemental requirement that the process be automated, you might add another supplemental system requirement regarding the communication process with the credit company.
Consider any deployment constraints.

This is especially important in an SOA project, as there are many actors that may be external to the enterprise.

For more detailed information about creating and working with use cases, refer to the following documents on the Oracle Technology Network:

Defining Business Requirements using UML Use Case Diagrams in JDeveloper 10g

http://www.oracle.com/technology/obe/obe9051jdev/Modeling/UML_UseCase.htm

Design First, Code Next

http://www.oracle.com/technology/pub/articles/masterj2ee/j2ee_wk3.html

3.2.4 Conducting a Discovery Phase

In the discovery phase, you first create a high-level design of the solution based on the use cases defined in the previous phase, without regard to any existing functionality. You then map existing services from the service portfolio to this high-level design. This mapping determines the services and functionality that must be created, that currently exist, and that exist but require some modification to satisfy the requirements.

You start this phase by conducting the discovery process on each of the SOBAs, as defined in Section 3.2.3, "Determining Business and Operational Requirements". For example, Global Company might conduct separate discovery phases for the Place Order and Register SOBAs. However, it is important that before any planning begins all dependencies between the packages be noted.

To conduct a discovery phase:

Define a process flow for each SOBA by creating a business interaction diagram.

When you begin to examine each SOBA defined in the previous phase, you may find that most of them are process-centric, meaning that they are basically the embodiment of high-level business processes that are orchestrated from some service-level endpoint. When this is the case, you should create a business interaction diagram for the SOBA. This diagram shows how each step in the process interacts with some service to achieve a goal, and how the services are orchestrated into the single process flow. It also shows whether the services should be invoked synchronously or whether they will require an asynchronous invocation.

For example, since Global Company knows that the order approval process will remain a manual task (the manager still must manually review and approve the order), the invocation will need to be asynchronous.

The Order Booking SOBA might have a business interaction diagram similar to Figure 3-6. Each step in the process flow points to some service that allows the process to continue to the next step.

Figure 3-6 A Partial Business Interaction Diagram for the Order Booking SOBA

Notice that by creating this diagram, Global Company discovers that the Order Booking SOBA will require the following (partial) list of services:

Order
Customer
Credit Validation
Decision
Approval

Tip:

The Customer service in this SOBA is likely the same as the Customer service in the Registration SOBA. For this reason, it is important when defining and designing services that you keep in mind all reuse between SOBAs throughout the project.

Define the discovered services.

Once all services are discovered, you can begin to define each service. The definition should remain at a high level, as the details will be determined during the design phase. For each service, you should define the following:

Service name: A unique name for the service.
Service description: An overview of the service.
Service type: Synchronous or asynchronous.
Functional domain: The business domain the service will belong to, as defined during the domain decomposition of the service portfolio planning.
Service classification: The service can be one of the following classifications:
- Component service: A simple atomic service potentially acting on a single enterprise resource. Examples are database and code.
- Data service: A service that provides data querying and/or combination and transformation for multiple data sources.
- Business service: An atomic service composed of combinations of component services and business rules, for example, aggregator services or business delegates.
- Workflow service: A long-lived business process that coordinates with other services and has external interactions.
Service process rules: Details of the service processing logic.
Message formats: Inbound and outbound messaging formats, including details of any fault message format for the synchronous services.
Security requirements: Security in relation to client authentication, authorization, and data encryption.
Applications: The data sources (for example, an application or database) this service interacts with to complete its functionality, including the details of the communication interface if available.
Service dependency: Any other services this service depends on for functionality.
Human workflow: Any human workflow capabilities.
Performance goals and measures: Specific performance metrics for the service. These can include service processing time, concurrent users, message data sizes, and so on.
Exception handling: Any exceptions and exception handling logic, including criteria for when faults are generated by the service.

For example, the CreditValidatingService definition in the Order Booking SOBA might be as shown in Table 3-1.

Table 3-1 CreditValidatingService Service Definition

Item	Description
Service Name	`CreditValidatingService`
Service Description	Determines if a customer's credit card is valid
Service Type	Synchronous
Functional Domain	Order Fulfillment
Service Classification	Business Service
Service Process Rules	A message with credit card type and number is sent to the external credit validation application. This application returns `true` if the card is valid, `false` if it is not.
Message Formats	XML
Security Requirements	The credit card number must be encrypted.
Applications	Interfaces with an external credit validation system. This system will provide a `wsdl` file to which all messages must adhere.
Service Dependency	The `Customer` service must provide the credit card information.
Human Workflow	None
Performance Goals and Measures	Must be available 24/7
Exception Handling	A fault is invoked when the credit card is not valid. This should set the status of the order to `canceled`.

Compare each of the defined services with the service portfolio created in Table 3-1 0, "Creating a Service Portfolio Plan".

You may find that a service required by the project already exists in the portfolio, either as an implemented service or as a conceptual service. If the project requires a service that is not part of the portfolio (either as an implemented service or as a conceptual service), it should be added. If a service exists as a conceptual service in the portfolio, then it needs to be created as part of the project.

3.2.5 Defining the Project

Once you have determined the business flows and services that need to be implemented, you further define how the flows will orchestrate the services. In this phase, you determine how the services will work together by defining the business process model logic, process variable definitions, and more detailed exception handling. For services, you define the responsibilities of the services, along with their needed granularity.

To define the orchestration:

Analyze the use cases, and determine how they will all work together.

For example, during the requirements and discovery phases, it was determined that Global Company will need the following SOBAs:
- Customer Registration: While customer registration functionality exists for internal customer service representatives, Global Company needs to implement a web-based registration process so that customers can register themselves.
- Create Order: Similar to the registration process, Global Company needs to implement a web-based shopping site for their customers.
- Order Booking: Although this business process currently exists for internal customer service representatives, Global Company's requirements state that the manual processes should be automated, and then used for both the internal employees and external customers. This means that the process and services must be accessible from both a web application and the internal application.
- Review Orders: This is an existing process where a manager must manually review an order to determine if the order should be fulfilled. This service must also be available to both the web site and the internal customer representative system.
Since the registration process will interface with the existing CRM application, Global company decides that the Customer service discovered in the last phase will interface directly with the CRM application. The flow of the registration process is defined for the web site.

Similarly, the web site will interface directly with the product database to allow customers to browse and select products. This flow is also defined. Both the registration and shopping process are simple flows. Because of this, Global Company determines they will not require a BPEL process flow.

Further definition and design of the web site can follow any standard web design process, including the definition of any needed classes to support the flow of information within the web site. For example, an entity class that will handle the display of products for the web site needs to be defined.

Since the order booking and order approval functionality needs to be accessed by both the internal customer service application and the customer web application, Global Company decides to use an enterprise service bus (ESB) to invoke that process. And since that process is long running and orchestrates many different services, they decide to use a BPEL process flow to manage the business process.

Because the order approval process needs to remain a manual workflow, they decide to keep that flow as is, but to automate its invocation.
Define the different process flows and ESBs.

Once you've determined where BPEL flows can be used, you can begin to define how they will orchestrate the services. Figure 3-7 shows how Global Company orchestrates the registration and order booking processes. Note how the focus in this diagram is more on how the system will work, rather than on how the system accomplishes a business goal.

Figure 3-7 A High-Level Design for Global Company.

For each process flow and ESB, define the following:
- Flow logic: Define what the flow will do, the steps it will need to include, and the way in which it will interact with the services.
  
  For example, the ESB used to route fulfillment information will need to transform order information to data that can be consumed by a batch process used by the USPS, and also by a database adapter that will populate the data into a table.
- Subprocesses: Define any subprocesses for the flow, at the same level of detail.
- Variable definitions: Define variables that will be needed to hold information used throughout the flow.
- Business process flow scopes: Define the scopes for the flow. A scope groups a collection of nested activities that are centered around a particular service, and contains a primary activity that defines its behavior. Scopes can have their own local variables, fault handlers, and so on.
  
  For example, the OrderBooking flow has the CreditService scope, which contains all the activities necessary to validate credit information.
- Exception handling: Define all possible errors that can occur in the flow, and how, technically, they should be handled. For example, determine how time-outs will be handled.
Analyze, define, and classify the services.

You define services in much the same way as analyzing and defining classes in a standard application. For example, in a typical class analysis phase, you might identify analysis classes, and classify them into boundary/interface classes, entity classes, and control classes.

However, when you define a service for an SOA system, your focus should be on the service's responsibilities to other components in the system. Additionally, you must define the granularity of the service. The following are important aspects in determining granularity:
- Business suitability: Ideally, a service supports an atomic operation of a business task. It provides just enough functionality for the given task. Making the service more simple makes it more general, and therefore, increases the likelihood of reuse.
  
  For example, the Order Booking flow contains both an Order and an Order Status service. The Order service is used just to persist order information. However, because the status of an order needs to be updated at various points during the flow, the updating status functionality was extracted. This extraction allowed that discreet functionality to be reused.
- Performance and size: Because services are called remotely (and therefore require a round trip), they incur performance overhead. To avoid this overhead, you want to call a service as few times as possible. Doing so needs to be balanced with the service having the right level of functionality (as described in the previous point). For example, you don't want to make services so granular that you would need many to make frequent calls to many services to complete a single task.
  
  For example, instead of defining one service that handles orders, and another that handles individual order items in an order, the Order Booking system has one service that handles both orders and order items.
  
  Additionally, services are limited by the size of the messages they can efficiently process. When a message becomes too big, it will require too many resources to process.
- State management: Transactions and state operations should be self-contained whenever possible. Doing so reduces the risk that the state will be lost if a service fails to complete. Whenever a service stores data, it should be done in one transaction, and failure of the transaction must not result in lost or corrupt data.
- Location transparency: All services should be invoked remotely. There should be no dependencies on where the service is located.
- Implementation independence: All services should use contract-based design, meaning that the interface they implement should remain stable and easily extendable. The implementation behind the interface should be able to change easily, without needing to change the interface.
Now that you have completed the discovery phase, and know more about how the services need to be created and used, you can further classify each service.

Typical service classifications are as follows:
- Functionality provided by the service
  - Infrastructure, for example, a DNS lookup
  - Data, for example, a federated query
  - Business logic, for example, a fraud-check algorithm
  - Utility, for example, transformation or routing
  - Information system, for example, an ERP function
  - Process control, for example, an approval process
  - UI, for example, a portlet
- How the service is used
  - High-level business, for example, PO processing
  - Supporting business, for example, a PO approval workflow
  - High-level technology, for example, a user lookup
  - Supporting technology, for example, logging
- How the service is constructed
  - Simple, for example, a web service provided by an out-of-the-box email application
  - Wrapped, for example, a web service invoking functionality in an existing CRM application.
  - Composite, for example, a service that combines bids from multiple suppliers.
- How the service is invoked
  - Synchronous/Asynchronous, for example, a request/reply to specific service
  - Event-based, for example, notifications for any interested party to consume
Services typically belong to more than one classification. For example, the CreditValidation service, first described in Table 3-1, might now be further classified as a utility service that provides supporting business logic, is a wrapper to an existing application, and is invoked synchronously.

This type of classification allows you to more easily adhere to any existing best practices for specific classifications. For example, Global Company may have standards for data access and security for any services that are classified as data services. Additionally, Global Company may have a standard that states that all services classified as composite services should use a BPEL flow to orchestrate the composition, and that those flows must adhere to existing standards. Using the classifications to help drive best practices and standards is further discussed in Section 3.3.2, "Designing Services".
Identify common, typically nonfunctional requirements for each flow and service.

Review any nonfunctional requirements described in the use cases and translate them to specific requirements. These requirements will drive the architectural design process. Some typical operational requirements include:
- Throughput
- Response time
  - Round-trip
  - Latency
- High availability
- Fault tolerance
- Security
  - Access control
  - Encryption
- Monitoring
  - Alerts
  - Key performance indicators

3.2.6 Creating a Solution Specification

At this point, it is useful to develop a solution specification. A solution specification provides a mechanism by which stakeholders can review the proposed system. Doing so ensures that the solution realizes the initial business objectives.

While companies will have their own requirements for a solution specification, the following topics must be covered for an SOA solution:

Background
- Important enterprise-level objectives regarding SOA
- Key governance principles to which SOA systems must adhere
Project scope
- Business goals and objectives as defined in Section 3.2.2, "Determining Business and System Objectives"
- Business requirements as developed in Section 3.2.3, "Determining Business and Operational Requirements"
SOBAs
- Required service and process portfolios as defined in Section 3.2.5, "Defining the Project"
High-level architecture
- Component view as the services are described in Section 3.2.5, "Defining the Project"
- Process flow view as also described in Section 3.2.5, "Defining the Project"
Operational requirements
- Performance and other nonfunctional requirements discovered documented during the various design phases
- Availability, Security and Manageability requirements
High-level synopsis of standards and project delivery best practices (detailed standards will be documented during the design phase)
SOA governance compliance check to ensure that the solution specification not only satisfies functional and operational requirements, but that it does so in a way so as to comply with all applicable architecture, design, implementation, and regulatory best practices of the company.