Visual Paradigm logo
Jump to Menu

How to Draw SoaML Diagrams?

Service Oriented Architect (SOA) allows us to describe and understand how people, organization and system components work together by using services to achieve business objectives. SoaML is an�Object Management Group (OMG)�standard that provides a domain neutral modeling language to architect and model SOA with the use of�Unified Modeling Language (UML).

Compatible edition(s): Enterprise, Professional

  • September 3, 2013
  • Views: 59,065
  • PDF

SoaML in Visual Paradigm

Visual Paradigm supports the modeling of SOA with SoaML. In Visual Paradigm, SoaML profile is organized into five SoaML diagram types, namely, the Service Interface Diagram, Service Participant Diagram, Service Contract Diagram, Services Architecture Diagram and Service Categorization Diagram. Each of them provides a unique view to describe and help to understand services and the services architecture. Combined with the use of UML diagrams like sequence diagramactivity diagramBPMN business process diagram and OMG business motivation model (BMM), you can describe SOA as well as to indicate its technical and business relevance.

What is this Tutorial about?

This tutorial is written to explain what SoaML is, how to use SoaML for SOA and how to draw the various SoaML diagrams in Visual Paradigm. There are mainly 5 parts in this tutorial. Each part explains one of the SoaML diagram types in details, with SoaML tool description, diagram definition and the steps to create the diagram.

The example that will be used in this tutorial is a basic version of a distilled water supplier. You will draw different SoaML diagrams to explain the different aspects of the distilled water ordering and delivery service.

Preparation

In order to perform the steps in this tutorial, make sure you have Visual Paradigm downloaded and installed. You may click here to download Visual Paradigm if you do not have it installed.

To avoid disrupting your production environment during the tutorial, please create a new project to perform the steps in this tutorial.

Part I - Drawing Service Interface Diagram

soaml service interface diagram

Service Interface Diagram Tools

What is Service Interface Diagram?

Service Interface Diagram is one of the most important SoaML diagram types. In order to understand what service interface diagram is, you must first know about a key concept of SoaML - service.

As specified in the SoaML specification, service is "value delivered to another through a well-defined interface". In SoaML, a service can be specified using three approaches: simple interface, service interface and service contract. Simple interface defines one-way service that does not require protocol. Such service can be used with anonymous callers and the participants know nothing about the caller. Service interface allows for bi-directional services. Such service involves the communication between provider and consumer of services in completing services. Service contract defines how participants work together to exchange value and we will talk about it when introducing the service contract diagram.

Service interface diagram allows for the modeling of service specification. You can model simple interfaces and service interfaces in service interface diagram. Now, follow the steps below to draw a service interface diagram.

