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.
Sign
Date
Http/MQ Gateway Instruction
Issuer (name, phone)
2 (40)
Johan Planmo
Approved by (name, phone)
Page
Info class
2012-05-22
Sign
Date
Valid
Contents
1.
REVISION HISTORY .................................................................................................... 4
2.
PUBLICATION OF HMG INFORMATION ..................................................................... 5
3.
INTRODUCTION ........................................................................................................... 6
3.1. Service Interface .................................................................................................. 7
3.2. Alternative to Web Services ................................................................................. 8
4.
SERVICE ENDPOINTS ................................................................................................. 9
5.
AUTHENTICATION ...................................................................................................... 9
5.1. Session cookies ................................................................................................... 9
6.
AUTHORIZATION....................................................................................................... 10
7.
SERVICE DEFINITION ............................................................................................... 11
7.1. General definition ............................................................................................... 11
7.2. HMG Specific Definition ..................................................................................... 11
8.
MESSAGE EXCHANGE PATTERNS ......................................................................... 12
8.1. General Header Information ............................................................................... 12
8.2. Tracking ID......................................................................................................... 13
8.2.1. Usage.......................................................................................................... 13
8.2.2. Setting the Tracking ID ................................................................................ 13
8.2.3. Idempotence ............................................................................................... 14
8.3. Fire&Forget ........................................................................................................ 15
8.3.1. MEP Overview ............................................................................................ 15
8.3.2. Purpose ....................................................................................................... 15
8.3.3. Operation .................................................................................................... 15
8.3.4. Specific 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
Document name Document1, saved date 2016-02-08
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
Reg. No.
Page
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 data 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. Purpose ....................................................................................................... 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. Specific 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
Http/MQ Gateway Instruction
Reg. No.
Page
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. HMG WSDL and Message Schema ................................................................... 36
11.3. Service Versioning ............................................................................................. 36
12.
ERROR MESSAGES .................................................................................................. 37
12.1.
12.2.
12.3.
12.4.
12.5.
12.6.
13.
Configuration Errors ........................................................................................... 37
Illegal arguments and incorrect usage errors ...................................................... 37
Generic error codes ........................................................................................... 37
Security error codes ........................................................................................... 37
Internal error codes ............................................................................................ 37
Back-end System Errors .................................................................................... 38
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 information
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.
Updated 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.
Http/MQ Gateway Instruction
2.
Page
5 (40)
Publication of HMG Information
This document is published on the Volvo IT EDI and B2B website:
http://www.volvoit.com/edi
Select the tab B2B HMG for news 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
Http/MQ Gateway Instruction
3.
Reg. No.
Page
6 (40)
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:
 Expose any Volvo back-end system based on WMQ as a Web Service
 A uniform authentication and authorization model for Web Services
 Remove Synchronous dependencies to Volvo back-end systems
o External system and back-end system can operate independently in
time (except synchronous Request/Reply)
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
3.1.
Reg. No.
Page
7 (40)
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 operations 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
Http/MQ Gateway Instruction
3.2.
Reg. No.
Page
8 (40)
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 Gateway 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.
Http/MQ Gateway Instruction
4.
Page
9 (40)
Service Endpoints
Environ
ment
TEST
URL
Purpose
https://sws-test.volvo.com/hmgWeb/ws/wsmq
QA1
https://hmgqa.integration.volvo.com/hmgWeb/ws/wsmq
PROD2
https://hmg.integration.volvo.com/hmgWeb/ws/wsmq
Mainly used for tests by
Volvo Group.
Used for testing with
external parties. May be
connected to QA backend services.
The production URL
with connection to real
back-end services.
5.
Authentication
Username and password should be entered in the Http 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.
1
2
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.
Not available yet and the address may be changed
Not available yet and the address may be changed
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
6.
Reg. No.
Page
10 (40)
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 the 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 Message 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.
Http/MQ Gateway Instruction
Page
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. When 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-reply or one-way inbound.
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
8.
12 (40)
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 Information
The Attributes are annotated in the schemas. Below is an overview of the most
important header attributes.
Attribute
Description
ServiceName
The name of the
service to call.
ServiceVersion The version of the
Service to be used.
CreationTime
RoleID
SourceSystem
Name
TrackingID
Date and time when
this message was
created. Include
timezone if possible.
The role which sends
or requests the
message. Defined by
the external partner.
Any name identifying
the system sending
this message.
GUID (Globally
Unique Identifier) set
by the external
partner to uniquely
identify a message.
Read more in section
Tracking ID
Purpose
Defined in
Specific
Service
Instruction
Identify which Service Yes
to call
Possibility to have
Yes
many concurrent
versions of a service
Logging
No
Mandatory
Authorization to the
incoming Service call.
It is also used to fetch
messages for a
specific role from The
Message Box
Logging
No
No
No
Yes
Tracking ID is used to
correlate responses
and for logging
purposes. It is also
used to fetch a unique
message from The
Message Box. The
tracking. Read more
in section Tracking ID
No
No, but
HMG will
generate a
unique ID
if not set by
the sender.
Yes
Yes
No
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
13 (40)
Attribute
Description
Purpose
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
systems. Only specific
back-end services
require GIM headers.
8.2.
Tracking ID
8.2.1.
Usage
Defined in
Specific
Service
Instruction
Yes
Mandatory
No
The Tracking ID makes it possible to identify a unique message. The tracking ID must
contain a Globally Unique 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 the 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
Http/MQ Gateway Instruction
Reg. No.
Page
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. HMG 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.
The back-end system which receives a message from HMG may have different levels
of impotence implemented. The Service 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.
Http/MQ Gateway Instruction
8.3.
Fire&Forget
8.3.1.
MEP Overview
8.3.2.
Purpose
Page
15 (40)
The purpose of Fire&Forget is to send a message to Volvo.
8.3.3.
Operation

