ECS Interface Specification
# Topic
1Overview
2Rules & Notations
3Fundamentals
4Service Methods

Overview

 This specification covers the definition of the Futura4Retail WebService interface definition (Futura4ECS).

Description

Futura4ECS is the default WebService of Futura Retail Solution AG for internal purposes as well as service integration for customers resp. partners.
Applications utilizing the service create stubs for the corresponding Futura4ECS WSDL document, which represents a SOAP WebService conform to WS-I (Basic Profile 1.1). By default the webservice is provided with a configuration defining a HTTP endpoint; HTTP resp. HTTP over TLS are assumed as the transfer protocol on target systems.

Scope

The Futura4ECS WebService provides methods for synchronous data integration in normalized form to publish functions of the Futura4Retail ERP backend system for external software components. All provided operations are designed to act stateless, therefore client applications resp. components utilizing the service are responsible to manage application state and (external) transaction integrity.

Compatibility

Specification conforms to namespace "http://ws.futura4retail.com/Futura4ECS/2018/02".
Required backend systems are Futura4Retail Versions 6.6.41 or higher.
Specific compatibility definitions (full version) are part of the respective ECS Release Notes.

System boundaries

The normalized service interface enables de-coupling of involved software systems.
Technical conditions: HTTP(S), SOAP, Binding Style/Use: document/literal wrapped.
Futura4Retail systems use native processes on Windows platforms (.NET 3.5/4.0).
Due to the normalized XML interface applications utilizing the service can be realized based on all known platforms, languages and frameworks supporting TCP networks, HTTP, XML and SOAP. For decoupling internal functionality from the interface transformation components normalize Futura4Retail data contracts and functions. All WebService calls are stateless and represent isolated transactions; internal calls to 4Retail functions are implemented accordingly.

Rules & Notations

 For effective high-quality development of a public service some typical arrangement must be made concerning names and technical boundary conditions, that shall be considered even for customer specific derivatives to this service component. The service definition is always based on a contract-first approach internally (guarantees maximum interoperability/contract stability).

Notations

Futura4ECS provides methods for reading and writing Futura4Retail data. The respective actual operation purpose shall be transparent to the webservice itself. Hence it some basic rules for method and type names are defined.

Operations

Service method names begin with a prefix identifying the type of data usage (read, write), followed by a functional suffix containing the name of the corresponding data type. The content of request objects corresponds to the respective definition of the request data type (exceptions to this norm are part of request definition).

PrefixDescription
GetPrefix for reader methods for a specific data type, e.g. GetArticles.
SendPrefix for writer methods for a specific data type, e.g. SendCustomer.

Type definitions

Futura4ECS data types correspond to a extensively homogenized transformation of Futura4Retail data types/names, as fas as reasonable for a public service interface. Too specific resp. functionally too restrictive names in the backend are adjusted accordingly. Data structured and names are chosen preferably by the following rules:

RuleReason
Definition language englishInteroperability, global operation, uniformity
Umlauts not allowedInteroperability, global operation, uniformity
Arbitrary object structureIntegrity
Circular references not allowedIntegrity, avoid side effects
Keywords not allowed Interoperability, forbidden keywords are:
Interface, Class, Import, Package, Unit, Port
Character encodingInteroperability, global operation, uniformity
Non-integer numbers are 'decimal'Interoperability, global operation, uniformity

Common WebService Conditions

For interoperability (see WS-I compliance) the following rules apply:

Service characteristicRule
WS-I compliance levelISO/IEC 29361:2008, WS-I Basic Profile 1.1
Transfer protocolHTTP
Network protocolSOAP
SOAP style/useDocument/literal wrapped
Target namespacehttp://ws.futura4retail.com/Futura4ECS/2018/02
Object namesSubject to domain modell, Camel-case (e.g. ProductGroups)
Service name suffix<object-name>Service
Service port suffix<object-name>Port
Service method namesCamel-Case (e.g. GetProductGroups)
Service versioning namespace suffix <year-4digit>/<sequence-number>, e.g. "2012/02".
(Variations can be enhanced on-demand)

Fundamentals

 The interface requirements are defined by the (customer) specific Futura4Retail ERP environment.
The underlying requirements analysis for this service covers the known use cases for a client application like Futura4-Apps, WebShops and external import/export components.
Specific technical aspects for WebService provisioning and Client production resp. adapters as well as aspects like security, availability, system boundaries, controlling, scalability and state transitions are not part of this specification.

