YEFI Header Metadata Specification

/ e-Government Program (Yesser)
YEFI SOAP Header Metadata Specification / Version 1.0
Page 1 / 28

Version1.0 Confidential e-Government Program (YESSER)

This document (either in whole or in part) cannot be modified or
reproduced without the prior written permission of the e-Government Program (YESSER)

/ e-Government Program (Yesser)
YEFI Header Metadata specification,
Version 1.0- Page 1 / 20

Document Description

Document TitleYEFI Header Metadata specification

Document version1.0

Document StatusRelease

Versioning

Version
0.1 / 20/5-07 / First version
1..0 / 27/5-07 / Final

Table of Contents

1.Introduction......

1.1.References......

1.2.Target Audience......

1.3.Document Assumptions......

1.4.Requirements Classification

1.4.1.Rationale......

2.SOAP Envelope Element Definition

2.1.Summary

2.2.General structure

2.3.SOAP Message

2.4.YEFI Header Structure

2.4.1.Version

2.4.2.Message Details......

2.4.3.Message Audit......

2.4.4.Message Errors......

3.YEFI Header Schema Definition

3.1.Version 1.0 Schema Diagram......

3.2.Version 1.0 Schema......

3.3.YEFI Schema Versioning

4.Glossary of Terms......

4.1.ebXML — Electronic Business eXtensible Markup Language

4.2.SOAP

4.3.MIME and S/MIME

4.4.SSL - Secure Sockets Layer

4.5.IETF – Internet Engineering Task Force

4.6.W3C – World Wide Web Consortium

5.Appendix

5.1.Sample YEFI Header

Copyright Notice

This document is a working draft or committee draft and is copyright-protected by MCIT.

While the reproduction of working drafts or committee drafts in any form for use by participants in the YEFI standards development process is permitted without prior permission from MCIT, neither this document nor any extract from it may be reproduced, stored or transmitted in any form for any other purpose without prior written permission from MCIT.

Reproduction for sales purposes may be subject to royalty payments or a licensing agreement.

Violators may be prosecuted.

1.Introduction

The core responsibility of the YEFI Header metadata specification is to ensure proper handling of SOAP messages exchanged within the e-Government interaction at the sending agency, messaging service, and receiving agency(ies).

The YEFI header metadata specification has three overall sections:

YEFI Header version
Message details, which include the source, service type, and service action.
Message Audit details which include the correlation ID, message ID, and Timestamp
Message Error which provides information about errors encountered to deliver the message to the destination such as YEFI header validation

The purpose of the specification is to define the details of YEFI header schema. All communication parties within the context of the e-Government of Saudi Arabia should adhere to these specifications, and include this header into the SOAP message within the <header> part. Ensure that messages between government agencies are delivered and routed accurately and securely. This specification can be extended to provide the same services outside the government, to services used by citizens and businesses.

1.1.References

This document is based on the following documents:

REACH SOAP envelope specifications, developed by the Irish e-government program.