8.3.4.
Web Service Operation: sendMessage
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 message has been received by HMG or not.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
8.3.6.
Examples:
Reg. No.
Page
16 (40)
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Http/MQ Gateway Instruction
Page
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

8.4.4.
Specific Header Information
Attribute
N/A
Web Service Operation: processMessage
Description
Purpose
Defined in
Specific
Service
Instruction
Mandatory
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
8.4.5.
Reg. No.
Page
18 (40)
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.
Examples:
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
8.5.
Push
8.5.1.
MEP Overview
8.5.2.
Purpose
Reg. No.
Page
19 (40)
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 Pattern 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 messages available for pickup.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
8.5.4.
20 (40)
Specific Header Information
Attribute
Description
Purpose
ReturnMessag
ePayloadType
Enter: XML, String or
Base64.
Used to decide how
the reply message
payload should be
encoded.
Make it possible for
the external party to
choose how many
messages which will
be returned in one
session.
MaxMessageC The maximum
ount
Messages returned in
the bundle. The
number cannot be
larger than defined in
HMG Rules of Usage
MaxMessageS
ize
8.5.5.
The maximum size of
the returned
message(s) fetched in
one call, expressed in
MB.
Make it possible for
the external party to
choose the maximum
size of returned
messages.
Defined in
Specific
Service
Instruction
Yes
Mandatory
No
No, but 1
message
will be
returned if
not set by
the
requestor
No, but the
size is
capped to
HMG Rules
of Usage.
No
Yes
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 described 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
Http/MQ Gateway Instruction
Figure 3 Pushing data to many Roles
8.5.7.
Examples:
Reg. No.
Page
21 (40)
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
8.6.
Asynchronous Request Reply
8.6.1.
MEP Overview
8.6.2.
Purpose
Reg. No.
Page
22 (40)
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.
Operation


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
8.6.4.
23 (40)
Specific Header Information
Attribute
Description
Purpose
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
message from The
Message Box. The
tracking. Read more
in section Tracking ID
8.6.5.
Defined in
Specific
Service
Instruction
No
Mandatory
No, but
HMG will
generate a
unique ID
of not set
by the
sender.
Reply
There is one response as in Fire&Forget to determine if the request was successfully
placed or not. The real reply will be returned asynchronously to The Message Box.
The external party polls for reply messages using the 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 does not enforce this behavior. In the case of
Asynchronous request 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 request, 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
Http/MQ Gateway Instruction
8.7.
List Messages
8.7.1.
MEP Overview
8.7.2.
Purpose
Reg. No.
Page
24 (40)
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 Date and time in descending order. By default the List Message
Operation 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