Request objects

Service method calls can be parameterized by request objects serving a filter criteria as well als criteria for building response objects in the target environment.
Generally data objects can be selected by defining an Id field. Multiplicity of the set of objects is 0..*.
By using optional use-case specific Ids and optional criteria (e.g. a filter parameter) a client can control type and scope of returned content (keeps defined object structure).
For example a FilterLockedCustomers parameter with value true is used to reduce a Customer resultset to those records with an active Gesperrt flag in 4Retail database.
Another example is the ResponseDetails setting in a GetArticle request, which is used to reduce the details of records if the Article resultset (ResponseDetails = ARTICLE_BASE would only return basic article information without branch details).

Such a mechamism was introduced to optimize services regarding quantity and polymorphism of provided operations, and cares for needs based selection and appropriate reduction of transfer size.

Iterators

 An Iterator is meant to be a ECS/Futura4Retail term within the scope of mass data replication.
Even if this is never an optimal solution, ECS supports (synchronous) replication of a complete set of certain data types by providing so-called IterationConstraints in some request object definitions.

In case of mass data processing requested by a client system (e.g. Articles, Customer) the specified amount of data must be splitted into segments, because firstly a synchronous call must return after a certain time, secondly there can not be transferred any amount of data in one operation and thirdly the response size of a service-oriented process should not exceed hundreds of KB (additionally XML marshalling is some worst-case for an efficient data transfer, therefore never an optimum).

Generally - especially XML-based - WebServices are not suitable for replicating large amounts of data due to their stateless, synchronous and XML-(un)marshalling characteristics as well as lack of efficiency . (We therefore strongly recommend another approach to realize full data replication by accepting the need for MQ-based or classic data integration patterns) .

To get things done in some manageable way for SOAP-based client processes during stateless communication, the signatures of certain Request and Response objects are provided with appropriate paging information to allow iteration on the stored data for a certain period of time.
The technical most demanding internal operations for this purpose should advice the client system to act with caution in scope of IterationRequests, because these are never small webservice methods with response times < 100 ms.

Iteration constraints

If a service method is defined to support iterations the client system needs to specify so-called IterationContraints for at least a BlockSize greater 0, a BlockIndex greater or equal 0 and an IterationId.
  1. <ns:IterationConstraints>
  2.   <ns:BlockSize>10</ns:BlockSize>
  3.   <ns:BlockIndex>0</ns:BlockIndex>
  4.   <ns:IterationId>ClientIteration001</ns:IterationId>
  5. </ns:IterationConstraints>
The backend system then assigns the IterationId to a set of records matching all defined selection/filter criteria; if the dataset is not yet built the backend will create it (could take long depending on backend capabilities and the actual amount of data). The resulting amount of data will be splitted into segments with size BlockSize and indexed with a zero-based BlockIndex; these "blocks" of data are then returned as requested.
The client system can iterate over the created amount of data blockwise by varying the BlockIndex and re-using the IterationId used by the backend for this purpose. If the IterationId is not used anymore, the system will discard the corresponding Iterator after 5 minutes of inactivity. If an IterationRequest is sent without IterationContraints, the service will set default values:

Constraint ParameterDefaultRange of values
BlockSize50[1,200]
BlockIndex0[0,)
IterationId<null><string> (whitespace-trimmed)

IterationStatus

If a service method is defined to support iterations the service provides additional information as an IterationStatus in the response object. The IterationStatus reflects the original IterationContraints and specifies the active IterationId, the number of returned data objects (Count), the maximum number of records reachable by the iteration (MaxCount) as well as some arbitrary comment (IterationInfo). The client system can detect the maximum BlockIndex or the end of iteration by relating BlockSize, Count and MaxCount on eath other.
  1. <IterationStatus>
  2.   <IterationId>ECS_ArticleRequest_60195d14-ced4-4883</IterationId>
  3.   <MaxCount>17568</MaxCount>
  4.   <Count>10</Count>
  5.   <RequestedBlockIndex>0</RequestedBlockIndex>
  6.   <RequestedBlockSize>10</RequestedBlockSize>
  7.   <IterationInfo>Futura4ECS returned (10) Articles.</IterationInfo>
  8. </IterationStatus>

Response objects

