Mavenlink

Ruby gem for Mavenlink's API v1.

Installation

Add this line to your application's Gemfile:

gem 'mavenlink'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mavenlink

Usage

Please read the API documentation (http://developer.mavenlink.com/) before using the gem.

You will also need your oauth_token, which can be found on your Mavenlink userpage.

Client

#####Initialize a new client

require 'mavenlink'
cl = Mavenlink::Client.new(oauth_token)

###User #####Get users

# All users
users = cl.users
    
# Filter users
filtered_users = cl.users({:participant_in => 12345})

###Expense #####Get expenses

# All expenses
expenses = cl.expenses
    
# Filter expenses
filtered_expenses = cl.expenses({:workspace_id => 12345, :order => "date:asc" })

#####Create a new expense

#Required parameters : workspace_id, date, category, amount_in_cents
#Optional paramters : notes, currency
expense = cl.create_expense({ :workspace_id => 12345,
                              :date => "2012/01/01",
                              :category => "Travel",
                              :amount_in_cents => 100 
                            })

#####Save and reload expense

#Savable attributes: notes, category, date, amount_in_cents
expense = cl.expenses.first
expense_copy = cl.expenses.first
expense.category = "Updated category"

# expense.category != expense_copy.category
expense.save

# expense.category == expense_copy.category
expense_copy.reload

#####Delete an expense

expense = cl.expenses.first
expense.delete

###Expense Category #####Get expense categories

# Returns an array of expense category strings
categories = cl.expense_categories

###Workspace #####Get workspaces

# All workspaces with all associated objects
workspaces = cl.workspaces({:include => "all"})

# Associated objects that can be included: primary_counterpart,participants,creator
workspaces = cl.workspace({:include => ['primary_counterpart', 'creator'])


# Filter and search workspaces
workspaces = @cl.workspaces({:search => "API Test Project"})

#####Create a new workspace

#Required parameters: title, creator_role(maven or buyer)
#Optional parameters: budgeted, description, currency, price, due_date, project_tracker_template_id
@cl.create_workspace({ :title => "Random Workspace X",
                        :creator_role => "maven"
                    }).

#####Save and reload a workspace

#Savable attributes: title, budgeted, description, archived
wks = cl.workspaces.first
wks_copy = cl.workspaces.first
exp.titile = "Updated title"

# wks.title != wks_copy.title
wks.save

# wks.title == wks_copy.title
wks_copy.reload

#####Create a workspace invitation

wks = cl.workspaces.first

#Required parameters: full_name, email_address, invitee_role
#Optional parameters: subject, message
wks.create_workspace_invitation({ :full_name => "example name",
                                  :email_address => "[email protected]",
                                  :invitee_role => "maven"
                               })

#####Associated objects

wks = cl.workspaces.first

#Lead of opposite team
counterpart_user = wks.primary_counterpart

#Array of participating users
participants = wks.participants

#Creator of workspace
creator = wks.creator

###Invoice #####Get invoices

    # All invoices
    invoices = cl.invoices

    # Associated objects that can be included: time_entries,expenses,additional_items,workspaces,user
    invoices = cl.invoices({:include => ['user', 'expenses'])

    # Filter invoices
    invoices = @cl.invoices({:workspace_id => "12345,12346", :paid => "true"})

#####Reload a invoice

inv = cl.invoices.first
inv.reload

#####Associated objects

inv = cl.invoices.first

#Time entries of an invoice
time_entries = inv.time_entries

#Expenses of an invoice
expenses = inv.expenses

#Additional items returned as a hash
additional_items = inv.additional_items

#Workspaces related to the invoice
workspaces = inv.workspaces

#Creator of the invoice
user = inv.user

###TimeEntry #####Get time entries

    # All time entries with all associated objects
    entries = cl.time_entries({:include => 'all'})

    # Associated objects that can be included: user,story,workspace
    entries = cl.time_entries({:include => ['user', 'story'])

    # Filter invoices
    entries = @cl.entries({:workspace_id => 12345})

#####Create a new time entry

#Required parameters: workspace_id, date_performed, time_in_minutes
#Optional parameters: billable, notes, rate_in_cents, story_id
ent = @cl.create_time_entry({
                              :workspace_id => 12345,
                              :date_performed => "2013-07-04",
                              :time_in_minutes => 34,
                              :notes => "Notes for TE"
                            })

#####Reload and save a time entry

Savable attributes: date_performed, time_in_minutes, notes, rate_in_cents, billable
ent = cl.time_entries.first
ent_copy = cl.time_entries.first
ent.time_in_minutes = 10

# ent.category != ent_copy.time_in_minutes
ent.save

# exp.category == exp_copy.category
ent_copy.reload

#####Delete an existing time entry

ent = cl.time_entry.first
ent.delete

#####Associated objects

ent = cl.time_entries.first

#Workspace that the entry belongs to
wks = ent.workspace

#User that submitted the entry
user = ent.user

#Story associated with entry. nil if no story.
story = ent.story

###Story #####Get stories

    # All stories
    stories = cl.stories

    # Associated objects that can be included: workspace,assignees,parent,sub_stories,tags
    stories = cl.stories({:include => ['workspace', 'parent'])

    # Filter and order stories
    stories = @cl.stories({:workspace_id => 12345, :order => "created_at:asc", :parents_only => true})

#####Create a new story

#Required parameters: workspace_id, title, story_type(task, milestone or deliverable)
#Optional parameters: description, parent_id, start_date, due_date, assignees, budget_estimate_in_cents,
#                     time_estimate_in_minutes, tag_list
stry = @cl.create_story({
                          :workspace_id => 3467515,
                          :title => "New Task",
                          :story_type => "task"
                       })

#####Reload and save a story

#Savable attributes: title, description, story_type, start_date, due_date,
#                    state, budget_estimate_in_cents, time_estimate_in_minutes, percentage_complete
stry = cl.stories.first
stry_copy = cl.stories.first
stry.description = "Updated description"

# stry.description != stry_copy.description
stry.save

# stry.description == stry_copy.description
stry_copy.reload

#####Associated objects

stry = cl.stories.first

#Workspace that the story belongs to
workspace = story.workspace

#Parent story, if exists. Nil, otherwise
parent = stry.parent_story

#Array of Users assigned to the story
assignees = stry.assignees

#Sub-stories of this story
sub_stories = stry.sub_stories

#Array of tags as strings
tags = stry.tags

###Post #####Get posts

    # All stories
    posts = cl.posts


    # Associated objects that can be included: subject,user,workspace,story,replies,newest_reply,newest_reply_user,recipients,google_documents,assets
    stories = cl.stories({:include => ['subject', 'replies'])

    # Filter and order posts
    posts = @cl.posts({:workspace_id => 3484825, :parents_only => true})

#####Create a new post

#Required parameters: message, workspace_id
#Optional parameters: subject_id, subject_type, story_id, recipient_ids, file_ids
pst = @cl.create_post({
                       :message => "Created new post",
                       :workspace_id => 3484825
                      })

#####Reload and save a post

#Savable attributes: message, story_id
pst = cl.posts.first
pst_copy = cl.posts.first
pst.message = "Updated message"

# pst.message != pst_copy.message
stry.save

# pst.message == pst_copy.message
pst_copy.reload

#####Associated objects

pst = cl.posts.first

#Workspace that the story belongs to
workspace = pst.workspace

#Parent post, if exists. Nil, otherwise
parent = pst.parent_post

#User who created the post
user = pst.user

#Story associated with this post
story = pst.story

#Replies to this post as an array of Posts
replies = pst.replies

#Recipients of this post as an array of Users
recipients = pst.recipients

#Newest reply to this post, if exists. Nil otherwise.
newest_reply = pst.newest_reply

#User who posted the newest reply
newest_reply_user = pst.newest_reply_user

# An array of urls to associated google docs
google_documents = pst.google_documents

# A list of assets linked to this pst
assets = pst.assets

###Asset #####Create a new asset

# Required parameters: data (filepath of asset), type (expense or post)
@cl.create_asset({
                  :data => "example_file_path",
                  :type => "expense"
                 })

#####Save an asset

#Savable attributes: file_name
asset.file_name = "updated_file_name"
asset.save

#####Delete an asset

asset.delete

Contributing

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