...
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
{code}
|
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
{code}
|
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. |