8.7.4.
Web Service Operation: listMessage
Specific Header Information
Attribute
Description
ReturnMessag
eStatusType
Specify what status of
messages should be in
the list reply. All,
Unread and Read.
8.7.5.
Purpose
Defined in
Specific
Service
Instruction
The purpose is to limit No
the response size if
there are a lot of
messages in the box
No
(defaults to
Unread)
List Message Logic
List Messages can be used in the following ways:
User ID
Role
Service
Mandatory
Blank
Blank
Mandatory
Role ID
Blank
Mandatory
Role ID
Service ID and
Version
Mandatory
Blank
Service ID and
Version
8.7.6.
Mandatory
Result
Lists all messages in
the message box for
the authenticated
User ID.
Lists all messages in
the message box for a
specific Role ID.
Lists all messages in
the message box for a
specific Role and
Service.
Lists all messages in
the message box for a
specific Service.
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
Http/MQ Gateway Instruction
8.7.7.
Examples:
Reg. No.
Page
26 (40)
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
8.8.
Update Message Status
8.8.1.
MEP Overview
8.8.2.
Purpose
Reg. No.
Page
27 (40)
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 parameter for each message
that needs to be reset.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Http/MQ Gateway Instruction
8.8.4.
28 (40)
Specific Header Information
Attribute
Description
Purpose
Defined in
Specific
Service
Instruction
N/A
8.8.5.
Reply
The response is a list of messages with the current read status.
8.8.6.
Page
Examples:
Mandatory
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Http/MQ Gateway Instruction
9.
Page
29 (40)
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 Interaction
The message box is used in the following Message Exchange Patterns:
 Push
 Asynchronous Request Reply
Messages are fetched from the Message box using:
 The fetchMessage operation as described in the Patterns above.
The message box can be monitored and altered by the following Message Exchange
Patterns:
 List Messages
 Update Message Status
9.1.
Message 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 message deleted
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Page
Http/MQ Gateway Instruction
30 (40)
No reply recieved
AwaitingReply
Reply
Received
Unread
Read by
Client
Read
Read
after
Reset
Reset By Client
Reset
Message is never fetched
Figure 5 Message box message status state chart
9.2.
Different ways of fetching 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 read status by Tracking ID using Update Message Status.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Reg. No.
Http/MQ Gateway Instruction
Page
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 need 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:



Cons:

9.2.2.
Few polls
Possible to get only one Service
Error handling based on Tracking ID possible
The back-end service needs to be able to distinguish different Services in one
response
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.
You need to repeat step 1 until you receive a successful reply with no included
message.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
Reg. No.
Page
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 gives a very controlled way of handling the poll since
only one message with a unique ID is handled at a time. This makes error handling
easier, but the cost is higher than fetching 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.
Http/MQ Gateway Instruction
Page
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 interactions 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 Service 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
with 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.
Http/MQ Gateway Instruction
10.
Page
34 (40)
HMG Rules of Usage
Rule
Poll interval in The Message
Box
Maximum Total Message
Size
Maximum Message Count
Clean-up of unread messages
Clean-up of read messages
Pushing large data volumes
(initial load)
Synchronous Request/Reply
time limits
Rule to adopt new versions
HMG Service Window
Value
It is not allowed to poll The
Message Box more frequently
than every five minutes for a
specific role and service.
5MB (single message or
message bundle)
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.
Unread messages are kept in
the Message box for 1 week
Read messages are kept for
retransmission for 2 days.
The pushing of large data
volumes should be discussed
with the back-end system in
order to plan capacity in
HMG and the back-end
system.
Used for sessions estimated
for about 10 seconds.
Maximum is 1 minute. For
longer sessions, use
asynchronous request/reply.
See section Version Handling
HMG may be down for
maintenance on Sundays
between 17.00-21.00 CET.
Comment
The use of small atomic
messages is preferred.
If MaxMessageCount is set
higher or is left out in a fetch
message, it will be capped
according to this rule.
Some services may have
specific solutions for initial
load which are not
implemented by HMG. It is
recommended to use these
services.
Company name
Type of document
Volvo IT
Instruction
Name of document
Issue
Http/MQ Gateway Instruction
10.1.
Reg. No.
Page
35 (40)
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 included 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 escaped 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
Practically anything can be attached to the message using Base64 for encoding any
text. Disadvantages are the cost for encoding 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
Http/MQ Gateway Instruction
Reg. No.
Page
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 backward 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
specific 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.
Http/MQ Gateway Instruction
12.
Page
37 (40)
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
2007
No Service was specified in the request.
2008
No Role was specified in the request.
2009
No Username was specified in the request (also checked by SWS)
2010
No Service version was specified in the request.
2011
Role 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.
Http/MQ Gateway Instruction
5001
5002
5003
Page
38 (40)
The message box is unable to parse the XML data in the payload.
Message Box update mismatch. Error in resetting a message status. Report
issue to support.
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.
Http/MQ Gateway Instruction
Page
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, please add this header in the request:
("Cookie", "SMCHALLENGE=YES")
13.2.
Timeouts
If you receive time outs, please increase your web service call time 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
Http/MQ Gateway Instruction
Reg. No.
Page
40 (40)
14.
WSDL and Schemas
14.1.
HMG 1.0.0
Date
Revision
Events
2013-04-25
1.0.1
First version