TracNav

e-Framework 101

This page is for collaborative development of a "getting started" guide to the e-Framework. (In plain english for dummies!?) The editorial team are putting this together. Please feel free to contribute comments.

Table of Contents:

  1. Introduction
  2. What is the e-Framework
  3. What are the bits of the framework
  4. How can you participate
  5. What makes a good Service Expression
  6. What makes a good SUM
  7. Steps for writing a SUM
  8. SUM Tips
  9. Steps for writing a Service Expression

Introduction

This document is a short introduction to the international e-Framework. It is intended for several different audiences each of which will use the document differently.

Are you interested in learning a little about the e-Framework? For those of you with little or no experience, this is a very good start. You should read What is the e-Framework, What are the bits of the framework and How can you participate.

Are you interested in contributing or using components of the e-Framework? For those of you who know a little and are wanting to start working with the e-Framework, this is the document for you! You should read from start to finish.

For those of you who are familiar with the e-Framework, this document may be useful for explaining the concepts to others. Providing feedback on this document is very important for helping others engage with the e-Framework.

What is the e-Framework

The e-Framework is an interoperability framework for services infrastructure. It's in use by the e-Framework partners (JISC in United Kingdom, DEST in Australia, MoE in New Zealand, SURF in Netherlands) in the context of higher education and research.

So what do we mean by a "framework"? A framework is a tool for meeting certain goals. It's a well specified way of doing things (methodology) and a record of the things that have been done. Most frameworks consist of three things. A "vocabulary" so many people using the framework can all understand each other and exchange ideas. A "model" which represents the framework's view of the world and helps meet the goals of the framework (in our case interoperability and a service oriented approach). And a "knowledge base" or "artifacts" which are documented ideas, concepts and things.

The e-Framework is not a software development framework such as Struts or JavaServer Faces. The e-Framework is a specific way of modeling and documenting service oriented activities towards the final goal of interoperability. The e-Framework itself does not dictate interoperability. The e-Framework vision is that the modeling and documenting can facilitate informed discussions and interoperability where appropriate. (Nick suggests: The e-Framework vision is that the modeling and documenting can facilitate informed discussions about how to achieve interoperability where appropriate.)

Here is an example of how the e-Framework might help facilitate interoperability. An institution might require that all new IT infrastructure/software projects use the e-Framework for documenting their initial models and proposals. This will ensure that the projects have considered a service oriented approach and interoperability from the start. At the close of the project the institution might require e-Framework documents describing the project. This would document exactly how to interoperate with what was built and all of the potential pain points. If done properly this can reduce barriers to services and promote reuse of infrastructure. In addition the e-Framework can provide a common way to document the business context and processes involved, the functionality provided, the standards used, the data models required and the service interfaces.

As another example, a later project may decide to use a previous project's services, rather than develop new services from scratch. The previous project has either released its code or is operating accessible services. The project has also documented its services in e-Framework documentation. The e-Framework documentation lets the later project work out what is different between the two projects' business processes, required functionality and service interfaces. With this information, the project can decide if the existing services are sufficient, if adjustments are needed, or if additional services can be used to augment the existing functionality.

What are the bits of the framework

How can you participate

What makes a good Service Expression

A Service Expression should be intended for reuse in some context (global, within a community, or even internal system reuse). However, this doesn't mean that all deployed service instances have to be exposed for reuse. Who you allow to use your services is your decision.

An internal service that is never intended for reuse is NOT a good Service Expression.

What makes a good SUM

A SUM is needed when you choreograph more than one service (expression or genre) to provide functionality or business processes.

As the e-Framework is an interoperability framework, it helps to ask the question "what do I want people to use (ie. interoperate with)"? If you've built your system on services, but you expect people to use only one service interface exposed to the world, then you should probably document this as a Service Expression. However, you might also document a SUM describing how you've built the system/application based on services.

If your system just exposes a collection of service interfaces, and there is no functionality or business process which uses them together, then they are probably not a SUM but a collection of Service Expressions.

