Thursday, October 9, 2014

My First Experience Using the JSON-RPC Service.

This is one of those posts, where I am writing to my future self so that I can remember all that I learned about using the JSON-RPC service.

If you are an XPages developer who is interested in learning about this tool then I first suggest checking out the following resources:
  • This email response to a question by Tim Tripcony is sheer brilliance. I had to read and re-read this several times to really understand it, but that speaks all about me and nothing about how Tim explains things.  A big thanks to David Leedy for making it available to all.
  • Keith Strickland has written a very helpful blog post on JSON-RPC way back in June 2011. It was Keith who first turned me on to the Remote Service control when I found his answer to this Stack Overflow question.

How I and why I used the JSON-RPC control

I needed to run a server based Java method that called a process and returned a result. My requirements stated that I need to try this process twice in a single event, and tell the user if the first try has failed. The way that Java works is to always one return value, so the intermediary messages would never be returned. In order to accomplish what I needed, I knew that clientside javascript was my best bet. In order to call a serverside java method from clientside JS, I decided to use an JSON-PRC call.

How to create the JSON-RPC service

1) Pull the tool from the pallet under “Data Access”. It is just called “Remote Service”.

2) Give the service a serviceName and/or a pathInfo. I believe that the service may be referred to as either.

3) Create the methods that you need to run. This will involve adding optional arguments and adding SSJS code to run in the script property. The script property doesn’t use the standard script editor that is usually used when you can enter serverside javascript.

4) The finished result

Using the Remote Service

It took me a while to understand that the service doesn’t return a value initially, it returns an object that contains a callback method. The callback method actually returns the value. Thanks to Toby Samples who answered my Stack Overflow question helping me with this.

Here is the code where I call my remote service methods:

Code Explanation:
  1. First the code shows the user a message that the process is starting
  2. Next, a value needed in one of the messages is pulled from a hidden input
  3. The RPC method is called, the object returned is assigned to the var “deferred”
  4. The callback of the object is called to get the result of the ‘first’ method
  5. If the ‘first’ method returns true, the user gets a success message
  6. If the ‘first’ method fails, the user gets a ‘retrying’ message, and the second method is called and the resulting object is assigned to a var “insideDeferred”
  7. If the result of the ‘second’ is true, the user gets a success message
  8. If the result of the ‘second’ method is false, the user gets a ‘try later’ message.

A slight problem

This code all worked great, except… it ran so fast that the ‘trying again’ message appeared too quick for a user to read. I spent a lot of time trying to figure out a way to use timers to slow it down. Eventually I decided that I was spending too much time on this, and used an simple alert for that message, which fulfills my requirement and allowed me to get moving with the rest of the project.

Parting Thoughts

Now that I understand how the Remote Service is used, I am sure I will find more uses for it.  It is an important tool in any XPages developers toolbox.  I can also see it being an important part of web applications that use a Domino backend and frontend Javascript frameworks like Angular JS.


  1. Nice post. Thanks for the mention.

    One thing that stood out. You say Java can only return a single value. Well that's yes.. And no.

    I return multiple values from Java often by putting them in a hash map. It's just key, value pairs right?

    So for user messages I might return a map with the keys "result", "title", "msg". And appropriate values to use in a dialog box maybe.

    1. Thanks for the post, I am techno savvy. I believe you hit the nail right on the head. I am highly impressed with your blog. It is very nicely explained. Your article adds best knowledge to our Java EE Training in Chennai. or learn thru Java EE Training in Chennai Students.

  2. Of course that returning a hashMap is multiple messages for one event. You're talking about about multiple events I think. Just wanted to make sure you knew about returning multiple values overall.

    1. Yes, I needed the same method to return something twice at different times. Not possible as far as I know.

  3. That email was in response to a question I had emailed him about the JSON-RPC service. I received it a couple of days before he passed on.

    I'll never delete that email :-(


    1. Dan, I thought that might have been from you. Great question and great answer. Even though I only met him once, I miss having him around.