Ellipse Web Services Overview

Ellipse Web Services Overview

Contents
Ellipse Web Services Overview 2
Commercial In Confidence 3
Introduction 4
Purpose 4
Scope 4
References 4
Definitions 4
Background 5
Ellipse Web Services - Overview 6
Executive Summary 6
Architecture Overview 6
Components Overview 6
Ellipse Server Middleware 6
J2EE Application Server 6
Enterprise Session Bean Interface (ESBI) 7
Client Access 7
SOAP over HTTP 7
Request Message 7
Simple Inbound Message, server by an MSK 7
Reply Message 8
Simple Outbound Message 8
Connection Handling 8
Transaction Control 8
Commercial In Confidence
Copyright 2016 ABB
All Rights Reserved
Confidential and Proprietary
Legal Disclaimer
The product described in this documentation may be connected to, and/or communicate information and data via, a network
interface, which should be connected to a secure network. It is your sole responsibility to ensure a secure connection to the
network and to establish and maintain appropriate measures (such as but not limited to the installation of firewalls, application
of authentication measures, encryption of data, installation of antivirus programs, etc.) to protect the product, the network,
your systems, and the interface against any kind of security breach, unauthorised access, interference, intrusion, leakage,
damage, or corruption or theft of data. We are not liable for damages or losses related to any such security breach,
unauthorised access, interference, intrusion, leakage, damage, or corruption or theft of data.
Introduction

Purpose
The purpose of this document is to provide an overview of the Ellipse Web Services (EWS) for Ellipse 8. The services provide
access to Ellipse business functionality from external systems. It contains an overview of the architecture, the components
contained within that and how these work.

Scope
The scope of this document encompasses an overview of the Ellipse Web Services for Ellipse 8. The EWS framework also
includes the Ellipse Event Framework (EEF). For an overview of this refer to the Ellipse Event Framework Overview [1].

References
Doc Document Title Author Version Document Reference
Ref
[1] Ellipse Event Framework Overview David Caine 8 Event Framework 8 Overview.doc

Definitions
Item Definition
API Application Programming Interface
EDOI
EEF Ellipse Event Framework
EJRA Ellipse Java Resource Adapter
Ellipse ABB Information Management System
EROI
ESBI Ellipse Session Bean Interface
EWS Ellipse Web Services
HTTP Hypertext Transfer Protocol
HTTPS Hypertext Transfer Protocol over Secure Socket Layer
J2EE Java 2 Platform, Enterprise Edition
JNDI Java Naming and Directory Interface
JVM Java Virtual Machine
POJO Plain Old Java Object
SOA Service Oriented Architecture
SOAP Simple Object Access Protocol
TP Transaction Processor
XML Extensible Mark-up Language
WSDL Web Service Definition Language
Background
Ellipse has evolved into an open, interoperable product capable of supporting complex integration scenarios within the
customer's enterprise landscape. This is fundamental to the positioning of Ellipse as a leader in delivering flexible business
solutions.
An effective integration strategy that leverages SOA will deliver significant business benefits, including: reducing ongoing
infrastructure maintenance costs, decreasing system complexity, improving the degree of integration openness, and vastly
improving the ability of the organization to rapidly respond to changing internal and external business conditions.
In an effort to address these business requirements, ABB has developed the Ellipse Web Services platform, which is the
implementation of the Service Oriented Architecture for Ellipse. Ellipse Web Services expose the business application layer as a
collection of building blocks upon which simple or composite inbound services are exposed to external systems.
In addition to this ABB has developed the Ellipse Event Framework, which is the implementation of the Event Driven
Architecture for Ellipse. The Ellipse Event framework provides the capability for Ellipse to publish events to subscribing
applications as XML messages conforming to the business entity schema definitions.
Together the Ellipse Web Services and the Ellipse Event Framework make up the ABB Intelligent Integration Framework. This
framework is the strategic solution platform for deploying and integrating web services to meet business requirements.
Ellipse Web Services - Overview

Executive Summary
The Ellipse Web Services (EWS) module has been created to enable integration using Service Orientated Architectural (SOA)
principles with Ellipse. The Ellipse Web Services enable access to Ellipse functionality to process business functions either
through simple or composite services. The services are currently used by ABB and customers to provide integration between
Ellipse other application packages. The following should be noted in relation to this module:

• Ellipse Web Services are available from Ellipse 6.3.3 onwards.

• The Ellipse Web Services can be accessed via the SOAP over HTTP.
• Currently the Ellipse Web Services do not provide access to all Ellipse functionality. For the list of available services refer
to the URL https://<server>:<port>/ews/ where the server and port values are those for your Ellipse installation.
• Ellipse Adapters are also available as part of the module. These are the functional equivalent of the Ellipse Services but
with additional components to allow the services to be deployed into a third party integration broker product. This allows
customers to perform EAI based integration using the toolsets provided via these brokers.

