Ariadni – Department Integration System Interface Message Specifications

Version 2.0

1         Introduction

1.1        Scope

The present document specifies the protocols and interfaces in order to submit and receive messages between Government departments through the DIS Connector and the Government Gateway.

1.2        Target Audience

The intended audience for this document are:

  • Software Designers
  • Software Developers
  • API Developers

1.3        Structure of this document

The document is organized as follows:

  • Chapter 1 – Introduction presents the scope and the terminology used in the document
  • Chapter 2 – An overview of the design of the Government Gateway platform and its components
  • Chapter 3 – Describes the Inbound Message Specifications and the Backend System API specifications
  • Chapter 4 – Describes the Outbound Message Specifications

2         Department Integration System

2.1        Interface Functional Specifications

Integration with Backend system is achieved though the concept of Department Integration System (DIS).

The overall Gateway platform is consisted by the following five corners:

  • C1: Backend system (client) submits an integration message to DIS;
  • C2: The sending DIS responsible to receive data from the Backend system and sends data to Government Gateway (GG);
  • C3: The Government Gateway is responsible for the security (Authentication, Authorization) and the routing of the messages.
  • C4: The receiving DIS responsible to receive data from Government Gateway and notify the Backend system through the available Connectors.
  • C5: The receiving Backend System (provider) receiving the integration message.
Ariadni_Interface Message Specifation Platform

Therefore, the Agencies Backend system should implement the following interfaces:

  • Handle incoming Integration Messages;
  • Submit Request messages at DIS Submission interface;
  • Submit Status Request Message at DIS Submission interface;
  • Submit Response messages at DIS response interface.

2.2        Supported Message Patterns

Gateway platform supports both Synchronous and Asynchronous message exchange:

  • In the synchronous exchange, the consuming client waits for a business response message from the provider service.
  • In the asynchronous exchange the business response message from the provider service will be returned at a later stage asynchronously to Government Gateway. The consuming client will poll the message from the Government Gateway.

3         Inbound Message Specifications

3.1        Supported Message Patterns

3.1.1     Synchronous

The DIS receives the message from the Government Gateway and then through the available Connectors notifies the Backend API waiting for the response.

3.1.2     Asynchronous

The DIS receives the message from the Government Gateway and then through the available Connectors notifies the Backend API.

If the Backend API accepts the integration message without errors then the DIS notifies the Government Gateway that the message is delivered. At this stage the DIS does not expect any response message. The response message will be submitted from the Backend system at a later stage based on business logic.

If the Backend API cannot accept the integration message the DIS connector will retry again X times, based on configuration, to notify the Backend API. Finally, if the maximum retries exceeded then DIS Connector will move the message to the DIS Failed Queue. It is the responsibility of the Administrator to investigate the reasons of the failure.

3.2        Backend System API Specifications

This section describes the supported integration technologies based on the type of the API implementation.

3.2.1     Gateway Metadata

Web services and DB API’s must understand specific Gateway metadata which are the following:

NameTypeDescription
CorrelationIDStringMessage id generated by Gateway
TransactionIDStringIn case the message is related to another request. It will contain the correlation id of the related request
UniqueIdentifierStringCitizen id
LegalUniqueIdentifierStringOrganization registration no
ClientIDStringProfile id of the sender
ReasonStringFree text of the reason the call was made
ServiceNameStringGateway service unique identifier
ProtocolVersionStringVersion of the headers
TimestampDateTimeRequest timestamp

3.2.2     SOAP Web Service

The SOAP Web service must have the following specifications:

  • The web service must be WS-I Basic Profile 1.1 compliant
    • The web service must generate a valid WSDL 1.1 document
    • The web service must understand specific SOAP headers send by Gateway with namespace

3.2.3     DB Procedures

The Database store procedure must implement the following signature:

  • inMsg: The request message in XML.
  • GatewayHeader: The request Gateway metadata in XML
  • outMsg: The response message in XML

The Backend system MUST configure one store procedure per database acting as an orchestrator and then call any other stored procedure.

