(last revised 25 September 2007)
Step 1. Prepare Service Usage Model description documentation
Use the e-Framework’s template to ensure that complete information is captured.
- Download the Service Usage Model Description Template (Microsoft Word document)
- Refer to the General Considerations, Helpful Links and Guidelines that will help you provide the appropriate information for the elements of the Service Usage Model description
- The description you prepare must include all required elements
- Include the recommended and optional elements if possible (elements that are not used can be deleted from the document prior to submitting the template to the e-Framework)
- Insert your copyright information in the footer of the template so that the copyright content you contribute will be properly acknowledged.
Step 2. Review relevant policy documents
Please read the e-Framework policy documents that govern the subsequent use of Service Usage Model descriptions that are submitted to the e-Framework.
- Intellectual Property Rights Statement
- Privacy Statement
Step 3. Submit the Service Usage Model Description to the e-Framework
When you have completed preparing the Service Usage Model Description, follow these steps to submit the document to the e-Framework for review.
- Go to Submit Service Usage Model page on the e-Framework website
- Fill in the requested information for the online form (your contact information, etc.)
- Upload your completed template document and diagrams
- Click “Submit”
- Service Usage Models that are ultimately accepted will be published and maintained in the SUM Registry on the e-Framework website
Back to top
- The words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document will be interpreted as described in [RFC 2119].
- When documenting a Service Usage Model, avoid making statements that are truisms for the e-Framework (e.g., do not write: "this XX Service Usage Model documents XX services")
- Avoid repetition
- Avoid using project-specific language
- Include a simple, real-world example where possible
Guidelines for all elements of the Service Usage Model Description
These directions and notes are provided to assist you in completing the Service Usage Model Description template completely and accurately. Required elements are so indicated within the brackets that follow each element in the list below and in the template.
If you need to see the complete technical definition of these elements, click on the particular element from the list of Service Usage Model Elements.
Note: The Service Usage Model description template includes e-Framework Service Usage Model description elements as of July 2007 and e-Framework service classifications as of March 2007.
Name [required]
- Provide an appropriate name for your Service Usage Model
- A meaningful name will allow others to quickly grasp what it covers and to discover your Service Usage Model efficiently
- The name should be simple, concise and informative
Note: The e-Framework may not use the common, English word that you supply, but may re-label this element with a Name or Identifier according to a system it will devise.
Version [required]
- Provide the version for this Service Usage Model Description
- If a revised Service Usage Model has technical changes or altered capabilities, you should submit an updated Version of the Service Usage Model Description
- Version information that reflects editorial changes to the descriptive document may differ from the Version of the Service Usage Model itself
- The e-Framework Editor will keep track of the versions
Rationale [required]
- Very briefly introduce the Service Usage Model that you are submitting
- Include a short statement of the problem the Service Usage Model addresses
- Summarise the underlying idea or principle that makes the Service Usage Model useful when applied in the domain(s)
Back to top
Classification [required]
- Select the most appropriate choice(s) for each classifier listed in the e-Framework Service Usage Model Classification Scheme
- In the template, type an “X” in the brackets next to your choice(s)
- Required classifiers are those in bold
- You may delete any Optional classifiers that you do not use
- You may select more than one choice for Domain, Purpose and Batch Behaviour
- Accurate classification choices will ensure that your Service Usage Model can be catalogued in numerous ways and be readily discovered by a search
- The e-Framework may add to or revise the classifier choices to ensure consistency
- The e-Framework Integrity Group (eFIG) will provide values for the Status and Confidence level of the submitted Service Usage Model
Notation[optional]
- List and explain conventions and core terminology used in describing this Service Usage Model
- Include a complete list of terms in the Terms (below)
- Notations and core terminology should be essential for understanding the other elements of the SUM
Description [required]
- Write a narrative description that explains in plain language what your Service Usage Model does
- Do not assume the members of your audience are programmers
- Provide sufficient details so that anyone reading your description can understand its basic purpose and capabilities
- Be sure to explain:
- Problem the SUM addresses and how it does it
- Reasoning behind the approach
- Limitations on use related to context or situation
- Organize the narrative in a logical way that is easy to follow, providing a clear picture of the Service Usage Model’s intended function and explaining how it can support the development of applications in the stated domain(s)
Business Process Modelling [required]
- Summarise the business analysis motivating the Service Usage Model by providing enough detail to be readable without referring to external sources
- Outline the business function(s) and process(es) that the Service Usage Model supports
- List and outline individual business functions or processes, if possible, and group according to business terms to help provide context for the Functionality (below); do not go into the details of system functionality or technical services
- Provide external links to full discussions of the business analysis, if possible
- In the business analysis, list all the capabilities from the domain or business-orientated perspective, including all constraints and conditions
Back to top
SUM Diagram [required]
- Provide a diagram that is similar to the Generic SUM diagram shown below; download the Blank Template for SUM Diagram (Visio 80 KB), or create your own using the example as a guide; a Visio Diagram Stencil file is also available if you want to build your own diagram (Visio 40 KB). Or you can label the cells in a spreadsheet as shown in this example of a spreadsheet-based SUM diagram.
- Include only the SUM diagram here; your narrative explaining the diagram should be included in "Structure & Arrangement"
- Be sure to upload the diagram in a separate graphics file, or combine if with your completed template document to upload as a ZIP file
Usage Scenarios [optional]
- Briefly describe one or more usage scenarios that show how your Service Usage Model is used, such as
- example business scenarios with workflows that involve the Service Usage Model
- an application that uses the Service Usage Model
Applicability [optional]
- Explain how your Service Usage Model should be used
- Point out any situations in which it should not be used
- Make the applicability description as specific as possible
Functionality [required]
- Outline the individual system functions that the Service Usage Model provides
- Explain the various steps within the individual functions; include constraints and conditions
- Detail each function provided by the SUM in terms of its messages and data (documents); include constraints and conditions
- Include an illustration that shows how the functions work together via their related data and processes, as appropriate
- If appropriate, provide a link to the supported business function or process in the Business Process Modelling element
- Do not include implementation-specific information
Note: Although the functionality is not a technical description, it should contain enough detail to develop the functional requirements. These will be used to evaluate the conformance of resultant applications to the functions stated in the SUM. Implementing the functions in an application that is based on the Service Usage Model will be outlined in Structure & Arrangment.
Structure & Arrangement [required]
- Document the service-oriented, operational view of the Service Usage Model in terms of services, coordination, data sources and their interactions via messaging
- Describe how services and data sources underlie each individual functionality, and how the functions are integrated at the service level
- Describe the SUM's parts in sufficient detail to allow their implementation
- Make sure this description supports the SUM diagram provided (above)
Note: The Structure & Arrangement is a technical description of the Service Usage Model. It is essential for implementing any applications that use the SUM, but this picture of ‘how’ the SUM works should not be essential for simply understanding ‘what’ it does (its Functionality).
Applicable Standards [recommended]
- List the names and versions of candidate domain and technical standards, specifications and application profiles that are needed to provide the functionality of the SUM (in addition to those referenced in ‘Services Used’)
- Where possible, link to the JISC Standards Catalogue for each standard referred to
- Only include the standards that pertain to the behaviour and functionality of the Service Usage Model
Design Decisions and Tradeoffs [optional]
- Describe the decisions involved in designing your Service Usage Model and explain why you made those choices
- Limit your discussion to the overall design of the Service Usage Model, not the internal details of the services or specific applications of the Service Usage Model
- Use the Aspects of Service Design guidelines in the 'Core Components and Concepts' document for suggestions on which design choice implications to include in your description (available as a PDF file)
Back to top
Implementation Guidance and Dependencies [optional]
- Share any anticipated issues that may affect the implementation of applications based on your Service Usage Model
- Note any assumptions you made about the technology dependencies not documented elsewhere in the template
Note: While design decisions are left up to the implementer, the implementation guidance you provide can be very helpful.
Known Uses [optional]
- List the known implementation or uses of your Service Usage Models by any applications or systems
- List known Service Usage Models that incorporate, use or are dependant on this Service Usage Model
- Tell how the Service Usage Model is used and its status: implemented, deployed, proposed, etc.
Data Sources Used [required]
- Document all data sources by name and description as used in the Service Usage Model
Related Service Usage Models (SUMs) [optional]
- List the names and versions of the other Service Usage Models that are used within this Service Usage Model to build the functionality
Note: This information is helpful when designing applications based on your Service Usage Model.
Services Used [required]
- List the names and versions of the Service Genres XOR Service Expressions that your Service Usage Model is based on
Note: Application designers will need to know what Service Genres or Service Expressions -including those in other SUMs - must be available when they use your SUM to create an application.
CORE SUMs Used [recommended]
- List the names and versions of all Commonly Recurring (CORE) SUMs that your Service Usage Model is based on
Note: Application designers will need to know the Service Genres (or Service Expressions) in any CORE SUMs that must be available when they use your SUM to create an application.
References [required]
- List the references and bibliographic terms citations to works needed to understand the Service Usage Model
Terms [optional]
- List and define domain-specific terms used in documenting the Service Usage Model
Download the Service Usage Model Description Template now. Please retain all parts to the template including the licensing statement. Add the copyright information to your content in the footer before submitting the completed template.