The webservice response to a SOAP request contains the requested payload (may be empty) as well as information about the current iteration (IterationStatus), the initiated Task and additional information that may include errors and/or warnings occured internally or due to failed request validation. With this information the client system can trigger appropriate local operations, e.g. continue or abort an iteration, or reconfigure its' worker thread for later processing.
  1. <GetArticlesResponse
  2.   xmlns="http://ws.futura4retail.com/Futura4ECS/2018/02">
  3.   <GetArticlesResult>
  4.     <TaskStatus>
  5.       <ProcessingStatus>FINISHED</ProcessingStatus>
  6.       <TaskInfo>GetArticles call finished.</TaskInfo>
  7.       <WorkerRecommendation>STOP</WorkerRecommendation>
  8.       <WorkerRecommendationDelaySeconds>0</WorkerRecommendationDelaySeconds>
  9.     </TaskStatus>
  10.     <IterationStatus>
  11.       <IterationId>ECS_ArticleRequest_60195d14-ced4-4883</IterationId>
  12.       <MaxCount>17568</MaxCount>
  13.       <Count>10</Count>
  14.       <RequestedBlockIndex>0</RequestedBlockIndex>
  15.       <RequestedBlockSize>10</RequestedBlockSize>
  16.       <IterationInfo>Futura4ECS returned (10) Articles.</IterationInfo>
  17.     </IterationStatus>
  18.     <Articles>
  19.         ...

Independent from an iteration, a client system can evaluate the (TaskStatus) which provides a ProcessingStatus about the result and a recommendation for further client processing (WorkerRecommendation). Due to the system limitations mentioned below, the client system should be designed in such a defensive way to reduce the probability of unexpected behaviour.

Normally the service methods will provide the requested payload together with ProcessingStatus FINISHED synchronously. If internal task processing is de-coupled from the request, a response could report a ProcessingStatus PENDING leaving the response payload empty and recommending WAIT together with a delay in seconds. The client system can follow the recommendation and reduce the load, abort the process or ignore this TaskStatus.

Delete Data

Service methods causing disposal of data are currently not allowed, i.e. data cannot be removed by omitting parts of a type definition in a request object. If data of a specific type are chosen to be optionally removed by a ECS service method call, it will only be marked as deleted to avoid a deep impact on the target backend system)

Security

In a later expansion stage all security related aspects concerning WebServices will be covered by applying WS-Security standards for Authentication, Authorization, Signing and Encryption, subject to a precise catalog of requirements. WS-Security is excluded in scope of this specification, therefore protection of the ECS service has to be managed administratively on webserver and the client system, e.g. using HTTP over TLS, server certificates and optionally client certificates.

System limitations

Futura4 WebServices use the same data access framework as the Futura4Retail ERP system.
Therefore the system limitations of ECS comply with the limitations of a Futura4Retail backend to a large extent.

With a comparatively more intensive use of operations executed concurrently on the WebService, availability and response times resp. performance depend on the capability and current working load of the backend system progressively. In less efficient server environments mass data transfers possibly could not be designed for concurrent execution resp. high request frequencies could lead to big delays, especially when using functions with complex internal database operations.

References

# Reference
1WS-I (Web Services Interoperability Organization)
2OASIS, Organization for the Advancement of Structured Information Standards
3WS-I Profiles ISO
4WSDL Reference Implementation in Futura4Retail Artifact Repository

Service Methods

 The ECS WebService defines the following methods in SOAP 1.1 Service Endpoint. The respective specifics of the business objects can be currently found in WSDL; the semantics of the individual elements will be updated with future releases of this specification.

A distinction is made between master data and transaction data: For classification of the (primarily) relevant request parameters the following markers are used:

Legend about (optionally) required request parameters
  Parameter is mandatory.
  Parameter is optional.
  Parameter is mandatory in specific contexts and use cases.
  Parameter is forbidden in specific contexts and use cases.

Request configuration

There are four different configurations for requests that may have an impact on the internal processing. Simple Get and Send requests operate mostly on one or a few objects and are therefore analysed faster. Iteration requests require a specific internal indexing based on the chosen selection criteria. ChangedSinceDate requests, depending on the complexity of the internal object structure, trigger corresponding database operations. Combined Iteration and ChangedSinceDate requests must on the one hand trigger complex queries and on the other hand make a specific indexing:

#  Request configuration Request structure
1StandardStandard request without Iteration and without ChangedSinceDate
2IterationRequest with IterationConstraints, without ChangedSinceDate
3ChangedSinceDateStandard request incl. ChangedSinceDate parameter
4Iteration+ChangedSinceDateRequest with IterationConstraints and ChangedSinceDate