How to Draw a Service Interface Diagram?

  1. In a new project, create a service interface diagram by selecting Diagram > New from the toolbar. In the New Diagram window, enter service interface diagram in the search field, click Next. Then, fill in the Diagram Name and Description (if any). Click OK to confirm diagram creation.
  2. We are going to create a service interface for the distilled water ordering service. Select Service Interface from the diagram toolbar.
  3. Click on the diagram to create a service interface. Name it Distilled Water Ordering Service.
    service interface created
  4. We are going to define the interface for the provider of the distilled water ordering service. Move your mouse pointer over the service interface Distilled Water Ordering Service. Drag out the Resource Catalog icon at top right.
    create provider interface
  5. Release the mouse button above the service interface. Select Realization -> Interface from Resource Catalog to create the interface, and name it Order Taker.
    interface created
  6. Provider interface contains operations that may be invoked during the course of service. It is a must for service provider to support the operation defined. Order taker is responsible for processing customers' order. Add an operation order() in Order Taker by right clicking on Order Taker and select Add > Operation from the popup menu.
    order operation added
  7. We are going to define the interface for the consumer of the distilled water ordering service. Move your mouse pointer over the service interface Distilled Water Ordering Service. Drag out the Resource Catalog icon at top right.
    create consumer interface
  8. Release the mouse button above the service interface. Select Usage -> Interface from Resource Catalog to create the interface, and name it Order Placer.
    interface created
  9. Add an operation orderConfirmed() in it. This indicates that consumer of service must support the orderConfirmed() operation.
    consumer interface created
  10. Let's define the roles of provider and consumer in the distilled water ordering service. The roles have to be defined inside the body of service interface. So let's resize the service interface Distilled Water Delivery Service to make it bigger.
  11. Click on the Resource Catalog icon of the service interface Distilled Water Ordering Service.
    create new role in service interface
  12. Select New Role from Resource Catalog.
    select new role in resource catalog
  13. The type of consumer role is Order Placer. Right click on the role and select Select Type... from the popup menu.
    select type
  14. Select Order Placer in the popup window. Click OK.
    select order type
  15. Create the provider role from the consumer role. Drag out the Resource Catalog icon from the consumer role.
    create rolee
  16. Select Connector Role from Resource Catalog.
    select connector role in resource catalog
  17. Similar to how you set type for the consumer role, set Order Taker to be the type of provider role. Up to now, your service interface diagram should look like this:
    provider role created
  18. You've completed defining the distilled water ordering service. Now, apply the skills you've learned in the previous steps to define the distilled water delivery service in a new service interface diagram. Your diagram should look like this:
    service role created
  19. Before we end this section, let's also try to create a simple interface. As mentioned before, simple interface defines a one-way service that require no protocol. Create a new service interface diagram first.
  20. Let's create a simple interface for querying the order delivery status. Click on the diagram to create a simple interface and name it Delivery Status.
    simple interface created
  21. Add an operation getDeliveryStatus(id:String):Stringd in it.
    create simple interface

Part II - Specifying Choreography Using UML Sequence Diagram

Service choreography defines the interaction between the provider and consumer in completing a service. A UML sequence diagram can be used for specifying service choreography. In Visual Paradigm, you can add sub-sequence-diagram to service interface for such purpose. Now, try to specify the service choreography for the service interface Distilled Water Ordering Service defined in the previous section.

  1. Open the first service interface diagram where the service interface Distilled Water Ordering Service was defined.
  2. Click on the service interface Distilled Water Ordering Service.
  3. Click on the tiny resource icon at the bottom right of the shape and select New Diagram... from the popup menu.
    create sub-diagram from service interface
  4. The New Diagram window is opened. In the New Diagram window, enter sequence diagram in the search field, click Next. Then, fill in the Diagram Name and Description (if any).
  5. Click OK to confirm diagram creation.
  6. A sequence diagram is created, with lifelines consumer and provider in it. The lifelines are created by following the roles you defined in the service interface.
    lifelines auto created
  7. Specify how the consumer interacts with the provider of service by drawing sequence messages between the two lifelines. The consumer begin by invoking provider's order() method. The provider will then react by calling consumer's orderConfirmed() method.
    sequence diagram completed
    In practice, you can specify optional call with the use of opt fragment.
  8. Now, try to specify the choreography of the distilled water delivery service, using UML sequence diagram. Your diagram should look like this:
    create sub-diagram from service interface

Part III - Drawing Service Participant Diagram

soaml service participant diagram

Service Participant Diagram Tools

What is Service Participant Diagram?

In SoaML, participant represents certain party or component that provides and/or consume service(s). Participants can be software components, organizations, system or individuals.

Service participant diagram allows for modeling primarily the participants that play role(s) in services architectures. It also presents the services provided and used by these participants. Now, try to draw a service participant diagram for the distilled water supplier.

