ellipse web services client application...

Ellipse Web Services Client Application Guide

Ellipse Web Services Client Application Guide

ContentsEllipse Web Services Client Application Guide 2

Commercial In Confidence 3

Introduction 4

Historical References 4

Purpose 4

Scope 4

References 4

Definitions 4

Overview of Ellipse Web Services 5

Connection Processing for EllipseWebServices 6

ConnectionPooling 6

ConnectionError Handling 6

Connection Management 7

Client Managed Transactions 7

Data Transfer Objects 8

Request DTOs 8

Reply DTOs 8

Required attributes DTOs 8

Operations/Interactions 9

Read 9

Retrieve 9

Update 10

Exception Handling 11

Warnings 11

Errors 11

Date / Time Processing for Ellipse Web Services 12

General Notes 12

Input of Date/Time Values 12

Output of Date/Time Values 12

Operation Context Overview 13

Run As Overview 14

Tracing 15

ClientTransaction Control 16

Initiate Transaction Processing 16

Complete Transaction Processing 16

Locale Setting 17

Commercial In ConfidenceCopyright 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 networkinterface, which should be connected to a secure network. It is your sole responsibility to ensure a secure connection to thenetwork and to establish and maintain appropriate measures (such as but not limited to the installation of firewalls, applicationof 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

Historical ReferencesIssue Date Author Status0.1 30/09/09 David Caine First Draft0.2 29/12/10 David Caine Second Draft

PurposeThe purpose of this document is to provide information relevant to client applications/ adapters that call Ellipse WebServices(EWS). The primary source of information relevant to Ellipse services are the WSDL's, this document is to supplementthe information that is contained there. This is document is intended then to be an aid to developers of applications that callEllipse services.This document should be read in conjunction with the EWS Overview].

ScopeThe scope of this document encompasses the installation and deployment of the Ellipse Web Services in an Ellipse 8 (andabove) environment only.

ReferencesDoc Ref Document Title Author Version Document Reference[1] EWS Overview Roger Altena 0.1 EWS 8 Overview[2] EWS Client Conversion Charles O'Farrell 0.1 EWS 8 Client Conversion

DefinitionsItem DefinitionAPI Application Programming InterfaceEllipse Information Management SystemEJB Enterprise Java BeanEWS Ellipse Web ServicesJ2EE Java 2 Platform, Enterprise EditionJVM Java Virtual MachinePOJO Plain Old Java ObjectSOA Service Oriented ArchitectureSOAP Simple Object Access ProtocolXML Extensible Mark-up Language

Overview of Ellipse Web ServicesThe Ellipse Web Services (EWS) expose the Ellipse service endpoints using standard web technology that adheres to Webservices standards. The EWS are comprised of both POJO's generated from the Ellipse repository and coded Java classes. Theseare exposed using a Web Service Description Language (WSDL) interface which specifies the service contract to remote clients.These clients can then invoke the services using Simple Object Access Protocol (SOAP) messages.

Conceptually all Ellipse legacy repository objects are now services in their own right with their own methods and attributes asdefined by the repository. In addition coded java services (modelled in IBM RSA and developed in Eclipse) also provide EWSendpoints. The EWS interface is defined using WSDL which describes each method and its associated request and reply DataTransfer Objects. The WSDL also defines the messages the service will accept, and the protocol (HTTP, SMTP,FTP, etc.) theSOAP client must use to access the service.

Some of the main features of the Ellipse Web Services are as follows:

• All invocations are stateless. No data is maintained on the server between method calls.

• Unbounded/Bounded arrays are dealt with as arrays of DTOs instead of strings of data.

• Inbuilt transactional control at the application server level thus removing the need for specifying transaction boundarytags within the interaction XML.

• Specific request and reply type DTOs to define the valid inputs and outputs of an interaction with Ellipse.NB. The screen service is the one exception to invocations being stateless. To manage this screen service requests must bewrapped in a client managed transaction (via Transaction service). Refer to the Screen service documentation of furtherdetails.

Connection Processing for EllipseWebServices

ConnectionPoolingA connections table in the application server hosting the Ellipse web services holds the user credentials for service requeststhat have been processed. This allows for more efficient processing of service requests. Where a set of user credentials alreadyexists in the connection pool then no login processing is performed.

When a service request is processed the following occurs:

• The user credentials from the request message are checked against the connections table to determine if there is anexisting connection associated with those credentials.

• Where there is an existing entry connection id is used to process the web service request.

• Where there is not an existing entry in the connections table a new connection id is created, the connections table isupdated with the user credentials.

This therefore requires that Ellipse user credentials (Username, Password, District Code and Position Id) are provided for eachweb service request that is to be processed.

ConnectionError HandlingThe Connection Manager must be able to identify between Connection errors which are immediately retryable, and Connectionerrors which are not. For example timeout errors should be immediately retried (a limited number of times); where as aninvalid logon credentials should not be immediately retried, but should be returned to be addressed further.

Error Messages which are deemed as transient (immediately retryable) should be retried by the Connection Manager. If anerror occurs creating a connection to Ellipse, then the Connection Manager with throw a ConnectionException with the cause ofthe error. This exception will be caught in the client application / adapter, and cause the service to be retried. The clientapplication / adapter will wait for a configured period of time before retrying the service.

If the client application / adapter retries the service the configured number of times without success, then the service errorshould be returned to the client application / adapter for manual action.

The scenarios where there will be problems with connections to Ellipse are as follows:

Connection Closed:

In this scenario the Connection has been closed (via the closedManagedConnection method for the Ellipse Connection Managerservice). Where this is the case the following SOAP response will be returned:<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><soapenv:Header/><soapenv:Body> <soapenv:Fault> <faultcode xmlns:p773="http://exception.enterpriseservice.mincom.com">p773: EnterpriseServiceOperationException</faultcode> <faultstring>Error 0: Code: UNKN Message: No connection exists with a connection id of [225e79bfdd5d5049:-1babaaef:125679a3962:-7ff9] FieldName: FieldIndex: 0 DtoIndex: -1</faultstring> <detail encodingStyle=""> <p773:EnterpriseServiceOperationException xmlns:p773="http://exception.enterpriseservice.mincom.com"> <errorMessages> <ErrorMessageDTO> <code>UNKN</code> <dtoIndex>-1</dtoIndex> <fieldIndex>0</fieldIndex> <fieldName/> <message>No connection exists with a connection id of [225e79bfdd5d5049:-1babaaef:125679a3962:-7ff9]</message> </ErrorMessageDTO> </errorMessages> </p773:EnterpriseServiceOperationException> </detail> </soapenv:Fault></soapenv:Body></soapenv:Envelope>

Application Server Shutdown:

In this scenario the Application Server hosting the Ellipse web services has been shutdown or is not available. The creation of anew connection should be processed in this scenario with a configurable number of retries to handle situation whereApplication Server has been shutdown and is being restarted. Where this is the case the following SOAP response will bereturned:

Error getting response: java.net.ConnectException: Connection refused: connect

Application Server Restarted:

In this scenario the Application Server hosting the Ellipse web services has been restarted. Where this is the case the followingSOAP response will be returned:<soapenv:Envelope> <soapenv:Header/> <soapenv:Body> <soapenv:Fault> <faultcode>p773:EnterpriseServiceOperationException</faultcode> <faultstring>Error 0: Code: UNKN Message: No connection exists with a connection id of [225e79bfdd5d5049:2edeb9ae:12549a749e7:-7fcd] FieldName: FieldIndex: 0 DtoIndex: -1</faultstring> <detail encodingStyle=""> <p773:EnterpriseServiceOperationException> <errorMessages> <ErrorMessageDTO> <code>UNKN</code> <dtoIndex>-1</dtoIndex> <fieldIndex>0</fieldIndex> <fieldName/> <message>No connection exists with a connection id of [225e79bfdd5d5049:2edeb9ae:12549a749e7:-7fcd]</message> </ErrorMessageDTO> </errorMessages> </p773:EnterpriseServiceOperationException> </detail> </soapenv:Fault> </soapenv:Body></soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header/> <soapenv:Body> <soapenv:Fault> <faultcode xmlns:p773="http://exception.enterpriseservice.mincom.com">p773:EnterpriseServiceOperationException</faultcode> <faultstring>Error 0: Code: UNKN Message: No connection exists with a connection id of [225e79bfdd5d5049:2edeb9ae:12549a749e7:-7fcd] FieldName: FieldIndex: 0 DtoIndex: -1</faultstring> <detail encodingStyle=""> <p773:EnterpriseServiceOperationException xmlns:p773="http://exception.enterpriseservice.mincom.com"> <errorMessages> <ErrorMessageDTO> <code>UNKN</code> <dtoIndex>-1</dtoIndex> <fieldIndex>0</fieldIndex> <fieldName/> <message>No connection exists with a connection id of [225e79bfdd5d5049:2edeb9ae:12549a749e7:-7fcd]</message> </ErrorMessageDTO> </errorMessages> </p773:EnterpriseServiceOperationException> </detail> </soapenv:Fault> </soapenv:Body></soapenv:Envelope>

Error messages which are not transient (e.g. invalid connection details or invalid data) will be immediately returned to theclient application / adapter.

Connection ManagementConnections will be kept in the pool for TBC period of time. Where they are not used within that timeframe they will be markedas stale and will be deleted from the pool. In addition where an error is found on the processing of a service request, theyconnection will be removed from the pool.

Client Managed TransactionsWhere client managed transactions are implemented (via the Transaction service), the connection will include the TransactionId. Due to this, this connection will NOT be re-used outside the transaction scope. When the commit or roll back is issued forthe transaction, the connection will be removed from the pool.

Data Transfer Objects

Request DTOsRequest data transfer objects as their name suggests are objects that are provided asthe means of transferring data as part ofa request for an interaction with Ellipse. DataTransfer Objects deal only with serializable Java types that are allowable as part ofthe SOAP specification. The request DTO can contain simple data types such as String and BigDecimal and can also containcomplex dependant entity data types and arrays of these types of elements.

The code is generated and should never be modified. They merely consist of a number of getters and setters for the specificvalid input attribute of the operation in question.

Service request attributes are set using setters on the request DTO.

public void setDistrictCode(java.lang.String districtCode) {this.districtCode = districtCode;}public void setWorkOrder(com.mincom.enterpriseservice.ellipse.dependant.dto.WorkOrderDTO workOrder) {this.workOrder = workOrder;}

Reply DTOsReply DTOs are provided to return data from the interaction to the client. Reply DTOsas with request DTOs deal only withserializable Java types that are allowable as part of the SOAP specification. The reply DTO can contain simple data types suchas Stringand BigDecimal and can contain complex dependant entity data types and arrays ofthese types of elements.

public java.lang.String getDistrictCode() {return districtCode;}public com.mincom.enterpriseservice.ellipse.dependant.dto.WorkOrderDTO setWorkOrder() {return workOrder;}

Required attributes DTOsThis type of DTO is provided only for retrieve type methods in order to limit the amount of data brought back in a retrieve typeoperation. By default any other type of operation will return all possible valid outputs in the reply for the operation beingperformed. The required attributes DTO is however optional and if null, all possible output values for the retrieve method will bereturned.

NB: The programmer should be careful when not specifying a required attributes DTO as this could cause a significant overheadon the retrieve mechanism.

The following is a sample of how the client would set this type of entity up for an interaction:

WorkOrderServiceRetrieveRequiredAttributesDTO requiredAttributes = new WorkOrderServiceRetrieveRequiredAttributesDTO();requiredAttributes.setReturnDistrictCode(true);requiredAttributes.setReturnWorkGroup(true);requiredAttributes.setReturnWorkGroupDescription(true);

An example of the usage of this type of DTO will follow in the section that deals with retrieval type operations.

Operations/Interactions

ReadRead type operations map directly to the underlying 'Fetch' operation of an MSK. (They are referred to as read methods due tosome current thinking on the definition of service methods and maintaining an underlying infrastructure separation.(i.e.theservice maybe accessed by way of some Delphi,Visual Basic or C# code as well as Java so the service methods should notcontain any relationship to the underlying platform.) Hence a FindByPrimaryKey is not a good service method name since itimplies Java EJB type functionality.

The basics of calling a read type method of the web service interface are as follows:

• Obtain a reference to the web service locator object.

• Use the service locator to return an instance of the web service proxy class.

• Setup the appropriate request DTO object, populated with the required values.

• Invoke the service method, assigning the output to a variable of the required replyDTO and specify whether or notwarnings are to be returned (third parameter ofthe method call)

• Test for any warnings or errors.The following code outlines how to perform a read operation on the Work Order Service to obtain the values for the specifiedwork order id:

WorkOrderServiceLocator workOrderServicelocator = new WorkOrderServiceLocator();WorkOrder workOrderProxy = workOrderServicelocator.getWorkOrder();WorkOrderServiceReadRequestDTO request = new WorkOrderServiceReadRequestDTO();request.setDistrictCode("0001");WorkOrderRequestDTO workOrderDTO = new WorkOrderRequestDTO();workOrderDTO.setPrefix("00");workOrderDTO.setNo("000068");request.setWorkOrder(workOrderDTO);try { WorkOrderServiceReadReplyDTO reply = workOrderProxy.read(connectionId, request, true); System.out.println(reply.getWorkOrder().getNo()); System.out.println(reply.getWorkOrderDesc()); System.out.println(reply.getAccountCode()); System.out.println(reply.getAccountCodeDescription()); System.out.println(reply.getActualLabHrs().toString()); System.out.println(reply.getClosedDate().toString());} catch (EnterpriseServiceOperationException e) { //Do something meaningful with the errors}

RetrieveRetrieve type operations are based around finding a collection of entities of a given type. The retrieve operation will return acollection reply object that contains the array of reply elements found by the search along with any warnings and restartinformation.The basic steps for performing a retrieve type operation are as follows:



• Setup the appropriate request object, populated with the required values.

• Setup a required attributes object that defines the attributes to be returned. (optional)

• Invoke the service method assigning the output to the appropriate reply collection type object. The client must alsospecify if any warnings are to be returned, the maximum collection size and any restart information as parameters to themethod call.

The following is an example of how to perform a retrieve type operation on the work order service and reinvoke the searchbased on restart information.final int MAX_COLLECTION_SIZE = 50;WorkOrderServiceLocator workOrderServiceLocator = new WorkOrderServiceLocator();WorkOrder workOrderProxy = workOrderServiceEntityLocator.getWorkOder();WorkOrderServiceRetrieveRequestDTO request = new WorkOrderServiceRetrieveRequestDTO();request.setDistrictCode("0001");request.setWorkGroup("Z002");//Create the required attributes objectWorkOrderServiceRetrieveRequiredAttributesDTO requiredAttributes = new WorkOrderServiceRetrieveRequiredAttributesDTO();requiredAttributes.setReturnDistrictCode(true);requiredAttributes.setReturnWorkGroup(true);requiredAttributes.setReturnWorkGroupDescription(true);requiredAttributes.setReturnWorkOrder(true);requiredAttributes.setReturnWorkOrderDesc(true);requiredAttributes.setReturnAccountCode(true);

//Invoke the service methodWorkOrderServiceRetrieveReplyCollectionDTO reply = workOrderProxy.retrieve(connectionId, request, requiredAttributes, MAX_COLLECTION_SIZE, true, "");//Deal with the outputWorkOrderServiceRetrieveReplyDTO[] elements = reply.getReplyElements();String firstWorkOrderNumber = reply.getReplyElements()[0].getWorkOrder().getPrefix() + reply.for (int i = 0; i < elements.length; i++) {WorkOrderServiceRetrieveReplyDTO replyDTO = elements[i];System.out.println(replyDTO.getWorkOrder().getPrefix() + replyDTO.getWorkOrder().getNo() }//Reinvoke the retrieve with restart informationreply = workOrderProxy.retrieve(connectionId, request, requiredAttributes,MAX_COLLECTION_SIZE, elements = reply.getReplyElements();for (int i = 0; i < elements.length; i++) { WorkOrderServiceRetrieveReplyDTO replyDTO = elements[i]; System.out.println(replyDTO.getWorkOrder().getPrefix() + replyDTO.getWorkOrder().getNo() }

NoteThe programmer should be careful to always specify an appropriate MAX_COLLECTION_SIZE value as this could cause asignificant overhead on the retrieve mechanism. Problems with timeouts can occur (long running service requests) andproblems with response messages (physical size limitations) can be encountered.**

UpdateUpdate type operations (create, modify and delete) are transactional and the deployment descriptor will define that theyrequire a new transaction.(NB.This is not something that the client needs to deal with as transactions by default are containermanaged (refer Section 8 for client managed transactions)).

The basic steps for performing an update type operation are as follows:



• Setup the appropriate request object, populated with the required values.

• Invoke the service method assigning the output to the appropriate reply collection type object. The client must alsospecify if any warnings are to be returned from the method call.

If warnings are to be returned from the method call then the client must be aware that the update will not be committed. If thereturnWarnings flag is set to false, then all updates will be committed so long as the method call does not throw anEnterpriseServiceOperationException. Any exception of this type will cause a transaction rollback to occur.

The following code is an example of an update operation that creates a work order on the underlying Ellipse system:

WorkOrderServiceLocator workOrderServicelocator = new WorkOrderServiceLocator();WorkOrder workOrderProxy = workOrderServicelocator.getWorkOrder();WorkOrderServiceCreateRequestDTO request = new WorkOrderServiceCreateRequestDTO();request.setDistrictCode("0001");request.setWorkOrderDesc("New testing work order");request.setAccountCode("1110010");request.setOriginatorId("97");request.setWorkOrderType("NO");request.setMaintenanceType("BD");request.setAccountCodeEnabled(true);request.setRaisedDate(new GregorianCalendar(2004, 9, 12));request.setUnitsRequired(new BigDecimal("2.3"));request.setUnitOfWork("DY");WorkOrderServiceCreateReplyDTO reply = workOrderProxy.create(connectionId, request, true);//This should throw a warning 5825WarningDTO[] warnings = reply.getWarnings();//TODO: Do something with the warnings//Reinvoke the create but ignoring the warnings.reply = workOrderProxy.create(connectionId, request, false);System.out.println("Work order number: " + reply.getWorkOrder().toString());

All update type operations are carried out in the same way.

Exception Handling

WarningsWarnings do not prevent a sequence of events from proceeding but they do however need to be trapped and dealt with at theclient and the invocation of update type operations needs to be re-sent with the returnWarnings flag set to false in order forchanges to be committed.

Warnings are returned as an array of WarningDTOs contained within the reply object.Warnings would normally be dealt with inthefollowing way:

WarningDTO[] warnings = reply.getWarnings();for(int i = 0; i < warnings.length; i++) { //Display warnings to the user}

ErrorsEllipse errors are returned to the client in the form of an EnterpriseServiceOperationException. They are contained as an arrayof ApplicationError objects. Any other exception is contained as a NestedException within the EnterpriseServiceException.Errors at the client side would normally be dealt with as follows:

try { reply = workOrderProxy. modify(connectionId, request, true);} catch (EnterpriseServiceOperationException e) { if(e.getNestedException() != null) { //Non-ellipse errors //Do something useful with the underlying exception. throw e.getNestedException(); } else { //Ellipse errors ApplicationError[] errors = e.getApplicationErrors(); for (int i = 0; i < errors.length; i++) { //Do something useful with the Ellipse error messages }}

Date / Time Processing for Ellipse Web Services

General NotesEllipse records date and time values separately in the database, therefore this needs to be understood when processing datesand times values via services. An Ellipse web service will process an Ellipse date value as a stringvalue (as it is defined as astring attribute in the service) and similarly will process an Ellipse time value as a stringvalue(as it is defined as astringattribute in the service).

Input of Date/Time ValuesDates and Times are input to Ellipse web services in the same format that they are held in the Ellipse database(CCYYMMDD).Below are some examples of the values input for Ellipse web services.

They accept date/time in SOAP request as it is held in Ellipse database, e.g.:

<soapenv:Body><req:search><req:context> <con:district>QBLD</con:district> <con:maxInstances>100</con:maxInstances> <con:position>MATMAN</con:position> <con:returnWarnings>false</con:returnWarnings></req:context><req:searchParams>  <ins:lastRunDate>20090320</ins:lastRunDate>  <ins:lastRunTime>090000</ins:lastRunTime></req:searchParams><req:restart xsi='nil'/></req:search></soapenv:Body>

They return date/time in SOAP response as it is held in the Ellipse database, e.g.:

<ns2:requestorMobileDTO><ns2:ahphonearea>414</ns2:ahphonearea><ns2:ahphoneno>67504534</ns2:ahphoneno><ns2:birthdate>19650705</ns2:birthdate><ns2:businessname>BUILDING INSPECTIONSERVICE</ns2:businessname><ns2:creationdate>19990302</ns2:creationdate><ns2:creationtime>104825</ns2:creationtime><ns2:creationuser>0000000097</ns2:creationuser><ns2:custno>000006</ns2:custno><ns2:emailaddress/><ns2:faxarea/><ns2:faxno/><ns2:firstname>MYLES</ns2:firstname><ns2:lastmoddate>20090826</ns2:lastmoddate><ns2:lastmodtime>150301</ns2:lastmodtime>

Output of Date/Time ValuesDates and Times are output by Ellipse web services in the same format that they are held in the Ellipse database(CCYYMMDD).Below are some examples of the values output for Ellipse web services.

Dates are output from Ellipse as follows for web services:

• <ns2:creationdate/>- this value is returned where value in Ellipse is zeroes or spaces.

• <ns2:creationdate>19980525</ns2:creationdate> - this value is returned where value in Ellipse is 19980525.Times are output from Ellipse as follows for web services:

• <ns2:creationtime/>- this value is returned where value in Ellipse is zeroes or spaces.

• <ns2:lastmodtime>170154</ns2:lastmodtime>- this value is returned where value in Ellipse is170154

Operation Context OverviewThe OperationContext in an Ellipse Web Service request is required to provide supporting Ellipse login details. The usernameand password are included in the security header. An example of this is as follows:<soapenv:Header><wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-3862294" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username>DC4340</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password> </wsse:UsernameToken> </wsse:Security></soapenv:Header>

The other details required for Ellipse login (e.g. District Code and Position) are available in the OperationContext. Referring tothe WSDL definition for an Ellipse web service, either java or ESBI (cobol msk) service, the OperationContext is as follows:

<xsd:complexType name="OperationContext"><xsd:sequence><xsd:element minOccurs="0" name="district" type="xsd:string"/><xsd:element minOccurs="0" name="eventDisable" type="xsd:boolean"/><xsd:element minOccurs="0" name="maxInstances" type="xsd:int"/><xsd:element minOccurs="0" name="position" type="xsd:string"/><xsd:element minOccurs="0" name="returnWarnings" type="xsd:boolean"/><xsd:element minOccurs="0" name="runAs" type="ns1:RunAs"/><xsd:element minOccurs="0" name="trace" type="xsd:boolean"/><xsd:element minOccurs="0" name="transaction" type="xsd:string"/></xsd:sequence>

Note that all the child elements have the minOccurs attribute defined as minOccurs=0, meaning they are optional, howeverthis is strictly not correct. The position and district attributes are mandatory elements, meaning on every soap request, theymust be provided. In addition, for client applications that utilise client transactions, all soap requests associated with a clienttransaction 'conversation' require the transaction element. The exception here is the BeginTransaction request, whosesubsequent response returns the transaction id to be 'remembered' by the client and returned in the subsequent soap requestsbelonging to the conversation. Note the runAs type, defined here:

<xsd:complexType name="RunAs"><xsd:sequence><xsd:element minOccurs="0" name="district" type="xsd:string"/><xsd:element minOccurs="0" name="position" type="xsd:string"/><xsd:element minOccurs="0" name="user" type="xsd:string"/></xsd:sequence></xsd:complexType>

This is an optional element and is inserted in use cases where service invocations apply the authorisation levels of the 'RunAs'ellipse user, NOT the user whose credentials are being inserted into the soap security header, together with theOperationContext position and district attributes.

Ellipse on-line application versus EWS behaviour In the on-line application there is a concept of users being able to beconfigured to have default profiles, permitting a user to log into the on-line application without providing a district and/orposition and having the default district and/or position applied. This isn't supported in EWS. So, in other words, district andposition attributes are mandatory.

Run As OverviewThe 'Run As' functionality in EWS is intended to allow web services interactions to be executed as any given user, even thoughthe issuer of the interactions has only one set of user credentials.

For instance, an integration agent may read messages off of a message queue, and create a Work Order based on eachmessage.

If the integration agent uses 'Run As' functionality then the Work Orders can be created as if they were created by a specificuser; they are not all created by the single user represented by the integration agent's Ellipse credentials. This allows theupdates in Ellipse to have the correct user credentials associated with the Ellipse data entity (e.g. the Originator Id on the WorkOrder will contain the Run As User identification rather than the integration agent's Ellipse credentials.

To enable 'Run As' functionality the caller's credentials must have access to the 'RUNASUSER' security class. This access can begranted/revoked by following the usual Ellipse security procedures in the Ellipse UI.

Once the caller has access then the 'Run As' functionality can be used by populating the RunAs object contained in theOperationContext parameter for any given EWS call. The RunAs object allows the specification of the following attributes:

• User

• District

• PositionIf these attributes are supplied then EWS will check for access to the 'RUNASUSER' class for the authentication credentialssupplied on the web service in the SOAP header. If the credentials have this access, then the interaction will be carried out as ifit was actually issued by the supplied RunAs user.

The context node when populated for 'Run As' processing would contain the following attributes:

<wor:context> <con:district>R100</con:district> <con:maxInstances>1</con:maxInstances> <con:position>SYSAD</con:position> <con:returnWarnings>false</con:returnWarnings> <con:runAs> <con:district>R200</con:district> <con:position>MATMAN</con:position> <con:user>BC1234</con:user> </con:runAs> <con:trace>false</con:trace></wor:context>

TracingIn order to trace the relevant msk cobol the web service executes,the <trace> attribute in the <context> node needs to haveit's value set to 'true'. The context node contains the following attributes:

<wor:context> <con:district>?</con:district> <con:maxInstances>?</con:maxInstances> <con:position>?</con:position> <con:returnWarnings>?</con:returnWarnings> <con:runAs> <con:district>?</con:district> <con:position>?</con:position> <con:user>?</con:user> </con:runAs> <con:trace>?</con:trace> <con:transaction>?</con:transaction></wor:context>

The trace can be accessed from the Ellipse UI from the Settings menu. Click on the Settings menu, select Trace and thenDownload to access the trace details.

ClientTransaction ControlBy default each Ellipse web service request will have transaction control managed by the application server. Therefore eachweb service request will be committed (where request successfully processed) or rolled back (where request unsuccessfullyprocessed) by the application server. Where transaction control is required to be applied across multiple Ellipse web servicerequests as a single transaction (such that all web service requests must succeed before updates are committed or if one webservices request fails then all web service requests are rolled back), then the client application must manage transactioncontrol. This will require that the client application initiate the transaction and commit or rollback the updates depending on theresponses received for the web services requests.

To do this the client application must call the Ellipse Transaction web service to initiate the transaction.To then commit orrollback the transaction, the client application must again call the Ellipse Transaction web service to complete the transactionprocessing.

Initiate Transaction ProcessingTo initiate transaction processing, the client application must call the Ellipse Transaction web service using the 'begin' methodto initiate the transaction.The web service request will need the <trace> attribute in the <context> node needs to have it'svalue set to 'true'.The context node contains the following attributeswhich will need to be populated appropriately:

<tran:context> <con:district>?</con:district>- Ellipse District Code (required) <con:maxInstances>?</con:maxInstances>- set to '1' <con:position>?</con:position>- Ellipse Position Id (required) <con:returnWarnings>?</con:returnWarnings>- set to false <con:runAs>- not required <con:district>?</con:district> <con:position>?</con:position> <con:user>?</con:user> </con:runAs> <con:trace>?</con:trace>- set to 'false' <con:transaction>?</con:transaction>- set to 'true'</tran:context>

The response to the Ellipse Transaction web service will contain a <transactionId> attribute,this will then need to be passed tothe require Ellipse web service requests in the <transaction> attribute in the <context> node. The context node contains thefollowing attributes:

<wor:context> <con:district>?</con:district> - Ellipse District Code (required) <con:maxInstances>?</con:maxInstances> - set to required value <con:position>?</con:position> - Ellipse Position Id (required) <con:returnWarnings>?</con:returnWarnings> - set to 'true' or 'false' as required <con:runAs> - not required <con:district>?</con:district> <con:position>?</con:position> <con:user>?</con:user> </con:runAs> <con:trace>?</con:trace> - set to 'true' or 'false' as required <con:transaction>?</con:transaction> - set to value returned from Transaction service</wor:context>

Complete Transaction ProcessingThe client application will need to check the responses returned from the called web services to determine if the updates are tobe committed or rolled back. Depending on the responses, the client application should process the transaction as follows:

• Where the requests are to be committed, the client application must call the Ellipse Transaction web service using the'commit' method to commit the transaction. The <transactionId> attribute returned from the Transaction service 'begin'method response will then need to be passed in the <transaction> attribute in the <context> node.

• Where the requests are to be rolled back, the client application must call the Ellipse Transaction web service using the'rollback' method to roll back the transaction. The <transactionId> attribute returned from the Transaction service 'begin'method response will then need to be passed in the <transaction> attribute in the <context> node.

Locale SettingTo support Internationalisation, the locale can be set in the http header of EWS SOAP requests. The http header property to beset is Accept-Language. EWS will pick this up and use it to set the locale for the context. From this point on the serviceoperates the same as if the locale had been set in the browser.

ellipse web services client application...

Documents