peterclark / redcap

A Ruby gem for interacting with the REDCap API

Redcap

A Ruby gem for interacting with the REDCap API

Installation

Add this line to your application's Gemfile:

gem 'redcap', github: 'peterclark/redcap'

And then execute:

$ bundle

Initialization

You can initialize a Redcap instance in one of three ways:

Using a .env file

# inside .env file
# REDCAP_HOST=http://yourhost.com
# REDCAP_TOKEN=12345

redcap = Redcap.new

Using a block

Redcap.configure do |config|
  config.host = "http://yourhost.com"
  config.token = 1234
end

redcap = Redcap.new

Passing in a hash of options

redcap = Redcap.new host: 'http://yourhost.com', token: 1234

Usage

Create a class that inherits from Redcap::Record.

# name the class after your REDCap project
# ex. Survey, Volunteer, Trial, People
class People < Redcap::Record
end

Find a record by record_id

bob = People.find 1

Find records using an array of ids

people = People.where id: [1,4,5]

Find a record by a field value

bob = People.where(first_name: 'Bob').first

Return all records

people = People.all

Return all records with only first_name and age

people = People.select(:first_name, :age)

Pluck a field from all records

names = People.pluck(:first_name)
# ['Joe', 'Sal', 'Luke']

Return all record ids

ids = People.ids
# [1,2,3, ... ]

Return the total number of records

total = People.count
# 125

Update a record

bob = People.where(first_name: 'bob').first
bob.last_name = 'Smith'
bob.save

Create a record

joe = People.new(first_name: 'Joe', email: '[e-mail]')
joe.save

Delete a record

joe = People.find(joe.id)
joe.destroy
# 1 (number of records deleted)

Delete multiple records

joe = People.new(first_name: 'Joe', email: '[e-mail]')
joe.save

ray = People.new(first_name: 'Ray', email: '[e-mail]')
ray.save

People.delete_all [joe.id, ray.id]
# 2 (number of records deleted)

> Greater Than

over40 = People.gt age: 40

< Less Than

under30 = People.lt age: 30

>= Greater Than or Equal To

over40 = People.gte age: 41

<= Less Than or Equal To

under30 = People.lte age: 29

Logging

# set log to true on the client
People.client.log = true

Enable Caching

Setting REDCAP_CACHE to ON inside your .env file will cache all calls to Redcap. A full cache flush will occur when any record is updated or created.

# inside .env
# REDCAP_CACHE=ON

Force cache flush

If REDCAP_CACHE is set to ON, the cache can be manually flushed by calling flush_cache on the client.

People.client.flush_cache

Using the Redcap class to return raw data

redcap = Redcap.new

# Get project info
redcap.project

# Get all records and all fields
redcap.records

# Get all records and a subset of fields
redcap.records fields: %w(first_name age)

# Get all records and all fields matching a filter
redcap.records filter: '[age] > 40'

# Get all records and a subset of fields matching a filter
redcap.records fields: %w(email age), filter: '[age] < 35'

# Get records with the given ids and a subset of fields matching a filter
redcap.records records: [1,4], fields: %w(email age), filter: '[age] < 35'

TODO

1. Method chaining

• People.where(age: 40).select(:first_name)

2. Create RedcapRecord module as alternative to inheritance

• include Redcap

3. Destroy a record

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/peterclark/redcap.

License

The gem is available as open source under the terms of the MIT License.