How to Draw a Service Participant Diagram?

  1. Create a service participant diagram by selecting Diagram > New from the toolbar. In the New Diagram window, enter participant diagram in the search field, click Next. Then, fill in the Diagram Name and Description (if any), click OK to confirm diagram creation.
  2. The distilled water supplier participant offers the distilled water ordering service. Let's create a participant for it. Select Participant from the diagram toolbar and click on the diagram to create a participant. Name it Distilled Water Supplier.
    participant created
  3. In SoaML, port is used to represent the point of interaction on a participant where a service is provided or consumed. A <<Service>> port typed by a service interface is known as a service port. It represents the point where the service is offered by participant, based on the typed service interface. Let's create such port on the Distilled Water Supplier participant. Click on the Resource Catelog icon at the top right of the Distilled Water Supplier participant, and select New Service Port from Resource Catalog.
    create service port
  4. A service port is created on the left hand side of the participant, following the convention. Let's type the port. Right click on the port and select Select Type... from the popup menu.
  5. In the Select Type window, select Distilled Water Ordering Service and click OK.
    select distilled water ordering
  6. You are prompted to visualize the provider and consumer interface associated with the service interface Distilled Water Ordering Service. Keep the default selection and click OK.
    visualize interfaces
    The port, provider and consumer interface are created automatically. Note that the port is said to provide the Order Taker interface and requires the Order Placer interface.
    service port created
  7. Just as we want to define the service provided by the distilled water supplier, we want to define what services a participant consumes. The Customer participant is a consumer of the distilled water ordering service. Create the Customer participant on diagram.
    customer participant created
  8. Participant requests for services from other participant (who provide the services). The request of service can be defined using a <<Request>> port. Make use of the resource centric interface to create a <<Request>> port on the Customer participant.
    create request port
  9. Type the <<Request>> port. Right click on the <<Request>> port and select Select Type... from the popup menu.
  10. In the Select Type window, select Distilled Water Delivery Service and click OK.
  11. You are prompted to visualize the provider and consumer interface associated with the service interface Distilled Water Ordering Service. Keep the default selection and click OK. Up to now, your diagram should look like this:
    request port created
    Note that both the Customer and Distilled Water Supplier have a port typed with the Distilled Water Ordering Service. The distilled water supplier is the provider of service, while the customer is the consumer of service. The distilled water supplier provides the Order Taker interface and requires the Order Placer interface. The customer provides the Order Placer interface and requires the Order Taker interface.
  12. Participant can be the provider and consumer of many services. Remember the distilled water delivery service? The delivery company is the provider of service and the distilled water company is the consumer. Apply the skills you have just learned to add the participant, <<Service>> and <<Request>> port to the diagram. The result should look like this:
    updated service participant diagram
  13. The delivery company also provides the delivery status service. Add a <<Service>> port to the Delivery Company participant and type it with the Delivery Status service interface.
    delivery status service port created
  14. Visualize the provided interface of the port. Drag out the Resource Catalog icon from the port and select Realization -> Interface from Resource Catalog.
    create provided interface from port
  15. When you release the mouse button, the provided interface is visualized - you don't need to name it manually.
    provided interface visualized
  16. Customer can check the delivery status. Add a <<Request>> port to the Delivery Company participant and type it with the Delivery Status service interface.
    request port added to customer
  17. Make use of the Usage -> Interface resource to visualize the required interface of the port.
    required interface visualized
    Up to now, your service participant diagram should look like this:
    finished service participant diagram

Part IV - Drawing Service Contract Diagram

soaml service contract diagram

Service Interface Diagram Tools

What is SoaML Service Contract Diagram?

As mentioned before, there are three approaches to specify a service. You've learned how to specify service with the two interface-based approaches - simple interface and service interface. In this section, we will talk about service contract.

Service contract defines the agreement between parties about how a service is to be provided and consumed. "Agreement" here refers to interfaces, choreography and any terms and conditions. Interacting participants MUST agree to the agreement in order for the service to be enacted.

How to Draw a SoaML Service Contract Diagram?

