SOA Standards Service Naming Conventions - eHealth · PDF fileSOA Standards Version: 1.2...

SOA Standards

Service Naming Conventions

SOA Standards Version: 1.2

Service Naming Conventions Date: 2013-10-28

eHealth Ontario Confidential ii

1 Contents

1 Purpose .................................................................................................................................... 1

2 Scope ....................................................................................................................................... 1

3 General Naming Standards ...................................................................................................... 2

3.1 Items Requiring Consistent Naming ................................................................................ 2

3.2 Name Uniqueness ............................................................................................................. 3

3.3 Name Descriptiveness ...................................................................................................... 3

3.4 Implementation Agnostic Names ..................................................................................... 4

4 Business Service Naming Standards ....................................................................................... 5

4.1 No “Service” in Name ...................................................................................................... 5

4.2 Service Name Context ...................................................................................................... 6

4.3 Data Service Layer Service Name ................................................................................... 6

4.4 Infrastructure Service Layer Service Name ..................................................................... 6

4.5 Business Logic Service Layer Service Name .................................................................. 7

4.6 Portal Service Name ......................................................................................................... 7

5 Capability Naming Standards .................................................................................................. 8

5.1 Capability Name Context ................................................................................................. 8

5.2 Capability Name Verbs .................................................................................................... 9

6 WSDL/SOAP Naming Standards ......................................................................................... 11

6.1 Unique Namespace ......................................................................................................... 11

6.2 WSDL Namespace Pattern ............................................................................................. 11

6.3 WSDL Documentation ................................................................................................... 12

6.4 WSDL/XSD File Names ................................................................................................ 12

6.5 WSDL Constructs – PortType, Port, Binding ................................................................ 13

6.6 SOAP Action Names ...................................................................................................... 16

6.7 Service Address Endpoints ............................................................................................ 18

7 Service Naming Example - Putting all the Names Together ................................................. 20

8 References ............................................................................................................................. 22



eHealth Ontario Confidential iii

Document Location

TBD

Document Revision History

Version Date Author Description

1.1 2012-10-29 E.Neroslavskaya Incorporated feedback from Ron McEwen and Mike Krasnay.

1.1.1 2012-11-01 Sharon MacMillan Formatted and edited.

1.1.2 2012-12-07 E.Neroslavskaya Added Datapower file location policy in 7.4

1.1.3 2013-01-07 E.Neroslavskaya Changed 7.3 WSDL documentation and 7.5 Port naming added versioning

1.2 2013-10-28 E.Neroslavskaya Cosmetic updates

Related Standards

Standard Location

SOA Standards - Service Versioning

SOA Standards - Service Taxonomy

Terminology Used in this Document

This document uses the following terminology:

MUST: This word means that the definition is an absolute standard.

MUST NOT: This phrase means that the definition is an absolute prohibition.

SHOULD: This word means that there may exist valid reasons in particular

circumstances to ignore a particular item, but the full implications must be understood

and carefully weighed before choosing a different course.

SHOULD NOT: This phrase means that there may exist valid reasons in particular

circumstances when the particular behavior is acceptable or even useful, but the full

implications should be understood and the case carefully weighed before implementing

any behavior described with this label.

MAY: This word means that the standard is optional. The service developer may choose

to include the item based on the needs of their design.



eHealth Ontario Confidential iv

The above definitions are loosely based on the RFC 2119 “Key words for use in RFCs to

Indicate Requirement Levels” as described at: http://www.ietf.org/rfc/rfc2119.txt

http://www.ietf.org/rfc/rfc2119.txt



eHealth Ontario Confidential 1

1 Purpose

The purpose of this document is to define the eHealth Ontario standards for architects/developers

with respect to naming services and related artifacts.

The SOA Principles state that the Standardized Service Contract design principle is perhaps the

most fundamental of the eight service-oriented design principles. It is by means of service

contracts that services express their purpose and capabilities (Ref1. SOA Principles Website).

In support of a standardized service contract, a number of design patterns are introduced, one of

which is the “Canonical Expression” pattern. The problem that this pattern addresses is that

services created by different teams may express similar capabilities in different ways, leading to

inconsistencies and potential misunderstandings that further risk denormalization of the service

inventory. The stated solution to this problem is to develop naming conventions, and enforce

them through a governance process (Ref2. SOA Patterns Website). Nowadays, design time

discoverability is becoming more and more important, and service naming is one of the key

concepts for defining discoverable services.

