1. XPages on IBM Bluemix:
The Dos and Don'ts
(Eme06)
Oliver Busse, We4IT, Germany
#engageug

2. Many Dos, not so much Don‘ts 
2#engageug

3. About me
3#engageug
• Working for We4IT
• Aveedo® Application Framework
• „Bleeding Yellow“ since R4.5
• IBM Champion for ICS
2015 + 2016
• OpenNTF Member Director
@zeromancer1972
www.oliverbusse.com
@we4it
www.we4it.com

4. Agenda
• Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
4#engageug

5. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
5#engageug

6. Prerequisites
• Create an IBM Bluemix account
• Create an XPages NoSQL database service
(i.e. a Domino Server)
• Get the latest* Extension Library from OpenNTF
• Install Extlib on your local Domino Designer to get the
Bluemix plugin
• Setup Bluemix preferences in DDE
6#engageug
*) 9.0.1v16, January 2016

7. Create or login to your Bluemix account
7#engageug

8. XPages NoSQL database service
• Add a service
• Scroll down to „Bluemix Labs Catalog“
• Find „XPages NoSQL Database“
8#engageug

9. Additional steps (not described here)
• Open the XPages NoSQL Database service properties
page
• Grab the user ID to access the Bluemix Domino
instance
• slaney/Bluemix (USA)
• langan/Bluemix (UK)
• coming soon: CAN and AUS
• Optional: setup additional web users
9#engageug

10. 10#engageug

11. 11#engageug

12. Get the Extlib from OpenNTF
• Download and install it via the updatesite mechanism
• https://extlib.openntf.org/
• https://www.dalsgaard-data.eu/blog/deploy-an-eclipse-
update-site-to-ibm-domino-and-ibm-domino-designer/
• Check Extlib version in DDE and server
12#engageug

13. Bluemix prefs in Domino Designer
• File, Preferences, Domino Designer, IBM Bluemix
13#engageug

14. New IBM Bluemix toolbar control
14#engageug

15. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
15#engageug

16. Design and data separation
• Create the data part on the Bluemix Domino instance
• create a blank database
or
• copy and existing database with data
• Setup ACL etc.
• Keep in mind the additional webusers you may have created
before
16#engageug

17. Setup local dev environment
• Separate data and design also on your local
environment
• Find and modify ALL static references to „database“ on
every XPage, Custom Control and Code
• Document data sources
• View data sources
17#engageug

18. Compute „database“ references
• Utilize the bluemixContext bean
• comes with the OpenNTF Extension Library since v13
• isRunningOnBluemix()
• findDatabaseName() always returns „tododata.nsf“
• static default filename of the data part on the XPages NoSQL
service
18#engageug
https://www.eu-gb.bluemix.net/docs/services/XPagesNoSQLDatabase/index.html

19. More flexible: use a custom bean
• Compute server and filepath dynamically
• for the local and the Bluemix environment
• Allows a different filename on the XPages NoSQL
service (other than „tododata.nsf“)
• Generic code for „database“ computation for
document, view and repeat data sources
• There is a snippet for you… 
• https://openntf.org/XSnippets.nsf/snippet.xsp?id=daobean-
for-xsp-on-bluemix
19#engageug

