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

1. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
XPages on IBM Bluemix:
The Dos and Don'ts
Oliver Busse, We4IT GmbH

2. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
„Many Dos, not so much Don‘ts“ 

3. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
About me
• Working for We4IT
–Aveedo® Application Framework
• „Bleeding Yellow“ since R4.5
• IBM Champion for ICS
2015 + 2016
• OpenNTF Member Director
@zeromancer1972
@we4it

4. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

5. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

6. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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
*) 9.0.1v16, January 2016

7. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Create or login to your Bluemix account

8. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
XPages NoSQL database service
• Add a service
• Scroll down to „Bluemix Labs Catalog“
• Find „XPages NoSQL Database“

9. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Additional steps
• 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

10. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug

11. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug

12. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

13. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Bluemix prefs in Domino Designer
• File, Preferences, Domino Designer, IBM Bluemix

14. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
New IBM Bluemix toolbar control

15. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

16. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

17. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

18. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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
https://www.eu-gb.bluemix.net/docs/services/XPagesNoSQLDatabase/index.html

19. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

20. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Examples: the DAO-Bean
<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. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

22. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

23. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

24. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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)

25. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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>

26. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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!)

27. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

28. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

29. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

30. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
The manifest.yml editor
• Gives you the basic configuration for a single XSP runtime
application

31. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Example: manifest.yml
---
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. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Did you know?
• The manifest.yml file can deploy more that 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

33. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

34. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

35. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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

36. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

37. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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!

38. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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!
• Locked out from design NSF?
• remove the runtime and re-deploy – phew!

39. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

40. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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!
+

41. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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)

42. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Using plugins: deployment
• Deploy the application (cf push)

43. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
• 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

44. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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/XPages%20
Toolbox/
• Setup automatically by modifying the manifest.yml file
• Add this to the env section:
– APP_INCLUDE_XPAGES_TOOLBOX: '1'

45. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
XPages Toolbox (Profiler)

46. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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
– APP_JAVA_POLICY_ALL_PERMISSION: '1‘
• Keep in mind that this may be a security issue

47. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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'

48. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Don‘t want to type?
• Use the editor to set those up ;-)

49. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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 

50. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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!

51. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
Q & A

52. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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)

53. XPages on IBM Bluemix: The Do‘s and Don‘ts
www.ics.ug #icsug
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