Cloud Pak for Business Automation CP4BA

 View Only

ICP4BA Business Application Addressable URL

By Kam To Frederick Ngo posted Fri October 01, 2021 08:11 PM

You are developing a Business Application, likely with many pages.  Have you ever wonder how you can allow users to share a url of your Business Application so that the application can be loaded again in a certain state by another user?  Copying the url from the browser address bar will not work because the URL there does not have the "state" information you would like to share.  At first glance, it seems impossible.

Fortunately, since 21.0.1, ICP4BA Business Application has provided two very useful JavaScript APIs that you can use in your View to implement this feature in your Business Application.   The two APIs are:
  1. context.getAddressableUrl(appState, withPageId)
  2. context.subscribeAppState(callback)
The two APIs work hand in hand together and you will need to use both in the Views to implement the addressable feature of your Application. 

The first API getAddressableUrl allows you to obtain an addressable URL with state information "appState" burnt in to the URL.  Note it is very important that you do not put confidential, personal, or sensitive information in the "appState" object as the whole object will be serialized out to be part of the URL as query parameter.  Also, keep in mind that there is always limit in URL length of different browser, so it will be wise to keep the "appState" info as simple as possible.  You can also get the URL with page id in it by setting the second parameter to true so that the Application can be loaded back to a specific page.  This is especially useful with Application that takes advantage of Navigation bar feature.  However, by instructing the Application to start in a specific page will skip all the steps before that page step, so make sure your page can be properly loaded on its own.

The second API allows your View to register a handler to react with the presence of an appState.  Once you get the state back in your handler function, you can restore your page with the state info.

The following is an example of how to use this two APIs in View to achieve the requirement.  The sample on-boarding Application has two pages, one search page and one candidate details page:

Assume I would like to allow the end user to share the Application URL to another user so that the second user can start the Application in the "Candidate Details" page with the selected candidate information from the first user.  First, I can create a View to allow user to copy the addressable URL.  In this example, the View contains just a button and a display text field:

The button has a binding to the selected candidate id, while the display text has binding to a variable that holds the current addressable URL.  The onclick event of the button can have a simple implementation like below to populate the addressable URL to the display text field:

The next thing is to update one of the View or create a new View in your page to register a handler function to react to the "appState" when the page is loaded.  In this example here, the handler function will send a boundary event to call an action to retrieve candidate details from the candidate id:

That's it!  Once the above two Views are on the page, the first end user will be able to obtain the addressable URL after a candidate selection:

The end user can then share the URL to other user.  And when the other user use the URL to load the Application, the Application will be loaded from the "Candidate Details" page with the selected candidate's details populated.

You can find the details about the APIs in the knowledge center

I appreciate any comments or feedback, using the comment function below.