2 Scope

The scope of the naming standards described in this document includes all eHealth Ontario

HIAL exposed services that are described in the SOA Service Catalog.

This topic is of particular importance because the structuring of the business names and the

challenges involved in maintaining consistency in naming WSDL and XML schema namespaces,

services, ports, operations, and other artifacts in the Web Services space have a significant

impact on discoverability and the complexity of managing a SOA environment.

While the discussion and examples are focused on Web Services (i.e., services defined with a

WSDL and SOAP), the basic naming principles apply to other approaches such as XML over

JMS, and REST.

The standards in this document are intended to be applied to naming services in the service

contract. They do not address code-specific naming conventions for specific languages such as

Java and C#.

Note: Services that have not been designated as members of the HIAL Service Catalog are not

required to use the naming standards specified in this document. However, there may be benefit

in doing so to promote consistency, as there is the possibility that they may eventually be

designated as enterprise services.




3 General Naming Standards

3.1 Items Requiring Consistent Naming

Standard Name SOA-NM-GN Items requiring consistent naming

Standard Definition In a SOA environment there are many things that require names. These include:

Abstract Service-related names:

Business Service Name;

Business Capability Name;

Functional Domain and Topic (defined in eHealth Ontario Service Taxonomy).

WSDL-related names:

The WSDL itself (the name attribute in the top-level <definitions> tag);

The WSDL filename;

The targetNamespace defined by the WSDL (also in the top-level <definitions> tag). By extension, the target namespace is the logical prefix for the name of each entity defined in the WSDL;

The entities defined by the WSDL: services, port types (interface), ports (interface instances);

Operations and messages;

The soapAction;

The schemaLocation of each imported XSD file;

The endpoint-location attribute for the address element of each service port.

Schema-related names:

The XSD filename (if the schema is not embedded in a WSDL);

The targetNamespace defined by the Schema (either embedded in the WSDL or a stand-alone XSD). By extension, this namespace is the logical prefix for the name of each entity defined in the schema;

The entities defined by the schema: types, elements, and attributes;

The schemaLocation of each imported XSD file.

REST names:

TBD.

WS-Policy names:

TBD.

Some of these items are actual artifacts such as files. Others are simply logical names for definitions (port types, messages, elements, etc.), or groups of definitions (namespace names). All of them will need to be dealt with by the producers and consumers of services.

Standard Strictness SHOULD

Standard Enforcement

HIAL Registry validation using regular expressions and UGP Gating Review.




3.2 Name Uniqueness

Standard Name Name Uniqueness

Standard Definition Services, Capabilities (operations) MUST be distinguishable from other services and operations. This is accomplished by giving a unique name to each service and, within the service, to each port type and operation of that service. Unique names are also required for the WSDLs, messages, data structures, and other artifacts used in the definition of the service.

Standard Strictness MUST


HIAL Registry validation.

Notes Best Practice: Eliminate the potential for name collisions across business domains by

the addition of domain-specific words where necessary.

For example, a one-word service called Protocol can have very different meanings in

different domains (e.g., Clinical Research vs. Life Sciences). For example, in clinical research, a more appropriate name would be Study Protocol, whereas, for life sciences there may be many types of protocols, e.g., Laboratory Protocol.

3.3 Name Descriptiveness

Standard Name Name Descriptiveness

Standard Definition Service, Capability (operation) names MUST be auto-descriptive and provide the consumer with enough information regarding the behaviour of the service.

For conceptual-level specifications, all names MUST be in plain English (e.g., Send Laboratory Order Request), and CamelCase MUST NOT be used.

For Logical- and Physical-level specifications, all names MUST use CamelCase (e.g.,

SendLaboratoryOrderRequest). Rationale: Service names are often used by tooling to generate associated artifacts, e.g., JMS queues or endpoint URIs, or on platforms where spaces or special characters are not permitted.

HL7V3: For HL7 transactions, the description field should be used for service operation names. (Refer to the Architecture Decisions document).



UGP review

http://en.wikipedia.org/wiki/CamelCase




Standard Name Name Descriptiveness

Notes Best Practice: Avoid using acronyms and abbreviations unless they are universally

understood across the enterprise.

Best Practice: Don’t include a version in the service name.

3.4 Implementation Agnostic Names

Standard Name Implementation Agnostic Names

Standard Definition Service, Capability and operation names MUST NOT reveal implementation details. This not only has the potential to lead to confusion if you decide to change the