The DB Connector currently supports the following databases:

  • Oracle
  • SQL Server.

The oracle store procedure signature should be as follow:

  • inMsg: Type CLOB.
  • GatewayHeader: Type CLOB
  • outMsg : Type CLOB

The SQL Server store procedure signature should be as follow:

  • inMsg: Type nvarchar(max).
  • GatewayHeader: Type nvarchar(max)
  • outMsg : Type nvarchar(max)

4         Outbound Message Specifications

The present section specifies the protocols and interfaces in order to submit synchronous or asynchronous request, asynchronous response and query messages between Government departments through the DIS Connector and the Government Gateway.

4.1        Supported Message Patterns

DIS Connector supports following message exchange:

  • In the synchronous outbound exchange, the client application makes a synchronous call to the DIS Connector and waits for a business response message from the provider.
  • In the asynchronous outbound exchange, the client application makes a synchronous call to the DIS Connector, triggering a long-running operation on the provider.

4.2        Base URL

All REST API’s are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

All URLs referenced in the API documentation have the following base:

–     https://{FQDN}/api/v1.0

FQDN: A fully qualified domain name (FQDN) that identifies the connector host.

4.3        Synchronous Outbound Request

4.3.1     HTTP Request

To send a new outbound message, make an HTTP POST to the following resource URL.

Resource: https://{Base URL}/outbound/request/{provider}/{serviceName}

Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.

4.3.1.1    Authentication

HTTP request to REST API are protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.

4.3.1.2    HTTP Headers

The following HTTP Headers may be provided.

4.3.1.2.1   X-TransactionID (optional)

Description: In case the message is related to another request. It will contain the correlation id of the related request

Format: String

4.3.1.2.2   X-Reason (optional)

Description: Free text of the reason the call was made Format: String

4.3.1.3    Payload

The payload must be a valid XML as specified by the provider of the API.

4.3.2     HTTP Response

4.3.2.1    HTTP Headers
4.3.2.1.1   X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.

4.3.2.1.2   X-CorrelationID

This HTTP header is returned in case of a successful request. Contains the Message ID generated by Gateway.

4.3.2.2    Possible HTTP status Codes
HTTP StatusDescription
200 OKThe request was successful and the response body contains the XML received from the department.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid XML.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
502 BAD GATEWAYThe server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response.
4.3.2.3    Successful Response Format

When the HTTP Status Code is 200 OK then the response body contains a valid XML message as specified by the provider of the API.

4.3.2.4    Error Response Format

The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.

An error has the following properties:

PropertyDescription
DescriptionError Description
NumberError Number

4.4        Asynchronous Outbound Request

The client application makes a synchronous call to the Connector, triggering a long- running operation on the provider.

The connector responds synchronously as quickly as possible. It returns an HTTP 202 (Accepted) status code, acknowledging that the request has been received for processing.

The response header holds a location reference pointing to an endpoint that the client can check for the result of the long running operation.

4.4.1     HTTP Request

To send a new asynchronous outbound message, make an HTTP POST to the following resource URL.

Resource: https://{Base URL}/outbound/async/request/{provider}/{serviceName}

Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.

4.4.1.1    Authentication

HTTP request to this endpoint is protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.

4.4.1.2    HTTP Headers

The following HTTP Headers may be provided.

4.4.1.2.1   X-TransactionID (optional)

Description: In case the message is related to another request. It will contain the correlation id of the related request

Format: String

4.4.1.2.2   X-Reason (optional)

Description: Free text of the reason the call was made Format: String

4.4.1.3    Payload

The payload must be a valid XML as specified by the provider of the API.

4.4.2     HTTP Response

4.4.2.1    HTTP Headers
4.4.2.1.1   X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.

4.4.2.1.2   X-CorrelationID

Returned on http status 202 Accepted. Contains the Message ID generated by Gateway.

4.4.2.1.3   Location

Returned on http status 202 Accepted. A URL the client should poll for a response status. See section 4 of this document.

4.4.2.1.4   Retry-After

