Electra Logistic 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 Electra Logistics 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 in core. While the Electra Logistic Engine project uses the shop order and webshop.

3 - API

The Electra Logistic for Generic Orders is located in

<dependency>
  <groupId>com.cdrator.integration.logistics</groupId>
  <artifactId>rator-logistics-dk-electra-generic</artifactId>
</dependency>

The way to invoke functionality in the project is through Actions, which there are presently two of

PlaceOrder

For placing a new order an Electra

@Action
@Description("Place a generic order to Electra")
public class PlaceOrder {

	/**
	 * Place an order at Electra
	 *
	 * Possible outcomes:
	 * DONE: Succesfull
	 * ERROR: unexpected error
	 *
	 * @param order
	 * @return
	 * @throws Exception, WebServiceException
	 */
	@ActionMethod
	@ReturnValue(description = @Description("String: DONE, ERROR"))
	public String execute(GenericOrder order) throws Exception, WebServiceException {}

The order must have

• 1-* order lines, which have DESCRIPTION, PRODUCTNUMBER and optional QUANTITY in parameters. If no quantity is present, '1' will be send
• 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 which communicating with Electra the ACTION will return "DONE", other wise 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

Used to query Electra for a status on an order

@Action
@Description("Get order status at Electra")
public class OrderStatus {

	/**
	 * Action that will get the order status for an order at Electra.
	 * The outcome is a string that will tell the caller what action to perform.
	 * DONE: The order was successfully packaged and sent. An ICC and package IDs have been updated in the order responseParameters
	 * RETRY: The order is still not processed at Electra
	 * CANCELLED: The order was cancelled
	 * ERROR: There was an unexpected error.
	 *
	 * @param order
	 * @return
	 * @throws Exception, WebServiceException
	 */
	@ActionMethod
	@ReturnValue(description = @Description("String: DONE, RETRY, CANCELLED, ERROR"))
	public String execute(GenericOrder order) throws Exception, WebServiceException {}

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.

Allways 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 ICC's those will be place upon the GENERIC_ORDER_LINE response parameter with the name 'SERIAL_NUMBER'

SERIAL_NUMBER - Colon seperated list of SerialNumbers example 'SERIAL_NUMBER=1234' or 'SERIAL_NUMBER=1234:122424'

Exception Handling

From version 1.0.2 of the project, the actions also throws WebServiceException explicitly, where previously it 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 one 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.

Be aware 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 that something on their side 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.

4 - Configuration

Parameters under ENGINE.LOGISTICS.ELECTRA

5 - Operational Considerations

Security

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

6 - Version