Bluemix™ and Designer Use Case 2 - Designer to Bluemix™

Existing XPages applications initially created in Domino® Designer can be pushed to (deployed) and hosted on the Bluemix site to take advantage of the application development options offered by Bluemix.

About this task

Existing XPages applications typically contain both the application design and the data in the form of documents. This is not compatible with the Bluemix model of separating the back-end data from the application design.

To safely host an existing XPages application that was initially created in Domino® Designer on Bluemix, the application must be split into two distinct parts:

a runtime to provide the visual aspects of the application
a service to persist the data

Any data that is stored in the runtime is lost if it is restarted manually or for load-balancing purposes. Having a distinct runtime also allows the application to be scaled by increasing the number of instances.

The following general steps must be done in order to take an existing application that was created on Domino® Designer and push it to Bluemix to be hosted. The sections that follow provide additional details on how to complete these steps.

Procedure

Create a XPages NoSQL Database service instance and prepare Designer.
Split the existing application into design and data elements
Replace all data references in the design application.
Copy the data application to the service-provided Domino® Server.
Deploy the design application to Bluemix.

Creating an XPages NoSQL Database service instance and prepare Designer

About this task

Use the following steps to create an XPages NoSQL Database service instance and prepare Designer for the push to Bluemix.

Procedure

In the Bluemix Dashboard, create an instance of the XPages NoSQL Database service and leave it unbound.
In the Services section of the Dashboard navigation bar, click on the instance of the XPages NoSQL Database service.
Click Launch.
The XPages NoSQL Database Service Dashboard opens in a new browser window and displays your credentials.
Click the ID Download link to save your credentials locally and then record the server and database name and location. Note that you need to know the database name so you can overwrite it in a later step.
Create a connection document. Refer to the XPages NoSQL Database Service documentation on the Bluemix site for more information on how to do this.

Splitting the XPages application into design and data elements

About this task

As mentioned earlier in this topic, you must split the application into design and data pieces to make it ftt the Bluemix model. Use the following steps to complete this task:

Procedure

Open Designer and log in using your regular Notes® ID.
Open the application that you want to split.
Right-click on the application in the Applications Navigator and select Application > New Copy to create a duplicate of the application. Name one copy myapp_design.nsf and the other copy myapp_data.nsf.
The applications appear in the Applications Navigator.
Right-click on the design application in the Applications Navigator and select Application > Access Control.
The Access Control dialog box opens.
Click Add to create a new user. Enter the name as the user name generated by the XPages NoSQL Database Service Dashboard.
Select Designer from the Access drop-down menu and click OK.
Repeat steps 4-6 (in this task) on the data application.
Switch to the service-provided Notes® ID by clicking File > Security > Switch ID.
Select the downloaded ID file and click Open. When prompted, enter the password that was generated by the XPages NoSQL Database Service Dashboard.
Double-click both applications in the Applications Navigator to reopen them.
In the data application, delete all XPages and Custom Controls. You can also delete unnecessary design elements such as .css files and images.
In the design application, delete all Forms and Views.
Right-click on the data application in the Applications Navigator and select Application > Sign Design. Click OK.
Repeat the previous step on the design application.

Replacing all data references in the design application

About this task

The next task is to replace all data references in the design application. Use the bluemixContext object when you reference the data application from the design application. Refer to this topic for more information on working with the bluemixContext object.

You can use the isRunningOnBluemix method to point your design application to a local copy of the data application when you run the application locally. Then, you can test the application before deployment to Bluemix. Use the following steps to complete this task

Procedure

Open the design application.
Search the XPages in your application for all occurrences of <xp:dominoDocument> and adjust them using the bluemixContext object as follows:
1. Search the XPages in your application for all occurrences of <xp:dominoView> and adjust them using the bluemixContext object as follows:
```
<xp:dominoView databaseName="#{javascript:bluemixContext.isRunningOnBluemix()? 
bluemixContext.getDataService().findDatabaseName() : 'myapp_data.nsf'}">
```
2. Adjust XPages controls and tags with a databaseName property as previously stated.
  For example, dominoViewListTreeNode and dominoViewEntriesTreeNode.