A SUM might describe how others can use your services correctly within their own system or application.

A SUM may not only use Service Expressions but create and expose new Service Expressions.

Steps for writing a SUM

If you are looking to write a SUM here are a few simple steps to get you started. Each step addresses writing a specific element/section within the SUM template which can be downloaded from here. These steps focus on some of the essential parts of your SUM. Start with brief lists and descriptions then fill in the details later.

  1. Rationale: Think carefully about what you want your SUM to convey and to whom. What problem does it solve? Do you want people to know how you built something? Are you proposing how to build something? Or do you want people to know how to use your services? Write only a few sentences.
  2. Business Process Modelling: List all key business processes with a good name for each. Briefly outline each business process. Simple steps are good. You may wish to focus on a single key business process, filling in the rest later.
  3. Functionality: For each business process you listed in step 2, specify the needed system functions with a good name for each. Briefly outline how you interact with each system function, what data/messages go in and what results.
  4. Structure & Organisation: For each system function, outline what service genres or expressions and data sources are used. You can put in service choreography, interactions and messaging later.
  5. SUM diagram: You should now have enough information to be able to start your SUM diagram. Most e-Framework users find the SUM diagram a useful way of understanding the SUM.

It's not necessary to do these steps in order. However, a good rationale and business process modelling section can help readers quickly understand the context of your SUM.

To complete the SUM you will need to read the SUM Template Guidelines accompanying the template. This is the best source of detailed instructions on each element. Viewing some example SUMs will also help. Look for existing SUMs about similar systems to yours.

SUM Tips

In designing your system you may have started with important use cases, user stories or business process modelling. There's no need to replicate your complete documentation. Brief summaries in the Business Process Modelling and Usage Scenarios sections will suffice. If your existing documentation is publicly available reference it from the SUM.

Remember, use only Service Genres or Expressions but not both [reference to why?]. You can use Service Genres for modelling systems or documenting at a high level. Use Service Expressions for more detailed documentation of systems.

There are generally 3 types of SUMs: Implemented SUMs describing an implemented system; Design SUMs describing a proposed system; and Modelling SUMs describing a general area of activity. Any type of SUM can be documented at a high level using Service Genres. Design SUMs can be documented in detail using Service Expressions if enough is know of the proposed system. Implemented SUMs should be documented using Service Expressions if possible.

Be on the lookout for reuse. Some business processes may depend on the same system functionality. Some system functions will rely on common services.

Do you just provide system functions for people to use? Do you leave business processes up to your users? In this case, if you can, try to generalise some business processes. The Usage Scenarios section will be very important for you to communicate example business scenarios.

Are your services loosely coupled or not coupled at all? Perhaps the only thing tying your services together is that others might use them in a certain way. If you expect the services to be used in a very specific way (inputs, outputs, workflow) then you might have a simple Business Process section and a tightly defined Functionality section. If you really only expect the services to be used within a common context/purpose you might have a detailed Business Process section, and a simple Functionality section outlining constraints. You may want to outline a good example of coordinating services under Functionality.

Have you drawn some blanks? Don't worry if not all your business processes require system functionality, or if some of your functionality doesn't rely on services. Outline them anyway, especially if you think your readers might be interested.

Once you have drawn up your SUM diagram, look for consistency across the rows and columns. You may realise you have left out a service for one business process that turns up in another. Or your business process may look busy enough that you should break it down into simpler bits. Revisit the diagram as you flesh out the details of the SUM or as your design develops.

Applicability and Implementation Guidelines can be important. They are a big part of what makes the SUM reusable. Try to think of anything that might go wrong. Is it possible to use the SUM in the wrong context or use incompatible services or data types. Anticipate what advice and feedback you would give others if things went wrong and make these explicit.