Architecture Overview
The logical architecture of the Ellipse Web Services can be seen in the following diagram:

Components Overview
The Ellipse Web Services are architected in a series of layers that provide access to endpoints contained within the Ellipse
backend. An overview of these components is specified in the following sections.

Ellipse Server Middleware

Various components on the Ellipse backend server allow the Ellipse application to communicate with J2EE application servers
and other middleware software. A discussion of these components is outside the scope of this document.

J2EE Application Server

Ellipse Web Services run inside a J2EE compliant application server (JBoss). The application server provides standards compliant
libraries that allow applications such as Ellipse Web Services to communicate with the Ellipse backend server. These libraries
deliver access to databases, transaction handling, resources such as queues, authentication and numerous other capabilities.
Enterprise Session Bean Interface (ESBI)
The Enterprise Session Bean Interface or ESBI consists of the following components:

• Core handling of interactions and connection management for Ellipse. This communicates primarily with the EJRA layer.
• A collection of beans and WSDL that constitute the implementation of the Enterprise Service Interface
POJOs are generated from the Ellipse Business Object repository, which contains a description of the methods, attributes and
operations of each Ellipse business entity. For each entity, a method is generated for each Ellipse Business Object method. For
example, the WorkOrder entity supports a Create operation. The generated POJO will contain the following method:
public WorkOrderCreateReply create (ConnectionId connectionId, WorkOrderCreateRequest request)

This method accepts a token representing an established session to the Ellipse instance, plus a request object. It will invoke the
WorkOrder Create operation and return the results in the reply object.
Each POJO is exposed to third party applications via a front end provided by the Application Server. This front end translates
standards-compliant SOAP messages into calls to the corresponding ESBI methods, with parameters translated into
corresponding java Data Transfer Objects (DTOs). The response from these calls (or the exception thrown when an error has
occurred) is translated back into a SOAP reply.
As a part of adding the front-end interface to the POJOs, a set of standards-compliant Web Services Definition Language (WSDL)
files is generated, one for each POJO. This describes each Ellipse Business Object method and how to call it, including details of
each field within the request and reply message.

Client Access
This section provides an overview of the Web Service Interface from a message-based perspective. It will provide information
on the component technologies that are being used in the processing of a message. Access is available via SOAP over HTTP

SOAP over HTTP

A traditional Web Service implementation operates with the following:

• HTTP transport
• SOAP bindings
• Synchronous invocation

Request Message
This section outlines the handling of a SOAP request message.

Simple Inbound Message, server by an MSK

The SOAP engine is deployed as a web application, and provides a servlet which takes care of the following:

• Extracting the SOAP envelope from the request message.

• Deserialising the message. This involves

• validation of the message elements according to schema

• establishment of a mapping between schema types and Java objects
• instantiation of relevant Java objects from the element state in the SOAP message
 • Finding the service endpoint.
• Invoking the endpoint with the objects which resulted from deserialisation.

Reply Message
This section outlines the handling of a SOAP reply message.

Simple Outbound Message

The path of a message on the way out is mostly a re-tracing of the steps taken on the way in. The following details processing
from the point where the session bean returns the result of its method invocation as a Java object. This object is handled in the
following way by the SOAP engine:

• Object is serialised according to JAX-RPC guidelines, resulting in a set of XML nodes which adequately represent the
object state.
• A new SOAP envelope is created, into which the serialised object is inserted.
• The envelope is inserted into a HTTP response, and socketed back to the client.

Connection Handling
Creating Ellipse connections can be an expensive process. The services infrastructure code of EWS provides automatic
connection pooling for re-use of created connections to reduce any potential performance impact.
Each request to an Ellipse web service will require the provision of Ellipse credentials (Username, Password, District, Position)
to be provided. When the request is processed, a check will be made in the application server to determine if a connection for
those credentials already exists in the connection pool. Where this is the case, the connection will be re-used. If the connection
is found to be invalid (e.g. it has timed out), the existing connection will be removed from the pool, a new one will be created
and then added to the pool. Where this is not the case, a new connection will be created and added to the pool.

Transaction Control
Each Ellipse web service that is called to process an update will have a transaction initiated by the application server, which will
then be committed or rolled back depending on the result of the update.
Where a client application requires multiple Ellipse web services to process updates within the scope of a single transaction, an
Ellipse Transaction service can be called that will allow the client application to control initiation of a transaction and the
subsequent commit or rollback of that transaction depending on the results of the update processing.