Just to refresh on this, the JSON RPC Service component is allocated a serviceName, which is the name you use to access it in CSJS. The methods complex property takes one or more remoteMethods, each with a name, which is the name you use to access that particular method as a child of the serviceName. So if the serviceName is userInfo and a particular method name is getUserName, you would call the remote method as
userInfo.getUserName(). The remoteMethod can take an optional list of arguments and has a script property, which is the SSJS to perform, potentially referencing the arguments. It returns a value, which is passed back to the CSJS.
Knowing that this allows you to run SSJS easily from CSJS, it’s tempting to use it to interact with the XPage, and indeed it does give you access to the components on the XPage. But if you try it, you’re likely to find it doesn’t do what you might expect. As with much of my session at IBM Connect and Engage, the root explanation is that expectations are incorrect and timing is essential. And the key to understanding everything is also the core of my session – a PhaseListener.
The PhaseListener shows the phases run with the JSON RPC Service. Or rather, phase. Because it only runs the Restore View phase. This may seem surprising, but it’s actually very straightforward. In order to load and run the JSON RPC Service, the Restore View phase is the minimum required, to reload the component tree in order to access the JSON RPC Service component, in order to run the SSJS – or, to be more exact, retrieve the string that will be parsed as “SSJS” by the XPages runtime and retrieve the argument properties.
Appreciating that Restore View is the only phase processed is key to understanding what the JSON RPC Service can and can’t be used for, because this is completely different to everything we understand from the rest of XPages experience.
The fact that Apply Request Values and Update Model Values means that it’s not possible to interact with any changes made in the browser. Nothing is passed back to the browser. Values aren’t passed to the submittedValue property of components or the value property of components. So the component tree you’re interacting with is as it was when the page was last passed back to the browser.
The other key point is Render Response is not triggered. This means that although the server-side code (which could be SSJS or Java) can update components, dominoDocument datasources, controllers etc updates made will not be stored. The code will run successfully, but because the Render Response phase doesn’t run, the updates are just dumped. They’re not stored in memory, they’re not stored on disk, they’re not stored at all.
The other impact of missing Render Response is that using the openLogBean in SSJS will also not work. That’s because openLogBean aggregates all event and error messages, to be written out during the Render Response phase. But because that doesn’t run, they’re not outputted. And because the updates are not stored, they literally don’t exist next time the Render Response phase runs.
So the JSON RPC Service is very useful for running server-side code and returning a response for CSJS to access. It’s also good if you don’t want to run server-side code but don’t want to pass back the whole web form. And although you won’t be able to update the server-side objects, that doesn’t mean it’s of no use if you want to perform updates. You can perform updates to database objects like backend documents. A
Document.save() method will still run.
So you could perform backend updates and one possible place where you would want to perform server-side code in a context without passing back the whole web form to update the database may be to delete a document from a view. However, that’s not actually what you want to do. You’ll usually want to delete the document and update the view to show it’s deleted. The former you can do with the JSON RPC Service. But as you will probably now appreciate, you won’t be able to do the latter.
So the JSON RPC Service has a valid purpose and set of use cases. But the key to understanding what they are is appreciating what’s actually running on the server side.