rhoconnect 3.1.2 → 3.2.0.beta1

data/doc/public/cli.txt

@@ -0,0 +1,191 @@
+Generating a RhoConnect Application
+===
+
+You can generate a RhoConnect app with RhoStudio or with the `rhoconnect` utility command line tool.
+
+## Generating a RhoConnect App with RhoStudio
+
+In RhoStudio, select File->New->Project...
+
+The New Project window opens. Select the RhoConnect application wizard and click the Next button.
+
+<img src="http://rhodocs.s3.amazonaws.com/rhoconnect-tutorial/new-project-rhoconnect.png"/>
+
+Enter the name for your RhoConnect application in Project name. You may specify a specific folder for your destination where your project is stored, by default, the destination is your RhoStudio workspace folder. Then press the Finish button.
+
+<img src="http://rhodocs.s3.amazonaws.com/rhoconnect-tutorial/rhoconnect-application-wizard.png"/>
+
+## Generating a RhoConnect App from the Command Line
+
+The `rhoconnect` utility is a command line tool for generating RhoConnect applications and source adapters.
+
+The app name is passed as a parameter.  The `rhoconnect` utility will generate a directory for your application with all the necessary files to get started.  We will start with running `rhoconnect help app` to see the usage:
+
+	:::term
+	Usage:
+		rhoconnect app NAME
+
+	Generates a new rhoconnect application.
+
+For example:
+
+	:::term
+	$ rhoconnect app storeserver
+	Generating with app generator:
+			 [ADDED]  storeserver/config.ru
+			 [ADDED]  storeserver/settings/settings.yml
+			 [ADDED]  storeserver/settings/license.key
+			 [ADDED]  storeserver/application.rb
+			 [ADDED]  storeserver/Rakefile
+			 [ADDED]  storeserver/Gemfile
+			 [ADDED]  storeserver/spec/spec_helper.rb
+	
+Here's a basic rundown of each of the files that were just generated:
+	
+	
+* **config.ru** - This is a rackup file which will load your application.  RhoConnect uses the excellent [sinatra](http://www.sinatrarb.com/) web framework to run the application.
+* **settings/settings.yml** - This contains settings such as your redis connection, which source adapters exist and their parameters.  You can also put custom settings here.
+* **settings/license.key** - The RhoConnect [license](/rhoconnect/licensing) associated with your application.  The default license allows up to 10 devices to synchronize with the application.
+* **application.rb** - The RhoConnect application class where you can implement authentication.  You can also add other custom methods here to use in your application.  This class is a singleton, so all methods should be added to the `class << self` block.
+* **Rakefile** - This contains tasks that can be run from the terminal.
+* **Gemfile** - This file specifies application's dependencies using [bundler](http://gembundler.com/).
+* **spec/spec_helper.rb** - A helper file which loads the environment for running [specs](/rhoconnect/testing).
+
+After generating the application, you might be asked to change directories to your application directory and run bundle install. For example, you would run these commands:
+
+	:::term
+	$ cd storeserver
+	$ bundle install
+
+## Rake Tasks
+<span class="label label-important">As of version 4.0 of rhoconnect rake tasks will be deprecated!!</span> 
+
+Each RhoConnect application uses [rake](https://github.com/jimweirich/rake) to manage development tasks such as starting/stopping the app, starting resque workers, and running specs.
+
+To run a RhoConnect rake task, simply type `rake the-task-to-run` in your RhoConnect application's root directory.
+
+### Installing DTach (Mac OS / Linux only)
+
+If you're using MacOS / Linux, install [dtach](http://dtach.sourceforge.net/) on your path before running any of the rake tasks.  [DTach](http://dtach.sourceforge.net/) is a simple utility which runs processes in a detached state so you can re-attach your console later.
+
+	:::term
+	$ cd storeserver
+	$ [sudo] rake dtach:install
+
+### Setup Redis
+
+Next, you will need to setup and start a [redis](http://redis.io/) server:
+
+	:::term
+	$ [sudo] rake redis:install
+	$ rake redis:start
+
+The server will show that it is running on the console.
+
+### Start the Application
+
+Open a new console window (since the redis server is running in the previous console window). Then change directories to your rhoconnect applciation and start the application.
+
+	:::term
+	$ cd storeserver
+	$ rake rhoconnect:start
+	
+If everything went well, you should see the following in your console:
+
+	[05:47:10 PM 2011-04-19] Rhoconnect Server v3.0.0 started...
+	
+To open the web console, navigate to [http://localhost:9292/](http://localhost:9292) in your browser or run:
+
+	:::term
+	$ rake rhoconnect:web
+	
+### Creating executable WAR containers (JRuby environment only)
+
+It is possible to create Java WAR containers for your Rhoconnect application that can be deployed into the
+Java App Servers (for example, JBoss). To create the executable WAR container, execute the following command in your app's root directory:
+	
+	:::term
+	$ cd storeserver
+	$ rake rhoconnect:war
+	
+This will build the WAR file named <your_app>.war that can be deployed into the Java App Server.
+
+
+### Common Tasks
+
+RhoConnect applications come with many useful rake tasks for administrative and development workflows.  Some common ones are:
+
+* 	`rake dtach:install` - (Mac OS / Linux only) This will install [dtach](http://dtach.sourceforge.net/) to /usr/local/bin.
+
+* 	`rake redis:install` - This will install to the system.  On Mac OS / Linux, it will attempt to install in '/usr/local/bin' (on windows, C:\redis-<version>), unless you have specified a REDIS_HOME to use instead. 
+If you cannot install redis on Linux due to insufficient user permissions, then follows these [instructions](/rhoconnect/install).
+	
+* 	`rake rhoconnect:set_admin_password` - Set the RhoConnect administrator password.  The default password is blank ''.
+
+*	`rake rhoconnect:get_token` - Get a RhoConnect API token to use for calling the RhoConnect REST API.
+		
+**NOTE: On Mac OS / Linux, you need to install dtach (i.e. by running `rake dtach:install`) to run the following tasks: **
+
+* 	`rake redis:start` - This will launch a redis server in a new console.
+	
+* 	`rake redis:stop` - Stop the currently-running redis server.
+
+*	`rake redis:attach` - (Mac OS / Linux only) Attach to a currently-running redis server.
+
+* 	`rake rhoconnect:start` - Start the RhoConnect application in a new console.  This requires a running redis server.
+
+* 	`rake rhoconnect:stop` - Stop the currently-running RhoConnect application.
+	
+*	`rake rhoconnect:attach` - (Mac OS / Linux only) Attach to a currently-running RhoConnect application. 
+
+* 	`rake rhoconnect:clean_start` - Useful for development, resets and bootstraps the RhoConnect application with a test user.
+
+Some other useful development tasks:
+
+*	`rake rhoconnect:reset` - Reset the RhoConnect application to the initial state.  This WILL DELETE ALL DATA IN REDIS! So be sure you don't run this in production!
+
+*	`rake rhoconnect:spec` - Run all source adapter specs in spec/sources/.
+	
+*	`rake rhoconnect:web` - Open the RhoConnect web console in a browser.
+
+Here is a complete list of the rake tasks available in a RhoConnect application:
+
+	:::term
+	$ cd storeserver
+	$ rake -T
+	(in ~/storeserver)
+	rake dtach:about                    # About dtach
+	rake dtach:install                  # Install dtach 0.8 from source
+	rake redis:about                    # About redis
+	rake redis:attach                   # Attach to redis dtach socket
+	rake redis:download                 # Download package
+	rake redis:install                  # Install the latest verison of Redis from Github (requires git, duh)
+	rake redis:restart                  # Restart redis
+	rake redis:start                    # Start redis
+	rake redis:stop                     # Stop redis
+	rake resque:work                    # Start a Resque worker
+	rake resque:workers                 # Start multiple Resque workers.
+	rake rhoconnect:attach              # Attach to rhoconnect console
+	rake rhoconnect:clean_start         # Clean rhoconnect, get token, and create new user
+	rake rhoconnect:create_user         # Creates and subscribes user for application in rhoconnect
+	rake rhoconnect:delete_device       # Deletes a device from rhoconnect
+	rake rhoconnect:delete_user         # Deletes a user from rhoconnect
+	rake rhoconnect:flushdb             # Flush data store - WARNING: THIS REMOVES ALL DATA IN RHOCONNECT
+	rake rhoconnect:get_token           # Fetches current api token from rhoconnect
+	rake rhoconnect:reset               # Reset the rhoconnect database (you will need to run rhoconnect:get_token afterwards)
+	rake rhoconnect:reset_refresh       # Reset source refresh time
+	rake rhoconnect:restart             # Alias for `rake rhoconnect:stop; rake rhoconnect:start`
+	rake rhoconnect:set_admin_password  # Sets the admin password
+	rake rhoconnect:spec                # Run source adapter specs
+	rake rhoconnect:start               # Start rhoconnect server
+	rake rhoconnect:stop                # Stop rhoconnect server
+	rake rhoconnect:war                 # Build executable WAR file to be used in Java App Servers
+	rake rhoconnect:web                 # Launch the web console in a browser - uses :syncserver: in settings.yml
+
+## Generate Source
+
+Connecting to a backend service with RhoConnect requires that you write a small amount of code for the query, create, update and delete operations of your particular enterprise backend. The collection of the code for these operations is called a source. You can create source for your RhoConnect application two ways:
+ 
+ * [RhoConnect source adapter](/rhoconnect/source-adapters): generate a Ruby code source adapter from RhoStudio or from the command line, similar to how you generate a RhoConnect app. This source adapter contains code for the query, create, update and delete operations.
+ 
+ * [RhoConnect plugin](/rhoconnect/plugin-intro): write the source code (the query, create, update and delete operations) into your backend application, and plug a RhoConnect plugin in the application. The plugin is written in the language that matchs your backend application, such as Java or .NET.

data/doc/push-backend-setup.txt

@@ -0,0 +1,148 @@
+Setting Up Push on Backend Application
+===
+
+A RhoConnect push to the client consists of executing a RhoConnect ping call. There are three ways to execute a ping call: you can use the RhoConnect REST API to remotely call the ping, perform the ping job directly in a blocking ruby call, or enqueue a resque job to ping asynchronously.
+
+## Pushing Remotely with the RhoConnect REST API
+
+You can trigger a push remotely using the [RhoConnect API Ping method](/rhoconnect/rest-api). This is useful if you want to fully control the push process from a remote server, such as when you use a RhoConnect plugin to connect your backend application to the RhoConnect server application.
+
+**NOTE: If you want to sync all the sources, use 'all' for the source list (the soure_name parameter) instead of a comma-separated list of the RhoConnect application source names to sync.**
+
+### Example of Ping for Ruby Backend Application
+
+As an example, here is how to send a PUSH message to all the devices of the specified user(s) from a Ruby backend app:
+
+	:::ruby
+	# :message - message which will be used to display notification popup dialog on the device
+	# :badge - iphone specific badge
+	# :sound - name of the sound file to play upon receiving PUSH notification
+	# :vibrate - number of seconds to vibrate upon receiving PUSH notification
+	# :sources - list of data source names to be synced upon receiving PUSH notification
+	ping_params = {
+      :api_token => token,
+      :user_id => [array_of_users],
+      :sources => source_name,
+      :message => 'hello world',
+      :vibrate => 2000,
+      :sound => 'hello.mp3'
+    }
+
+	RestClient.post(
+	  "#{server}/api/client/ping",ping_params.to_json, 
+	  :content_type => :json
+	) 
+
+### Example of Ping for .NET Backend Application
+
+As an example, here is how to send a PUSH message to all the devices of the specified user(s) from a .NET backend app:
+
+    private static bool perform_ping(String method, String source_name, String the_message, String vibrate_time, String sound_file,  Hashtable reqHash)
+        {
+            // add meta information
+            reqHash.Add("api_token", _api_token);
+            reqHash.Add("user_id", [array of users]); // not sure how I do this
+            reqHash.Add("source_id", source_name);
+            reqHash.Add("message", the_message);
+            reqHash.Add("vibrate", vibrate_time);
+            reqHash.Add("sound", sound_file);
+
+            JavaScriptSerializer js = new JavaScriptSerializer();
+            string requestBody = js.Serialize(reqHash);
+            
+            
+            // Uri address = new Uri(_endpoint_url + "/api/source/" + method);
+            Uri address = new Uri(_endpoint_url + "/api/client/ping");
+            HttpWebRequest request = WebRequest.Create(address) as HttpWebRequest;
+            request.ContentType = "application/json";
+            request.Method = "POST";
+
+            byte[] byteData = UTF8Encoding.UTF8.GetBytes(requestBody);
+            request.ContentLength = byteData.Length;
+            using (Stream requestStream = request.GetRequestStream())
+            {
+                requestStream.Write(byteData, 0, byteData.Length);
+            }
+            using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
+            {
+                ;
+            }
+
+            return true;
+        }
+
+### Example of Ping for Java Backend Application
+
+As an example, here is how to send a PUSH message to all the devices of the specified user(s) from a Java backend app:
+
+	:::java
+	private boolean performPing(String method, String sourceName, HashMap<String, Object> hash) {
+		hash.put("api_token", apiToken);
+		hash.put("source_id", sourceName);
+		hash.put("user_id", partition);
+		hash.put("message", "hello world");
+		hash.put("vibrate", "2000");
+		hash.put("sound", "hello.mp3");
+		
+
+		HttpHeaders headers = new HttpHeaders();
+		headers.setContentType(MediaType.APPLICATION_JSON);				 
+		HttpEntity<Map> entity = new HttpEntity<Map>(hash, headers);
+
+		ResponseEntity<String> response = restTemplate.exchange(
+				endpointUrl + "/api/client/ping", 
+				HttpMethod.POST,
+				entity,
+				String.class);
+		HttpStatus statusCode = response.getStatusCode();
+
+		return(statusCode.value() == 200);
+	}
+
+## Pushing Directly from a RhoConnect Source Adapter
+
+When you use a RhoConnect source adapter to connect to your backend service, you can use the PingJob.perform method to perform a ping on your mobile client.
+
+	:::ruby
+	PingJob.perform(
+	  'user_id' => current_user.login,
+	  'sources' => ['Product','Customer'],
+	  'message' => 'hello world',
+	  'vibrate' => 2000,
+	  'sound' => 'hello.mp3'
+	)
+
+Let's say we want to execute a ping for the `current_user` at the end of your RhoConnect source adapter query.
+
+	:::ruby
+	def query(params=nil)
+	  parsed = JSON.parse(RestClient.get("#{@base}.json").body)
+
+	  @result = {} 
+	  parsed.each do |item|
+	    @result[item["product"]["id"].to_s] = item["product"]
+	  end if parsed    
+	  PingJob.perform(
+	    'user_id' => current_user.login,
+	    'sources' => ['Product'],
+	    'message' => "There are new products!",
+	    'vibrate' => 2000
+	  )
+	  @result
+	end
+
+## Queuing a Resque Job to Push Asynchronously
+
+To queue a ping that is executed asynchronously in a job, you can have PingJob queued from anywhere in your RhoConnect application (i.e. at the end of another job or adapter query method).
+
+	:::ruby
+	Resque.enqueue(
+	  PingJob,
+	  'user_id' => current_user.login,
+	  'sources' => ['Product','Customer'],
+	  'message' => 'hello world',
+	  'vibrate' => 2000,
+	  'sound' => 'hello.mp3'
+	)
+
+**Note: For this job to execute, you will need to have a resque worker running.  See running [async jobs](/rhoconnect/async-jobs) for more information.**

data/doc/push-client-setup.txt

@@ -0,0 +1,61 @@
+Setting Up for RhoConnect Push on Client Application
+===
+
+Push notification support (receiving push notifications from the RhoConnect server/backend) is currently available for Android, Blackberry and iPhone. 
+
+## Configuring a Rhodes Application to Receive Push
+
+Enable push in your rhodes application in build.yml.
+
+	:::yaml
+	capabilities:
+	  - push
+	  - vibrate #=> if you want to enable vibrate in your push messages
+
+Set up your application [rhoconfig.txt](configuration#run-time-configuration) syncserver to point to your RhoConnect server:
+
+	syncserver = 'http://<rhoconnect_server_url>/application'
+
+## Registering a Push Callback in the Rhodes Application
+
+To handle a push message from a Rhodes application, you must register push callback with the System `set_push_notification` method.
+
+    :::ruby
+    class AppApplication < Rho::RhoApplication
+      def initialize
+        super
+        System.set_push_notification "/app/Push/push_callback", ""
+      end
+    end
+
+Push callback is set up in the form of a local application URL and called as callback whether or not rho_callback=1 is specified in its parameters list.
+
+The parameters trigger certain operations in the Rhodes client when the callback returns "rho_push". (When the callback retuens an empty string, this automatic handling is not performed.) The operations are to show an alert, vibrate the device, play a sound, and perform a sync.
+
+To have your Rhodes app automatically perform the operations listed in the push message, you can write the callback as follows.
+
+    :::ruby
+    def push_callback
+      "rho_push"
+    end
+
+## Understanding the Rhodes Push Message Payload
+
+From Rhodes 2.0.4 on, the callback push message parameters are in the form of a hash. This hash contains parameters and values for the operation to perform. If the parameter for that operation is not listed, the operation is not performed.
+
+The hash payload may include the parameters of alert, do_sync, sound, and vibrate which perform operations that the client performs when it receives the PUSH message. Here is an example of a push message body with the parameter names and values. It will have a popup alert message of "some message", play a sound of alert.mp3, will vibrate the device, and will sync the product and customer sources.
+
+    :::text
+    alert=some message here&sound=alert.mp3&vibrate=2000&do_sync=product,customer
+
+To sync all the sources with do_sync, the source name list would specified as 'all' in the ping call, instead of 'product,customer' as in this example.
+
+The sound file should be included in the Rhodes application bundle in the `/public/alerts` folder.
+
+### Setting up the Rhodes Client for iPhone, Android, and Blackberry
+
+To set up your Rhodes client for push, refer to these links for your respective platforms.
+
+* [Setting up iPhone Client for Push](/rhodes/device-caps#iphone-push-setup)
+* [Setting up Android Client for Push](/rhodes/device-caps#android-push-setup)
+* [Setting up Blackberry Client for Push](/rhodes/device-caps#blackberry-push-setup)

data/doc/push-server-setup.txt

@@ -0,0 +1,91 @@
+Setting Up Push on RhoConnect Server
+===
+
+To set up your RhoConnect server application for delivering push messages, you need to set up the application settings configurations for the operating system of your mobile client.
+
+## Setting up RhoConnect Server Push for iOS
+
+To set up your RhoConnect application for pushing to an iOS client, you will need to update `settings/settings.yml` to include the following:
+
+	:::yaml
+	:development: 
+	  :redis: localhost:6379
+	  :iphonecertfile: settings/apple_push_cert.pem
+	  :iphonepassphrase: #=> empty or put password for your certificate
+	  :iphoneserver: gateway.sandbox.push.apple.com
+	  :iphoneport: 2195
+	  :syncserver: http://localhost:9292/application/
+	  :licensefile: settings/license.key
+
+This is for running your application in development mode; for production, you will need all of the iphone settings, and you change the `:iphoneserver:` to:
+
+	:::yaml
+  	:iphoneserver: gateway.push.apple.com
+
+## Setting up RhoConnect Server Push for Blackberry
+
+To set up your RhoConnect application for pushing to a BlackBerry client, you will need to update `settings/settings.yml` to include the following:
+
+	:::yaml
+	:development: 
+	  :redis: localhost:6379
+	  :mdsserver: 192.168.1.110
+	  :mdsserverport: 8080
+	  :syncserver: http://localhost:9292/application/
+	  :licensefile: settings/license.key
+
+Replace `:mdsserver:` and `:mdsserverport:` with the hostname/IP and port of your machine (default port is 8080).
+
+## Setting up RhoConnect Server Push for Android
+
+To set up your RhoConnect application for Android push, you will need to update `settings/settings.yml` to include the following:
+
+	:::yaml
+	:development:
+	  :redis: localhost:6379
+	  :syncserver: http://localhost:9292/application/
+	  :licensefile: settings/license.key
+	  :c2dm_username: username
+	  :c2dm_passwd: passwd
+	  :authtoken: authtoken
+
+In order to push messages to the Android device, your server needs to obtain Google's C2DM authentication token associated with the trusted google account.
+For this purpose, you can specify C2DM Google account's username/password combo via the `:c2dm_username` and `:c2dm_passwd` settings.
+At run-time, the system will use these credentials to obtain the C2DM token and store it in the Redis for the future use.
+Once the token is expired, the system will automatically connect to the Google C2DM service to renew the token.
+
+Alternatively, you can use `:authtoken` setting to specify the pre-defined authentication token. This token MUST be related to the role-based google account registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). Uncomment last two lines and put your google account specific data, then run it. It will print token to stdout.
+However, this approach will not allow the server to connect to the C2DM service and renew the token once it is expired.
+
+For those who interested in what this token means, the description is [here](http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html).
+
+Now start up your RhoConnect application and setup [push notifications](/rhodes/device-caps#push-notifications) in your Rhodes application.
+
+## Testing Push in the RhoConnect Web Console
+
+The [RhoConnect Web Console](/rhoconnect/web-console) includes a utility for testing push to make sure everything is wired up correctly.  
+
+First, make sure you've logged in and performed a sync on the device/simulator you are going to test. 
+
+Next, once you've logged into the web console, navigate to the user's page you used to login in the Rhodes application.  For example, if you logged in as user 't', the url would be: 
+
+	http://localhost:9292/console/user?user_id=t
+
+You should see a registered device for this user, for example: "c92e36874bc74f39a8fbd7c1a86f9e0e".  Click on the link for this device and you will see the device attributes:
+
+  	device_type: APPLE
+	device_pin:	10fd92abfa8ee48155d9af6e7329086322b323fd0d18fdbd19e92d03c0fef7c8
+	device_port: 100
+	user_id: t
+	app_id:	application
+
+**NOTE: If you don't see all of these attributes, then something is incorrect in your Rhodes application settings. Please verify you followed the [Rhodes application push setup](/rhodes/device-caps#push-notifications).**
+
+Now that the device is registered, go back to the user page and click 'Ping User'.
+
+Here you can specify an alert message, sources array to sync, badge value (iOS only), sound file to play, and duration to vibrate.
+
+Enter in some values or try the defaults, you should see a push message on the device when you click "Ping!".
+
+By default, the sources list will be a comma-separated list of your RhoConnect application's sources. This sources list will be sent in the push message to trigger a sync. You can specify one or more sources, or 'all' to trigger a sync of all sources.
+

data/doc/push.txt

@@ -1,143 +1,14 @@
-Device Push
+Push Synchronization
 ===
 
-RhoConnect has a simple ruby API for sending push notifications to a user's devices.  This API can be called directly, queued as a resque job, or called remotely via the [RhoConnect REST API](/rhoconnect/rest-api). The push message can trigger the following actions in the rhodes application: alert with a message, sync one or more sources, vibrate, display a badge, play a sound file.
+Use push synchronization when you want to automatically detect changes on the RhoConnect side, and you want to push those changes to your client without having to tell your client to sync.
 
-We will now show you how to use the RhoConnect application to deliver push messages on each platform and how you can handle the push notification in your Rhodes application.
+RhoConnect has a simple ruby API for sending push notifications (a ping call) to a user's devices. This API can be called directly, queued as a resque job, or called remotely via the [RhoConnect REST API](/rhoconnect/rest-api). The push message can trigger the following actions in the rhodes application: alert with a message, sync one or more sources, vibrate, display a badge, and play a sound file.
 
-## iOS
-To setup your RhoConnect application for iOS push, you will need to update `settings/settings.yml` to include the following:
+The following sections show how to use the RhoConnect application to deliver push messages on each platform and how you can handle the push notification in your Rhodes application.
 
-	:::yaml
-	:development: 
-	  :redis: localhost:6379
-	  :iphonecertfile: settings/apple_push_cert.pem
-	  :iphonepassphrase: #=> empty or put password for your certificate
-	  :iphoneserver: gateway.sandbox.push.apple.com
-	  :iphoneport: 2195
-	  :syncserver: http://localhost:9292/application/
-	  :licensefile: settings/license.key
+You will need to perform the following tasks.
 
-This is for running your application in development mode, for production you will need all of the iphone settings, and change the `:iphoneserver:` to:
-
-	:::yaml
-  	:iphoneserver: gateway.push.apple.com
-
-## Blackberry
-To setup your RhoConnect application for BlackBerry push, you will need to update `settings/settings.yml` to include the following:
-
-	:::yaml
-	:development: 
-	  :redis: localhost:6379
-	  :mdsserver: 192.168.1.110
-	  :mdsserverport: 8080
-	  :syncserver: http://localhost:9292/application/
-	  :licensefile: settings/license.key
-
-Replace `:mdsserver:` and `:mdsserverport:` with the hostname/IP and port of your machine (default port is 8080).
-
-## Android
-To setup your RhoConnect application for Android push, you will need to update `settings/settings.yml` to include the following:
-
-	:::yaml
-	:development:
-	  :redis: localhost:6379
-	  :syncserver: http://localhost:9292/application/
-	  :licensefile: settings/license.key
-	  :c2dm_username: username
-	  :c2dm_passwd: passwd
-	  :authtoken: authtoken
-
-In order to push messages to the Android device, your server needs to obtain Google's C2DM authentication token associated with the trusted google account.
-For this purpose, you can specify C2DM Google account's username/password combo via the `:c2dm_username` and `:c2dm_passwd` settings.
-At run-time, the system will use these credentials to obtain the C2DM token and store it in the Redis for the future use.
-Once the token is expired, the system will automatically connect to the Google C2DM service to renew the token.
-
-Alternatively, you can use `:authtoken` setting to specify the pre-defined authentication token. This token MUST be related to the role-based google account registered for your application. See [the rhodes push instructions](/rhodes/device-caps#push-notifications) for more details. To retrieve this token, use sample script [c2dm.rb](http://github.com/rhomobile/rhodes/blob/master/bin/c2dm.rb). Uncomment last two lines and put your google account specific data, then run it. It will print token to stdout.
-However, this approach will not allow the server to connect to the C2DM service and renew the token once it is expired.
-
-For those who interested in what this token means, the description is [here](http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html).
-
-Now start up your RhoConnect application and setup [push notifications](/rhodes/device-caps#push-notifications) in your Rhodes application.
-
-## Testing Push in the Web Console
-The [RhoConnect Web Console](/rhoconnect/web-console) includes a utility for testing push to make sure everything is wired up correctly.  
-
-First, make sure you've logged in and performed a sync on the device/simulator you are going to test. 
-
-Next, once you've logged into the web console, navigate to the user's page you used to login in the Rhodes application.  For example, if you logged in as user 't', the url would be: 
-
-	http://localhost:9292/console/user?user_id=t
-
-You should see a registered device for this user, for example: "c92e36874bc74f39a8fbd7c1a86f9e0e".  Click on the link for this device and you will see the device attributes:
-
-  	device_type: APPLE
-	device_pin:	10fd92abfa8ee48155d9af6e7329086322b323fd0d18fdbd19e92d03c0fef7c8
-	device_port: 100
-	user_id: t
-	app_id:	application
-
-**NOTE: If you don't see all of these attributes, then something is incorrect in your Rhodes application settings.  Please verify you followed the [Rhodes application push setup](/rhodes/device-caps#push-notifications).**
-
-Now that the device is registered, go back to the user page and click 'Ping User'.
-
-Here you can specify an alert message, sources array to sync, badge value (iOS only), sound file to play, and duration to vibrate.
-
-Enter in some values or try the defaults, you should see a push message on the device when you click "Ping!".
-
-By default, the sources list will be a comma-separated list of your RhoConnect application's sources.  This sources list will be sent in the push message to trigger a sync.  You can specify one or more sources, or 'all' to trigger a sync of all sources.
-
-## Push API
-The RhoConnect push API consists of executing a ping call.  There are three ways to execute a ping call:  use RhoConnect API to remotely call the ping, perform the ping job directly in a blocking ruby call, enqueue a resque job to ping asynchronously.
-
-### RhoConnect API Ping Method
-You can trigger a push remotely using the [RhoConnect API Ping method](/rhoconnect/rest-api).  This is useful if you want to fully control the push process from a remote server (instead of your source adapter).
-
-### Direct Push
-To perform a ping directly, you can call the following:
-
-	:::ruby
-	PingJob.perform(
-	  'user_id' => current_user.login,
-	  'sources' => ['Product','Customer'],
-	  'message' => 'hello world',
-	  'vibrate' => 2000,
-	  'sound' => 'hello.mp3'
-	)
-
-### Asynchronous Push
-To queue a ping that is executed asynchronously in a job, you can call the following:
-
-	:::ruby
-	Resque.enqueue(
-	  PingJob,
-	  'user_id' => current_user.login,
-	  'sources' => ['Product','Customer'],
-	  'message' => 'hello world',
-	  'vibrate' => 2000,
-	  'sound' => 'hello.mp3'
-	)
-
-**Note: For this job to execute, you will need to have a resque worker running.  See running [async jobs](/rhoconnect/async-jobs) for more information.**
-
-### Example
-Let's say we want to execute a ping for the `current_user` at the end of our source adapter query:
-
-	:::ruby
-	def query(params=nil)
-	  parsed = JSON.parse(RestClient.get("#{@base}.json").body)
-
-	  @result = {} 
-	  parsed.each do |item|
-	    @result[item["product"]["id"].to_s] = item["product"]
-	  end if parsed    
-	  PingJob.perform(
-	    'user_id' => current_user.login,
-	    'sources' => ['Product'],
-	    'message' => "There are new products!",
-	    'vibrate' => 2000
-	  )
-	end
-
-### Push Notifications in Rhodes
-Now that you can send push messages in your RhoConnect application, you can now handle the [push notification](/rhodes/device-caps#push-notifications) in your Rhodes application.
+* [Set up the configuration settings in the RhoConnect application](/rhoconnect/push-server-setup) for your mobile client operating system.
+* [Execute a ping call](/rhoconnect/push-backend-setup) from your RhoConnect source adapter or from your backend application that uses a RhoConnect plugin.
+* [Set up push notification support](/rhoconnect/push-client-setup) -- receiving push notifications from the RhoConnect server/backend -- on your Android, Blackberry, or iPhone client application.