Returned on http status 202 Accepted. Indicates how long the client should wait before making a follow-up request. A non-negative integer indicating the seconds to delay.

4.4.2.2    Possible HTTP status Codes
HTTP StatusDescription
202 ACCEPTEDThe request was successful received for processing.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid XML.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
502 BAD GATEWAYThe server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response.
4.4.2.3    Successful Response Format

When the HTTP Status Code is 202 ACCEPTED then the response body is empty.

4.4.2.4    Error Response Format

The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.

An error has the following properties:

PropertyDescription
DescriptionError Description
NumberError Number

4.5        Status Request for Asynchronous Outbound Request

The client application makes a synchronous call to the Connector, to receive the response for a long running operation initiated by an asynchronous outbound request.

4.5.1     HTTP Request

The client must send an HTTP GET request to the status endpoint.

The initial status endpoint was returned in the location header of the asynchronous outbound response.

4.5.2     HTTP Response

4.5.2.1    HTTP Headers
4.5.2.1.1   X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.

4.5.2.1.2   X-CorrelationID

This HTTP header is returned in case of a HTTP status code 200 / 202. Contains the Message ID generated by Gateway.

4.5.2.1.3   Location

Returned on http status 202 Accepted. A URL the client should poll for a response status.

4.5.2.1.4   Retry-After

Returned on http status 202 Accepted. Indicates how long the client should wait before making a follow-up request. A non-negative integer indicating the seconds to delay.

4.5.2.2    Possible HTTP status Codes
HTTP StatusDescription
200 OKThe request was successful and the response body contains the XML received from the department
202 ACCEPTEDThe request was successful received for processing.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid XML.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
502 BAD GATEWAYThe server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response.
4.5.2.3    Successful Response Format

When the HTTP Status Code is 202 ACCEPTED then the response body is empty.

4.5.2.4    Error Response Format

The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.

An error has the following properties:

PropertyDescription
DescriptionError Description
NumberError Number

4.6        Asynchronous Outbound Response

The client application makes a synchronous call to the Connector, to return the result of an Asynchronous Inbound Request.

The connector responds synchronously as quickly as possible. It returns an HTTP 202 (ACCEPTED) status code, acknowledging that the response has been received.

4.6.1     HTTP Request

To send a new outbound response message, make an HTTP POST to the following resource URL.

Resource: https://{Base URL}/outbound/async/response/{provider}/{serviceName}/{CorrelationID}

Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.

The CorrelationID is the Message id generated by Gateway and was delivered with the asynchronous inbound request (see ” D3.3-Gateway DIS Interface Specifications-v2 / 3.1.1.1 Gateway Metadata”)

4.6.1.1    Authentication

HTTP request to this endpoint is protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.

4.6.1.2    HTTP Headers

The following HTTP Headers may be provided.

4.6.1.2.1   X-TransactionID (optional)

Description: In case the message is related to another request. It will contain the correlation id of the related request

Format: String

4.6.1.3    Payload

The payload must be a valid XML as specified by the provider of the API.

4.6.2     HTTP Response

4.6.2.1    HTTP Headers
4.6.2.1.1   X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.

4.6.2.1.2   X-CorrelationID

Returned on http status 202 Accepted. Contains the Message ID generated by Gateway.

4.6.2.2    Possible HTTP status Codes
HTTP StatusDescription
202 ACCEPTEDThe response was successful received for processing.
401 UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUESTEmpty request body or not valid XML.
404 NOT FOUNDThe server cannot find the requested resource.
500 INTERNAL SERVER ERRORIndicates that the server encountered an unexpected condition that prevented from fulfilling the request.
502 BAD GATEWAYThe server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: –     Communication Failure with the central Hub or the Hub with the Department
4.6.2.3    Successful Response Format

When the HTTP Status Code is 202 ACCEPTED then the response body is empty.

4.6.2.4    Error Response Format

The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1.

An error has the following properties:

PropertyDescription
DescriptionError Description
NumberError Number
Print Friendly, PDF & Email