frankhock / mavenlink_gem

Mavenlink API

Mavenlink API

Usage

Examples below use Mavenlink::Workspace as an instance. You also have other collections to use in similar way:

Mavenlink::Assignment # assignments collection Mavenlink.client.assignments
Mavenlink::Attachment # attachments collection Mavenlink.client.attachments
Mavenlink::Expense    # expenses collection Mavenlink.client.expenses
Mavenlink::Invoice    # invoices collection Mavenlink.client.invoices
Mavenlink::Post       # posts collection Mavenlink.client.posts
Mavenlink::Story      # stories collection Mavenlink.client.stories
Mavenlink::StoryAllocationDay
Mavenlink::TimeEntry  # time_enties collection Mavenlink.client.time_entries
Mavenlink::User       # users collection Mavenlink.client.users
Mavenlink::WorkspaceGroup
Mavenlink::Workspace

Setting up access token

In order to be able to perform any requests you should set outh_token obtained by your Mavenlink Account.

Mavenlink.oauth_token = "your_token"

If you are using Rails, put this line into config/initializers/mavenlink.rb. If you are using Heroku or Foreman, set MAVENLINK_OAUTH_TOKEN env var.

Creating new records

workspace = Mavenlink::Workspace.create(title: 'new workspace', creator_role: 'buyer')

# Exactly the same:
workspace = Mavenlink::Workspace.new(title: 'New workspace', creator_role: 'maven')
workspace.save # will call "create" and store record in Mavenlink db
workspace.new_record? # -> false

Fetching records

Mavenlink::Workspace.find(9)
# Same as:
workspace = Mavenlink.client.workspaces.find(9)

# Reload record from remote host:
workspace.reload

Updating records

workspace = Mavenlink::Workspace.find(1)

workspace.title = 'new title' # writes attribute
workspace.save                # returns true if record has been saved
workspace.save!               # will raise exception if record is invalid

workspace.update_attributes(title: 'title')
workspace.update_attributes!(title: 'title')

workspace.attributes = {title: 'title'}
workspace.save

Destroying records

post = Mavenlink::Post.find(1)
post.destroy

Associations

workspace.participants        # will return participants as an array of Mavenlink::User instances, will do http API call if association is not "included"
workspace.participants        # now it returns cached value
workspace.participants.first  # returns Mavenlink::User record
workspace.participants(true)  # flushes association cache

participant = workspace.participants.first
participant.full_name = 'new name'
participant.save # performs "update" query, full_name will be changed

In order to include association use include as follows:

Mavenlink::Workspace.scoped.includes(:participants).search('My Workspace')
Mavenlink::Workspace.includes(:participants).search('My Workspace')

Mavenlink::Workspace.scoped.search('My Workspace').order(:updated_at, :desc).each do |workspace|
  if workspace.valid?
    workspace.destroy
  end
end

Search

Mavenlink::Workspace.search('Something')
Mavenlink::Workspace.scoped.search('Something')
Mavenlink.client.workspaces.search('Something')

Filtering

Mavenlink::Workspace.filter(include_archived: true).all
Mavenlink::Workspace.scoped.filter(include_archived: true).all
Mavenlink.client.workspaces.filter(include_archived: true).all

Pagination

Mavenlink::Workspace.page(2).per_page(3)
Mavenlink::Workspace.scoped.page(2).per_page(3)
Mavenlink.client.workspaces.page(2).per_page(3)

Mavenlink::Workspace.limit(2).offset(3)
Mavenlink::Workspace.scoped.limit(2).offset(3)
Mavenlink.client.workspaces.limit(2).offset(3)

You'll never receive full results set if number of records in requested collection is greater than 200. Pagination allows you to go through entire collection.

Mavenlink::Workspace.scoped.each_page do |page|
  page.each do |workspace|
    p workspace.inspect
  end
end

Use your paginator as Enumerable:

Mavenlink::Workspace.scoped.each_page(200).to_a     # 200 records per page
Mavenlink::Workspace.scoped.each_page.to_a.flatten  # Returns full collection
Mavenlink::Workspace.scoped.each_page(2).each_with_index { |page, i| puts i }

Kaminari pagination is also supported.

Client side validation

By default client side validation is disabled, you can enable it by setting perform_validations to true

Mavenlink.perform_validations = true

Now any record will be validated before you perform any request to change its attributes.

workspace = Workspace.new(title: 'My workspace')
workspace.save # -> returns false
workspace.errors.full_messages # -> ["Creator role is not included in the list"]

Invite new user

Mavenlink::Workspace.find(7).invite(email: '[e-mail]', full_name: 'John Doe', invitee_role: 'maven')

Requesting expense categories

Mavenlink.client.expense_categories

Custom requests

client = Mavenlink.client
client.get('/custom_path', {param: 'anything'})
client.post('/custom_path', {param: 'anything'})
client.put('/custom_path', {param: 'anything'})
client.delete('/custom_path', {param: 'anything'})

More examples

client = Mavenlink::Client.new(oauth_token: '...')
client.workspaces.each { |workspace| do_something(workspace) }

client.workspaces.includes('participants')
client.workspaces.includes('participants')
client.workspaces.includes('participants, creator')
client.workspaces.includes('participants', 'creator')
client.workspaces.includes(['participants', 'creator'])
client.workspaces.includes(:participants, :creator)

client.workspaces.find(2) # Returns one Mavenlink::Workspace

client.workspaces      # Returns sort of "active record relation collection"
client.workspaces.to_a # Same as calling #to_a on activerecord scope
client.workspaces.all  # Same as calling #to_a on activerecord scope

client.workspaces.page(3).per_page(20)
client.workspaces.limit(100).offset(10)
client.workspaces.filter(by_something: true)
client.workspaces.search('some text')

client.workspaces.order(:updated_at)
client.workspaces.order('updated_at:desc')
client.workspaces.order(:updated_at, :desc)
client.workspaces.order(:updated_at, 'ASC')
client.workspaces.order(:updated_at, true)

client.workspaces.create(title: 'New workspace')
client.workspaces.only(8).update(title: 'new title')
client.workspaces.only(8).delete

# ...

Running Developer Console

Run in your project directory bundle exec mavenlink-console or TOKEN=your_oauth_token bundle exec mavenlink-console. Or just mavenlink-console (depending on your current setup).

Contributing

1. Fork
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request (git pull-request)

License

Created by Mavenlink, Inc. and available under the MIT License.