Document Logs
Change log:
Date: | Author: | Version: | Changes: | Completed | Ext. | Int. | Is in Core |
---|---|---|---|---|---|---|---|
|
| 1.0 | Doc. created | Yes | X |
|
|
10.02.2015 | RWJ | 2.1 | Configuration options for header authentication, service and port qualified names. |
Terms and definitions:
Terms/definitions: | Meaning: |
---|---|
TBD | To be defined |
N/A | Not applicable |
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
Key | Default | Description | Optional | Version |
---|---|---|---|---|
WSDL_PATH |
| Absolute path for the WSDL file for the engine. Mandatory. | No | |
AUTHENTICATE.ENABLED | false | If a boolean true value (e.g., 'y', 'true' etc) a header will be created in the SoapRequest containing password and username | Yes | 2.1, 1.1.1 |
AUTHENTICATE.USERNAME | - | The username provided by logistics partner. Used in soap request header. | Mandatory if ENABLED is true | 2.1, 1.1.1 |
AUTHENTICATE.PASSWORD | - | The password provided by logistics partner. Used in soap request header. | Mandatory if ENABLED is true | 2.1, 1.1.1 |
QUALIFIED_NAME.SERVICE | The parameter tree for specifying qualified name of service. If either of URI/LOCAL_PART child is specified, the other is mandatory | Yes | ||
URI | Specify uri part of qualified name of the logistics service | See description | 2.1, 1.1.1 | |
LOCAL_PART | Specify uri local part of qualified name of the logistics service | See description | 2.1, 1.1.1 | |
QUALIFIED_NAME.PORT | The parameter tree for specifying qualified name of the port. If either of URI/LOCAL_PART child is specified, the other is mandatory | Yes | ||
URI | Specify uri part of qualified name of the logistics service port | See description | 2.1, 1.1.1 | |
LOCAL_PART | Specify local part of qualified name of the logistics service port | See description | 2.1, 1.1.1 |
Authenticate & QualifiedName Configuration
The values that are possible to configure under these nodes are <not> business related logic.
The AUTHENTICATE values enables providing a security header in the soap requests, which may or may not be required depending on the logistics partner setup.
The QUALIFIED_NAME values enables further configuration of the third-party service- and port names and locations, used in the generated stubs. Under normal circumstances it is enough to configure the endpoint (wsdl location) in the WSDL_PATH. Consult with Integration Department before changing or adding these values.
4 - Operational Considerations
Security
At time of writing Electra validates incoming requests based upon the senders IP. No other security is used.
5 - Version
Version | Released | Changes |
---|---|---|
1.0 | 21-05-2013 10:24:08 | First stable release |
1.0.2 | 03-07-2013 16:07:40 | Exception handling for WebServiceExceptions so users of the project actions can differentiate between error scenarios. Soap_client_log entries in separate transaction. |
2.1 | 10.02.2015 | Configuration options for header authentication, service and port qualified names. |