Your Development & Design Resource

MDS Push Confirmation, Custom HTTP Headers, and a LotusScript and Java HTTP Request Consumer

Better a thumb than a finger... in most situations! Today I updated Showtime, my BlackBerry Enterprise Server MDS Push Utility for the IBM Lotus Notes Client, to use the X-RIM-Push_NotifyURL HTTP Header to create a confirmation logger for any Showtime job submission...

Well, that's an over-simplification of what's happening.

When Showtime initiates an HTTP Request (via the POST Method) to the target BlackBerry Enterprise Server MDS Push API, it generates a simple log NotesDocument tracking who initiated the request, the Destination, etc. -- pretty simple stuff there.

What it could not do, however, was confirm that the request was accepted by the MDS Push API and -- more importantly -- that the MDS Push actually pushed the Browser, Message, Channel, or Channel-Delete job to the Destination.

When working with an enterprise-level solution, "I dunno, it should'a worked!" just don't cut it!

After hitting the Push applications for the BlackBerry Enterprise Server - Development Guide (Warning: PDF), I discovered the X-RIM-Push_NotifyURL HTTP Header.

The idea behind X-RIM-Push_NotifyURL is simple: upon completion of the given MDS Push API request, the MDS Push engine will initiate an HTTP Request (via the POST Method) to the URL defined in the X-RIM-Push_NotifyURL HTTP Header.

So I updated first the Showtime Preferences Form to include an option that will allow you to specify a Notify URL value, and then updated the doPost Java Method in Showtime's showtime Java Script Library:


All I needed to do now was create a simple HTTP Request Consumer that would accept the MDS Push Engine HTTP Post and create a log document for reference purposes.

At first pass, I created a simple LotusScript Agent:

Sub Initialize()
    Dim s As New NotesSession
    Dim doc As NotesDocument
    Set doc = s.Currentdatabase.Createdocument()
    Call s.Documentcontext.Copyallitems(doc, true)
    Call doc.Replaceitemvalue("form", "document")
    Call doc.Save(True, False, False)
End Sub

But then I remembered that LotusScript ain't gonna help me when I eventually XPage-enable Showtime! So I created a duplicate Java Agent:

import lotus.domino.*;

public class JavaAgent extends AgentBase {

    public void NotesMain() {

        try {
            Session session = getSession();
            Document doc = session.getCurrentDatabase().createDocument();
            session.getAgentContext().getDocumentContext().copyAllItems(doc, true);
            doc.replaceItemValue("form", "document");

        } catch (Exception e) {

I put these Agent Design Elements into a NotesDatabase residing on a Domino server, put the full URL to the Java Agent in the Showtime Preferences Notify URL, and kicked off a few jobs.


The MDS Push Engine was initiating an HTTP Request (via the POST Method) to my defined japi Java Agent Design Element, which consumed the request and created NotesDocuments for review!

This new feature will -- of course -- make it into the next release of Showtime, which I hope to get out soon. Since I find myself working on this more and more, is there anything else you would like to see in the next release? Leave requests in the comments to this post and I'll see what I can do!

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.