implementation of the service, but is also a security risk as it gives the service consumer insight into how the service may be implemented, which they may be able to exploit.

Don’t include protocol information in the service names. This is generally

unnecessary as the service advertises itself at a particular endpoint which clearly defines the protocol to be used.

Standard Strictness MUST NOT


UGP Review

Notes




4 Business Service Naming Standards

To facilitate the discovery of services, it is helpful to categorize service names according to a set

of preexisting business domains or subject area. Services may exist at different levels, and

provide different granularity. A general classification of different levels of services is as follows:

Infrastructure service layer (utility-centric) is found in application services involving

operations that encapsulate common functions, such as event logging, exception

handling, or notification. These reusable services need to be labeled according to a

specific processing context, agnostic in terms of any particular solution environment. For

example, a utility service might be named “Notify”.

Data service layer (entity-centric) represents a specific-business entity, such as a

customer. The labeling of entity-centric business services is often predetermined by the

entity name. For example, a service may simply be named “Lab Report”.

Business logic service layer, process or transaction (task-centric) encapsulates process

logic. In this case, the thread that ties together the grouped operations is a specific

activity being automated by the service logic. Therefore, the use of verbs in service

names is common. For example, a task-centric service may be called “Get Lab Report”, if

that accurately represents the task's scope.

For additional details, refer to the document entitled SOA Policy – Service Taxonomy, Layers

(SOAPolicy_ServiceTaxonomy.doc).

4.1 No “Service” in Name

Standard Name No “Service” in Name

Standard Definition The name assigned to a Business service SHOULD NOT include the word “service”.

Exceptions to this standard are services that have as their functional context the management of some aspect of service metadata, or the management and coordination of other services.

For example, a service that has eligibility for a study as its focal entity should be called “Eligibility” and not “EligibilityService”.

Standard Strictness SHOULD NOT


HIAL Registry validation

Notes These business service names will be registered in the HIAL SOA Service Registry.




4.2 Service Name Context

Standard Name Service Name context

Standard Definition Service names should place the service capabilities/operations in the appropriate context, and define the service scope wisely. Service names should be assigned differently, depending on service type



UGP gating review

Notes Some examples of bad service names are service names which:

Lack scope or context. For example: Service Name “Inventory” — what is the scope of "Inventory"? Just managing inventory levels? Or inventory locations? Both? Something else?

Have ambiguous naming. For example: “OrderManagement::execute” What is it that the order management service is actually executing? Is it executing order fulfillment or ordering?

4.3 Data Service Layer Service Name

Standard Name Data Service Layer (Entity) Service Name

Standard Definition For an Entity service, the name assigned SHOULD be the noun that best describes the entity (singular) that is the focal point of the service.

<noun>

For example, a service that provides agnostic business logic in support of the business entity ‘Person’ should be called “Person”.

Other examples: LabReport, Invoice.



UGP gating review

Notes

4.4 Infrastructure Service Layer Service Name

Standard Name Infrastructure Service Layer (Utility) Service Name

Standard Definition For a Utility service, the name assigned SHOULD best describe the agnostic cross-cutting function that is the context of the service. The minimum combination of verbs and nouns that most closely and adequately describes the cross-cutting function should be used.

For example, a service that provides a set of capabilities to log, query, and analyze events and messages across the enterprise, and thus facilitates the auditing of access to sensitive data, should be named “Audit Management”.

Other examples include “Logging” and “Authentication”.




Standard Name Infrastructure Service Layer (Utility) Service Name



UGP Review

Notes

4.5 Business Logic Service Layer Service Name

Standard Name Business Logic Service (Task) Layer Service Name

Standard Definition For a Task (or Orchestrated Task) service, the name assigned SHOULD be either the verb-noun combination, or the noun that best describes the non-agnostic (i.e., context-specific, single-purpose) business task that is the context of the service.

<verb> <noun>

For example, a service that provides business process-centric logic for registering a subject to a trial could be called either “Register Subject”, or “Subject Registration”.

Other examples include “Order Management” and “Medication Management”.



UGP Review

Notes

4.6 Portal Service Name

Standard Name Portal Service Name

Standard Definition For Portal services, (portlet) names assigned SHOULD be either the verb-noun or the

noun that best describes the non-agnostic business task that is the context of the service, similar to Task Services.

[<verb>] <noun> Portlet

For example: “Lab Results Portlet”.



UGP Review

Notes




5 Capability Naming Standards

