Integrating a custom Domino database into IBM Digital Experience

Integrating a custom Domino database into
IBM Digital Experience
using the Digital Data Connector
Kai Brennenstuhl
[email protected]
December, 2015
This article is about the integration of a custom IBM Domino database into IBM Digital
Experience (DX). Besides the IBM Web Content Manager (WCM) the capabilities of the
Digital Data Connector (DDC) are used. This article starts with outlining the integration
options. After that a sample implementation follows. This demonstration is divided into two
parts. Part one shows the integration of a sample database. A custom DDC plugin
implementation is provided that connects to the database using the Java API of the Domino
server.
Part two connects to the same database. However, the REST service of the Domino server as
well as the DDC JSON profile is used for integrating the data.
In addition the Credential Vault is used to store necessary credentials. Moreover both
solutions support a paging mechanism which splits up the data requested from the Domino
server.
1
Table of Contents
Preliminary Considerations..................................................................................................................3
The role of the Digital Data Connector...........................................................................................3
Domino connection data..................................................................................................................3
Presentation templates.....................................................................................................................4
Personalization Components............................................................................................................4
HTML Details View Link................................................................................................................4
Alternative Domino Connections....................................................................................................5
Domino Java API and custom DDC plugin................................................................................5
Domino REST API and JSON DDC plugin................................................................................5
Paging..............................................................................................................................................5
Common Setup instructions.................................................................................................................6
Install sample Domino database......................................................................................................6
Install and deploy paa......................................................................................................................7
(Optional) Setup shared Credential Vault Slot.................................................................................7
Part 1 - Using the Java API of the IBM Domino Server......................................................................9
Setup Domino Server.......................................................................................................................9
Activate and start Domino IIOP service.....................................................................................9
Setting Domino host, database location and access credentials..................................................9
Details of WCM items...................................................................................................................11
Content......................................................................................................................................11
Presentation Templates..............................................................................................................11
Components..............................................................................................................................13
Personalization Components................................................................................................13
HTML – Domino Document Details Link...........................................................................13
Java Implementation .....................................................................................................................14
Paging........................................................................................................................................14
Extension Points and profile.properties....................................................................................15
Extracting attributes from BeanListRequest.............................................................................16
Part 2 - Using the REST Service of IBM Domino Server.................................................................18
Setup instructions...........................................................................................................................18
Activate the Data REST service on the IBM Domino sever.....................................................18
Setup the Ajax proxy configuration..........................................................................................18
Edit WCM “Domino Connection Details” content item...........................................................19
WP ListRenderingProfileService Configuration...........................................................................20
Details of WCM items...................................................................................................................22
Presentation Templates..............................................................................................................22
Personalization components......................................................................................................22
HTML Components..................................................................................................................23
Removing the DDC Domino Sample PAA........................................................................................24
2
Preliminary Considerations
A use case of Digital Experience is the integration of data from different applications in one portal.
A Domino database can be one source which can be integrated into Digital Experience. One option
to integrate the Domino database is developing a custom portlet. This might be time consuming and
a lot of development activity is required. Another option is leveraging the capabilities of the Digital
Data Connector framework. This article shows how to use DDC to integrate a custom Domino
database into DX.
The role of the Digital Data Connector
The Digital Data Connector (DDC) framework helps rendering data from external sources within
IBM Web Content Manager components. Therefore this article uses DDC to integrate the data from
a Domino database into Digital Experience. The benefit is that the external data i.e. the information
from the Domino documents is styled with WCM so that for visualization of this data the same
workflow and consistent design templates can be used like in other WCM components within DX.
On the one hand DDC renders the overview over the documents from the Domino database. This
overview shows the most important information of each document like for example the subject of
each document. On the other hand a details view is rendered by DDC too. This view displays all
properties of a single Domino document. Because DDC renders a list of items, for the details view a
list containing only one item i.e. a single document is rendered.
Furthermore a list rendering profile describes which properties i.e. fields the Domino document
contains.
Domino connection data
To connect to the Domino database following information is required:
•
•
•
•
Domino host
Database name and path on the Domino host
Domino view that is accessed
optional: username and password necessary for accessing the Domino database
In the following example a WCM content element stores this information. The benefit is that within
other WCM items it is possible to access this information. For the integration using the JSON REST
API this means no additional Java code needs to be deployed. Moreover, the information can be
changed during run time. However, the username and password necessary for accessing the Domino
database are stored in the Credential Vault of IBM WebSphere Portal. There the password is saved
but still can be included in the requests that connect to the Domino host. To reference the Credential
Vault its ID is added to the other properties in the WCM content item. In case the database is moved
to another server or the credentials for accessing the database are changed the values of the WCM
content item respectively the Credential Vault values can be changed easily. If the database allows
anonymous access the Credential Vault can be omitted.
3
Presentation templates
The presentation templates are used to initialize the list rendering context of the DDC plugin. This
means they contain a Plugin:ListRenderingContext WCM tag which sets
1. the extension ID of the DDC plugin i.e. defines which plugin is used. For a custom
implementation this is equal to the return value of the getExtensionID method of the
implementation of the BeanListProvider listed in the plugin.xml
2. attributes containing the Domino host, database location and the name of the Domino view
that needs to be accessed
3. optionally an attribute containing the Credential Vault ID where the Domino server access
credentials are stored
The values of the attributes mentioned in 2. are referenced indirectly since they are saved in a WCM
content item. Furthermore, the presentation templates include the personalization component which
renders the BeanListResponse returned by the DDC plugin.
Personalization Components
The personalization component renders the list of items provided by the DDC plugin. A
personalization component consists of the three sections: header, result design and footer. Within
the result design AttributeResource tags render the properties of the ResourceBean. In the
sample used in this article these are the fields of the Domino document.
HTML Details View Link
The result design of the personalization component which renders the list of documents contains an
HTML component that creates the link to the details view. This details view is a separate page.
Therefore the Plugin:RenderURL WCM tag, that is used to create this link, contains the uri
attribute which contains the unique page name of the details view. Moreover, a public render
parameter is set that contains the id of the document which should be displayed.
4
Alternative Domino Connections
There are two alternative ways to connect the Domino server. One is using the Domino Java API
however a custom DDC plugin is required for that. The other alternative uses the JSON DDC
plugin and connects to the Domino server via its REST API.
Domino Java API and custom DDC plugin
The advantage of using the Domino Java API is that the data from the Domino database can be
modified before displayed in DX. For example different fields can be aggregated or additional
values can be computed. The disadvantage compared to using the JSON REST API is that Java
programming skills are necessary. A custom DDC plugin needs to be developed which uses the
Domino Java API and provides the bean list rendered by DDC. The effort of the Java
implementation is higher compared to using a standardized REST API.
Domino REST API and JSON DDC plugin
In this part an alternative way of integrating a custom Domino database is demonstrated. The
benefit of this solution is that no Java Code needs to be written for the DDC plugin. The reason for
that is that it leverages the built-in DDC JSON plugin. A list rendering profile is still needed to
describe the structure i.e. the fields of the Domino database. The following example shows how to
use the WP ListRenderingProfileService resource environment provider to maintain this
profile. Furthermore, an Ajax proxy configuration entry needs to be added to access the Domino
database server.
Paging
In order to request only the information from the documents that are displayed paging needs to be
implemented. This means an offset and page size parameter are included into the requests to the
custom DDC plugin implementation which calls the Domino Java API. The same is true for the
Domino REST API a start and count1 parameter determine which documents are requested from the
database. The specific paging implementation is described in the following example.
1 http://www-10.lotus.com/ldd/ddwiki.nsf/xpAPIViewer.xsp?
action=openDocument&res_title=Specifying_a_request_URL_with_IBM_Domino_Access_Services_das901&cont
ent=apicontent
5
Common Setup instructions
These setup instructions describe how to install the Domino database on which this article is based
on. The sample database is a shopping list storing 20 documents that have fields like name, count,
location, price, date and comments.
In addition to that config tasks show how to import the Portal Application Archive which comes
with in this article. Furthermore the setup of the Credential Vault in DX is described. That step is
necessary to access restricted Domino databases.
Install sample Domino database
1. Copy the ShoppingList.nsf into your data directory of your Domino server
2. Restart your sever
3. Optional: After you import the Domino database you might want to restrict access.
(a) Select the application in the Domino Admin, right click and go to Access Control →
Manage (Figure 1).
Figure 1: Manage Access Control
(b) Select the Default user and set the Access attribute to No Access (Figure 2).
Figure 2: Access Control List assistant
(c) Select your user (you might need to add the user entry first) and assign Manager access.
You can add a further user for read access only. This user can be used later to access the
Domino server. However, one user in the Access Control List needs to have Manager access
assigned.
(d) To save your changes in the access control list, click OK.
6
Install and deploy paa
To install and deploy the DDC Domino Sample PAA package run the following commands:
1. wp_profile_root/ConfigEngine/ConfigEngine.sh install-paa
-DPAALocation=path_to_DDCDominoSample.paa -DWasPassword=password
-DPortalAdminPwd=password
2. wp_profile_root/ConfigEngine/ConfigEngine.sh deploy-paa
-DappName=DDCDominoSample -DWasPassword=password -DPortalAdminPwd=password
If you deploy to a virtual portal, you need to include the context root or host name parameters for
the virtual portal. Add the -DVirtualPortalHostName or -DVirtualPortalContext
parameters to the deploy-paa task. For example:
wp_profile_root/ConfigEngine/ConfigEngine.sh deploy-paa
-DappName=DDCDominoSample -DvirtualPortalContext=vp1 -DWasPassword=password
-DPortalAdminPwd=password
Note: If the package has been installed to a WebSphere Portal server once you don't need to run the
install-paa task again. Instead only run the deploy-paa task again to deploy the package to
a different virtual portal.
At the end of this article it is described how you can uninstall and remove the paa again.
(Optional) Setup shared Credential Vault Slot
This step is only necessary if anonymous users cannot access your database.
(ShoppingList.nsf has no access restrictions unless applied like described above)
The user name and password for accessing the Domino database are stored in the Credential Vault
of DX.
1. Login as administrator into Digital Experience.
2. Open the portal administration and select Access → Credential Vault. Select the Add a vault
segment option (Figure 3).
3. Enter a vault segment name for example Domino Segment. To create the vault segment
click the OK button.
4. Select the Add a vault slot option.
5. Enter a vault slot name e.g. DominoSlot (this is the Vault Slot Id) (Figure 4)
Do not use a space nor a special character in the slot name.
6. Create a new vault resource by selecting the radio button new.
7. Enter a resource name e.g. Domino Resource
8. Check the Vault slot is shared box and enter the Domino user name and password that is
required to connect to the Domino database. Confirm your information by clicking on the
OK button.
Now you have set up a Credential Vault Slot. For further information about the Credential Vault
read Using credential vault to provide single sign-on for portlets by Konduru2.
2 http://www.ibm.com/developerworks/websphere/library/techarticles/0211_konduru/konduru.html#N102DD
7
Figure 3: Credential Vault in DX administration menu
1.
2.
3.
4.
5.
Figure 4: Add a vault slot form
8
Part 1 - Using the Java API of the IBM Domino Server
In part one the sample database (ShoppingList.nsf) is integrated into DX using a custom
DDC implementation which connects to the Domino server through the Domino Java API.
In this sample the documents of the database are presented on two pages in DX. One page shows an
overview over the documents of the Domino database i.e. a list of documents. Whereas the other
page serves as details view and displays one single document with its properties. The underlying
DDC implementation is separated similarly. There are two list rendering profiles, one for the list of
documents while the other provides access to the properties of a single document that was selected
in the list.
Setup Domino Server
Activate and start Domino IIOP service
In order to use the Java API on the Domino server the Domino IIOP service has to be loaded and
configured correctly. If the Domino IIOP service is not running start it by executing the load
diiop command in the IBM Domino Console. For further information how to set up the DIIOP
service on your Domino server read section Administration in the article about Java access to the
Domino Objects, Part 13. This section explains also on which port the DIIOP service runs. You will
need this information later.
Setting Domino host, database location and access credentials
The Domino connection details i.e. Domino host, database location and Domino view that is
accessed but also the Credential Vault Slot ID are stored in the content item “Domino Connection
Details”.
Follow these steps to configure the content item according to your environment:
1. Log into DX
2. Open the Web Content Authoring portlet
3. Navigate to the “Domino Connection Details” content item in the “DDC Domino Sample”
library.
4. Enter the Domino host where the database is located as well as the database path including
the file name and the Domino view you want to access (Figure 5).
3 http://www.ibm.com/developerworks/lotus/library/ls-Java_access_pt1/#N100DD
9
Figure 5: WCM Content item: Domino Connection Details
5. If your database allows anonymous access leave the Credential Vault Slot Id field empty.
Otherwise enter the vault slot ID you have given in (Optional) Setup shared Credential Vault
Slot.
Now the setup is completed and you can access the “Domino Database” page. Open the site menu
and click on DDC Samples (Figure 6).
1.
2.
Figure 6: Domino Database page
10
Details of WCM items
Content
The DDC Domino Sample library contains three content items. The content item ”Domino
Connection Details”, which you used in the previous step, holds the information for accessing the
Domino server.
The content item “Domino Database” is mapped to the presentation template “PT – Domino
Database” and references the component “PZN – Domino DB” in the list appearance property.
Whereas the content item “Domino Document” is mapped to the presentation template “PT – Single
Domino Document” and references the component “PZN – Details View” in the list appearance
property.
Presentation Templates
In the sample used in this article there are two presentation templates.
The presentation template “PT – Domino Database” initializes the list rendering context for the list
view of the documents in the database. Figure 7 to Figure 9 visualize this relationship between
presentation template, BeanListProvider implementation and plugin.xml. The plugin.xml is
used to register the extension points with the specific implementations of BeanListProvider.
The other attributes of the WCM Plugin:ListRenderingContext tag refer to the attributes
in content item ”Domino Connection Details“ and set Domino host, Domino database location,
Domino view as well as the Credential Vault Slot ID.
The last WCM tag not mentioned yet in the presentation template “PT – Domino Database” is a
component tag which references the personalization component “PZN – Domino Database”.
The presentation template “PT – Single Domino Document” contains almost the same
Plugin:ListRenderingContext WCM tag as the previously described presentation
template “PT – Domino Database”. The only difference is the value of the extension-id attribute.
Whereas “PT – Domino Database” refers to ibm.samples.domino.document.list this
presentation template contains the value ibm.samples.domino.details.view. That's why
this presentation template refers to the BeanListProviderDetailsView.
11
Figure 7: "PT - Domino Database" presentation template
Figure 8: Extension ID property in BeanListProvider
Figure 9: plugin.xml listing BeanListProvider as an extension point
12
Components
Personalization Components
While the personalization component “PZN – Domino DB”
renders the list of all documents the component “PZN – Details
View” renders a list with only one item i.e. a single Domino
document.
In the list presentation markup of the personalization
component it is possible to access the list properties of the
rendered list. These properties are defined in the
implementation of BeanList and made accessible by the
getListProperty(String key) method.
The result design renders the attributes of each list item. In
“PZN – Domino DB” only the name and the serial number are
included. The HTML component “HTML – Domino Document
Details Link”, which is described later, generates a link to the
details view.
The footer section contains paging links (see Paging).
Figure 10: Insert Tag assistant
The “PZN – Details View” renders the properties of a Domino document. The corresponding WCM
tags can be inserted using the Insert Tag button. In the form Insert a Tag the tag type Attribute
Resource needs to be selected as well as Domino Details View as the target component (Figure
10). In the Java implementation the attribute names like “id”, “title” or “name” are implemented in
ResourceBeanDetailsViewImpl which extends the ResourceBeanAdapter.
HTML – Domino Document Details Link
[Plugin:RenderURL pr.mode="set" copyCurrentParams="true"
uri="nm:oid:domino.document" pr.key="sources" pr.type="public"
pr.value="com.ibm.sample.domino.document:[AttributeResource
attributeName='serialNumber' separator=',']"]
Code 1: HTML - Domino Document Details Link Component
The component “HTML Domino Document Details Link” creates the URL to the details view of
each Domino document. This HTML component is referenced in the result design of the
component “PZN – Domino DB”. Code 1 shows that this component contains a
Plugin:RenderURL tag. The value of the parameter with the key sources is an uri scheme
followed by the serial number of the current document. The source uri scheme is defined in
BeanListProviderDetailsView. Moreover the uri parameter contains the unique name
of the Domino Document page (Figure 11) where the link is redirected to. For further information
how to resolve a DDC list item to its details view refer to Resolving a DDC list item to its details
view4.
4 https://ibm.biz/resolving-a-item-to-its-details-view
13
Figure 11: Pages in DDC Sample unique name of page "Domino Document" highlighted
Java Implementation
When importing the source files of the DDC Domino Sample into your IDE you might need to
configure your build path.
Ensure the jar libraries in the folder PortalServer/doc/compile are in your build path.
Furthermore, add NSCO.jar from your Domino installation (installation_folder/
data/domino/java/NSCO.jar).
As already mentioned in the Components section there are two lists rendered in this DDC Domino
Sample. One list contains the Domino documents while the other is used in the details view and
contains a single Domino document with all its properties. The packages
com.ibm.portal.samples.ddc.domino.details.view and
com.ibm.portal.samples.ddc.domino.document.list reflect this separation too.
Moreover, there are two implementations of BeanListProvider as well as two
implementations of ResourceBean, two implementations of BeanResponse and two
implementations of BeanList.
Paging
Although the sample database used in this article does not contain many documents this DDC
implementation supports advanced paging. This means not all documents are fetched from the
Domino database though only the ones which are displayed on the page the user is looking at.
This is the major difference compared to the built in WCM paging component. That component
enables paging too, however only on a rendering basis. In that case still the total list of documents is
requested but only a part of it is displayed. The approach used in this sample fetches only list items
that are currently displayed and therefore can be used when working with lists that contain a high
number of list items.
14
In the footer of the personalization component “PZN – Domino DB” there are references to
components generating the links for paging.
The BeanList which is rendered by the personalization component has list properties that contain
attributes for the document offset, the page size, the number of total documents in the database and
a flag for determining if the last document on the requested document list is the last document of the
database view.
Furthermore, the page size and document offset i.e. the serial number of the first document on the
displayed list are included as URL parameters in the paging links in the footer of the personalization
component. For the previous and first link a minus-sign is added in the WCM attribute in front of
the page size parameter. These parameters are extracted from the request and used for returning a
list of documents fetched from the Domino database (Code 4 & Code 5).
Since with this paging approach only a subset of the total documents is requested and subsequent
requests have to show predictable results it is necessary that the list of all documents is sorted.
Therefore a view containing all documents is accessed using the Domino Java API. The document
offset and page size determine the amount and position of the requested documents (Code 2).
Database dominoDatabase = DatabaseHelper.getDatabase(session);
View v = DatabaseHelper.getDominoView(dominoDatabase);
ViewEntryCollection vc = v.getAllEntries();
ViewEntry ve = vc.getNthEntry(offset);
Code 2: Requesting a document from the Domino database using the offset parameter
When caching is enabled and the Domino database is updated frequently, checks need to be
implemented to invalidate or change the cache key as soon as the requested list of documents has
been changed.
Change the page size
To change the page size the presentation template “PT – Domino Database” needs to be modified.
The references personalization component includes the resultsPerPage parameter. Update the value
of this parameter to change the page size. Furthermore the number component “PageSize” in the
“Paging” component folder has to reflect this change.
Extension Points and profile.properties
The plugin.xml in the src directory lists the three extension points that are plugged into DX. The
first two refer to the bean list providers implementing the list of documents respectively the single
document list. The third extension point refers to the implementation of the
ListRenderingProfileProvider. This provider parses the profile.properties file
which defines the item attributes of the lists provided by the bean list provider. These item attributes
can be selected in the WCM insert tag assistant (see Figure 12). Depending on the database these
properties have to be changed. However changing (adding/removing) a property has the implication
to modify the resource bean implementation i.e. the class extending the
ResourceBeanAdapter. This implementation provides the get methods for the attributes
defined in the profile.properties file.
In this DDC Domino Sample there are two resource bean implementations one is the
ResourceBeanDocumentListImpl containing only the properties shown in the list of
documents while the ResourceBeanDetailsViewImpl contains all properties of the Domino
15
document which are displayed on the details view page.
Figure 12: Insert Tag assistant (left) and profile.properties (right)
Extracting attributes from BeanListRequest
The BeanListRequest contains the attributes and properties set in different WCM tags such as
the Plugin:RenderURL or Plugin:ListRenderingContext tags. Depending on WCM
tag and attribute used different steps are necessary to extract the delivered information from the
Java object.
The setDatabaseParameters (Code 3) method in DatabaseHelper gives an example
how to extract the attributes set in the presentation templates (Figure 7).
public static void setDatabaseParameters(BeanListRequest request) {
[…]
DOMINO_HOST = request.getAttributes().get("DominoHost");
DOMINO_VIEW = request.getAttributes().get("DominoView");
DOMINO_DATABASE_FILE_LOCATION = request.getAttributes().get(
"DominoDatabaseLocation");
CREDENTIAL_VAULT_SLOT_ID = request.getAttributes().get(
"CredentialVaultSlotId");
}
Code 3: setDatabaseParameters from DatabaseHelper.java (logging statements left out)
The URL parameters set in the paging HTML components (Code 4) are extracted differently from
the BeanListRequest (Code 5).
16
[Plugin:RenderURL p1.type="private" p1.mode="set"
p1.key="documentOffset" p1.value="10" p2.type="private"
p2.mode="set" p2.key="pageSize" p2.value="-10"
copyCurrentParams="false" compute="once"]
Code 4: HTML First Link Component
private int getPageSize(Map<?,?> requestParameterMap){
int pageSize = 10;
String pageSizeS = ((String[])requestParameterMap.get(PAGE_SIZE))[0];
pageSize = getIntFromString(pageSizeS);
return pageSize;
}
Code 5: Method in BeanDocumentListResponseImpl to extract page size
Extracting the serial number set in the component “HTML – Domino Document Details View”
(Code 6) works different again because here the sources parameter is used to transport the serial
number from one page to another.
private int getDocumentSerialNumberFromRequest(BeanListRequest request){
int serialNoRequestedDoc = 0;
List<Addressable> sources = request.getListRenderState().getSources();
if (sources != null) {
URI uri = null;
for (Addressable source : sources) {
try {
uri = source.getURI();
} catch (URISyntaxException e) {
[...]
}
if (uri != null) {
//SOURCE_URI_SCHEME=com.ibm.sample.domino.document
if (SOURCE_URI_SCHEME.equals(uri.getScheme())) {
serialNoRequestedDoc = Integer.valueOf(uri.getSchemeSpecificPart());
break;
}
}
}
}
return serialNoRequestedDoc;
}
Code 6: Method in BeanDetailsViewResponseImpl to extract serial number from request
17
Part 2 - Using the REST Service of IBM Domino Server
The following sections describe how to use the REST service of the Domino server as well as the
DDC JSON plugin to integrate the same example database into DX.
Setup instructions
Follow the Common Setup instructions if not already applied.
Activate the Data REST service on the IBM Domino sever
To access the REST service of your Domino server it is necessary that the Data service is enabled
on the server. Read the section Enable your REST service in the article Create your own Domino
REST service using DAS5 for further information on how to enable the Data REST service of your
Domino server. Moreover the Data service needs to be enabled for the database and the view you
want to access. The ShoppingList.nsf does meet these requirements. Slide 26 in REST
services in Domino - Domino Access Services6 shows how to enable the Domino Data service for
your own database and the view of the database.
Setup the Ajax proxy configuration
To access the REST service of your Domino server through Digital Experience you have to set up
an Ajax proxy configuration.
1. Log in as administrator into your WebSphere Integrated Solutions Console
2. Go to Resources → Resource Environment → Resource Environment Providers.
3. Select the WP ConfigService entry and click on Custom properties in the additional
properties section.
4. Click the New button and enter
wp.proxy.config.urlreplacement.digital_data_connector_policy.
json_domino_sample
in the Name field and http://your.domino.server/* as a value.
Figure 13: Setting up the Ajax proxy configuration
5. Click the OK button and in the following dialog on Save
Now you have to restart the Ajax Proxy service.
5 http://www-10.lotus.com/
ldd/ddwiki.nsf/dx/Create_your_own_Domino_REST_service_using_DAS#Enable+your+REST+service
6 https://ibm.biz/domino-access-services-pdf
18
6. In your WebSphere Integrated Solution Console go to Applications → Application Types →
WebSphere enterprise applications.
7. Select the AJAX Proxy Configuration entry and click on the Stop button
8. Select the AJAX Proxy Configuration entry again and click on the Start button
Edit WCM content item “Domino Connection Details”
Similar to part one a WCM content item is used to store the information about Domino host,
database location, database view as well as the ID of the Credential Vault that holds the password
and username that is necessary to access the Domino database.
In the next step you need to enter your Domino Connection details in the WCM content element.
1. Log in DX
2. Go to the library “DDC Domino JSON Sample” and open the content item “Domino
Connection Details” (Figure 14)
Figure 14: JSON Lists: Domino Connection Details
3. Enter the Domino Host you used previously when setting up the Ajax Proxy
4. In the field DominoDatabaseLocation you might need to add the path to the database on
19
your Domino server
5. In the field CredentialVaultSlotId enter the vault slot ID you have used in (Optional) Setup
shared Credential Vault Slot. If you did not set up a Credential Vault and your database as
well as the Domino data REST service can be accessed by the anonymous user leave the
field empty.
6. Click Save and Close.
Now you can open the Domino JSON page. Go to your site menu and open the DDC Samples
section there you can navigate to the Domino JSON page (Figure 15).
1.
2.
Figure 15: Domino JSON page
WP ListRenderingProfileService Configuration
When deploying the PAA a new list rendering profile is installed. The properties of this profile can
be displayed, changed or also created in the WebSphere Integrated Solution Console.
1. Login as administrator into the WebSphere Integrated Solution Console
2. Go to Resources → Resource
Environment → Resource
Environment Providers.
Select the WP
ListRenderingProfileService entry
and click on Custom properties in the
Figure 16: Properties of list rendering profile
additional properties section.
3. Scroll down until you see the entries
starting with domino.
Figure 16 shows the extension-id of the list rendering profile that is defined here as well as the type
of the profile. Within WCM the profile name value appears in the profile attribute of the
Plugin:ListRenderingContext tag in the presentation template (Code 7).
The entries that contain ItemAttribute (Figure 19) in their name are shown in the Insert a tag
assistant (Figure 18) and relate to the JSON properties of the Domino data REST service JSON feed
(Figure 17).
Depending on the fields of the database the list rendering profile needs to be adjusted. This means
new property entries have to be added to the WP ListRenderingProfileService or
existing once need to be modified.
20
{
"@href":"http:\/\/localhost:80\/ShoppingList.nsf\/api\/data\/col
lections\/name\/all\/unid\/95A8ED5884491995C1257EFB0050A5E2",
"@link":
{
"rel":"document",
"href":"http:\/\/localhost:80\/ShoppingList.nsf\/api\/data\/docum
ents\/unid\/95A8ED5884491995C1257EFB0050A5E2"
},
"@entryid":"12-95A8ED5884491995C1257EFB0050A5E2",
"@unid":"95A8ED5884491995C1257EFB0050A5E2",
"@noteid":"922",
"@position":"12",
"@siblings":20,
"@form":"Item",
"Name":"bread",
"Count":1,
"Location":"bakery",
"Comments":"a fresh bread",
"Price":"2",
"Date":"2015-11-19T16:00:56Z"
}
Figure 17: Snippet from the response of the Domino data REST service
Figure 18: Insert a Tag form showing the
Domino JSON list rendering profile
Figure 19: ItemAttribute properties of the list
rendering profile
21
Details of WCM items
Similar to part 1 there are two presentation templates and two personalization components. One
template respectively component renders the list of all documents while the other shows the
properties of a single document.
Presentation Templates
The “JSON List” presentation template initializes the ListRenderingContext of the list view.
In Code 7 the extension-id as well as the profile attributes are highlighted. The later one is equal to
the name visible in the WP ListRenderingProfileService properties (Figure 16). The
attribute starting with source defines the JSON REST service URL of the Domino server. This
request includes values from the WCM content item “Domino Connection Details”, which has been
set up previously. In addition to this a private Plugin:RenderParameter which is set by the
paging components is read in order to set the correct offset of the requested document list.
[Plugin:ListRenderingContext action="set" extensionid="ibm.portal.ddc.json" profile="sample.domino.profile.json"
attribute="source=..."]
Code 7: Plugin:ListRenderingContext of the JSON List presentation template
The last tag in this presentation template is a component tag and references the personalization
component “PZN – JSON List”.
The “JSON Details View” presentation template is structured similarly. However the URL for the
JSON REST service is constructed differently since only a single document is requested and not a
list of documents. Furthermore, the personalization component “PZN – JSON Details View” is
referenced at the end which renders the properties of a single document.
1. http://localhost/ShoppingList.nsf/api/data/collections/name/all
?start=5
2. http://localhost/ShoppingList.nsf/api/data/documents/unid/...
Figure 20: Requests to the Domino Data REST service API
Figure 20 shows two different HTTP requests using the Domino Data REST service API. The first
request URL contains the file name ShoppingList.nsf. It requests documents from the view
all starting with the sixth document (the parameter start is zero based). However, the second
request fetches a single document (the unique ID is left out for readability reasons).
22
Personalization components
The personalization component“PZN – JSON List” renders the list of documents. In the result
design there are AttributeResource tags. The attribute names of these tags are defined in the
WP ListRenderingProfileService property (Figure 19).
Moreover two request attributes are set which are read in the paging links referenced in the footer.
These request attributes are overwritten for each list item so that only the values of the last list item
are used. This solution was chosen because the JSON feed provided by the Domino server does not
have properties in the root element itself but only in the objects within the root array.
The footer of the personalization component includes the HTML components that generate the
paging links.
The personalization component “PZN – JSON Details View” renders only one list item. However,
in contrast to the personalization component “JSON List” all properties of the list item are rendered.
Therefore more AttributeResource tags are used in the result design of this personalization
component.
HTML Components
There are three HTML components creating the <a href=...> tags for the paging links.
The component “Previous Link” generates the link to go to the page of documents which come
before the currently displayed documents. Like the “Next Link” component this component sets the
private render parameter with the key offset. This render parameter is read in the presentation
template and included in the request to the Domino REST API. Therefore the correct subset of
documents is requested from the Domino server. However, for generating the value of the offset
parameter a custom rendering plugin is called. This plugin is installed during the PAA deployment.
Based on the current position and the page size it returns the offset which is needed to display the
previous page ( previousOffset=currentPosition−2∗ pageSize ).
The HTML component “First Link” removes the offset parameter from the request. The Domino
server REST API provides by default the first documents when the request does not contain a start
parameter.
Moreover, there is an HTML component which generates the link to the details view. Similarly to
part one a Plugin:RenderURL WCM tag is used which sets a public parameter containing the
unique id of the Domino document and the unique name of the Domino JSON Details View page.
[Plugin:RenderURL copyCurrentParams="true"
uri="nm:oid:domino.json.details.view" pr.key="{http://ibm.com}unid"
pr.type="public" pr.mode="set" pr.value="[AttributeResource
attributeName='documentId' separator=',']"]
Code 8: ComponentHTML - Details View
Changing the Page Size
The presentation template “JSON List” needs to be modified to change the page size. Alter the
value of the resultsPerPage parameter in the referenced personalization component. Furthermore,
23
change the component item Page Size in the Paging component folder.
Removing the DDC Domino Sample PAA
To remove the DDCDominoSample PAA package run the following command:
1. wp_profile_root/ConfigEngine/ConfigEngine.sh remove-paa
-DappName=DDCDominoSample -DforceRemove=true -DWasPassword=password
-DPortalAdminPwd=password
2. wp_profile_root/ConfigEngine/ConfigEngine.sh uninstall-paa
-DappName=DDCDominoSample -DforceUninstall=true -DWasPassword=password
-DPortalAdminPwd=password
To remove the package from a virtual portal, you need to include the context root or
host name parameters for the virtual portal. Add the -DVirtualPortalHostName or
-DVirtualPortalContext parameters to the remove-paa task. For example:
wp_profile_root/ConfigEngine/ConfigEngine.sh remove-paa
-DappName=DDCDominoSample -DforceRemove=true -DvirtualPortalContext=vp1
After running the uninstall-paa task and removing the assembly from the ConfigEngine
registry, the PAA content remains in the PAA directory. To remove any remaining content run the
delete-paa command. This command inspects the PAA directory and removes content that is
not registered.
wp_profile_root/ConfigEngine/ConfigEngine.sh delete-paa
-DassemblyList=DDCDominoSample -DWasPassword=password
-DPortalAdminPwd=password
24