20. Examples: the DAO-Bean
20#engageug
<xp:this.data>
<xp:dominoDocument
var="document1"
databaseName="#{javascript:dao.dbpath}"
formName="greeting">
</xp:dominoDocument>
</xp:this.data>
<xp:repeat
id="greetings"
rows="9999"
var="greeting"
indexVar="index">
<xp:this.value>
<![CDATA[#{javascript:dao.getViewEntries("greetings")}]]>
</xp:this.value>
…
</xp:repeat>

21. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Caveats and restrictions
• Tipps & tricks
21#engageug

22. What the DDE Plugin does
• When running for the first time
• It will ask for a local folder
• It will create a copy (or replica) of the XSP part
• It will create a manifest.yml file
• It contacts the Bluemix XSP runtime and uploads the 2 files
• Afterwards
• It updates the local copy / replica
• It modifies the manifest.yml file
• It contacts the Bluemix XSP runtime and uploads the 2 files
22#engageug

23. What the DDE Plugin also does…
• It won‘t display error messages or log outputs during
deployment
• hard to troubleshoot
• Sometimes it may not work when running a second,
third, … time
• DDE restart will solve this problem
23#engageug

24. The CF command line
• CF = Cloud Foundry
• Download and install the command line
• https://github.com/cloudfoundry/cli/releases
• http://docs.cloudfoundry.org/devguide/cf-cli/
• You can create a batch file to accellerate deployment
• Verbose output of any action during deployment
process
• Access to the XSP runtime file system (e.g. for reading
system logs)
24#engageug

25. A simple triplet of commands
• cf api
• use api.bluemix.net or api.eu-gb.bluemix.net
• cf api https://api.bluemix.net
• cf login
• provide username and password
• cf login –u username –p password
• cf push
• will upload your local droplet instantly using the
manifest.yml file
• cf push
• cf push <applicationName>
25#engageug

26. Benefits using the CF command line
• Full control of what‘s being done
• Understand how cloud deployment works
• Create new XSP runtimes and instances on the fly (wait
for it!)
• Deploy plugins and other resources (wait for it!)
26#engageug

27. Disadvantage using the CF command line
• You have to create the local NSF copy / replica
manually
• beware of local encryption!
• You have to type in a console… ;-)
• I recommend using CMDER command line replacement for
Windows
27#engageug

28. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
28#engageug

29. The manifest.yml file
• The manifest.yml file is a simple text file (not even
XML)
• It contains fundamental definitions for the runtime and
the service(s) used
• When using hybrid it contains credentials!
• do not commit the file to a repository!
• Domino Designer Plugin comes with a versatile editor
for the manifest.yml file
29#engageug

30. The manifest.yml editor
• Gives you the basic configuration for a single XSP
runtime application
30#engageug

31. Example: manifest.yml
31#engageug
---
applications:
- name: greets
host: greets
instances: 1
memory: 512M
timeout: 180
buildpack: xpages_buildpack
command: /app/launch_xpages_webcontainer
env:
APP_HOME_URL: /greets_xsp.nsf
APP_PRELOAD_DB: greets_xsp.nsf
services:
- IBM XPages NoSQL Database-UK
= custom setting
= default setting

32. Did you know?
• The manifest.yml file can deploy more than one
application to the XSP runtime 
• APP_PRELOAD_DB: xsp1.nsf, xsp2.nsf, xsp3.nsf
• By setting values manually you can modify and / or
create new XSP runtimes, e.g.
• scaling instances and memory
• setting up new XSP runtimes and hosts
32#engageug

33. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
33#engageug

34. Experiment: data in the XSP runtime
• This is not supported!
• This may work flawlessly, but don‘t rely on it
• Maybe useful for configurations, not for production
data
• XSP Runtime is a slim Domino environment, so
everything is possible regarding data
• Faulty behavior of pager
34#engageug

35. Pros and cons
+Direct and fast access to commonly used data sets (e.g.
application and user profiles)
+No data separation necessary
+No changes needed in an existing application
- Data will be overwritten
- every time you re-deploy
- every time you re-scale the application
- every time the runtime restarts
35#engageug

36. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
36#engageug

37. Security considerations
• You have to manage at least two ACLs
• XSP Runtime (design part)
• XPages NoSQL service (data part)
• Design part
• manage Anonymous access only to force a login page
• Data part
• Manage ACL corresponding to the user ID and web users you
may set up in the XPages NoSQL service
• Other known ACL rules such as user roles apply here
• You can lock yourself out from that ACL – be careful, Full
Access Admin is NOT available to unlock!
37#engageug

38. Locked out from data NSF?
• Deleting and re-creating the service has no effect, NSFs
will re-appear!
• You have to contact IBM support for unlocking or
deleting the NSF!
38#engageug
• Locked out from design NSF?
• remove the runtime and re-deploy – phew!

39. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
39#engageug

40. Imagine…
• to use your favorite extensions even on IBM Bluemix
• to enrich your application with genius software like the
OpenNTF Domino API or the XLogger
• You can do this!
40#engageug
+

41. Using plugins: preparation
• Create a folder „shared-plugins“ in the local
deployment folder
• Download the plugin or extension, unzip it
• Locate the updatesite version of the plugin
• Copy the content of the plugins folder into the
“shared-plugins” folder (.jar-files)
41#engageug

42. Using plugins: deployment
• Deploy the application (cf push)
42#engageug

43. • Prerequisites
• Best practices: design and data separation
• Using the DDE plugin vs. the CF command line
• Understanding the "mysterious" MANIFEST.YML file
• Experiment: holding data in the XSP runtime
• Security considerations
• Plugins and extensions? No problem!
• Tipps & tricks
43#engageug

44. Using the XPages Toolbox
• Versatile profiling tool for performance monitoring
• Available on OpenNTF for on-premises use
• https://www.openntf.org/main.nsf/project.xsp?r=project/XP
ages%20Toolbox/
• Setup automatically by modifying the manifest.yml file
• Add this to the ENV section:
• APP_INCLUDE_XPAGES_TOOLBOX: '1'
44#engageug

45. XPages Toolbox (Profiler)
45#engageug

46. Grant restricted access of the JVM
• Like in on-premises environments you may want to
enable full access for the JVM when using e.g. Java
reflections.
• Instead of setting the java.pol file you simply add this
to the manifest.yml ENV section
• APP_JAVA_POLICY_ALL_PERMISSION: '1‘
• Keep in mind that this may be a security issue
46#engageug

47. Verbose mode while deploying
• When using the CF command line the following added
to the manifest.yml file will deliver detailed messages
during the deployment
• APP_VERBOSE_STAGING: '1'
47#engageug

48. Don‘t want to type?
• Use the editor to set those up ;-)
48#engageug

49. Missing view icons
• When using view icons in XPages view panels the icons
are missing
• They won‘t be displayed even if you use
@ViewIconUrl SSJS function
• However, you can add them manually 
49#engageug

50. View icons: lost but found
• Open the deployment folder of the XSP part
• Create the folder notesdata/domino
• Copy the folder <NotesData>/domino/icons to it
• The folder will be published to the XSP runtime
• The view icons will re-appear!
50#engageug

51. Q & A
51#engageug

52. Thank you!
Special thanks to:
• Tony McGuckin, Martin Donnelly, Brian Gleeson
(IBM Ireland Labs, XPages and Bluemix Dev Team)
• Pete Janzen
(IBM, Sr. Product Manager, IBM Enterprise Social Solutions)
52#engageug

53. Resources
• https://openntf.org/XSnippets.nsf/snippet.xsp?id=daobean-for-xsp-on-Bluemix
• http://notesx.net:8090/obusse/Greets
• http://greets.eu-gb.mybluemix.net/
• http://cmder.net/
• https://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20Toolbox/
• http://oliverbusse.notesx.net/hp.nsf/blogpost.xsp?documentId=10C2
53#engageug