Steps for writing a Service Expression

  1. Rationale: Think carefully about what you want your Expression to convey and to whom. What problem does it solve? Will people be developing service implementation that conform to this expression or will they be writing systems that bind to service instances of this type.
  2. Functionality: What does this service do? Summarise it as a few actions from a business perspective. The business modelling may be motivated through usage scenarios.
  3. Requests & Behaviours: For each instance of functionality given above, map out what the service can be asked to do from a systems perspective. One instance of functionality can correspond to multiple requests, and vice versa. At this stage, include the arguments you would need to pass to each request; but do not specify actual interfaces.
  4. Interface Definition: Whenever you issue a request, it needs to follow a certain interface standard; those standards are documented here.
  5. Applicability: This is crucial as service expressions are strongly motivated by reuse. (need more text)

Comments:

Comment by philnicholls on Mon Jul 9 20:36:43 2007

I have added two diagrams.

I think the confusion is coming in because expressions are able to detail their own innards - which to me is wrong. I think if we are going down the documenting services route for re-use then we have to include the millions of little technical services which exist. (i.e. put the content packaging service back in).

All I want is a consistent party line.

Comment by oneil on Thu Jul 12 15:16:33 2007

Hi guys,

I was thinking about some simple notes for myself for the next time I'm involved in writing a SUM and don't have a Lyle on hand. Eg. something like:

1. List all key business processes 2. Specify the functions (and services?) related to each business process 3. Use identified services as the headings for the structure section 4. In the functionality section, describe the functionality of business processes

A difficulty for me is understanding the relationship between the functions in the functionality section and the services in the structure + organisation section.

Current documentation seems to take a linear approach to writing a SUM - eg. explains each section but not where to start, what the relationships between relationships are, etc.

Cheers, Owen

Comment by LyleWinton on Fri Jul 13 10:02:15 2007

Owen, see my above section which I hope starts to address your notes. This is very much from my angle, so consider this an initial response to your steps which we should change. Between Phil, Nick, and yourself we should be able to cover a range of experience.

Comment by oneil on Tue Jul 17 14:11:24 2007

Hi Lyle, I amended your steps to include creation of the SUM diagram because this is quite an important part of the SUM development process and should be shown in the context of the other steps. What do you think? In fact, I would also support adding another step for "Complete other relevant sections" for completeness.

Comment by opoudjis on Fri Aug 10 12:22:07 2007

Typos:

  • in the context of higher education and research.
  • A SUM is needed when you choreograph
  • LyleWinton - Done

"and a record of the things that have been done." Too vague; at least add "that have been done this way".

  • LyleWinton - A framework in general is a vague thing. I'm gonna leave it, as the suggested changes the meaning.

I'd prefer

The e-Framework itself does not dictate or guarantee interoperability.

  • LyleWinton - I don't want to get into legal talk in the 101. I think the next sentence covers it.

The e-Framework vision is that the modeling and documenting can facilitate informed discussions about how to achieve interoperability where appropriate.

  • LyleWinton - Hmmm. Didn't like my sentence to start with, but this change makes it too wordy. I've added it inline and will solicit Heather's opinion and expertise.

To the example of e-Framework use, I would add explicit mention of reuse and exposure of lack of interoperability.

  • LyleWinton - Good suggestion. I left out exposing "lack of interop", as implied I think. I'm using soft talk. :)

"A second project may decide to use the first project's services, rather than develop new services from scratch. The first project releases not only its code, but its e-Framework documentation. The e-Framework documentation lets the second project work out what is different between the two projects' business processes and service interfaces. With this information, the project can decide what adjustments it needs to make to the service, to make it useful in its new context."

  • LyleWinton - Hmm. Getting long, but a good example.

What makes a good Service expression: Add "A service that is not exposes to external systems is NOT a good service expression".

  • LyleWinton - "An internal service that is never intended for reuse is NOT a good Service Expression." was an attempt at distilling the real reason behind this. Who you expose a service to is your decision, I think we support a spectrum. What is an "external" and "internal" system is fuzzy. I think if you intent it to be "reused" then it's a candidate Service Expression. Thoughts?

