Service description notes

Each Service starts with narrative description or overview of the purpose, scope, and design of the service. There is a corresponding entity diagramthat provides a graphic representation of the primary concepts of the service and how they relate to each other (dependency and cardinality). The actual Service Contracts are defined by the operations, aka methods, that are the vehicle for applications (implementations) to interact with the underlying objects (data). Operations within a service contracts are grouped according to primary function ::

• Setup :: basic information needed to interact with the Service, e.g., fetch/find types related to service entities
• Read :: various read operations (fetch and find) against the service entities
• Search :: true search operations, with parameters to help guide and filter the search
• Maintenance :: various create, update, and delete operations associated with service entities

Each operation definition includes ::

1. parameters (input) expected to be passed in when the method is called,
2. a return (output) to describe the result of a successful execution of the method, and
3. basic error messages if something goes wrong.

If known, parameters and return are described by specific data elements, if not, then a structure is listed <bracketed by chevrons> indicating that further work needs to be done to nail down the specifics. Conventions used for the structures across services include ::

• <x info> output structure used to pass all detailed information about object
• <x create info> input structure used to pass in information needed to create object
• <x update info> input Structure used to pass in information needed to update object
• <x criteria> input Structure used to pass search criteria into a search operation for object
• *<x display list>*output Structure which is one form of return from a search. It would be enough information to display in a list, but not be passing back all the detailed info for each object