Quercus Message Link Developer’s Guide<>

Receiving messages from Quercus Message Link

ReceiveMessage service

The ReceiveMessage Service allows users to dequeue the next message from either the MESSAGE_OUT queue table.

The URL call for the ReceiveMessage service is:

https://<servername.domain>/<DAD>/qml_rest.ReceiveMessage

There are a number of parameters that are used for the ReceiveMessage service:

Parameter name

Required

Description

Accessid

Yes

Minimum security access ID. The value passed must match the value stored in the database parameter QML.REST.ACCESS_ID

messageType

No

This parameter allows users to determine what type of message they want to dequeue, e.g. MODULE_OUT

The list of available message types is available from the APIWS_MESSAGE table in Quercus or Quercus Message Link Monitor. The message must be enabled in order to dequeue from the system.

receiptTimeout

No

The receiptTimeout parameter is used as part of the two phase acknowledgement process. The number passed in this parameter determines the amount of time in seconds a message is kept on the receipt queue before being requeued to the MESSAGE_OUT queue. A value of zero means that the message is immediately deleted from the MESSAGE_OUT queue.

Receiving messages from the MESSAGE_OUT queue

The most basic method of dequeuing messages from the MESSAGE_OUT queue is to call the service with just the one required parameter appended to the service call:

https://<servername.domain>/<DAD>/qml_rest.receiveMessage?accessid=<accessid>

Example

https://labs.campusit.net/qdev/qml_rest.ReceiveMessage?accessid=USERGROUP

The above will simply dequeue the next message in the MESSAGE_OUT queue. Adding the parameter messageType will allow you dequeue messages for that particular type giving you more control over how you interact with the system.

If there is a message in the table that can be dequeued then the response back from the service will contain a SUCCESS status, a receipt and the payload will contain the message itself, for example:

If there is no message in the queue table the response back from the service will contain a NO-DATA status and a description saying that message queue is empty, for example:

ReceiveMessage receipt and the two-phase acknowledgement

Each message that is dequeued from the system will be presented to you with a unique receipt in the response. As messages are dequeued from the MESSAGE_OUT queue they are then enqueued into a MESSAGE_OUT_RECEIPT_QUEUE where they remain for a specified amout of time, the default is 60 seconds, until they are either deleted by the user using a DeleteMessage service call or they are enqueued again in the MESSAGE_OUT queue table. This process is known a two phase acknowledgement.

The unique receipt in the ReceiveMessage service must be used in the DeleteMessage service to delete the message from the system.

You can control the receiptTimeout by passing it as a parameter in the calling URL, it is passed as a number and is the timeout time in seconds, for example:

https://labs.campusit.net/qdev/qml_rest.ReceiveMessage?accessid=GIVE_ME_ACCESS&receiptTimeout=90

If you do not want to use the Two Phase Acknowledgement then a receiptTimeout time of zero should be passed in the calling URL, for example:

https://labs.campusit.net/qdev/qml_rest.ReceiveMessage?accessid=GIVE_ME_ACCESS&receiptTimeout=0

If a receiptTimeout of zero is passed then the message is immediately deleted from the MESSAGE_OUT queue.

Receiving messages from the hospital queue

Any inbound message that cannot be processed in Quercus will be sent to the hospital queue. There are three main reasons why a message cannot be processed:

1Mandatory fields missing from the message

2Lookup fields containing data that is not in Quercus

3Validation – the message is trying to do something that is not permitted in Quercus, e.g. remove a module from course structure but the module is already used in a student curriculum record.

When a message fails in Quercus and the status of the message is queried a failed response message will be returned with a hospital receipt included, see example below:

A check can be made to see why the message failed. This is done by calling the ReceiveHospital service specifying a valid hospital receipt for the failed message.

The ReceiveHospital service allows users to dequeue failed messages from the HOSPITAL queue table using the hospital receipt from the message status to specify which message to dequeue.

The URL call for the ReceiveHospital service is:

https://<servername.domain>/<DAD>/qml_rest.receiveHospital
 

There are a number of parameters that are used for the ReceiveHospital service:

Parameter name

Required

Description

Accessid

Yes

Minimum security access ID. The value passed must match the value stored in the database parameter QML.REST.ACCESS_ID

Receipt

No

The value for this parameter will be a unique receipt ID for a message in the hospital queue. The receiptID is obtained by checking the status of a message on the system, if the message failed it will have a hospital receipt ID which is used here to retrieve the message from the hospital queue.

If the receipt parameter is not used then the next available message in the hospital queue will be dequeued.

receiptTimeout

No

The receiptTimeout parameter is used as part of the two phase acknowledgement process. The number passed in this parameter determines the amount of time in seconds a message is kept on the HOSPITAL RECEIPT queue before being requeued to the HOSPITAL queue. A value of zero means that the message is immediately deleted from the HOSPITAL queue.

