Sample script to create recurring project budgets for specific projects in your Freckle account using the API.

freckle_recurring_budgets.rb

# Hey there!
#
# This is a basic script that shows how to give projects an "allowance", like
# 5 hours every month. First, it looks at how many hours you want to budget for
# each project. Then, it establishes a connection with the Freckle API, using your
# API token. It then loops through all the projects you listed, finding out how many
# minutes it needs to add or remove from the existing project budget. Finally, it
# updates the project and goes onto the next one.
#
# If you want to set a monthly budget, you would run this script once every month.
# For weekly budgets, once a week.
# To run the script, just run the command: `ruby freckle_recurring_budgets.rb`
#
# Cheers,
# Your Freckle Team

# We need an HTTP client library and URI parser to call the API in JSON.
require 'net/http'
require 'net/https'
require 'uri'
require 'json'


# Here is where you configure the script to access your account. Just add your account
# name and your personal API key.
subdomain = 'apitest'
api_key = 'lx3gi6pxdjtjn57afp8c2bv1me7g89j'

# This is the list of projects, with the number of hours you want to budget for each
# one. In this example, I want the "Gear GmbH" project (the ID of the project is: 34580)
# to have a 1.5 hour budget and the "Fixture Company" (project ID: 8475) project to have
# a 5 hour budget.
project_budgets = {
  34580 => 1.5,
  8475 => 5
}


# Loop through all the projects, updating the budget for each one.
project_budgets.each do |project_id, hours|

  # parse the URI we will call to update the project.
  # See: developer.letsfreckle.com/projects.html#update
  url = URI.parse("https://#{subdomain}.letsfreckle.com/api/projects/#{project_id}.json")

  # Establish a connection with the Freckle API, using HTTPS and SSL

  https = Net::HTTP.new(url.host, url.port)
  https.use_ssl = true

  # First, we will get the details for the project.
  # We need to create a new request and set the correct headers
  request = Net::HTTP::Get.new(url.path)
  request.add_field("X-FreckleToken", api_key)
  request.add_field("Content-Type", "application/json")

  response = https.request(request)

  #check if the API request was successful.
  abort("ERROR: Your API key or account name are incorrect.") if(response.code == "401")

  unless (response.code == "200")
    puts("ERROR: Unable to get the details for project `#{project_id}`. The error was: #{response.code} #{response.message}")
    next
  end

  project_details = JSON.parse(response.body)


  # Now calculate how many hours we need to add to the budgeted minutes for the project
  # the easiest way to calculate this is to subtract the remaining minutes of the current
  # budget from the budget you want the project to have. If the project is over budget,
  # the remaining minutes will be negative and we will add enough minutes to compensate.
  # We add these minutes (whether positive or negative) to the total number of billable
  # minutes in the project

  # Formula: minutes_to_add = desired_budget - remaining_minutes
  # Examples:
  # 1) Desired budget: 100 minutes. Remaining minutes: 50 minutes.  Minutes to add: 50  minutes (100 - 50    = 50)
  # 2) Desired budget: 100 minutes. Remaining minutes: -50 minutes. Minutes to add: 150 minutes (100 - (-50) = 150)
  # 3) Desired budget: 100 minutes. Remaining minutes: 100 minutes. Minutes to add: 0   minutes (100 - 100   = 0)
  # 4) Desired budget: 50  minutes. Remaining minutes: 100 minutes. Minutes to add: -50 minutes (50 - 100   = -50)
  #
  # Formula: budget_minutes = (billable_minutes + (remaining_minutes + minutes_to_add))
  # Examples:
  # 1) Billable Minutes: 300 minutes. budget_minutes: 400 (300 + (50  + 50 ) = 400)
  # 2) Billable Minutes: 300 minutes. budget_minutes: 400 (300 + (-50 + 150) = 400)
  # 3) Billable Minutes: 300 minutes. budget_minutes: 400 (300 + (100 + 0  ) = 400)
  # 4) Billable Minutes: 300 minutes. budget_minutes: 350 (300 + (100 + -50) = 350)

  billable_minutes = project_details["project"]["billable_minutes"].to_i
  remaining_minutes = project_details["project"]["remaining_minutes"].to_i
  minutes_to_add = (hours * 60) - remaining_minutes

  budget_minutes = (billable_minutes + (remaining_minutes + minutes_to_add))

  # Now it's time to update the project!
  # We need to create a new request and set the correct headers
  request = Net::HTTP::Put.new(url.path)
  request.add_field("X-FreckleToken", api_key)
  request.add_field("Content-Type", "application/json")

  # Time to create the body of the update
  request_body = {
    :project => {
      :budget_minutes => budget_minutes
    }
  }
  request.body = JSON.generate(request_body)

  # Now update the project and print out a helpful message
  response = https.request(request)

  abort("ERROR: You cannot update projects.") if(response.code == "403")

  if(response.code == "200")
    puts "Project '#{project_details["project"]['name']}' now has #{hours} hours in its budget"
  else
    puts "ERROR: Unable to update '#{project_details["project"]['name']}'. The error was: #{response.code} #{response.message}"
  end
end