Standard Name Capability Name pattern

Standard Definition All capability names SHOULD follow “verb” + “noun” + [“subject”] format, where:

“verb” is the action that the consumer is performing; and

“noun” is the name of the primary object on which the action is being performed.

The (optional) subject allows for distinguishing between different logical subjects that may be meaningful to use for certain nouns. Examples include “UpdateOrder” and “UpdateOrderHeader”.

For standard verb list please refer to SOA-NM-CN Capability Name Verbs



UGP Review

Notes

5.1 Capability Name Context

Standard Name Capability Name context

Standard Definition The names assigned to the capabilities of a service SHOULD fall within the context of the service that is indicated by the service name.

For example, given an entity service called “Person”, which stores different kinds of Persons including physicians, the view history capability which will provide this functionality should NOT be named “QueryPhysicianHistory”. It should be named within the context of the service, (i.e., “QueryHistory”), as the service may store other kinds of Persons.



UGP Review

Notes Typically, the service name implies the context for the capability, making it useless to repeat the service name in the capability name.

For example: OrderManagement::updateOrderShippingAddress would result in the OrderManagement::updateShippingAddress name.




5.2 Capability Name Verbs

Standard Name Capability Name verbs

Standard Definition All capability names SHOULD use the following standard prefixes for common functionality. According to the Blueprint, standard verbs for HIAL capabilities SHOULD be:

Standard Prefix Description

Put For operations that create an object completely

Get For operations which retrieve a particular instance of an object using the identifier provided

List For operations that perform a query and return all the matching objects based on the input criteria

If a service exposes functionality that does not correspond with any of the prefixes below, then the most appropriate verb should be chosen.

Alternative Prefix Description

Create For operations that create an object completely.

Add For operations that add a child object to a parent object.

Initiate For operations that initiate the creation of an object.

Update For operations that update object attributes.

Amend For operations that modify object attributes once an object has been approved, finalized, or submitted.

Deactivate For operations that (soft) delete a particular object. Soft delete does not remove the object from the database, but removes it from the working set.

Activate For operations that change the state of an object from “deactivated“ to “active”.

Delete/Remove For operations that completely delete a particular object so that it will no longer be retrievable in any context.

Query/Find For operations that perform a query and return all the matching objects based on the input criteria.

Retrieve For operations which retrieve a particular instance of an object using the identifier provided.

Publish For operations that publish a particular object or artifact.

Submit For operations that submit a particular object for review or approval.

Withdraw For operations that withdraw submission of a particular object for review or approval

update<objectname> State

For operations that change the state of the primary object only.





Standard Name Capability Name verbs


UGP Review

Notes TBD: REST Service Capabilities follow HTTP operations convention.




6 WSDL/SOAP Naming Standards

Web service providers communicate with their customers (consumers) by means of publishing

the WSDL of the service. In most cases, developers create the client code for the service by

generating classes from the published WSDL file. Therefore, we need to ensure that the WSDL

that we publish, and which acts as a “bridge”, will help service consumers generate good client-

side code.

6.1 Unique Namespace

Standard Name Unique namespace

Standard Definition Each service WSDL MUST have its own namespace, to avoid naming conflicts between the messages, ports, and operations of different services.

HL7V3: MUST conform to fixed target namespace urn:hl7-org:v3



HIAL Registry Validation

Notes

Related Standard SOA-NM-GN-02 Name Uniqueness

6.2 WSDL Namespace Pattern

Standard Name WSDL Namespace pattern

Standard Definition The idealized structure for a WSDL or XSD namespace name has the form:

WSDL:

http://ehealthontario.ca/ws/<domain>/[servicename]/V<major>

XSD types:

http://ehealthontario.ca/xmlns/<domain>

Common (cross LOB) XSD types

http://ehealthontario.ca/xmlns/<conceptType>

Where:

domain = functional context or LOB

servicename = name of the service

major = two digit major version of the service

conceptType = element type like Address, Person

HL7V3: MUST conform to fixed target namespace urn:hl7-org:v3

http://ehealthontario.ca/ws/%3cdomain%3e/%5bservicename%5d/V%3cmajor

http://ehealthontario.ca/xmlns/%3cdomain

http://ehealthontario.ca/xmlns/%3cconceptType




Standard Name WSDL Namespace pattern



HIAL Registry validation

Notes Examples:

http://ehealthontario.ca/ws/hial/Audit/V01

http://ehealthontario.ca/ws/olis/ReportManagement/V02

http://ehealthontario.ca/xmlns/client/common

Note: Frameworks generate package names from the namespace in Java and .NET.

<wsdl:definitions name="ListPatients"

targetNamespace="http://ehealthontario.ca/ws/clentregistry/ListPatients/V02

">

…

</wsdl:definitions>

Related Standard SOA-NM-GN-0x Name Uniqueness

6.3 WSDL Documentation

Standard Name WSDL Documentation

Standard Definition Each service WSDL MUST include documentation with Business name and version of the service.

<wsdl:definitions name="ListPatients"

targetNamespace="http://ehealthontario.ca/ws/clentregistry/ListPatients/V02

">

<wsdl:documentation>List Patients,@version V2.0,@date 2011-08

</wsdl:documentation>

</wsdl:definitions>




Notes

6.4 WSDL/XSD File Names

Standard Name WSDL/XSD file names

Standard Definition Filenames MUST use the structure of the WSDL or XSD namespace as the basis for defining the structure of the filename.

The idea is to make the fully qualified filename a URL (or at least a URI). Making it a URL tells you where to locate the file.

In order to support multiple service consumers (using different minor versions), it will be necessary to provide access to each schema version and all its dependent parts.

http://ehealthontario.ca/ws/hial/Audit/V01

http://ehealthontario.ca/ws/olis/ReportManagement/V02

http://ehealthontario.ca/xmlns/client/common




Standard Name WSDL/XSD file names

With this approach, the idealized structure for the filename is:

http://ehealthontario.ca/ws/<domain>/[servicename]/V<major>.<minor>/<filename>

or in the case of a file system:

file://ca/ehealthontario/ws/<domain>/<servicename>/V<major>.<minor>/<filename>

for Datapower artifacts:

local://<domain>/<servicename>/V<major>.<minor>/<schemas>/<filename>




Notes <wsdl:types>

<xsd:schema

targetNamespace="http://ehealthontario.ca/ClientRegistry/ManagePatient/V02"

>

<xsd:include schemaLocation="ca/ehealthontario/ws/

ClientRegistry/CustomerService/V02.01/CustomerService.xsd"/>

</xsd:schema>

</wsdl:types>

Datapower WSDL:

local://OLIS/GetLabResults/V01.01/schemas/ReportLabResults.wsdl

Related Standard SOA-NM-WS-02 WSDL Namespace pattern

6.5 WSDL Constructs – PortType, Port, Binding

Standard Name WSDL Constructs – PortType, Port, Binding

Standard Definition A port type is a named set of abstract operations and the abstract messages involved. Each portType name must be unique across all of the services in the namespace. Since the service names also have to be unique in the namespace, incorporating the service name into the portType name also guarantees the uniqueness of the portType name.

Binding provides details of the portType’s implementation; the binding is then used in defining a port (an actual interface instance) on the service. The port has its own name.

WSDL Artifact Naming Conventions

message <operationName>Request|Response

portType <serviceName>Service

SOAP 1.1 binding <serviceName>Soap11Binding

SOAP 1.2 binding <serviceName>Soap12Binding

http://ehealthontario.ca/ws/%3cdomain%3e/%5bservicename%5d/V%3cmajor%3e.%3cminor%3e/%3cfilename





SOAP 1.1 port <serviceName>Soap11Port_<VMajor>

SOAP 1.2 port <serviceName>Soap12Port_<VMajor>

Service Name <serviceName>Ports

HL7V3: MUST conform to rules defined in TLI specification.




Notes Best practice: Make sure that the WSDL that we publish, and which acts as a “bridge”, will help service consumers generate good client-side code.

wsdl:portType translates to the Java or C# interface (business interface) of a Web Service

(where each operation maps to a method of the interface). Used by C# to create a client class name.

wsdl:service in Java translates to, essentially, a factory class that extends

javax.xml.ws.Service. This class has "get" methods for each port defined as part of the service element. "getPortName" methods return a dynamic proxy that implements the service business interface.

<wsdl:portType name="LabReportService">

<wsdl:operation name="PutOrder">

<wsdl:input wsa:action="http://ehealthontario.ca/Laboratory/LabReport/PutOrder/V01" message="tns:PutOrderRequest"/>

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="LabReportServiceSOAP11Binding" type="tns:LabReportService">

<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>


<soap:operation soapAction="http://ehealthontario.ca/Laboratory/LabReport/PutOrder/V01"/>

<wsdl:input>