Example

https://labs.campusit.net/qdev/qml_rest.ReceiveHospital?accessid=USERGROUP&receipt=DAF9401EDF2FB3A8E040A8C0CE3E4062

This service call will return the message as it is in the hospital queue with accompanying validation failure reasons. These reasons are found at the bottom of the hospital queue message; see example below:

In this example a MODULE_IN message failed because the Module Level Code of 454654654 did not exist in the Quercus.Module_Level table.

There can be many validation failure reasons and each reason will be listed in the hospital queue message.

Hospital queue receipt and the two-phase acknowledge

Like the standard receiveMessage service for dequeuing messages from the MESSAGE_OUT queue, messages that are dequeued from the HOSPITAL_QUEUE can either be deleted immediately or can be deleted within a specified amount of time. If the hospital queue message is not deleted within the specified amount of time it is requeued onto the hospital queue and made available for dequeue again.

This is achieved using the receiptTimeout parameter in the calling URL. The receiptTimeout determines the amount of time in seconds that a message will stay on the hospital receipt queue before it is requeued to the hospital queue.

https://<servername.domain>/<DAD>/qml_rest.receiveHospital?accessid=<accessid>&receipt=<hospitalreceipt>&receiptTimeout=60

Example

https://labs.campusit.net/qdev/qml_rest.ReceiveHospital?accessid=USERGROUP&receipt=DAF9401EDF2FB3A8E040A8C0CE3E4062&receiptTimeout=60

If the receiptTime is set to 0 then the message is deleted from the hospital queue immediately.

If the receiptTimeout is set to a number greater than 0 then the message will go to the hospital queue receipt queue and wait for the receiptTimeout to expire, in which case it will be enqueued to the hospital queue, or for the message to be deleted via the deleteMessage service call.

The illustration below shows the two phase acknowledgement for the hospital queue.

DeleteMessage service

The DeleteMessage service allows users to delete a specific message from the message out receipt queue. The DeleteMessage service is used in conjunction with the ReceiveMessage service as part of the two phase acknowledgement. The idea is that when you successfully receive a message you can respond with the DeleteMessage service call which tells Quercus Message Link that the message was received successfully and can now be deleted.

The URL call for the DeleteMessage service is:

https://<servername.domain>/<DAD>/qml_rest.DeleteMessage

There are a number of parameters that can be appended to the service call:

Parameter name

Required

Description

Accessid

Yes

Minimum security access ID. The value passed must match the value stored in the database parameter QML.REST.ACCESS_ID

Receipt

Yes

This value of this parameter determines which message will be deleted from the specified queue. The value passed should be a valid receipt ID.

The DeleteMessage Service requires a valid message receipt to be passed back to the system within the specified receipt timeout, for example a valid DeleteMessage URL call might look like this:

https://<servername.domain>/<DAD>/qml_rest.DeleteMessage?accessid=<accessid>&receipt=<receipt>

Example of a deleteMessage service call deleting a message from the Receipt Queue.

https://labs.campusit.net/qdev/qml_rest.DeleteMessage?accessid=USERGROUP&receipt=DB0B15A6C49D0227E040A8C0CE3E468D

The response from the web service will be:

If a valid receipt is not passed in the DeleteMessage Service call then the following response will be returned:

DeleteHospital Service

The DeleteHospital service allows users to delete a specific message from the hospital receipt queue. The DeleteHospital service is used in conjunction with the ReceiveHospital service as part of the two phase acknowledgement. The idea is that when you successfully receive a hospital message you can respond with the DeleteHospital service call which tells Quercus Message Link that the message was received successfully and can now be deleted.

The URL call for the DeleteHospital service is:

https://<servername.domain>/<DAD>/qml_rest.DeleteHospital

There are a number of parameters that can be appended to the service call:

Parameter name

Required

Description

Accessid

Yes

Minimum security access ID. The value passed must match the value stored in the database parameter QML.REST.ACCESS_ID

Receipt

Yes

This value of this parameter determines which message will be deleted from the hospital queue. The value passed should be a valid hospital receipt ID.

The DeleteHospital Service requires a valid hospital receipt to be passed back to the system within the specified receipt timeout, for example a valid DeleteHospital URL call will look like this:

https://<servername.domain>/<DAD>/qml_rest.DeleteMessage?accessid=<accessid>&receipt=<receipt>

Example of a deleteHospital service call deleting a message from the Receipt Queue:

https://labs.campusit.net/qdev/qml_rest.DeleteHospital?accessid=USERGROUP&receipt=DB0B15A6C49D0227E040A8C0CE3E468D

The response from the web service will be:

If a valid receipt is not passed in the DeleteHospital Service call then the following response will be returned: