Http/MQ Gateway - HMG

balecomputerSecurity

Nov 3, 2013 (3 years and 10 months ago)

508 views













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