<soap:body use="literal"/>

</wsdl:input>

</wsdl:operation>

</wsdl:binding>

<wsdl:service name="LabReportServicePorts">

<wsdl:port name="LabReportServiceSOAP11Port_V01"

Business interface

LabReportService.java

LabReportServiceClient.cs

LabReportsService

Factory class

LabReportServicePorts

Port getter

getLabReportServiceSOAP11Port()





binding="tns:LabReportServiceSOAP11Binding">

<soap:address location="https://wsgateway.pst.ehealthontario.ca/Laboratory/LabReport/V01"/>

</wsdl:port>

</wsdl:service>

</wsdl:definitions>

Sample C# client:

[System.ServiceModel.ServiceContractAttribute(Namespace="http://ehealthontario.ca/ws/Laboratory/LabReport/V01", ConfigurationName="LabReportService")]

public interface LabReportService

{

[System.ServiceModel.OperationContractAttribute(IsOneWay=true, Action="http://ehealthontario.ca/Laboratory/LabReport/PutOrder/V01")]

[System.ServiceModel.XmlSerializerFormatAttribute()]

void PutOrder(PutOrder request);

}

public partial class LabReportServiceClient : System.ServiceModel.ClientBase<LabReportService>, LabReportService

{

public LabReportServiceClient(string endpointConfigurationName) :

base(endpointConfigurationName)

{

}

[System.ComponentModel.EditorBrowsableAttribute(System.ComponentModel.EditorBrowsableState.Advanced)]

void LabReportService.PutOrder(PutOrder request)

{

base.Channel.PutOrder(request);

}

}

Sample Java client:





public interface LabReportService {

@WebMethod(operationName = "PutOrder", action =

"http://ehealthontario.ca/Laboratory/LabReport/PutOrder/V01")

@Oneway

public void putOrder(SubmitOrder parameter);

}

