RoQua ROM API

Make sure the following environment variables are defined:

ENV['ROM_SITE']             # URI of the RoQua application whose API you are targeting
ENV['ROM_BASICAUTH_ID']     # username used for HTTP basic authentication on the RoQua API
ENV['ROM_BASICAUTH_SECRET'] # password used for HTTP basic authentication on the RoQua API

An HTTP basic auth username password combination can be generated in the RoQua admin interface integration tab

General notes

I18n

By default the ROM API Gem supports the :nl language only. If you use another locale or want to change some of the messages, simply extend your locale file by providing a value for some or all of the keys defined config/locales/*.yml in the root of this Gem.

Usecases

In general, the use case classes will return an outcome object. You can query this object to find out if the API call was successful with #valid?. The result of the API call is available under #result, and/or the errors under #errors. In general, this means that you'll usually write a pattern like this:

outcome = Roqua::RomApi::Something.run param: 1, other: 2

if outcome.valid?
  responses = outcome.result
else
  log_or_display outcome.errors.full_messages
end

Fill Out Requests

To create a fill out request run:

Roqua::RomApi::CreateFillOutRequest.run! dossier_id: dossier_id,
                                         questionnaire_keys: ['key1', 'key2'],
                                         callback_url: notify_callback_path(token: 'secret')

See api for more info on how callbacks work.

Fill Out Sessions

To start filling out a set of questionnaires run:

outcome = Roqua::RomApi::StartFillOutSession.run dossier_id: dossier_id,
                                                 questionnaire_keys: questionnaire_keys,
                                                 return_to: '/some/return/url/or/path'

Redirect to the fill_out url received when the outcome is valid:

if outcome.valid?
  redirect_to outcome.result
else
  log_or_display outcome.errors.full_messages
end

Protocol Subscriptions

List

To retrieve active protocol subscriptions run:

outcome = Roqua::RomApi::ListProtocolSubscriptions.run dossier_id: dossier_id

Start

To subscribe to a protocol run the following command:

outcome = Roqua::RomApi::StartProtocolSubscription.run dossier_id: dossier_id,
                                                       protocol_key: protocol_key,
                                                       start_at: start_at

Stop

To unsubscribe from a protocol run the command:

outcome = Roqua::RomApi::StopProtocolSubscription.run dossier_id: dossier_id,
                                                      protocol_subscription_id: subscription_id

Responses

List

To retrieve filled out, pending or scheduled questionnaires run:

outcome = Roqua::RomApi::ListResponses.run dossier_id: dossier_id

Create

To store an externally filled out questionnaire run:

outcome = Roqua::RomApi::CreateResponse.run questionnaire_key: 'questionnaire_key',
                                            dossier_id: 'dossier_id',
                                            answer_data: {some: 'aswer_data'}

Update

To store external data on an existing pending response:

outcome = Roqua::RomApi::CreateResponse.run questionnaire_key: 'questionnaire_key',
                                            dossier_id: 'dossier_id',
                                            id: 230, # response id,
                                            answer_data: {some: 'aswer_data'}

Contributing to roqua-rom-api

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

RoQua ROM API

General notes

I18n

Usecases

Contributing to roqua-rom-api

Copyright