Electra Logistics for Generic Orders

Document Logs
Change log:

Terms and definitions:

1 - Purpose of Document

This document provides the overall technical details and design of implementing and using the functionality as specified in section 2 - Introduction. This document will not cover implementation details – for this the code base should be inspected.

2 - Introduction to Functionality

The Generic Order Engine handles the order placing and the retrieval of the order status from Electra. The Electra Logistic for Generic Orders uses the generic order framework.

There are the following two actions: Place order and Order status.

Place order

This action is used for placing a new order with Electra. The action is:

 com.CDRator.billing.logistics.electra.action.PlaceOrder

The order must have

• 1-* order lines, which have DESCRIPTION, PRODUCTNUMBER and optional QUANTITY in parameters. If no quantity is present, '1' will be sent.
• a valid deliveryAddress, which have FULLNAME, ADDRESS1, CITY, ZIP. Optional COMPANY.
• a valid ACCOUNT, used to find brand.
• an ORDER_NUMBER.

If no errors occurred while communicating with Electra the ACTION will return "DONE", otherwise it will return "ERROR".

Place Order Response Logging

The responseParameters on the GENERIC_ORDER object are always updated with the latest reply for Electra.

Allways set: ResponseCode, ResponseDescription - Did the communication with the gateway go OK?

Order status

This action is used to query Electra for the status of an order. The action is:

 com.CDRator.billing.logistics.electra.action.OrderStatus

The order must have:

• a valid ACCOUNT, used to find brand
• an ORDER_NUMBER, used to query Electra

The action can return 4 different strings:

• DONE: When all order lines on an order are fulfilled, Electra responds that the order have been delivered and the action returns 'DONE' 
• RETRY: If the order is still being processed by Electra the ACTION returns 'RETRY'
• CANCELLED: If the order have been cancelled, the ACTION will return 'CANCELLED'
• ERROR: If something unexpected occurs 'ERROR' is returned.

Order Status Response Logging

GenericOrder

The responseParameters on the GENERIC_ORDER object are always updated with the latest reply for Electra.

Always set: ResponseCode, ResponseDescription - Did the communication with the gateway go OK.

If the order was delivered("DONE") these are also set:

• OrderStatusCode,OrderStatusDescription - Order description
• PackageIds - Tracking Ids

GenericOrderLine

If the response contains serial numbers like ICCs, those will be placed upon the GENERIC_ORDER_LINE response parameter with the name 'SERIAL_NUMBER'.

SERIAL_NUMBER - Colon separated list of serial numbers   example 'SERIAL_NUMBER=1234' or 'SERIAL_NUMBER=1234:122424'

Exception Handling

From version 1.0.2 of the project, the actions also throw WebServiceException explicitly, where previously they only threw Exception. WebServiceExceptions occur in various scenarios where no communication can be done with the Electra interface, e.g. if their service is down for a short while.

This allows for the client to differentiate between the regular Exception scenario and the WebServiceException scenario when configuring the action and the workflow using it. In case of a WebServiceException the workflow could for instance just wait a bit before retrying instead of going into error, or more complex handling could be added such as creating an alert and/or attempting a number of times before going into error if it remains unable to communicate with Electra.

In case of a WebServiceException the actions will log the error to the log file, set the error message from the exception on the associated generic_order.response_parameter with the key "WebServiceError" and re-throw the caught exception to allow the user of the action to decide on the handling.

An example of the message shown on the generic_order.response_parameter could look like this:

WebServiceError=Call to Electra resulted in a WebServiceException: 2 counts of InaccessibleWSDLException.

Please note that if the action is used in a transaction, the setting of such a message on the generic_order is not ensured: then it is the responsibility of the caller to appropriately handle the re-thrown WebServiceException.

If errors such as these persist, Electra would have to be consulted as the cause is likely to have been caused by something on their side that would have changed, whether it is just the service continually being down, endpoints or IP screening updated etc.

In the log file of the process (e.g. the workflow engine) using the action something similar to the below stack trace would be shown:

2013-07-03 11:15:04.0004 ERROR [main] | WebServiceException occurred in orderStatus call to Electra: 2 counts of InaccessibleWSDLException.

com.sun.xml.internal.ws.wsdl.parser.InaccessibleWSDLException: 2 counts of InaccessibleWSDLException.

java.io.IOException: Got test.electra-sweden.se while opening stream from http://test.electra-sweden.se/Tre/CDRatorService.asmx
java.io.IOException: Got test.electra-sweden.se while opening stream from http://test.electra-sweden.se/Tre/CDRatorService.asmx?wsdl

	at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.tryWithMex(Unknown Source)
	at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.parse(Unknown Source)
	at com.sun.xml.internal.ws.wsdl.parser.RuntimeWSDLParser.parse(Unknown Source)
	at com.sun.xml.internal.ws.client.WSServiceDelegate.parseWSDL(Unknown Source)
	at com.sun.xml.internal.ws.client.WSServiceDelegate.<init>(Unknown Source)
	at com.sun.xml.internal.ws.client.WSServiceDelegate.<init>(Unknown Source)
	at com.sun.xml.internal.ws.spi.ProviderImpl.createServiceDelegate(Unknown Source)
	at javax.xml.ws.Service.<init>(Unknown Source)
	at se.electra.smartlds.CDRatorService.<init>(CDRatorService.java:42)
	at com.CDRator.billing.logistics.electra.stub.ElectraConnection.getPlaceOrderStub(ElectraConnection.java:46)
	at com.CDRator.billing.logistics.electra.ElectraFacade.orderStatus(ElectraFacade.java:69)
	at com.CDRator.billing.logistics.electra.action.OrderStatus.execute(OrderStatus.java:82)
	at com.CDRator.billing.logistics.electra.action.OrderStatusTester.main(OrderStatusTester.java:33)

Soap Client Log

The project used the SOAP_CLIENT_LOG to save the XML being sent to and from Electra.

From version 1.0.2 of the project these logs are inserted in a separate transaction, so in case communication has been done with Electra, the log entry should always be available, barring database errors when attempting the insert or similar: in such cases, that error will be logged to the log file of the process using the action.

3 - Configuration

Parameters under ENGINE.LOGISTICS.ELECTRA

4 - Operational Considerations

Security

At time of writing Electra validates incoming requests based upon the senders IP. No other security is used.

5 - Version