Writing A Sum:

  • Functionality: "some business processes may depend on the same system functionality: be on the lookout for reuse"
  • Struct & Org: Why XOR: "once you commit to a particular interface for one service in the SUM, you need to decide on interfaces for all your services, so you can make sure that they can all talk to each other."
    • LyleWinton - I want a reference for this, didn't want to include in discussion.
  • Struct & Org: "a system function can rely on several services, and can have services in common".
  • SUM diagram: "Once you have drawn up your diagram, look for consistency across the rows and columns. You may realise you have left out a service for one business process that turns up in another. Or your business process may look busy enough that you should break it down into simpler bits. Don't be afraid to revisit the diagram as you flesh out the details of the SUM: as you keep thinking about your design, you are allowed to change your mind about how your services fit together!"

Comment by opoudjis on Fri Aug 10 12:35:28 2007

In authoring SUMs, I start with the Usage Scenarios, and use that to motivate the Business processes. If the business processes are not already available as an artifact, I'd mention starting with Usage Scenarios as at least an option. Doing UML diagrams for scenarios was quite helpful in identifying not only services, but system boundaries. So I would add that as a way of fishing out more detail for the SUM. And I would emphasise (as I already did above) that writing the SUM is not linear: as you discover new things through analysis, you can revisit the definitions you've already written.

Discussion of service patterns seems to have wandered off into limbo, but service patterns do matter as a design convenience, and I would nudge users to look for and apply patterns if they can.

  • LyleWinton - this is a design practice, not sure how e-Framework like it is. Perhaps guidance but not really part of the SUM process, I think. Also only applicable to modelling, not to documenting.

I'd also give emphasis to the Applicability and Implementation Guidelines: they are a big part of what makes the SUM (and service expressions) reusable. Have readers think of anything that can go wrong if J. Random Project sticks services from your SUM into their system. For that matter, anything that can go wrong if someone in your project starts implementing your SUM without adult supervision --- anticipate what feedback you would give as they got things wrong, and make it explicit in the SUM.

  • LyleWinton - Overall comment on this comment: Again, I wanted to keep this short and sweet. I realise the full process isn't always short. It struck me that yours is a very Business Analyst approach, and a perfectly good one. Perhaps the best way is to provide an alternative steps section. Or perhaps we should include "Usage Scenarios" in the steps, and write a separate section on "completing a SUM" in which we ask if the writer as considered all the interop/reuse pain points (inc "Applic" and "Impl"). I will solicit Phil's opinion.

Comment by LyleWinton on Mon Aug 13 12:01:44 2007

I've updated some of the document based on Nick's (opoudjis) suggestions. Mostly changes to the What is the e-Framework and Steps for writing a SUM. Comments still to be addressed/discussed:

  • Nick's last commment regarding Usage Scenarios, service patterns, Applicability and Implementation Guidelines.
  • Need a reference to discussion/explanation of why the XOR.
  • What is the e-Framework statement of the "The e-Framework vision" needs good wording.
  • Thoughts on what makes (or doesn't make) a candidate Service Expression.

Comment by opoudjis on Mon Aug 13 14:07:53 2007

Steps for writing a Service Expression

* Rationale: As for SUM. * Functionality: what does this service do? Summarise it as a few actions from a business perspective. The business modelling may be motivated through usage scenarios. * Requests & Behaviours: For each instance of functionality given above, map out what the service can be asked to do from a systems perspective. One instance of functionality can correspond to multiple requests, and vice versa. At this stage, include the arguments you would need to pass to each request; but do not specify actual interfaces. * Interface Definition: Whenever you issue a request, it needs to follow a certain interface standard; those standards are documented here. * Applicability: as I have suggested for SUM. More crucial here, since service expressions are strongly motivated by reuse.

Comment by philnicholls on Mon Aug 13 19:21:53 2007

(Sometimes we refer to these as proto-SUMs, prototype SUMs.) - Ditch this. Who cares what 'we' call things? To outsiders it's just another piece of terminology.

It needs to be laced with a common example, and a rationale on why in the example it was done in the way that it was done.

General comments: I think isn't bad, but i'm not sure that this is baby steps enough. It feels like we've restated the adult version again. Going from BP/functions to services is "fiddly". Erl has a good chapter on Service Oriented A&D;, which is what we are asking these folks to do. In my head, it makes a lot of sense for us to come up with a process like Erl hs got. I think if we have this in place then at least there is a way of making the leap from the BP to the services.

I would also add more context. I'll stick my neck out and say that there are two main types of SUM - a modelly sum and an implementationy sum. I think the steps for creating both are different. In the modelly SUM I am probably going to know less about the detail; in the implementiony SUM I am going to know lots of small details. I would probably hit the implementiony one from the bottom up (but that might be just me). I'd do the modelly one top down. Are there are any other differences between these two main flavours of SUM, and if so, do those differences impact on the process?

For each section: 1) Rationale is okay - you might want to add "For example" somewhere into the text, to distinguish between what the Rationale means and some typical rationales.