Let's draw service contract diagrams to show the agreements of the three services.

  1. To create a Service Contract Diagram, select Diagram > New from the toolbar. In the New Diagram window, enter service contract diagram in the search field, click Next. Then, fill in the Diagram Name and Description (if any), click OK to confirm diagram creation.
  2. Select Service Contract from the diagram toolbar and click on the diagram to create a service contract. Name it Distilled Water Ordering.
    empty service contract created
  3. Visualize the roles of consumer and provided in the distilled water ordering service. Click on the Resource Catalog icon of Distilled Water Ordering contract, and then select New Role from Resource Catalog.
    new role from service contract
  4. Name the role consumerConsumer is the participant that has some needs and requests for a service of a provider.
    role added in service contract
  5. Let's type the role. Right click on the role and select Select Type... from the popup menu.
  6. In the Select Type... window, select Order Placer and click OK.
    select order placer
    The type of consumer role is Order Placer. This is the interface that a consumer will and must implement to use the distilled water ordering service.
  7. Visualize the role of the provider in the distilled order ordering service. Create a new role from the consumer role with the help of Resource Catalog.
    create role from role
  8. Name the role provider. It is the role that provides something of value to the consumer.
  9. Let's type the role. Right click on the role and select Select Type... from the popup menu.
  10. In the Select Type... window, select Order Taker and click OK. The type of consumer role is Order Taker. This is the interface that a provider will and must implement to provide the distilled water ordering service.
    service contract created
  11. We can specify the terms and conditions of contract in the description of service contract. Select the Distilled Water Order contract on diagram.
  12. In the Description Pane, enter the following terms that the consumer and provider have to follow. There is no standard or rule to govern the way you describe the terms. Just to make sure everything is cleared described.
    describe distilled water order contract
    As a side note, you can add model element link, which is the hyperlink shown in the image above, by clicking the Add Model Element... button in the toolbar of Description Pane.
  13. Apply the skills you have just learned to draw a new service contract for the distilled water delivery service. The contract should involve the consumer role requester and provider role provider, and are typed with Delivery Requester and Delivery Provider respectively. The result should look like this:
    distilled water delivery service contract
    And this is the terms of the Distilled Water Delivery contract:
    describe distilled water delivery contract
  14. Let's create a contract for the Delivery Status service. The case is a bit tricky, so let's walk through the steps together. Create a new service contract diagram and a Delivery Status contract first.
    delivery status contract created
  15. Create a role consumer in the contract. Consumer is the consumer of the delivery status service.
    customer role defined
    Here we have a problem. Remember the delivery status service was defined as a simple service (in our service interface diagram)? Simple service is a one-way service that does not require a protocol. The provider needs not to know about the consumer. Thus, there is no required interface defined for such service. So how do we type the role consumer here? The answer is - you don't need to type it. Just leave the interface part unspecified when you need to indicate the use of a simple service.
  16. Complete the rest of the service contract diagram to make it looks like:
    delivery status contract created
    And here are the terms:
    describe delivery status

Part V - Drawing Services Architecture Diagram

soaml services architecture diagram

Service Architectures Diagram Tools

What is SoaML Services Architecture Diagram?

Till now we have defined and specified the services to use in distilled water ordering. We also have defined the participants. However, nothing shows us how the customer, distilled water supplier and delivery company work together, providing and using the services in the services architecture. To represent this information, we can draw a services architecture diagram.

A services architecture, abbreviated as SOA, shows the participant roles that provide and consume services to fulfill certain purpose.