The UK Govtalk message envelope (

ebXML and ebXML messaging (

ebXML Message Service Specification Version 2.0 (

1.2.Target Audience

This document is intended for architects, developers and other parties interested in building systems that will communicate with the services provided by Saudi-Arabian government agencies through the Government Service Bus (GSB).

1.3.Document Assumptions

This document makes the following assumptions:

Assumption 1

This document will be used by developers and other parties involved in developing system and software that communicate with other party/agency systems via the GSB, utilizing the SOAP messaging standards.

Assumption 2

The YEFI Interoperability Committee will recommend this specification as the draftstandard for SOAP envelopes used in the Saudi public sector.These specifications will to be validated by the initial GSB implementation. Updates and changes will be made to this document based on the GSB implementation feedback. The updated specifications will follow the versioning rules as specified by the later sections of this document.

Assumption 3

The following areas will be addressed in following versions of this document and be based on feedback from the GSB architecture.

Message security: Message security details will be defined in the next release of this document and be based on the architecture decisions and features provided by the GSB implementation.
Errors and auditing: Some error handling is described in this document, but further work is needed to make error messages smarter and more advanced, in order to make them human-readable and useable by receiving systems.

1.4.Requirements Classification

All standards will use either “Shall”, “Should”, “May” and “Can” as defined by the IEEE when describing expected behaviors with regard to the utilization and usage of standards.[1]

The use of the terms “Must” and “Will” is not permitted.

1.4.1.Rationale

SHALL / The word shall is used to indicate mandatory requirements strictly to be followed in order to conform to the standard and from which no deviation is permitted (shall equals is required to).
SHALL NOT / This phrase means that the definition is an absolute prohibition of the specification.
SHOULD / The word should is used to indicate that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required; or that (in the negative form) a certain course of action is deprecated but not prohibited (should equals is recommended that).
SHOULD NOT / This phrase means that the definition is prohibited. Only under particularcircumstances and if strong reasons exist (that SHALL be accepted as valid),the definition can be ignored, but the full implications SHALL be understood and carefully weighed before choosing a different course.
MAY / The word may is used to indicate a course of action permissible within the limits of the standard (may equals is permitted to).
CAN / The word can is used for statements of possibility and capability, whether material, physical, or causal (can equals is able to).

2.SOAP Envelope Element Definition

This section describes the various elements used within the YEFI Header. It also provides an overall W3C XML based schema defining the envelope elements and their relationship.

2.1.Summary

Element name / Description / Element type
YEFIHeader / The top-level element, containing the YEFI header / Complex
Version / The version number of the envelope / Integer
MessageDetails / Contains the details of the SOAP message, including: MessageType, MessageRole, MessageSource, SourceID, SourceName, MessageDestinations, MessageDestination, PropertyName / Complex
MessageType / Contains the type of the message / String
MessageRole / Contains the role of the message. A message can be a request, an acknowledgement, a negative acknowledgement, a response, an inquiry or it can have no role. / String
MessageSource / Contains the identity of the message sender / String
SourceID / Contains a message identifier, making it possible to uniquely identify a message on a receipt / Integer
SourceName / Contains a message sender name / String
MessageDestinations / Contains the MessageDestination element, can contain multiple instances / Complex
MessageDestination / Contains the definition of the destination, usually the receiving agency. / String
DestinationID / Contains a message destination identifier, making it possible to uniquely identify a message on a receipt
DestinationName / Contains a message destination name
MessageAudit / Contains the CorrelationID, MessageID, Timestamp, ProcessedName, PropertyName and MessageTrace elements / Complex
CorrelationID / The correlation ID is used to track the progress of a message and link message acknowledgements, negative acknowledgements and responses in a system independent manner. / Integer
MessageID / A globally unique identifier for a message within the messaging service / Integer
Timestamp / AnISO 8601 formatted timestamp. Indicates the time at which a document was received for processing by the messaging service. / DateTime
ProcessedName / Indicates the processing which the messaging service performed on the message. Can be pass or fail. / String
PropertyName / A mechanism for including additional properties or parameters with a message / String
MessageTrace / A message origination and route based audit trail. Will be defined further in future versions of this document. / String
MessageAuthentification / Reserved for future implementations of sender signing details. / String
MessageErrors / Errors encountered, updated by the YEFI messaging gateway or by a destination agency where errors are encountered. / String
Error / Represents an individual error, which was generated during the processing of the message / String
RaisedBy / Identifies the system which raised the error / String
Code / Contains an error code / Integer
Text / A human readable description of the error / String
Type / Contains a string defining the type of error message that has occurred / String
Location / The location within the message where the error occurred / String

2.2.General structure

<YEFIHeader

<MessageSource

</MessageSource>

<MessageDestination

</MessageDestination>+

<Property Name=””> Property Value </Property>

</MessageDetails>

<Timestamp> ISO8601 formatted string </Timestamp>

<Processed Name=””> Result : pass | fail <Processed>

<Property Name=””> Value </Property> *

<MessageTrace> Reserved </MessageTrace> *

</MessageAudit>

<Error>

<RaisedBy/

<Code/

<Text/

<Type/

<Location/

</Error>

</MessageErrors>

</YEFIHeader

2.3.SOAP Message

YEFI header SHALL be part of the headers attributes included within the SOAP message. The SOAP message consists of three parts:

SOAP Header
SOAP Body
SOAP Fault

YEFI header will be injected into the SOAP Header as a header complex type.

2.4.YEFI Header Structure

The <YEFIHeader> element SHALL be the root element of every YEFI header attribute. It SHALL declare the namespace for the YEFI Header. This element exists only once for each SOAP message

YEFI Header consists of the following elements:

Version (Mandatory)
Message Details (Mandatory)
Message Audit (Populated by the messaging service)
Message Errors (Optional)

The following sections provide more information about each of the above elements and their internal structure.

2.4.1.Version

The <Version> element SHOULD be present. It specifies the version of the YEFI header that has been used by the message originator. This element appears only once within the YEFI header. It will be used by the messaging service to validate YEFI header against the proper schema version.

Please refer to schema versioningbelow.

2.4.2.Message Details

Message Details are defined by message originator. The <MessageDetails> element provides the service provider with information about the message, its type, source and destination. This section SHOULD NOT be modified by the service provider.

2.4.2.1.Service Type

The <ServiceType> element represents the requested service name at the provider side. Information entered into this element controls the validation, processing, transformation and routing rules, which are applied to a message. This element SHALL be present in YEFI header and it SHALL only be present once.

The list of valid message types and class identifiers is controlled by the messaging service in order to ensure uniqueness.

2.4.2.2.Service Action

The <ServiceAction> element is the primary identifier by which the service provider processes the message. The value of this element is the actual operation name that the requestor is trying to call. This element SHALL be present in YEFI header and it SHALL only be present once.

2.4.2.3.Message Role

The <MessageRole> element denotes the role of the message in relation to its message type. A message type such as ‘MomraRegistration’ may have a number of roles through out its business life cycle. The possible values MAY be as follows:

requestIndicates a submission or service request, the requirement for a response is however not implied. Messages which indicate this role are assigned correlation ID’s which are referenced by subsequent ack’s, nack’s or responses to this request.
ackIndicates an acknowledgement where the recipient has received and accepted a message, it will now proceed to route it to the recipient(s). Ack messages will always contain a correlation ID.
responseIndicates that the message is a response to a previous message request. The correlation ID that was forwarded with the message request SHALL be included in the response. The correlation ID can then be used to link the request to a response.
nackIndicates a negative acknowledgement or error message, which has been generated by the recipient of a message.
inquiryIndicates a request for the current status and audit log of a message within the messaging service. In this case, the element <MessageTrace> should be populated by the messaging service.
noneIndicates that the message role is not relevant to this message type.

This element SHALL be present in the YEFI header and it SHALL only be present once.

The optional rtype attribute provides an additional qualification to the <MessageRole> element, which provides the messaging service with an identifier for role types. Where the rtype attribute is not specified the default role type value is ‘YEFI’

rtype = ‘YEFI’ / YEFI specific message role types, used by default

The verbs used in the <MessageRole> element will depend on the business process for which the message type was designed and the protocol over which it is transported. The role type attribute values will depend on the communicating parties.

2.4.2.4.Message Source

The <MessageSource> element contains information on the identity of the message sender. The sender identifier may be an agency or a service provided by an agency. In the future this may contain the sender ID for an individual or business.

2.4.2.5.Source ID

The <SourceID> element is required; it contains a message identifier, which has been supplied by the message originator. This element will be returned on a message receipt. It is the only method by which a message originator will be able to cross reference the receipt received with the originating message.

The sender identification will use the unique identifiers defined for each government agency in the Kingdom of Saudi Arabia. The identifiers are composed of parent government agency, branch code, and department ID.

In case a business agency needs to be connected to the e-Government framework, the source ID is not provided by the e-Government. For this purpose, the “idtype” attribute was added. This attribute defines the type of the identifier being used. For the government agencies, the value should be “government”, for business “CR” for commercial registration. Other values can be added in the future based on need.

Two organization codes are currently defined:

Government / Specific organization identifier codes distributed by the government
CR / A business-based identifier –Commercial Registration

This element SHALL be present in all YEFI headers and it SHALL only be present once.

2.4.2.6.Source Name

The <SourceName> element is required. It contains the name of the agency, or business organization requesting the service. This can be used in the future to simplify knowing the source name instead of looking it up from the ID.

2.4.2.7.Message Destination

The destination identification code taxonomy SHALL depend on future documents. Organization identification codes MAY be based on established organization identification standards such as

The ‘idtype’ attribute is used to provide an identification type qualifier to the source identifier.

Two organization identifier type codes are currently defined. It is envisioned that other identifier type codes may be introduced in the future.

YEFI / YEFI specific organization identifier codes
URL / A web based identifier -Uniform Resource Locator

An idtype of ’YEFI’ SHALL be used where:

the destination is decided by the content of the message (e.g. message type) and not by the sender.
there is no primary destination other than the following destination.

The ‘source’ attribute is optional and is used by the messaging service to indicate to the message source that additional destinations have been associated with this message. The value of this attribute SHALL be a keyword identifying the source of these additional message destinations.

The following keywords are currently defined for the source attribute:

AUDIT / Used during testing
SUBSCRIPTION / Indicates that this destination was added based on a subscription service associated with message type.

2.4.2.8.Message Destinations

The <MessageDestinations> element contains one or more <MessageDestination> elements. It specifies a list of destination agencies that MAY receive the containing envelope.

The order in which the <MessageDestination> elements appear SHALL NOT be significant.

2.4.2.9.Message Destination

The <MessageDestination> element contains data that defines the destination agency to which the message will be sent. In many cases the destination of the message will be determined from the data in the <MessageType> element.

The <MessageDestination> element SHALL NOT be used to override the primary routing processes associated with the <MessageType> element but MAY be used to further qualify it.

Within <MessageDestination>, two sub elements exist. These are

<DesinationName> and <DestinationID>. Both of these follow the exact convention used by <SourceName> and <SourceID> structure above, but populated with values for each destination

2.4.2.10.Property

The <Property Name= “”> element and its attribute ‘Name’ provide a mechanism for including additional properties or parameters with a message.

2.4.3.Message Audit

Updated by the messaging service and provided as part of a receipt.

2.4.3.1.Correlation ID

The <CorrelationID> is populated by the messaging service when a valid message is received which has a <MessageRole> equal to request. The <CorrelationID> is appended to the message prior to it being routed to the recipient(s) and is included in the message acknowledgement from the messaging service.

The correlation ID is used to track the progress of a message and link message ack’s, nack’s and responses in a system independent manner. The receipt of a populated correlation ID in an acknowledgement message from the messaging service indicated that the message has passed all pre-processing checks.