...
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:
| Code Block |
|---|
com.CDRator.billing.logistics.electra.action.PlaceOrder
|
The order must have
- 1-* order lines, which have db columns DESCRIPTION, PRODUCTNUMBER filled in and optional QUANTITY in parameters column. 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:
| Code Block |
|---|
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:
| Code Block |
|---|
WebServiceError=Call to Electra resulted in a WebServiceException: 2 counts of InaccessibleWSDLException.
{code}
|
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:
...
| Code Block |
|---|
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)
{code}
h5. Soap Client Log
The project used the |
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 |
| Note | ||
|---|---|---|
| ||
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. |