How to Draw a SoaML Services Architecture Diagram?

  1. To create a Service Contract Diagram, select Diagram > New from the toolbar. In the New Diagram window, enter services architecture diagram in the search field, click Next. Then, fill in the Diagram Name and Description (if any), click OK to confirm diagram creation.
  2. Select Services Architecture from the diagram toolbar and click on the diagram to create a services architecture. Name it Distilled Water Ordering Architecture.
    services architecture created
  3. Let's start by adding the participant role customer to the services architecture. Click on the Resource Catalog icon of Distilled Water Ordering Architecture and select New Internal Participant Part from Resource Catalog.
    new internal part
  4. Let's type the participant role. Right click on the part and select Select Type... from the popup menu.
  5. In the Select Type... window, select Customer and click OKCustomer, Delivery Company and Distilled Water Supplier are the participants we defined in the service participant diagram.
    select customer
  6. Add two more parts dws and dc. Type them with Distilled Water Supplier and Delivery Company. Your services architecture diagram should look like this:
    parts defined in services architecture
  7. Let's visualize the service contracts that the participants provide or use, within the SOA. Click on the Resource Catalog icon of Distilled Water Ordering Architecture and select New Service Contrac Use from Resource Catalog.
    new service contract use
  8. Give an empty name to the service contract use. Type it by right clicking on it and select Select Type > Select Type... from the popup menu.
    select service contract use type
  9. In the Select Type... window, select Distilled Water Order and click OKDistilled Water OrderingDistilled Water Delivery and Delivery Status are the service contracts we defined in the service contract diagram.
  10. Add two more service contract uses. Type them with Distilled Water Delivery and Delivery Status. Your services architecture diagram should look like this:
    updated services architecture diagram
  11. Participants provide and use the services within the SOA. This is modeled as role bindings to the related service contracts. Drag the Resource Catalog icon from the participant role Customer to service contract use : Distilled Water Ordering to bind them.
    bind participant to service contract use
  12. You are prompted to select the role the customer plays in the distilled water ordering service. Select consumer: Order Placer and click OK.
    select consumer place order
    The participant role and service contract use is connected.
    participant role connected
  13. Distilled water supplier provides the distilled water ordering service. Let's bind the participant role Distilled Water Supplier with service contract use Distilled Water Ordering. Select provider to be the role.
    participant and service contract use connected
  14. Apply the skills you have just learned to bind the other participant roles and service contract uses. The result should looks like this.
    complete services architecture diagram

Summary of SoaML Notations

The SoaML notation you can apply in your SoaML diagrams are listed below. Notation description was extracted from OMG SoaML specification and OMG UML specification.

SoaML NotationsDescription
Service InterfaceService interface represents the service itself.
InterfaceAn interface is a simple interface that defines a one-way service that does not require a protocol.
RoleA role defines the role of provider or consumer in a service.
ConnectorA connector connects roles and interfaces.
CapabilityThe ability to produce an outcome that achieves a result.
ExposeExpose is a kind of dependency used to indicate what capabilities that are required by or are provided by a participant should be exposed through a service interface.
DependencyIndicates that an element depends on another.
RealizationA service interface specifies the receptions and operations it receives through interface realization.
UsageA service interface specifies its required needs through usage dependences to interfaces.
Message TypeMessage type is a specification of information that exchange between the consumers and providers of a service.
MilestoneA milestone defines a signal that is sent to an abstract observer.
ParticipantParticipant represents some party or component that provides and/or consumes services. Participants can be people, organization, system, etc.
AgentAutonomous entities that can adapt to and interact with their environment. Agents can be software agents, hardware agents, firmware agents, robotic agents, human agents, etc.
PartThe part has a type that specializes/realizes the type of role.
PropertyAn identifying property for uniquely identifying the containing classifier. This is also known as a primary key.
Service PortService port is a kind of port that represents the point of interaction on a participant where a service is actually provided.
Request PortRequest port is a kind of port that represents the point of interaction on a participant where a service is actually consumed.
PortService uses port to indicate the feature or interaction point through which a classifier interacts with other classifiers.
Service ChannelService channel is a communication path between services and requests within an architecture.
Service ContractService contract is the specification of the agreement between providers and consumers of a service as to what information, products, assets, value and obligations will flow between the providers and consumers of that service.
ProviderFor modeling the interface provided by the provider of a service.
ConsumerFor modeling the interface provided by the consumer of a service.
Services ArchitectureServices Architecture describes how participants work together for a purpose by providing and using services expressed as service contracts.
Internal ParticipantInternal role that is involved in a services architecture
External ParticipantExternal role that is involved in a services architecture
Service Contract UseIndicates the ability of an owning classifier to fulfill a service contract or adhere to a services architecture.
Role BindingA role binding binds each of the roles to a part of the containing architecture to indicate what role each part in the owning architecture play.




Turn every software project into a successful one.