Search for occurrences of @DbName in your code and decide whether to reference the design or data application. If you choose to reference the data application, replace the reference with bluemixContext methods: var one = @Unique(@DbColumn(@DbName(),"xspFiltersView",1)); changes to
```
var one = @Unique(@DbColumn(bluemixContext.isRunningOnBluemix()? 
bluemixContext.getDataService().atDbName():@DbName,"xspFiltersView",1));
```

Search for all occurrences of database in your code and decide whether to reference the design or data application. If you choose to reference the data application, replace the reference with bluemixContext methods: database.getViews() changes to

if( null == requestScope.dataServiceDatabase) {
 if (bluemixContext.isRunningOnBluemix()) {
  var otherDatabaseVector = bluemixContext.getDataService().atDbName();
  var otherDatabaseServer = otherDatabaseVector.get(0);
  var otherDatabaseAppPath = otherDatabaseVector.get(1);
  var otherDatabase = session.getDatabase(otherDatabaseServer,otherDatabaseAppPath);
  requestScope.dataServiceDatabase = otherDatabase;
 } else {
  requestScope.dataServiceDatabase = session.getDatabase(null, "myapp_data.nsf");
 }
} 

requestScope.dataServiceDatabase.getViews();

Copying the data application to the service-provided Domino® Server

About this task

The next task is copy the data application to the service-provided Domino® Server. Use the following steps to complete this task.

Procedure

Right-click on the data application in the Applications Navigator and choose Application > New Copy.
The Copy Application dialog box appears.
In the Server field, enter the Domino® Server name that was generated by the XPages NoSQL Database Service Dashboard.
In the File name field, change the NSF name to the one generated by the XPages NoSQL Database Service Dashboard.
Click the folder button next to the File name field.
The Select Folder dialog box appears.
Browse to the path generated by the XPages NoSQL Database Service Dashboard and click Select.
The Select Folder dialog box closes.
In the Copy Application dialog box, click OK.
A dialog box appears to confirm that you want to replace the existing database.
Click Yes.
The data application is copied to the service Domino® Server and is now available for use.

Deploying (pushing) the design application to Bluemix

About this task

The last task in this process is to deploy (push) the design application to Bluemix. When this is accomplished, the Bluemix site will be hosting your application. Follow these steps accomplish that task:

Procedure

Open the design application in Domino® Designer.
Select the application in the Applications Navigator and click the Deploy to IBM Bluemix button in the toolbar.
The Configuration Wizard appears.
Choose a new deployment directory, the organization, and space where you created the service, and on the last page choose to create a new application. Enter the application name and click Finish to close the wizard and configure the application.
In the Applications Navigator, choose Application Configuration > IBM Bluemix Manifest to open the advanced Bluemix configuration options.
In the Bound Services section, click Choose.
The Services dialog box appears.
Select the service that you want to bind and then click OK.
The dialog closes.
Click Save to save the Bluemix configuration.
Click the Deploy to IBM Bluemix button in the toolbar and select Deploy Application.
Designer copies your modified application to the deployment directory, and the application is pushed to Bluemix. Your application stops, restages, and restarts on Bluemix. This process takes a few minutes and a success dialog box appears when complete.
To open the application in a browser, select the application in the Applications Navigator. Click the Deploy to IBM Bluemix button in the toolbar and select Open in Default System Browser.

When your application is deployed, you can use the other available services in Bluemix to make your application more powerful. For more information, see Adding a service to your application topic in the Bluemix site documentation.

What to do next

Once your application has been deployed to Bluemix, you can still import it from the Bluemix site into Designer to make local modifications. Refer the this topic for more information on how to do this.