Http/MQ Gateway
-
HMG
Instructions
1.0
.
2
Company:
Volvo IT
Issuer:
Johan Planmo
Date:
2013
-
05
-
22
Issue:
Company name
Type of
document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
2
(
40
)
Issuer (name, phone)
Sign
Date
Info class
Johan Planmo
2012
-
05
-
22
Approved by (name, phone)
Sign
Date
Valid
Document name
balecomputer_412a7a24
-
b114
-
4c65
-
a89d
-
0f55ef179be0.docx
, saved date
2013
-
11
-
04
Contents
1.
REVISION HISTORY
................................
................................
................................
....
4
2.
PUBLICATION OF HMG I
NFORMATION
................................
................................
.....
5
3.
INTRODUCTION
................................
................................
................................
...........
6
3.1.
Service Interface
................................
................................
................................
..
7
3.2.
Alternative to Web Services
................................
................................
.................
8
4.
SERVICE ENDPOINTS
................................
................................
................................
.
9
5.
AUTHE
NTICATION
................................
................................
................................
......
9
5.1.
Session cookies
................................
................................
................................
...
9
6.
AUTHORIZATION
................................
................................
................................
.......
10
7.
SERVICE D
EFINITION
................................
................................
...............................
11
7.1.
General definition
................................
................................
...............................
11
7.2.
HMG Specific Definition
................................
................................
.....................
11
8.
MESSAGE EXCHANGE PAT
TERNS
................................
................................
.........
12
8.1.
General Header Information
................................
................................
...............
12
8.2.
Tracking ID
................................
................................
................................
.........
13
8.2.1.
Usage
................................
................................
................................
..........
13
8.2.2.
Setting t
he Tracking ID
................................
................................
................
13
8.2.3.
Idempotence
................................
................................
...............................
14
8.3.
Fire&Forget
................................
................................
................................
........
15
8.3.1.
MEP O
verview
................................
................................
............................
15
8.3.2.
Purpose
................................
................................
................................
.......
15
8.3.3.
Operation
................................
................................
................................
....
15
8.3.4.
Speci
fic Header Information
................................
................................
........
15
8.3.5.
Reply
................................
................................
................................
...........
15
8.3.6.
Examples:
................................
................................
................................
...
16
8.4.
Synchronous Request/Reply
................................
................................
..............
17
8.4.1.
MEP Overview
................................
................................
............................
17
8.4.2.
Purpose
................................
................................
................................
.......
17
8.4.3.
Operation
................................
................................
................................
....
17
8.4.4.
Specific Header Information
................................
................................
........
17
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
3
(
40
)
8.4.5.
Reply
................................
................................
................................
...........
18
8.4.6.
Examples:
................................
................................
................................
...
18
8.5.
Push
................................
................................
................................
...................
19
8.5.1.
MEP Overview
................................
................................
............................
19
8.5.2.
Purpose
................................
................................
................................
.......
19
8.5.3.
Operation
................................
................................
................................
....
19
8.5.4.
Specific Header Information
................................
................................
........
20
8.5.5.
Reply
................................
................................
................................
...........
20
8.5.6.
Pushing d
ata to many Roles
................................
................................
........
20
8.5.7.
Examples:
................................
................................
................................
...
21
8.6.
Asynchronous Request Reply
................................
................................
............
22
8.6.1.
MEP Overview
................................
................................
............................
22
8.6.2.
Purpose
................................
................................
................................
.......
22
8.6.3.
Operation
................................
................................
................................
....
22
8.6.4.
Specific Header Information
................................
................................
........
23
8.6.5.
Reply
................................
................................
................................
...........
23
8.6.6.
Error code when the reply has not yet arrived
................................
.............
23
8.6.7.
Duplicate Control
................................
................................
.........................
23
8.6.
8.
Examples:
................................
................................
................................
...
23
8.7.
List Messages
................................
................................
................................
....
24
8.7.1.
MEP Overview
................................
................................
............................
24
8.7.2.
P
urpose
................................
................................
................................
.......
24
8.7.3.
Operation
................................
................................
................................
....
25
8.7.4.
Specific Header Information
................................
................................
........
25
8.7.5.
List Message Logic
................................
................................
......................
25
8.7.6.
Reply
................................
................................
................................
...........
25
8.7.7.
Examples:
................................
................................
................................
...
26
8.8.
Update Message Status
................................
................................
.....................
27
8.
8.1.
MEP Overview
................................
................................
............................
27
8.8.2.
Purpose
................................
................................
................................
.......
27
8.8.3.
Operation
................................
................................
................................
....
27
8.8.4.
Speci
fic Header Information
................................
................................
........
28
8.8.5.
Reply
................................
................................
................................
...........
28
8.8.6.
Examples:
................................
................................
................................
...
28
9.
THE MESSAGE BOX
................................
................................
................................
.
29
9.1.
Message Box state handling
................................
................................
..............
29
9.2.
Different ways of fetching responses from the Message Box
..............................
30
9.2.1.
1
-
List & Fetch
................................
................................
............................
30
9.2.2.
2
-
Fetch by Role
................................
................................
.........................
31
9.2.3.
3
-
List by Role
................................
................................
............................
32
9.2.4.
4
-
Fetch by Service
................................
................................
....................
33
10.
HMG RULES OF USAGE
................................
................................
...........................
34
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
4
(
40
)
10.1.
Encoding of Message Payload
................................
................................
...........
35
10.1.1.
String
................................
................................
................................
...........
35
10.1.2.
AnyXML
................................
................................
................................
......
35
10.1.3.
Base64
................................
................................
................................
........
35
11.
VERSION HANDLING
................................
................................
................................
36
11.1.
Version Naming
................................
................................
................................
..
36
11.2.
HM
G WSDL and Message Schema
................................
................................
...
36
11.3.
Service Versioning
................................
................................
.............................
36
12.
ERROR MESSAGES
................................
................................
................................
..
37
12.1.
Configuration Errors
................................
................................
...........................
37
12.2.
Illegal arguments and incorrect usage errors
................................
......................
37
12.3.
Generic error codes
................................
................................
...........................
37
12.4.
Security error codes
................................
................................
...........................
37
12
.5.
Internal error codes
................................
................................
............................
37
12.6.
Back
-
end System Errors
................................
................................
....................
38
13.
TROUBLE SHOOTING
................................
................................
...............................
39
13.1.
Authentication setup.
................................
................................
..........................
39
13.1.1.
Cookies and Microsoft Windows Communication Framework
–
WCF
..........
39
13.2.
Timeouts
................................
................................
................................
............
39
14.
WSDL AND SCHEMAS
................................
................................
..............................
40
14.1.
HMG 1.0.0
................................
................................
................................
..........
40
1.
Revision History
Date
Revision
Events
2012
-
10
-
02
1.0
First release
2013
-
04
-
05
1.0.1
Clarifications about
Idempotence
. Clarifications
about duplicate
detection in section
Asynchronous Request Reply (Out of Scope in
first Release)
.
List Messages
has been updated with informati
on
about sorting and a new default behavior. List Messages will only
return unread messages by default.
Updated
error messages
2015,5002,5003
.
Updated trouble shooting regarding
timeout
.
Updat
ed
cookie
section
.
Updated section about
Async Request
Reply
.
New section
Publication of HMG Information
.
2013
-
05
-
22
1.0.2
Shortened the external
link
.
Re
-
inserted attachemements.
Update
of broken links.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
5
(
40
)
2.
Publication of HMG Information
This document is published on the Volvo IT EDI and B2B web
site:
http://www.volvoit.com/edi
Select the tab B2B HMG for new
s
and decommissioning statements about HMG
versions. The subpage Instructions contains this Instruction (Latest and older
versions)
.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
6
(
40
)
3.
Introduction
HMG stands for Http/MQ Gateway. This is an
infrastructural component at Volvo
Group which bridges synchronous Web Service calls from outside Volvo Group to
asynchronous messages based on WMQ inside Volvo Group.
The purpose is to protect the Volvo back
-
end systems from synchronous
dependencies
and enable all existing services based on WMQ to be exposed as Web Services outside
Volvo. This means that
HMG
Web Services do not behave as a Web Service would
normally do, we aim to
mimic the behavior of messaging as far as we can.
Purpose
of HMG
:
Expo
se any Volvo back
-
end system based on WMQ as a Web Service
A uniform authent
ication and authorization model for Web Services
Remove Synchronous dependencies to Volvo back
-
end systems
o
Extern
al system and back
-
end system
can operate
independently in
time
(ex
cept synchronous Request/Reply)
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
7
(
40
)
3.1.
Service Interface
In order to offer a general solution
,
Volvo will expose one generic Web Service. This
Web Service is described in section
WSDL and Schemas
.
There
are
operation
s
for all
Message Exchange Patterns
available in HMG. Meta data
headers are used to specify
which Volvo back
-
end Service that will be used.
Figure
1
Conceptual Message Structure
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
8
(
40
)
3.2.
Alternative to Web Services
Web Services is a non
-
transactional protocol. This means that delivery cannot be
guaranteed. Pushing messages is also problematic. Web Services are also synchronous
which mean that both communicating systems need to
be available
at the same time.
The Http/Message G
ateway can mitigate some of these issues, but to get full
transactionality
another approach is needed. If there are higher requirements than
supported by Web Services
,
Volvo
offers
WMQ interfaces.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
9
(
40
)
4.
Service Endpoints
Environ
ment
URL
Purpose
TEST
https://sws
-
test.volvo.com/hmgWeb/ws/wsmq
Mainly
used
for tests
by
Volvo Group.
QA
1
https://hmg
-
qa.integration.volvo.com/hmgWeb/ws/wsmq
Used for testing with
external parties. May be
connected to QA back
-
end services.
PROD
2
https://hmg.integration.volvo.com/hmgWeb/ws/wsmq
The production URL
with connection to real
back
-
end services.
5.
Authentication
Username and password should be entered in the H
ttp
header using the Basic
Authentication Standard.
Always use lower case user names.
User name and password will be supplied by
your local Volvo
contact.
5.1.
Session cookies
When logged in with a SOAP request using basic authentication, a session cookie will
be returned.
It is highly recommended that you use this cookie in subsequent requests,
as this increases the throughput and lowers the per
-
request round trip delay of your
requests to HMG.
1
Not available yet
and the address may be changed
2
Not available yet
and the address may be changed
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
10
(
40
)
6.
Authorization
In order to
offer
a flexible
authorization model
,
HMG provides a
role concept which
enables
one authenticated user to
play many
different roles with access to different
Services
Figure
2
Role Concept
In the example above one
DMS (Dealer Management System) administers two
different dealers in t
he DMS system. Trucks United can access all services, but US
Trucks can only fetch Standard Times. Role is mandatory in messages sent to HMG
.
The role concept can also be used to
fetch
messages from the Messag
e Box for a
specific
role. This is described in section
The Message Box
.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
11
(
40
)
7.
Service Definition
7.1.
General definition
A service is the primary concept used in all application integration. A service exposes
application functionality via a
well
-
defined
interface. From “WS Definitions and
Principles”: “At a high level, a Service is a mechanism by which the need or want of
the Service Requestor is satisfied according to a negotiated contract”.
Services make use of
messages
to communicate.
Whe
n using HMG a
message
is
conveyed by
a SOAP request
. A message defines the message format (payload) as
well as other characteristics, e.g. headers and character set.
Services can support several different message exchange patterns, for example
request
-
re
ply or one
-
way
in
bound.
7.2.
HMG Specific Definition
A service is identified by
Name
Version
A service is implemented by one
Message Exchange Pattern
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
12
(
40
)
8.
Message Exchange Patterns
This section gives general instructions on how to use the different Message Exchange
Patterns provided by HMG. For details on a specific Service, there is a specific
instruction available which is provided by the local Volvo contact.
8.1.
General Header Inform
ation
The Attributes are annotated in the
schemas
. Below is an overview of the most
important header attributes.
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
ServiceName
The name
of the
service to call.
Identify which Service
to call
Yes
Yes
ServiceVersion
The version of the
Service to be used.
Possibility to have
many concurrent
versions of a service
Yes
Yes
CreationTime
Date and time when
this message was
created. Include
timezone if possible.
Logging
No
No
RoleID
The role which sends
or requests
the
message. Defined by
the external partner.
Authorization to the
incoming Service call
.
It is also used to
fetch
messages for a
specific role from
The
Message Box
No
No
SourceSystem
Name
Any name identifying
the system sending
this message.
Logging
No
Yes
TrackingID
GUID
(Globally
Unique Identifier)
set
by the external
partner to uniquely
identify a message.
Read more in section
Tracking ID
Tracking ID is used
to
correlate
response
s
and for logging
purposes.
It is also
used to
fetch
a unique
message from
The
Message Box
.
T
he
tracking
. Read more
in section
Tracking ID
No
No
, but
HMG will
generate a
unique ID
i
f not set by
the sender.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
13
(
40
)
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
GIMHeader
The GIMHeaders are
used to add specific
and dynamic meta
data to the message.
The GIM headers are
used for routing or
specific handling in
the Volvo back
-
end
system
s
.
Only specific
back
-
end services
require
GIM headers.
Yes
No
8.2.
Tracking ID
8.2.1.
Usage
The Tracking ID
makes it p
ossible
to
identify a unique message.
The tracking ID must
contain a
Globally Uni
que ID (
GUID
).
The Tracking ID can be set in the incoming message to Volvo by the external party. If
a Tracking ID is missing in the incoming message
,
HMG will provide a
Tracking ID
which is returned in the synchronous response.
It is recommended that t
he Tracking ID
is
set by the external partner in the incoming
message
to Volvo for the following reasons:
The
external party can easily correlate a response with a specific request
It
is easier to manage errors, since
duplicates can be spotted
more easily by the
external party
8.2.2.
Setting the Tracking ID
There are standard ways to create a GUID in common development platforms. See
examples below.
8.2.2.1.
Java Example
Java:
UUID uuid =
UUID.randomUUID();
11.
String randomUUIDString = uuid.toString();
8.2.2.2.
.Net Example
System.Guid
guid
=
System.Guid.NewGuid
();
String
id
=
guid.ToString();
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
14
(
40
)
8.2.2.3.
Development Platforms lacking native GUID support
Volvo may provide a prefix in cases when the
development platform cannot create a
Globally Unique ID.
A manual GUID can be created by combining the Volvo prefix
and a sequence
number
.
The external party is responsible to ensure a unique sequence
.
8.2.3.
Idempotence
HMG does not support idempotence.
Even if
HMG require a unique Tracking ID
,
we
will not check if the Tracking ID has been used before. HMG does not inspect the
payload to detect duplicates
or in any other way ensure that a
unique
message always
give the same result in the Volvo Back
-
end system
.
H
MG only provide transport and
protocol conversion.
However, a
basic level of duplicate control is available in the
Asynchronous Request
Reply
Message Exchange Pattern. HMG will check that no current message
is in in
flight or in the message box with the same tracking id as an incoming message. In that
case, the incoming message will be rejected.
T
he back
-
end system which receives a message from HMG may have different levels
of impotence implemented. The Serv
ice Specific Instruction states if a back
-
end
service is idempotent and how it supports idempotence.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
15
(
40
)
8.3.
Fire&Forget
8.3.1.
MEP Overview
8.3.2.
Purpose
The purpose of Fire&Forget is
to send
a message to Volvo.
8.3.3.
Operation
We
b
Service Operation:
sendMessage
8.3.4.
Specific
Header
Information
Attribute
Description
Purpose
Defined
in
Specific
Service
Instruction
Mandatory
N/A
8.3.5.
Reply
The Fire&Forget MEP does not offer a real reply. However
,
a response will be sent
in
the same session
with an ACK or
an error message
in order for the external party to
understand if the m
essage has been received by HMG or not.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
16
(
40
)
8.3.6.
Example
s
:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
17
(
40
)
8.4.
Synchronous Request/
Reply
8.4.1.
MEP Overview
8.4.2.
Purpose
The purpose of Request Reply is to request data from a Volvo Service and to get the
reply in the same
session
. Request
/Reply should be used for sessions lasting for a few
seconds
(see
HMG Rules of Usage
)
.
Asynchronous Request Reply (Out of Scope in
first Release)
can be used when the reply message is expected after a longer time.
8.4.3.
Operation
Web Service Operation:
processMessage
8.4.4.
Specific
Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
N/A
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
18
(
40
)
8.4.5.
Reply
The
reply
is
returned in the same session.
The reply message payload is encoded in the
same way as the request.
8.4.6.
Example
s
:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
19
(
40
)
8.5.
Push
8.5.1.
MEP Overview
8.5.2.
Purpose
The purpose
of
Push is to send out a message from a Volvo
back
-
end
system to an
external partner.
The message is fetched by polling
The Message Box
. This Message
Exchange Patt
ern
is an outgoing Fire&Forget from
Volvo.
Some use cases for Push:
Push can be used to
push out basic data to an external partner.
Push
can be used
to give an independent reply to an incoming
Fire&Forget
message.
8.5.3.
Operation
Web Service Operation:
fetchMessage
Read section
Different ways of fetching responses from the Message Box
to
understand how the fetch can be managed.
List Messages
can also be used to discover Push mes
sages available for pick
-
up.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
20
(
40
)
8.5.4.
Specific Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
ReturnMessag
ePayloadType
Enter: XML,
String or
Base64.
Used to decide how
the reply message
payload should be
encoded.
Yes
Yes
MaxMessageC
ount
The maximum
Messages returned in
the bundle.
The
number cannot be
larger than defined in
HMG Rules of Usage
Make it possible for
the external party to
cho
o
se how many
messages which will
be
returned in one
session.
No
No
, but 1
message
will be
returned if
not set by
the
requestor
MaxMessageS
ize
The maxim
um size of
the returned
message(s) fetched in
one call, expressed
in
MB.
Make it possible for
the external party to
choose
the maximum
siz
e of returned
messages.
No
No,
but the
size is
capped to
HMG Rules
of Usage
.
8.5.5.
Reply
The reply contains the
information pushed from the Volvo back
-
end system
.
The
encoding of the Push message can be chosen according to
Specific Header
Information
.
The FetchMessage operation used in the Push Message Exchange Pattern may return
many messages in one Session. This is called a Message Bundle.
How the message
bundle behaves is des
cribed in
Specific Header Information
above.
8.5.6.
Pushing data to many Roles
Some messages are intended for many roles. This is common for different types of
basic data.
A proper Publish/Subscribe pattern is not
available in HMG, but a similar effect can
be established by setting up a generic role representing the Authenticated User (e.g. a
DMS Provider). The Volvo back
-
end systems can push messages to this specific role
and the external system can distribute the
message to all or a selection of managed
roles.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
21
(
40
)
Figure
3
Pushing data to many Roles
8.5.7.
Examples:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
22
(
40
)
8.6.
Asynchronous Request
Reply
8.6.1.
MEP Overview
8.6.2.
Purpose
The purpose of the Asynchronous
Request/Reply is to manage replies which are sent
much later than the request
(long running)
. Like in
Fire&Forget
, there is a response
sent in the same session to clarify if the message was received by HMG or not. The
reply
containing the message payload is processed by the back
-
end system
asynchronously and is placed in the Message Box for the external party fetch at will.
The TrackingID is used to correlate the incoming request
with the
reply
by the
external party
.
8.6.3.
Operatio
n
Web Service Operation
for sending the request
:
sendMessage
Web Service Operation for fetching the response:
fetchMessage
o
Use the TrackingID
acquired from the sendMessage reply
to fetch the
specific reply for the request using the fetchMessage operation.
o
Replies can also be listed and fetched in bulk with the same semantics
as the
Push exchange pattern.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
23
(
40
)
8.6.4.
Specific Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
TrackingID
In this MEP the
Tracking ID is used to
fetch the reply for a
specific request
asynchronously from
The Message Box
Tracking ID is used to
correlate responses
and for logging
purposes. It is also
used to
fetch
a unique
mes
sage from
The
Message Box
.
The
tracking. Read more
in section
Tracking ID
No
No, but
HMG will
generate a
unique ID
of not set
by the
sender.
8.6.5.
Reply
There is one response as in
Fire&Forget
to determine if the re
quest was successfully
placed or not. The real
reply
will be returned asynchronously to
The Message Box
.
The external party polls for reply messages using t
he TrackingID
to identify
a specific
reply message.
8.6.6.
Error code when the reply has not yet arrived
An asynchronous reply might by design take some time to arrive to HMG. An attempt
to fetch an asynchronous reply when it has not yet arrived will result in
an error with
the error code 2017. This can be good to know of and not log as a real error, but rather
look for the reply at a later stage.
8.6.7.
Duplicate Control
HMG requires a unique
Tracking ID
, but do
es
not enforce this beha
vior
. In the case o
f
Asynchronous reques
t reply
,
HMG will check for duplicates in the Message Box. If
there is an existing message in the Message Box
,
the incoming message will not be
accepted. No history is saved, which means that a message with the same
Tracking ID
may be accepted at a later stage when the first message has been
deleted from the
Message Box. The purpose of the duplicate detection is to ensure that the reply is sent
to the same requestor.
8.6.8.
Examples:
Example messages include a sendMessage r
equest, a sample response and a
fetchRequest message. Those are the same as used in
Push
and
Fire & Forget
scenarios, so check them out as well.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
24
(
40
)
8.7.
List Messages
8.7.1.
MEP Overview
8.7.2.
Purpose
There are
many
purposes with List Messages:
Overview of the messages in Message Box (foundation for retransmission)
Error
-
handling
List Messages can be a method to poll the message box.
See section
Different
ways of pulling responses from the Message Box
List Messages will return a list of Messages currently in the message box.
The list is
sorted by Creation D
ate
and time
in descending orde
r. By default the List
Message
O
perati
on only return unread messages.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
25
(
40
)
Since Web Services is a non
-
transactional protocol it is possible that messages are
marked as read by HMG,
even if
the message was lost on the way
back
to
the
external
party.
By listing the messages in the
Message box it is possible to see which messages
that can be retransmitted.
8.7.3.
Operation
Web Service Operation:
listMessage
8.7.4.
Specific Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
Retu
r
n
Messag
eStatusType
Specify what status of
messages should be in
the list reply. All,
Unread and Read.
The purpose is to
limit
the response size if
there are a lot of
messages in the box
No
No
(defaults to
Unread)
8.7.5.
List Message Logic
List Messages can be used in the
following ways:
User ID
Role
Service
Result
Mandatory
Blank
Blank
Lists all messages in
the message box f
or
the authenticated
U
ser
ID
.
Mandatory
Role ID
Blank
Lists all messages in
the message box for
a
specific Role ID.
Mandatory
Role ID
Service ID and
Version
Lists all messages in
the message box for a
specific Role and
Service.
Mandatory
Blank
Service ID and
Version
Lists all messages in
the message box for a
specific Service.
8.7.6.
Reply
The reply is a list of messages in
The Message Box
with its current read status
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
26
(
40
)
8.7.7.
Examples:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
27
(
40
)
8.8.
Update Message Status
8.8.1.
MEP Overview
8.8.2.
Purpose
The purpose of Update Message Status is to change the read status of a message in
The Message Box
. It is possible to alter the read status to
Reset
. This makes it possible
to
fetch
the message(s)
from
The Message Box
again.
8.8.3.
Operation
Web Service Operation:
updateMessageStatus
Update Message Status requires a Tracking ID as input paramete
r for each message
that needs to be reset.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
28
(
40
)
8.8.4.
Specific Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
N/A
8.8.5.
Reply
The response is a list of messages with the current read status
.
8.8.6.
Examples:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
29
(
40
)
9.
The Message Box
The message box makes it possible for a Volvo back
-
end system to reply to an
incoming Web Service Call asynchronously.
It also makes it possible to push out
messages to an external party.
Figure
4
Conceptual Message Box Interacti
on
The message box is used in the following Message Exchange Patterns:
Push
Asynchronous Request Reply
Messages are
fetch
ed from the Message box using:
The
fetchMessage
operation as described in
the Pattern
s
above.
The message box can be monitored and altered by the following Message Exchange
Patterns:
List Messages
Update Message Status
9.1.
Me
ssage Box state handling
The message box is able to store messages waiting to be fetched by the client. Each
message in the message box has a status attached to it. The status can be either of
“AwaitingReply”, “Unread”, “Read” and “Reset.
Awaiting Reply
–
A request is sent
Unread
–
A response is received from the backend system
Read
–
The response is fetched by the client
Reset
–
The client has reset the message to be able to read it again
The state chart stops when the time to live is reached and the messa
ge deleted
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
30
(
40
)
AwaitingReply
Unread
Reset
Read
No reply recieved
Reply
Received
Message is never fetched
Reset By Client
Read
after
Reset
Read by
Client
Figure
5
Message box message status state chart
9.2.
Different ways of
fetch
ing responses from the Message Box
There are many ways to fetch message
from the Message Box. The different methods
have different pros and cons. The different polling patterns are described below in the
order Volvo would like recommend.
9.2.1.
1
-
List & Fetch
List and fetch is based on a
reoccurring
poll using the list message operation
based on
role
. When list message
gives a result the messages are retrieved
by a role based fetch.
The initial list operation gives knowledge in which messages that are supposed to be
fetched, if anything goes wrong. This makes it possible to reset individual messages
by resetting the rea
d status by Tracking ID using
Update Message Status
.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
31
(
40
)
Service can be used as a parameter in the fetch, but is more costly since there will be
more fetches performed
.
If MaxMessageCount is not set or set to 1, you n
eed to repeat
step 1 until you receive a successful reply with no included message. This is also true
if MaxMessageCount is set to 25 and the number of messages in the List Operation
exceeds 25 messages.
Pros:
Few polls
Possible to get only one Service
Er
ror handling based on
Tracking ID possible
Cons:
The back
-
end service needs to be able to distinguish different Services in one
response
9.2.2.
2
-
Fetch
by Role
Fetch by role is based on a reoccurring
fetch based on role.
This
polling pattern is
basically the reverse of List and Fetch.
If an error occurs the
external system needs to list all messages in order to understand which message
that has not been received. After this, it is possible to reset the read status
and fetch
again.
Y
ou need to r
epeat step 1 until you receive a successful
reply with no included
message.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
32
(
40
)
Pros:
The fetch is easy to implement in the external system
Few(er) polls
Cons:
The back
-
end service needs to be able to distinguish different Services in one
response
9.2.3.
3
-
List
by Role
List by Role is based on a reoccurring poll using the list message operation based
on role. The fetch is made on each individual Tracking ID received in the list
message operation. This giv
es a very controlled way
of
handling the poll
since
onl
y one message with a unique ID is handled at a time. This makes error handling
easier, but the cost is higher than f
etching many messages in one go
due to the
overhead of fetching single messages.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
33
(
40
)
Pros:
The best option for error handling, since every poll
is isolated to one specific
Tracking ID
Fewer polls than
polling one service as a time
Cons:
Many
fetch i
nteractions due to one fetch per message
9.2.4.
4
-
Fetch
by Service
Fetch by Service is based on a reoccurring fetch based on both Role and Service.
The result will be clean replies with only one Serv
ice for one specific Role. The
backside of this solution is that there may be very many
polls, since
each service is
polled individually.
You need to repeat step 1 until you receive a successful reply
wit
h no included message.
Pros:
It is easy to implement this solution in the external application
.
Cons:
Many polls, since each service needs to be polled individually.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
34
(
40
)
10.
HMG Rules of Usage
Rule
Value
Comment
P
oll interval in
The Message
Box
It is not allowed to poll
The
Message Box
more frequently
than every five minutes
for a
specific role and service.
Maximum
Total
Message
Size
5MB
(
single message or
mes
sage bundle)
The
use of small atomic
messages is
preferred
.
Maximum Message Count
25 Messages
in any bundle.
A message bundle can only
contain messages for one role
in order to correlate
asynchronous responses from
back
-
end systems.
If MaxMessageCount
is set
higher
or is left out
in a fetch
message, it will be capped
according to this rule.
Clean
-
up of unread messages
Unread messages are kept in
the Message box for 1 week
Clean
-
up of read messages
Read messages are kept for
retransmission for
2 day
s
.
Pushing
large data volumes
(initial load)
The pu
shing
of large data
volumes should be discussed
with
the back
-
end system
in
order to plan capacity in
HMG and the back
-
end
system.
Some services may have
specific solutions for initial
load
which are not
implemented by HMG. It is
recommended to use these
services.
Synchronous Request/Reply
time limits
Used for sessions estimated
for about 10 seconds.
Maximum is 1 minute. For
longer sessions, use
asynchronous request/reply
.
Rule to adopt new versions
See section
Version Handling
HMG Service Window
HMG
may be
down for
maintenance
on Sundays
between 17.00
-
21.00 CET.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
35
(
40
)
10.1.
Encoding of
Message Payload
There are
three ways to encode the Message Content:
String
XML
Base64
10.1.1.
String
The easiest
way to encode a message is as
a string
. An XML message can also be
encoded as a string using CDATA markup
or by escaping the
XML characters
.
However
,
if the in
cluded XML file includes CDATA sections,
you need to
use
AnyXML or
encode the payload
using
Base64.
10.1.1.1.
Known Limitations
If a string contains
“
<
”
or
“
&
” characters
, they will be e
scaped in response messages.
10.1.2.
AnyXML
The payload can be encoded as XML. However, it may be difficult to parse
the reply
in some environments. The XML declaration needs to be removed before inserting the
payload as XML in
a message to HMG.
10.1.3.
Base64
Practic
ally anything can be attached to
the
message using Base64
for encoding any
text
. Disadvantages are the cost for enc
oding and a larger message size.
Another
disadvantage is that the message is not readable by humans.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
36
(
40
)
11.
Version
Handling
11.1.
Version Naming
X.Y.Z (1.0.0):
First digit X: Major version. Big changes which
are not backwards compatible
Second digit Y: Change in the current major version which is not backwards
compatible
Third digit
Z
: Minor version change. The change is ba
ckward compatible.
11.2.
HMG WSDL and Message Schema
The HMG WSDL and Message Schema will be available in different versions over
time.
A
version will be
available
for 2 years
after
a defined decommissioning
statement.
The external user of HMG needs to migrate
to a newer version within this
time.
11.3.
Service Versioning
A specific Service has its own
life cycle.
A
version will be
available
for 2 years
after
a
defined decommissioning statement
as a default.
Decomissioning statements is
available on the
HMG Webpage
.
Specific rules for a
Service may be defined in the
s
pecific Service Instruction
. The external user of the Service needs to migrate to a
newer version within this time.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
37
(
40
)
12.
Error Messages
12.1.
Configuration Errors
Error Code
Description
1001
Role ID not found in HMG
1002
No service with specified name found in HMG
1003
Message Exchange Pattern is defined differently for this request
1004
Unexpected message type
1005
Correlation type not specified
1006
Missing update information
1007
No
role
with specified name found in HMG
1008
No
user
with specified name found in HMG
12.2.
Illegal arguments and incorrect usage errors
Error Code
Description
2001
Authentication header not specified. Request should go
through the SWS
service.
2002
No messages found
with given tracking id when Fetching data
200
7
No Service was specified in the request.
2008
No Role was specified in the request.
2009
No Userna
me was specified in the request (also checked by SWS)
2010
No Service
v
ersion was specified in the request.
2011
R
ole
ID
should be specified using the
GIMDestinationId header
when
message is routed from MQ to HMG.
2012
CorrelationId needs to be set.
Typically, this means that the header
HMGVirtualQueueName
needs to be specified on a MQ message to HMG.
2013
Unexpected Request data type, String, Base64 and XML are valid
2014
Incorrect tracking id given when trying to update message status
2015
Payload validation error (message could not validate against
schema)
12.3.
Generic error codes
Error Code
Description
3001
Unknown error. Please contact support for more information.
12.4.
Security error codes
Error Code
Description
4001
Permission denied
–
the user/role does not have access to perform the
operation
requested.
12.5.
Internal error codes
Error Code
Description
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
38
(
40
)
5001
The message box is unable to parse the XML data in the payload.
5002
Message Box update mismatch. Error in resetting a message status. Report
issue to support.
5003
Tracking ID already exists
in HMG. Please provide a globally unique
(guuid) tracking ID for each send request.
12.6.
Back
-
end System Errors
Error Code
Description
6001
The backend system response timed out. Please try again.
6002
Service defined MQ queue not found.
6003
Unknown MQ error.
Please contact support for more information
.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
39
(
40
)
13.
Trouble Shooting
13.1.
Authentication setup.
Basic authentication is needed.
However, SWS also requires a specific cookie. Most
clients are able to set this header automatically by doing a request
to HMG/SWS, but
some are not able to. Please add the HTTP cookie “SMCHALLANGE=YES”. This
resolves into the following HTTP header:
Cookie: SMCHALLANGE=YES
13.1.1.
Cookies and
Microsoft Windows Communication Framework
–
WCF
When Communicating with HMG from a .Net based solution additional headers may
have to
be set.
When using WCF, p
lease add this header in the request:
(
"Cookie"
,
"SMCHALLENGE=YES"
)
13.2.
Timeouts
If you receive time outs, please increase your web
service call ti
me out to more than
60s to make sure you are able to receive HMG error message.
HMG currently has a timeout of 60s, add additional time on top of that to cope with
network round trip time etc.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
40
(
40
)
14.
WSDL and Schemas
14.1.
HMG 1.0.0
Date
Revision
Events
201
3
-
04
-
25
1.0.
1
First version
Enter the password to open this PDF file:
File name:
-
File size:
-
Title:
-
Author:
-
Subject:
-
Keywords:
-
Creation Date:
-
Modification Date:
-
Creator:
-
PDF Producer:
-
PDF Version:
-
Page Count:
-
Preparing document for printing…
0%
Σχόλια 0
Συνδεθείτε για να κοινοποιήσετε σχόλιο