2) BPM - I think this is a candidate to explain in more detail. Baby step is to do 1 business process, not all of them. Do we need to define what we mean by a business process? I think the section needs re-ordering... Something like "Think about one of the business processes that your SUM covers. Describe the process in a short paragraph, before attempting to describe the process in a short phrase. For Example..."

3a) I thought we'd named the function points in step 2? In 2, I am asked to provide a 'good name' for each business process. In 3, I am asked to provide a 'good name' for each function? Is this correct? Don't I name them once? 3b) This sounds technical. Should it be? 3c) Data in and out to each function point sounds awfully like you have a service interface to me. SUMs, I thought, were a collection of services, rather than a single "over the top" service that does routing and messaging. Thus, functionality should describe only the non technical functions that one gets whemn a collection of services are used together in a certain way. So, I think this section needs to be a lot less technical. Note that this is how I looked at the R2Q2 SUM, which was then turned into an expression.

4) I think I'd put the messaging stuff from 3) in here. So to interact with Genre/Expression 'A' I need to send this message, and then the result of that onto Genre/Expression 'B' and so forth. I also think at this stage, the SUM has rapidly gone beyond baby steps.

5) I think you can do the SUM diagram before hitting the hard detail in 3 and 4. Relate the creation of the SUM diagram to the other steps. So if they do one BP, they have one column.

These steps have been practised - Proof? Can you give me a url which shows how this has helped?

Comment by hwalls on Fri Aug 17 06:26:21 2007

A shorter version of the "vision" statement:

"In the e-Framework view, modeling and documenting will facilitate discussions about how - or whether - interoperability can be achieved."

Genres XOR expressions reference:

My understanding was this is an e-Framework rule to make things simpler. The reference would be the Core Components and Concepts document, available as a PDF from the website. It is linked from the text on the Guides\Models page.

See the "baby steps for SUMs" .doc file for my suggestion of developing the SUM diagram and descriptions in parallel (following on some of Phil's comments). If someone is supposed to come up with a SUM diagram at the end of the writing process, they might want to look at what they will need to put into the diagram before they begin writing. The sense of progress from completing one piece of the diagram at a time fits also with the 'baby steps' idea.

Comment by oneil on Mon Sep 10 16:10:57 2007

I have been reading through the document now that it's starting to mature and it's starting to look good. However, it has become quite wordy and could possibly do with some culling. With this in mind, in the "What is the e-Framework" section - the first two paras are only background info - I don't think they're necessary. If the second para is necessary, it could go under a subheading about terminology. The first sentence of the 3rd para answers the question "what is the e-framework" and should be elevated to be the first sentence in this section. The 4th/5th paras should probably have sub-headings because they read like small case-studies

Under the "What are the bits of the framework" I recommend using a diagram rather than text (presumably that was the plan?).

The "How can you participate" section should be moved towards the end of the doc

The "SUM tips" section should have summaries of each tip as a subheading for that tip. Eg for the first tip something like "Existing documentation", for the second "Service Genres vs Service Expressions", etc. This is a fairly standard way of presenting tips.

Cheers, Owen

Error: Failed to load processor AddComment
No macro or processor named 'AddComment' found

Attachments