@WebServiceClient(name = "LabReportServicePorts",

targetNamespace =

"http://ehealthontario.ca/ws/Laboratory/LabReport/V01",

public class LabReportServicePorts

extends Service

{

@WebEndpoint(name = "LabReportServiceSOAP11Port_V01")

public LabReportService getLabReportServiceSOAP11Port_V01()

{

return super.getPort(…);

}

}

6.6 SOAP Action Names

Standard Name SOAP Action Names

Standard Definition wsa:Action attribute for each WSDL input and output message MUST be defined.

wsa:Action name MUST reflect the fully qualified operation name, including WSDL namespace, service name, and operation name.

http://ehealthontario.ca/<domain>/<servicename>/<operation>/V<major>

This approach provides the maximum flexibility in defining endpoints. With this approach, all requests could be sent to a single endpoint (location) without ambiguity: the SOAP action uniquely identifies the required operation.

HL7v3: TLI Rule 50 (Ref9 : TLI Spec)The naming convention of WS Actions is designed to

support multiple versions of Web Services and HL7 v3 messages, and is structured as:

http://ehealthontario.ca/%3cdomain%3e/%3cservicename%3e/%3coperation%3e/V%3cmajor




Standard Name SOAP Action Names

urn:hl7-org:v3:{Interaction ID}.{Interaction version}

Where {Interaction version} : “LE” (Local) or “NE” (Normative) + YYYYMMDD




Notes Use WS-Addressing wsa:Action and not an HTTP-specific soapAction to provide protocol neutrality.

<wsdl:portType name="TestResultsPortType">

<wsdl:operation name="GetResults">

<wsdl:input wsa:Action="http://ehealthontario.ca/Laboratory/TestResults/GetResults/V01 " message="tns:GetResultsMessage" name="GetMessage"/>

<wsdl:output wsa:Action="http://ehealthontarioca/Laboratory/TestResults/GetResults-Response/V01" message="tns:GetResultsResponseMessage" name="GetResponse"/>

</wsdl:operation>

</wsdl:portType>

HL7v3:

<wsdl:portType name="REPC_AR000004CA_I">

<wsdl:operation name="REPC_IN000012CA_I">

<wsdl:documentation>

Requests that a new allergy or intolerance record be recorded against the specified patient.

</wsdl:documentation>

<wsdl:input message="hl7:REPC_IN000012CA"

wsa:Action="urn:hl7-org:v3:REPC_IN000012CA.LE20080203"/>

<wsdl:output message="hl7:REPC_IN000012CA-Response"

wsa:Action="urn:hl7-org:v3:REPC_IN000012CA-Response.LE20080203"/>

</wsdl:operation>

</wsdl:portType>

Related Standard




6.7 Service Address Endpoints

Standard Name Service Address Endpoints

Standard Definition Address location names indicate the actual connection points (physical destinations) to which operation requests are directed. Endpoint names identify the lines of business and services, and may also indicate versions.

Endpoint locations standards:

External DNS: <prefix>.[<region>].<env>.ehealthontario.ca

Internal DNS: <prefix>.[<region>].<env>.ont.gss

URI: /<domain>/[subdomain]/<servicename>/[Vmajor.minor]

Ports: 443 – TLS; 4443 – Mutual SSL; 80 - HTTP

Where:

1. prefix: standard prefix for all services IF-GTWY: “wsgateway”, IF-BKBN: “backbone”, Native services “*” lob names.

2. region: HIAL region that is providing/owns service. “cgta”| “cswo”|”cneo” (nothing for provincial – it’s default, not applicable for LOB).

3. env: testing environment “prod” | “pst” | “fit”.

4. domain: business domain “ClientRegistry”, “Laboratory”, “Portal”.

5. subdomain: optional if further refinement is needed; similar to Topic in HL7V3 “Orders”, “Results”, “PubSub”.

6. servicename: name of the service.

7. major.minor: version of the service (e.g., 02 or 02.02).

Rule: If client sends specific service version in URI then IF/HIAL routes to this specific

version. If client does not send version or minor version, then the IF/HIAL routes request based on client certification to the most appropriate version.

Rule: Service MUST be accessed using same endpoint names from Internet and MPN.




Notes External (provincial and regional gateway services for external clients and clients accessing though MPN):

1. CR Client Management Service Version 1.0 external endpoint in prod:

https://wsgateway.prod.ehealthontario.ca/ClientRegistry/ClientManagement/V01

2. CR PubSub Subscription Management Service Version 1.1 external endpoint in pst:

https://wsgateway.pst.ehealthontario.ca/ClientRegistry/PubSub/SubscriptionManagement/V01.01

3. Patient Portal WSRP service version 2.0 external endpoint in fit:

https://wsgateway.fit.ehealthontario.ca/Portal/Patient/WSRPBaseService/V02

4. CR Client Management service CSWO-owned endpoint in prod:

https://wsgateway.cswo.prod.ehealthontario.ca/ClientRegistry/ClientManagement

%3cprefix%3e.%5b%3csegment%3e%5d.%3cenv%3e.ehealthontario.ca

prefix%3e.%5b%3csegment%3e%5d.%3cenv












Standard Name Service Address Endpoints

Internal (provincial and regional gateway/backbone for internal clients):

1. Lab Results Reports Distribution service version 1.0 internal endpoint in prod:

https://wsgateway.prod.ont.gss/Laboratory/Results/ReportDistribution/V01

2. Lab Results Reports Distribution service version 2.2 CSWO-owned internal endpoint in prod:

https://wsgateway.cswo.prod.ont.gss/Laboratory/Results/ReportDistribution/V02.02

3. CR Client Management internal backbone endpoint in prod:

http://backbone.prod.ont.gss/ClientRegistry/ClientManagement

4. CR Client Management version 1.0 – CSWO-owned internal backbone endpoint in prod:

http://backbone.cswo.prod.ont.gss/ClientRegistry/ClientManagement/V01

Native (Native/LOB services for internal connections):

http://sts.ur.prod.ont.gss/UserRegistry/STS/V1

http://cr.prod.ont.gss/ClientRegistry/EMPI/AddClient/V2

Architecture Decisions

Versioning of URLs options:

1. Content based routing: include version/ client ID in payload:

Pros: Single endpoint for all clients, routing done by ESB, supported by WSRR;

Cons: Client has to include fields in the payload or ESB has to add code to use some existing fields as version/client IDs.

2. Context based routing: include Major version in URL:

Pros: More descriptive endpoints, No code on ESB to do routing;

Cons: Client has to be updated and endpoints should be modified for version changes.

Decision: Use hybrid of URI and mediated versioning, as it provides the most flexible approach.

https://wsgateway.prod.ont.gss/Laboratory/Results/ReportDistribution/V01



http://backbone.prod.ont.gss/ClientRegistry/ClientManagement

http://backbone.cswo.prod.ont.gss/ClientRegistry/ClientManagement/V01

http://sts.ur.prod.ont.gss/UserRegistry/STS/V1

http://cr.prod.ont.gss/ClientRegistry/EMPI/AddClient/V2




7 Service Naming Example - Putting all the Names Together

The following is an example of service and artifact names based on the policies defined in this

document. The Business Context for this example is the Lab Ordering service:

Business Domain: Laboratory

Business Service Name: Order Request

Business Capability: Put Order Request

WSDL File “OrderRequest.wsdl”

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"

xmlns:tns="http://ehealthontario.ca/ws/Laboratory/LabReport/V01"

targetNamespace="http://ehealthontario.ca/ws/Laboratory/LabReport/V01">

<wsdl:documentation>Lab Reports Query, @version 1.0, @date 2012-09</wsdl:documentation>

<wsdl:types>

<xs:schema targetNamespace="http://ehealthontario.ca/ws/Laboratory/LabReport/V01" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://ehealthontario.ca/ws/Laboratory" elementFormDefault="qualified" attributeFormDefault="unqualified">

…..

</xs:schema>

</wsdl:types>

<wsdl:message name="PutOrderRequest">

<wsdl:part name="parameter" element="tns:SubmitOrder"/>

</wsdl:message>

<wsdl:portType name="LabReportService">


<wsdl:input wsa:action="http://ehealthontario.ca/Laboratory/LabReport/PutOrder" message="tns:PutOrderRequest"/>

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="LabReportServiceSOAP11Binding" type="tns:LabReportService">




<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>


<soap:operation soapAction="http://ehealthontario.ca/Laboratory/LabReport/PutOrder"/>

<wsdl:input>

<soap:body use="literal"/>

</wsdl:input>

</wsdl:operation>

</wsdl:binding>

<wsdl:service name="LabReportServicePorts">

<wsdl:port name="LabReportServiceSOAP11Port_V01" binding="tns:LabReportServiceSOAP11Binding">

<soap:address location="https://wsgateway.pst.ehealthontario.ca/Laboratory/LabReport/V01"/>

</wsdl:port>

</wsdl:service>

</wsdl:definitions>




8 References

ID Reference Location/Description

Ref SOA Principles Web Site: Standardized Service Contract

http://www.soaprinciples.com/standardized_service_contract.php

Ref2 SOA Patterns Web Site: Canonical Expression

http://www.soapatterns.org/canonical_expression.php

Ref3 SOA: Principles of Service Design P 39

Ref4 ZapThink: Are services Nouns or Verbs?

http://www.zapthink.com/2009/10/14/are-services-nouns-or-verbs/

Ref5 NCI SAIF Service Inventory Blueprint

https://wiki.nci.nih.gov/display/SAIF/6.4+-+Catalog+of+NESI+Precepts

https://wiki.nci.nih.gov/display/EAWiki/SOA+Service+Taxonomy

Ref6 FHIR: Resource design considerations

http://wiki.hl7.org/index.php?title=Category:FHIR_Discussion

Ref7 Understanding generated WCF client code

http://msdn.microsoft.com/en-us/library/ms733881.aspx

Ref8 JAX-WS client code naming http://myarch.com/wsdl-naming-conventions

Ref9 Transport Layer Interoperability Specification

http://wiki.marc-hi.ca/TLI/Application/Rule_50

Ref10 Managing endpoints http://documentation.softwareag.com/webmethods/wmsuites/wmsuite8-2_sp2/CentraSite/8-2-SP2_CentraSite/ig-deploy/Impl_Endpoints.htm

Ref11 Web Services Enablement for Healthcare HL7 Applications


http://www.soaprinciples.com/standardized_service_contract.php

http://www.soapatterns.org/canonical_expression.php

http://www.zapthink.com/2009/10/14/are-services-nouns-or-verbs/



https://wiki.nci.nih.gov/display/EAWiki/SOA+Service+Taxonomy

http://wiki.hl7.org/index.php?title=Category:FHIR_Discussion


http://myarch.com/wsdl-naming-conventions

http://wiki.marc-hi.ca/TLI/Application/Rule_50

http://documentation.softwareag.com/webmethods/wmsuites/wmsuite8-2_sp2/CentraSite/8-2-SP2_CentraSite/ig-deploy/Impl_Endpoints.htm




SOA Standards Service Naming Conventions - eHealth · PDF fileSOA Standards Version: 1.2...

Documents

Transcript of SOA Standards Service Naming Conventions - eHealth · PDF fileSOA Standards Version: 1.2...