Design a message and service definition integration strategy based on Common Information Model standards
Create CIM-compliant SOA artifacts with Rational Software Architect
The evolving value chain of utilities
Electric utility companies are in the midst of a large scale transformation, embracing the changing landscape of smart grid technologies. The impacts of these changes reach far into the IT infrastructure that, up until now, was relatively slow to change. For example, with thousands of new smart meters being added to a utility's network comes the challenge of incorporating new business processes to exploit the large volume of meter data. Having a well-designed integration strategy based on the International Electrotechnical Commission's Common Information Model (IEC CIM) standards will prove increasingly valuable as information flow dramatically increases and utilities evolve.
Figure 1. Transformational change
Users of IBM® Rational® Software Architect are familiar with its UML modeling capabilities, as well as its ability to transform a model into other domains, including Java, XML Schema Definition Language (XSD), and Web Services Description Language (WSDL). However, when it comes to using an industry information model, such as the IEC-CIM, and evolving the model into definitive message and service definitions that can be directly used in a service-oriented architecture (SOA) messaging infrastructure, there is very little guidance. This article describes a process that uses the IEC-CIM to guide message and service definitions. After a model is established that holds the definitions of all services and messages for an enterprise, it becomes a valuable asset that can be referenced as the enterprise grows.
Along with a process, CIM extensions to Rational Software Architect have been developed to assist you. These extensions make it easier to follow the process and automate tasks that can be time-consuming. The Rational Software Architect CIM extensions are available as a services asset. Contact your IBM Rational representative for details about acquiring the toolkit.
Model management of the CIM
The first step in using the CIM in Rational Software Architect is to get the model into Rational Software Architect format. This can be done in more than one way, with the results varying depending on your route. However, the easiest way to accomplish this is to ask your IBM Rational technical representative to help you get a specific CIM version into Rational Software Architect format for you.
The Object Management Group (OMG) is performing significant work to improve the UML interchange between modeling tools. See the OMG's Model Interchange Working Group and the Diagram Definition Finalization Team for details. Hopefully, these standards will be adopted for all modeling tools, and we will have an easy migration of the CIM to all relevant vendor modeling solutions in the near future.
Now that you have a Rational Software Architect version of the model, you must develop a strategy for how to use the model. Keep the following details in mind as you develop your CIM management strategy:
- The architectural integrity and structure of the model as delivered by the CIM User Group should not be altered. In other words, the CIM is a reference model and should be used accordingly. You should resist the urge to refactor the model or delete modeling elements without understanding the impacts of doing so.
- Extensions to the model itself will probably be required. Business processes within an organization are unique, so you almost always need to extend the constructs with additional information. The additions should be managed and captured so that you have a well-understood and well-documented audit trail of custom IEC-CIM extensions. Your extensions could also be submitted to the CIM User Group for possible inclusion in the next model release.
- A strategy must be established to deal with new versions of the CIM that are released by the CIM User Group. As a new model is released, how can you be sure that you understand the changes and the impact on your architecture?
To begin with, I suggest that you keep an intact copy of the CIM as delivered by the CIM User Group. There is usually a need to check the original model to compare and contrast architectural solutions to the original CIM constructs. If you keep this model in your Rational Software Architect workspace, you can use various diff utilities to compare models.
A second model will be used to capture the extensions that you make to the CIM standard. By using a second model, you can easily compare your extended CIM with the original to illustrate the deltas that you have added to the original. The Rational Software Architect CIM extensions provide a simple spreadsheet-based diff capability that allows you to get a simple table that illustrates model differences.
Of course, the determination of the extensions that are required to the CIM is based on the analysis that you must go through to determine your architectural interfaces and messages. This article does not prescribe any techniques for this, although there are many to choose from, such as use case analysis or business process modeling. Whatever technique you use, you will ultimately come up with a series of interfaces for architectural components, as well as data definitions that specify the message traffic between those components. Rational Software Architect comes with service and XSD modeling capabilities that you can use to capture that information and use it to create WSDL and XSD documents.
Figure 2. Suggested model structure
Rational Software Architect has a model differencing (diff), or comparison, utility that is a key component of its diff/merge capabilities. It will show the detailed differences between two models, even down to the diagram deltas. As you extend the CIM with extensions that you need for your organization, the Rational Software Architect diff utility will help you understand those changes as you proceed. If you need a spreadsheet-based diff capability that simply compares the model structures to each other (packages, classes, attributes, and associations), then the Rational Software Architect CIM extensions provide this simple capability.
Figure 3. Structural changes list with merged results, visualizations of changes
Figure 4. CIM extensions model diff output
Extending the CIM
Your architectural analysis will determine the message types and message type elements that you need to fulfill the application integration scenarios. You will undoubtedly need to extend the published CIM. The Rational Software Architect CIM extensions can help.
Examining the CIM architecture
As part of your architectural analysis, examine the CIM to understand its abstractions and their relationships. You can use Rational Software Architect to query the model and to produce diagrams to help learn the model. One such capability is the Browse diagram.
The Browse diagram provides a browser-like interface to allow you to examine an element and selectively determine what types of related elements to show. You can follow relationships through different levels of depth and different relationship types to learn the scope of an element (see Figure 5). This utility gives you a fast and easy way to browse a model.
Figure 5. Rational Software Architect Browse diagram
The Rational Software Architect CIM extensions also provide a quick diagram creator. A context menu option allows you to select a package and to have a class diagram that depicts all classes in the package created. There is a modeling preference so you can determine whether relationships are also shown.
These capabilities (along with others) provide a way to interrogate the CIM to learn the model elements and their relationships as specified by the published CIM. This information is important as you determine the scope of data that you need for integration message definitions.
Automating model extensions
In order to attempt to follow the principle of maintaining CIM integrity and structure, the Rational Software Architect CIM extensions provide some automation to help you keep from altering the CIM structure. as well as automatic marking of any additions to the model. To accomplish this, the CIM extensions include a model profile named "Information Model Extend." When this profile is applied to a model, it enables new functionality.
First, any new element added to the model is automatically marked with the «
Extend» stereotype. This insures that any new modeling construct that has been added to the extended CIM (as shown in the suggested model structure in Figure 2) is marked for easy identification.
Secondly, the profile prevents you from deleting any model element that does not have the «
Extend» stereotype. This is simply a roadblock to prevent the easy deletion of modeling elements provided by the published CIM. If you have determined that you need to delete an element delivered in the published CIM, you can easily apply the stereotype and then delete the element.
Managing model extensions
As you build the extended CIM, there will be numerous new classes, attributes, and associations added to the model. It is important to develop a strategy that specifies the procedures in extending the CIM. This strategy borrowed from another industry is one that is worth mentioning:
The TeleManagement Forum, or TMForum(see Related topics for a link), provides a series of models for the telecommunications industry. They provide the Shared Information/Data (SID) model that, in essence, is the equivalent of the CIM in its purpose and function.
The TMForum guidance for extending the SID model is summarized in these three points:
- Create a new package to hold extensions. This preserves the published CIM package structure and ensures that all extensions are in new and unique packages.
- Create subclasses to add attributes and associations. Rather than adding new attributes or associations to existing CIM classes, first create a new subclass of the class that you intend to extend, and then add your attribute to it.
- Create new entities in the new package.
Although you are not required to follow these guidelines, it can help to be able to compare changes that you have made to changes made in a subsequent release of the CIM. Regardless of the strategy that you follow, the Rational Software Architect CIM extensions capabilities for managing your extensions will be useful.
First, the coloring add-in for the toolkit helps you build rules to automatically color various classes in your extended CIM. For example, you can specify that all elements with the «
Extend» stereotype are colored with a specific color on any diagram. This gives a visual indication of all extended elements so that readers can quickly recognize them on diagrams.
Figure 6. Stereotype color rule
Also, the toolkit features an extension-reporting mechanism. This report is, again, very simple. It just dumps all elements with the «
Extend» stereotype into a spreadsheet file. Along with the «
Extend» stereotype is a stereotype attribute called "comments." It is for adding any type of free-form text information to accompany the extended element. This stereotype attribute is in the Extensions report.
Figure 7. Extensions report
Figure 8. Example of the comments attribute of the «Extend» stereotype
Creating CIM-based messages
As mentioned earlier, there are numerous techniques available that use modeling to analyze the integration scenarios to determine the appropriate services and corresponding messages. Those techniques are beyond the scope of this article. However, at some point, you will have made a decision about the elements that are to be part of a particular message. Your analysis will reveal any necessary enhancements , and you will add them to your extended CIM.
Rational Software Architect features built-in tools to generate XSDs from UML. However, generating XSDs directly from the extended CIM is probably not desirable. If you quickly examine the CIM, using a Browse diagram, and begin to explore the range of relationships, out a few levels, you will quickly see the broad relationship scope of the CIM. Also, most relationships are specified as optional (multiplicity lower bound of zero, 0..1). You will need to determine how to treat relationship multiplicities. Also, there are likely to be numerous attributes that are part of classes that are not needed in some scenarios.
There are numerous design decisions to make, based on specific integration scenarios, to produce the most efficient and specific message payload definitions. This will help to improve throughput (through whatever middleware or integration strategy you employ) and reduce message payload processing.
The CIM extensions information model transformation
To isolate the elements that are applicable to your particular messaging situation, the Rational Software Architect CIM extensions offer a model transformation that will copy various selected elements to the third model in the suggested modeling structure. To select CIM elements for inclusion in the transformation, a model profile and set of stereotypes are provided. This accomplishes two things.
- First, there might be different uses of the same element for different message definitions. Each scenario that guides the need for message data can use different aspects of the same CIM elements. The ability to move elements to a downstream model and manipulate them there enables you to preserve the extended CIM.
- Second, the XSD and SoaML (Service-oriented architecture Modeling Language) profiles can be applied to the services model, again leaving the extended CIM model preserved. You apply the appropriate SoaML and XSD stereotypes to the elements in the services model.
Also, the structure and organization of a service model is typically very different from an information model, such as the CIM. All of these factors influenced the decision to create a transformation that moves selected elements to a downstream model.
Let's examine in more detail the extended CIM element selection process. First, there might be many different scenarios that require different elements from the extended CIM. Also, you might want to keep those selections separate as you move the selected elements to a subsequent model. Therefore, the marking model feature of Rational Software Architect adds a valuable capability to separate the stereotype application from the model itself. You are free to maintain multiple marking models that apply to the same target model. This separation of concerns allows multiple selection actions to occur at the same time. (For more information, see the link in Resources to the "Marking models" section of the Rational Software Architect Information Center.) The screen capture in Figure 9 illustrates the application of the "Information Model Select" model profile to an extended CIM model, using a marking model. Notice that the extended CIM shows the IMExtend profile but not the IMSelect profile. This is because the IMSelect profile application has been externalized to the marking model. Therefore, any application of stereotypes from the IMSelect profile will be captured in the marking model, not the extended CIM. You can have numerous marking models that capture different selections.
Figure 9. Marking model
There are actually two selection stereotypes: «
Select» and «
Select» can be applied to any class, enumeration, or attribute. The transformation will process any item with this stereotype.
- The «
SelectAll» stereotype can be applied to a class, and it indicates that the transformation should take all surrounding elements of the class, as well.
You can apply the stereotypes in the standard way through an element's Properties view. Or you can right- click on an element in the Project Explorer or in a diagram and choose Select or SelectAll for the element from the Information Model context menu.
The transformation that moves elements to the service model also tries to save you from having to find all related elements of a selected CIM element. For example, take a look at the MeterReading class from the IEC61968 Metering package.
Notice that it actually has six associations to other classes, one property that is of the DateTimeInterval type, and it is a subclass of the IdentifiedObject element. Rather than having to find and select each and every one of MeterReading's related elements, you can simply apply the «
SelectAll» stereotype to MeterReading. The transformation interprets «
SelectAll» as a directive to find the closure elements of the selected class. Therefore, it will include all of MeterReading's related classes, based on associations, property types, and generalization relationships. However, all of the related elements are brought over only as the classes. The closure of the related elements is not included. If you want more data from the closure elements, you must apply the appropriate «
Select» stereotypes to them, as well.
Figure 10. «SelectAll» closure
Select» stereotype tells the transformation to take only the element selected. For example, if you «
Select» a single element, you will get only the selected class. None of the properties of the class or related classes will be included in the transformation.
Selecting various elements to be included in the transformation should be an iterative process. As you «
Select» or «
SelectAll» various CIM elements and perform the transformation, you can observe the transformed elements and then repeat the process with more or less elements selected. At some point, you should have the correct set of elements that you need for your particular scenario. At that point, you must make some design decisions in the service model to make the message definition what you want, specifically.
Performing the transformation
Performing the Information Select transformation is the same as any other Rational Software Architect transformation: You create a transformation configuration, choose the Information Model Select transformation, and include the source and target models. All transformed elements are moved to a single package that is created off of the root of the target model. The structure of the CIM is for organizational reasons, but typically resulting message and service modeling elements do not follow the same model structure. By transforming the elements to a single package, you are free to then move them to other locations in the model, based on how your service model is organized. The name of the target package can be specified in the transformation configuration. Also, the transformation can make an attempt to process non-navigable associations. By default, associations are created as non-navigable in the published CIM. However, non-navigable associations are not normally found by the transformation because they are not known by the selected elements, given that they are not navigable. If you want the transformation to seek out non-navigable associations and process them also, you can indicate that in the transformation configuration.
There are also two additional transformation configuration properties that allow you to specify how to process non-navigable associations, as well as the name of the target package, as shown in Figure 11.
Figure 11. Information Model Select transformation configuration properties
As an example, run the transformation with just the «
SelectAll» stereotype applied to MeterReading. Figure 12 shows the result. Notice that all of MeterReading's properties come over, including the associations that correspond to all but one of the properties. And all related classes are present, including all other ends of associations, the type of the valuesInterval property (DateTimeInterval), and the superclass (IdentifiedObject). Also notice that the classes that were included because of the closure do not include their closure, as well. For example, MeterAsset was included because it is the other end of an association. However, if you look at MeterAsset, the only property that it has is the property that represents the other end role of the bidirectional association. No other properties are included.
Next, notice that, for each class, a trace relationship is included that provides a trace link back to the original element that it came from in the source model. For each element that is transformed, a trace relationship back to its original CIM element is created so you can find its source.
Finally, notice that all elements transformed are located in the IMSelect package, which was specified as the target package in the transformation configuration.
Figure 12. Transformation result
There is an additional stereotype that can be applied to a property that represents the role end of a relationship. You can apply the
«Mandatory» stereotype to a property, and this will force the transformation to ensure that the lower value of the associated multiplicity is 1 (one), not 0 (zero), thereby making the relationship required as opposed to optional. Figure 13 shows the
«Mandatory» property with 0..* changed to 1..* after the transformation.
Figure 13. Source model «Mandatory» property with 0..* changed to 1..*
Producing XSDs and WSDLs
After you have your candidate set of elements, transformed to the service model, along with their properties and relationships, you need to examine each and every element, property, and relationship and determine exactly what you want for this particular scenario. Assuming that your goal is to keep the message payload to a minimum, here are several things to examine:
- Information models, in general, do a good job of creating inheritance hierarchies to ensure that there is minimal data duplication across classes. Although this is a legitimate goal for an information model, you can choose to flatten these hierarchies for an individual message.
- Relationship multiplicities
- Usually, an information model leaves the refinement of multiplicities to the designer. Multiplicities are kept very general and typically assume that both sides of the relationship are aware of the other (bidirectional, or in the case of the CIM, non directional). You must examine each and every association and determine, exactly, the correct multiplicity for you particular scenario needs, often paring down an association to a single direction.
- It is easy to examine the CIM and determine very quickly that there are numerous levels of element relationships as you continue to follow the related elements. At some point, you will need to limit the related information to keep the message payload at a manageable amount. This can be addressed as you select elements for transformation, but you might need to pare back more as you further examine your scenario.
It is beyond the scope of this article to describe the full details of the UML-to-XSD transformation that is included in Rational Software Architect. Read the instructions for "Transforming UML models and XSD schema files" (see the link in Related topics) to learn more. Also, check the citations in Resources to find useful IBM developerWorks articles. To properly model an XSD, the XSD Transformation Profile should be applied to the service model and the XSD Data Types reference model should be included.
Figure 14 is an example of the MeterReading CIM part 9 message modeled in Rational Software Architect using the XSD stereotypes. Notice the various stereotypes that are made available by the XSD transformation profile. Embedded types can also be used, and a property indicates that it should be processed as an anonymous type. Multiplicity values indicate upper and lower bounds. There is also a stereotype for «
attributes». For the most part, any XSD style that you want to create can be modeled. There is a reverse (XSD-to-UML) transformation also available as part of Rational Software Architect. Perform a reverse transformation on some existing XSDs to get an idea of how the software models their constructs.
Figure 14. Details of the XSD schema UML modeling
The numbers added to the screen capture refer to these points:
«global»element MeterReadings is the top-level element of the schema.
«global»element class has an
«element»attribute of the same name and of the
«element»MeterReading of the
«complexType»MeterReadings is defined as another
- The same element can be duplicated as an inner class to provide anonymous elements.
simpleType»restrictions are defined by a generalization relationship to a standard XSD type.
- Cardinalities determine upper and lower bounds.
There are other XSD stereotypes that provide more functionality. With the use of inner classes as anonymous elements, you can use Rational Software Architect to model XSDs in whatever style you would like.
It is also beyond the scope of this article to fully explore the SoaML profile and the service modeling capabilities of Rational Software Architect. However, take a look at the following example of modeling a metering service. The service will have various operations that use message payloads based on CIM elements.
The Rational Software Architect UML-to-WSDL transformation is a superset of the UML-to-XSD transformation. Therefore, any XSD stereotypes that you include in your model will get transformed accordingly when you run the UML-to-WSDL transformation.
First, look at the model itself and the applied model profiles and libraries. All models have the Default, Deployment, and Standard profiles. For this example, we have also added the XSD and WSDL transformation profiles to ensure that we have all that we need for those transformations. The SoaML profile is also applied, so we can model services. Also, notice the Semantic Annotations for WSDL (SAWSDL) profile, which this article will discussed later, and notice that we have imported the XSDDataTypes model library.
Figure 15. Applied model profiles and libraries
A simple model structure looks like Figure 16. The package for the message payload data contains a series of XSD schemas modeled in UML. You could choose to keep these XSD definitions in another model and use whatever organizational structure you would like. But for simplicity, this example keeps all message payload schema definitions in the Message Payloads package. There is another package for Services. This is where you will define your UML representation of a service.
Figure 16. A simple service model structure
Also notice , in the Service Model package, the XSD schema named IEC61968MessageStructure. This schema defines the standard request, response, and fault message structure shown in Figure 17.
Figure 17. The standard IEC61968 message structure
Now, let's examine the details of a service. Figure 18 shows the major elements of a service as defined by stereotyped UML elements.
Figure 18. A modeled service
The numbers added in the screen capture refer to these points:
«Participant»MeteringService is the top-level service element. It is actually a UML component. The UML-to-WSDL transformation looks for this as the root of a modeled service.
«Service»itself is actually a port defined by the component. Notice that it has a «usage» relationship to the binding.
- The binding is a
«SoapBinding»stereotyped UML artifact. Notice also (below the binding's operations) that the binding has a
«usage»relationship to the service interface.
- Each bound operation has a
«usage»relationship to its corresponding operation definition in the service interface.
«ServiceInterface»is a UML interface that defines the detailed operations that make up the service.
- Each operation defines its request, response, and fault messages.
Figure 19 shows the details of how the message parameters are defined. A schema is included in the service definition that defines the specific message types.
Figure 19. Message definitions
The numbered elements refer to these points:
- The CreateEndDeviceControlsRequest message is typed as a
«global»element is typed as the RequestMessageType that comes from the IEC61968MessageStructure schema.
Service modeling extensions
The UML-to-WSDL or -XSD transformations included do not support SAWSDL. However, the CIM extensions provide this capability. As evident in Figure 16, there is a SAWSDL profile. This profile adds a hidden and required
«sawsdl» stereotype to every UML package, class, interface, property, operation, and parameter. The stereotype also contains three attributes:
For any modeling element, you can see and set the values for these attributes on the Advanced tab in the element's Properties view, as shown in Figure 20. Here, you can set your desired value (String) for the SAWSDL property, and the transformation extension will produce the correct output according to the spec.
Also, If you set the SAWSDL modelReference property for any package that also contains the XSD
«schema» stereotype to a root URI, the extension will use that root URI and append the specific modeling element information to it to make it a full model reference URI for each element in the schema. This allows you to set a root URI once for an entire schema and have each of the elements receive their appropriate model reference URIs, based on a standard root.
Figure 20. SAWSDL stereotype properties
There is an additional transformation extension that is applied to both the UML-to-WSDL and UML-to-XSD transformations that allow you to have the UML documentation removed from any resulting XSD file that is generated. You can take advantage of the documentation capabilities of Rational Software Architect to fully document all of your modeling elements. However, some users do not want the documentation to be added to the generated XSD output. By default, the UML-to-XSD transformation produces documentation annotations for each element that contains documentation in the model. The extension is included in the transformation configuration extensions tab so that you can select the application of this extension.
Figure 21. Remove XSD documentation transformation extension
Rational Software Architect contains many valuable features that you can use to model information and to describe the use of that information by services. The CIM extensions provide additional capabilities, so you can start with the standard IEC CIM model and produce a service model that traces data back to the original CIM definitions and any extensions that you define.
- For more information related to this article:
- See the Rational Software Architect Information Center, including the information about marking models and generating XSD and WSDL from UML.
- See the Semantic Annotations for WSDL and XSD Schema website for details.
- See the IEC CIM User Group website for information on the CIM.
- See the TeleManagement Forum's website, TM Forum, for information on its Information Framework and suggested methods for extending it.
- See the Object Management Group's Model Interchange Working Group and Diagram Definition finalization team for details in future improvements in model interchange.
- For more detailed information on developing XSD UML models in Rational Software Architect, read this article: Design SOA services and schema definitions with SoaML and XSD transformation profiles: An easier, more architecturally oriented alternative to WSDL by Mohamed M. Kattaya (developerWorks, May 2011).
- For more detailed information on service modeling in Rational Software Architect, see the IBM developerWorks series titled Modeling with SoaML, the Service-Oriented Architecture Modeling Language, by Jim Amsden, co-author of the OMG SoaML standard. (2010).
- For information on marking models, see the marking models section of the Rational Software Architect Information Center, the developerWorks article titled Update on UML modeling features in IBM Rational Software Architect Version 8.0: Part 2 by Wayne Diu, as well as the instructions for Transforming UML models and XSD schema files.
- To learn more about Rational Software Architect, start at the developerWorks page. Also explore the product overview, the information center for installation and use instructions, and the Rational Software Architect wiki for more resources.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
- Download either or both versions for a trial:
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.