ohmage gem

The ohmage ruby gem is a lightweight API wrapper interacting with an ohmage 2.x server. While this gem is still in early development, it can be found to be extremely helpful for scripting everyday tasks (and does it's best to stay out of the way, allowing the ohmage server to dictate failed interactions). While the inclusion in a ruby script is a great way to do lots of tasks, this gem also comes with a stripped down CLI for use.

gem install ohmage

Getting started is quite easy, just go ahead and instantiate a new client for interaction (note full http url)

oh = Ohmage::Client.new(user: 'testuser', password: 'testpassword', server_url: 'https://test.mobilizingcs.org/')

You can also pass a block for configuration:

oh = Ohmage::Client.new do |conf|
  conf.user = 'testuser'
  conf.password = 'testpassword'
  conf.server_url = 'https://test.mobilizingcs.org/'
  # defaults here, but offering in case you need something else!
  conf.path = 'app/'
  conf.client_string = 'ruby-ohmage'
  conf.port = 443
end

From there you can just start making calls! Take a look at the (ohmage 2.x API specs)[https://github.com/ohmage/server/wiki/APIs-for-2.x-Top-Level-Entities] to see what params are needed for which calls. Here's a sample call using the client defined above:

oh.user_create(username: 'newuser', password: 'newpassword', admin: false, enabled: true, new_account: true)

The hyperloaded survey_response/read api is really just that. This gem does the best job it can to stay out of the way but provides some sane defaults to get survey responses to play with from the least amount of effort. In particular, the parameters column_list, output_format and user_list all have defaults to provide the most useful (and most complete response) from the server. Please feel free to pass these parameters though if you know you want something different. An extremely simple example to get an array of all responses your current user has access to in the campaign urn:campaign:sample:

responses = oh.survey_response_read(campaign_urn: 'urn:campaign:sample')
p responses # outputs the entire array of Ohmage::SurveyResponse objects

A few APIs can/must use files on the disk for uploading (document/create, survey/upload if sending multimedia). Passing the filename as the expected parameter will result in the expected behavior:

oh.document_create(document: '/path/to/file/sample.docx', privacy_state: 'shared', document_class_role_list: 'urn:class:public;reader')

will create a document on the server with the sample.docx file as the content.

The survey_upload method requires a distinct parameter setup (make sure to take a look at the server api for details). Here's a simple example of how this method would work with an image. Note that it shells out to the file command to return a useful mime-type (required by ohmage).

oh.survey_upload(campaign_creation_timestamp: '2015-05-13 08:53:00',
                 campaign_urn: 'urn:campaign:mobilize:steve:phototest',
                 surveys: [{survey_key: 'b08c05b2-67d0-4962-8c82-913edd534504',
                           location_status: 'unavailable',
                           time: 1434046871000,
                           timezone: 'America/Los_Angeles',
                           survey_id: 'test',
                           survey_launch_context: {
                             launch_time: 1434046871000,
                             launch_timezone: 'America/Los_Angeles',
                             active_triggers: []
                           },
                           responses: [
                             {prompt_id: 'photo',
                              value: 'a3d25bdd-8d4b-4db6-96f6-d26dcc9aeac3'}
                           ]}].to_json,
                 'a3d25bdd-8d4b-4db6-96f6-d26dcc9aeac3':'/path/to/image.png'
                 )

About object types! Calls that are able to return entities will return new instances of top-level objects: Ohmage::User, Ohmage::Campaign, Ohmage::Clazz (note the zz) and Ohmage::Document. Calls involving deletes (user_delete, campaign_delete) and user_password return nil if successful.

A list of the APIs which are currently implemented, and their internal method name:

• While media/read becomes support in server 2.17, this wrapper has mapped all methods to work regardless of the server version. Prefer the media_read method for all media calls, regardless of type.

Getting started with the CLI is a piece of cake. In the current implementation, you need to set 3 environment variables for access. Let's get that out of the way:

export OHMAGE_SERVER_URL = 'https://test.mobilizingcs.org/'
export OHMAGE_USER = 'testuser'
export OHMAGE_PASSWORD = 'testpass'

Now you can make api calls via some really nice shorthands. the basic layout of the CLI is: ohmage <action> <entity> <entity_options>

A few examples:

ohmage ls class # returns list of class urns the current user can view
ohmage ls class -t # returns a table of classes and info the current user can view
ohmage create user testuser --password "testpassword" # creates a new user with defaults (enabled, new_account set, not admin)
ohmage update user testuser --no-admin --new # sets admin to false and new_account to true for testuser
ohmage update password testuser --password "testpassword" # updates user's password. this is a different API in ohmage from user/update
ohmage update class urn:class:test --restricted restricted.user1,restricted.user2 --privileged priv.user1 --remove remove.user1 # adds/removes users from a class. note the need to provide multiple users comma-separated and the param based on intended user role.

Copyright (c) 2015 Steve Nolen See LICENSE for details.