require 'sinatra'
require 'sinatra/reloader' if development?
require 'httparty'
require 'json'
require 'dotenv'
require 'byebug'
Dotenv.load
This is a Sinatra application that integrates with the Control API. Sinatra is a small Ruby web application framework that provides a DSL (domain specific language) for handling HTTP requests like get
and post
. It should be easy to read even if you don’t read Sinatra’s documentation.
require 'sinatra'
require 'sinatra/reloader' if development?
require 'httparty'
require 'json'
require 'dotenv'
require 'byebug'
Dotenv.load
This class uses a library called HTTParty to connect to the Control API. All API responses are JSON. HTTParty
automatically detects this and parses into a Ruby object.
For more information, see the HTTParty website.
class ControlAPI
include HTTParty
base_uri ENV['CONTROL_API_BASE_URI']
basic_auth ENV['CONTROL_API_KEY'], ENV['CONTROL_API_SECRET']
Set the ‘Content-Type’ header to ‘application/json’ to ensure that the API accepts and returns JSON. This is currently the only supported format, but this will ensure you still get JSON if the API supports XML in the future.
headers 'Content-Type' => 'application/json'
end
helpers do
def parsed_body
request.body.rewind
::JSON.parse(request.body.read)
end
end
The root path in this application simply provides navigation.
erb :view_name
renders the file in views/view_name.erb
. For example, this will end up rendering views/root.erb
.
get '/' do
erb :root
end
Check the API status. Useful for testing authentication without knowing other information.
GET /v1/status
{"description":"up"}
The request was not properly authenticated.
description
: A text description of the API state.error
: A text description of any error in the API call.get '/status' do
status = ControlAPI.get('/v1/status.json').parsed_response
if status['error']
"API error: #{status['error']}"
else
"API status: #{status['description']}"
end
end
Get all users, optionally filtering by emails, external employee IDs, or manager emails
GET /v1/users
GET /v1/users?email[]=gwashington@example.com&gbush@example.com
GET /v1/users?employee_id[]=1234
GET /v1/users?manager_email[]=mwashington@example.com
{
"users": [
{
// Content from GET /v1/users/:email
'email': 'gwashington@example.com',
...
},
{
'email': gbush@example.com',
...
}
]
}
get '/users' do
users = ControlAPI.get('/v1/users', query: params)
erb :'users/index', locals: users.to_h
end
Create a new user and send an invitation for setting password, etc.
POST /v1/users
Content-Type: application/json
{
"user": {
"email": "abe@whitehouse.gov",
"first_name": "Abraham",
"last_name": "Lincoln"
}
}
The following fields are allowed:
email
: Requiredfirst_name
: Requiredlast_name
: Requiredmanager_email
title
employee_id
review_on
started_on
For field descriptions, please see GET /v1/users/:email
.
Refer to GET /v1/users/:email
response.
{
"errors": {
"email": [
"is invalid",
]
}
}
get '/users/new' do
erb :'users/new'
end
post '/users' do
user = ControlAPI.post('/v1/users', body: params.to_json)
case user.response.code
when '201'
[200, erb(:'users/created', locals: { email: user['email'] })]
when '422'
[422, erb(:errors, locals: { errors: user['errors'] })]
else
[500, 'There was an error while processing your request']
end
end
Get an individual user by their email
{
"path": "/v1/users/gwashington@example.com",
"email": "gwashington@example.com",
"first_name": "George",
"last_name": "Washington",
"created_at": "1732-02-22T12:34:56Z",
"updated_at": "1799-12-14T12:34:56Z",
"review_on": "2076-07-04",
"started_on": "1789-04-30",
"manager_path": "/v1/users/mwashington@example.com",
"manager_email": "mwashington@example.com",
"title": "President of the United States",
"administrator": true,
"employee_id": "1",
}
path
: API path for this useremail
: Primary emailfirst_name
: Personal namelast_name
: Surnamecreated_at
: ISO8601 datetime of the creation of this user, in UTCupdated_at
: ISO8601 datetime of the time at which this user was updated, in UTCreview_on
: The ISO8601 date for the next review of this userstarted_on
: The ISO8601 date when this user’s employment startedmanager_path
: The API path for the user’s managermanager_email
: The email address of the user’s managertitle
: The job title of the useradministrator
: Whether or not the user has administrator access for their organizationemployee_id
: (string) This is the external employee ID of the user. The value is arbitrary and is assigned by their organization. However, it must be unique to their organization.
get '/users/:email' do
user = ControlAPI.get("/v1/users/#{params[:email]}")
case user.response.code
when '200'
erb :'users/show', locals: user.to_h
when '404'
[404, 'Not found']
else
[500, 'There was an error while processing your request']
end
end
Updates a user. Note that changing a user’s email address will affect their identification in other API calls, as well as the email they use to log in.
Refer to POST /v1/users
request. NOTE: you can omit keys as necessary
Refer to GET /v1/users/:email
response
get '/users/:email/edit' do
user = ControlAPI.get("/v1/users/#{params[:email]}")
erb :'users/edit', locals: user.to_h
end
post '/users/:email' do
user = ControlAPI.patch("/v1/users/#{params[:email]}", body: params.to_json)
case user.response.code
when '200'
erb :'users/show', locals: user.to_h
when '422'
[422, erb(:errors, locals: { errors: user['errors'] })]
when '404'
[404, 'Not found']
else
[500, 'There was an error while processing your request']
end
end
“Soft delete” the user by disabling them. Associated records, such as completed ToDos, are not deleted.
post '/users/:email/delete' do
user = ControlAPI.delete("/v1/users/#{params[:email]}")
case user.response.code
when '204'
[200, erb(:'users/deleted')]
when '422'
[422, erb(:errors, locals: { errors: user['errors'] })]
when '404'
[404, 'Not found']
else
[500, 'There was an error while processing your request']
end
end
Get all the TemplateToDos for your organization. NOTE: not filtered by enabled/disabled state.
GET /v1/template_to_dos # GET /v1/template_to_dos?tags[]=annual&tags[]=security
tags
: Only return TemplateToDos that are tagged with all of the specified tags.{
"template_to_dos": [
{
"uuid": "12345678-1234-5678-1234-567812345678",
"name": "Review server logs",
"tags": ["security", "annual", "training"]
}
]
}
template_to_dos
: an Array of TemplateToDos, or an empty array []
if none match the given criteriauuid
: UUID for each TemplateToDo.name
: The human-readable name for each ToDo.tags
: The tags for each TemplateToDo, as an array of strings. If there are no tags, it will be an empty array.get '/template_to_dos' do
template_to_dos = ControlAPI.get("/v1/template_to_dos", :query => params)
erb :template_to_dos, :locals => template_to_dos
end
Asynchronously distribute a ToDo to the given assignees. (The work happens in a job queue.)
POST /v1/distributed_to_dos
Content-Type: application/json
{
"distributed_to_do": {
"template_to_do_uuid": "12345678-1234-5678-1234-567812345678",
"due_on": "2013-11-29",
"assignee_emails": ["bobama@example.com", "gwbush@example.com", "bclinton@example.com"],
"field_values": {"field1": "value1", "field2": "value2"},
}
}
distributed_to_do
: Required. Holds parameters for the DistributedToDo.template_to_do_uuid
: Required. The UUID for the TemplateToDo that will be distributed. This can be found via GET /v1/template_to_dos
, or in Continuity Control under “Settings”.due_on
: Required. ISO8601 date of when the DistributedToDo is due, in your configured Time Zone.assignee_emails
: Required. An Array of email addresses of Users that will receive the DistributedToDos.field_values
: Dictionary (Object) of values to pre-fill in the DistributedToDo. Field names are available in Continuity Control under “Settings”.{
"uuid":"f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"path":"/v1/distributed_to_dos/f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
}
The request was not properly authenticated.
{
"errors": {
"template_to_do_uuid": [
"does not exist",
],
"assignee_emails": [
"has email alice@example.com which does not exist for this organization",
"has email bob@example.com which does not exist for this organization"
],
"due_on": [
"could not be parsed"
]
}
}
uuid
: A UUID for the DistributedToDo which will be created asynchronously. Please include it in any bug reports to Continuity.path
: The path where the DistributedToDo will be available once created.errors
: An object with one key per request field and an array of all the validation errors that apply to that field. The exact text of the error messages is not guaranteed and may change without warning.get '/distributed_to_dos/new' do
erb :distributed_to_dos_new
end
post '/distributed_to_dos' do
distributed_to_do = ControlAPI.post('/v1/distributed_to_dos',
:body => params.to_json)
case distributed_to_do.response.code
when '202'
[200, erb(:distributed_to_dos_post, :locals => distributed_to_do)]
when '422'
[422, erb(:errors, :locals => distributed_to_do)]
else
[500, 'There was an error while processing your request']
end
end
Get the current state of a distributed_to_do as found by an uuid
.
GET /v1/distributed_to_dos/f81d4fae-7dec-11d0-a765-00a0c91e6bf6
{
"uuid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"name": "Review server logs",
"created_at": "2013-11-02T12:34:46.000Z",
"completed_at": null,
"due_on": "2013-11-08",
"tags": ["security", "annual", "training"],
"assignments": [
{
"email": "bobama@example.com",
"finished_on": "2013-11-07",
"fields": [
{
"uuid": "8edfc480-a174-0135-509d-1e3560338d6d",
"todo_script_id": null,
"label": "I was able to generate this report.",
"value": true,
"disabled": false
}
]
},
{
"email": "bclinton@example.com",
"finished_on": null,
"fields": [
{
"uuid": "7fcfc480-a174-0135-509d-1e3560338d6d",
"todo_script_id": null,
"label": "I was able to generate this report.",
"value": null,
"disabled": false
}
]
}
]
}
The request was not properly authenticated.
Returned when the resource does not exist. Note that after a POST
to /v1/distributed_to_dos
that gives a 202
, /v1/distributed_to_dos/:uuid
would return a 404
until the resource is asynchronously created.
uuid
: UUID for this DistributedToDo.name
: The human-readable name for this DistributedToDo.created_at
: ISO8601 datetime of the creation of this DistributedToDo, in UTC.completed_at
: ISO8601 datetime of when the DistributedToDo was completed, in UTC. This is when all the assignments have been finished. May be null
.due_on
: ISO8601 date of when the DistributedToDo is due, in your configured Time Zone.tags
: The tags for this DistributedToDo, as an array of strings. If there are no tags, it will be an empty array.assignments
: Arrayemail
: User email of DistributedToDo assignmentfinished_on
: ISO8601 date on which the assignment was completed (in UTC), or null
if not completedfields
: Arrayuuid
: UUID for the Fieldtodo_script_id
: Friendly reference id for the Field,label
: The human-readable name for the Fieldvalue
: The value submitted by the assigneedisabled
: Boolean, if the Field is disabled it is not visible to the assigneeget '/distributed_to_dos/:uuid' do
distributed_to_do = ControlAPI.get("/v1/distributed_to_dos/#{params[:uuid]}")
case distributed_to_do.response.code
when '200'
erb :distributed_to_do, :locals => distributed_to_do.to_h # NOTE: this gives us locals that are keys in the distributed_to_do response
when '404'
[404, 'Not found']
else
[500, 'There was an error while processing your request']
end
end
Get all the DistributedToDos for your organization. Each DistributedToDo in this “collection” GET request is in the same format as the “member” GET request.
GET /v1/distributed_to_dos
GET /v1/distributed_to_dos?created_after=2013-11-02
GET /v1/distributed_to_dos?created_after=2013-11-02&created_before=2013-11-07
GET /v1/distributed_to_dos?created_before=2013-11-07
GET /v1/distributed_to_dos?late=true
GET /v1/distributed_to_dos?complete=true
GET /v1/distributed_to_dos?created_after=2013-11-02&created_before=2013-11-07&late=true&complete=false
GET /v1/distributed_to_dos?tags[]=annual&tags[]=security
created_after
: ISO8601 date of exclusive lower bound of created_at
time.created_before
: ISO8601 date of exclusive upper bound of created_at
time.late
: When true
, respond with only “late” DistributedToDos. When false
, respond with only “on time” DistributedToDos. When not present, do not filter on lateness.complete
: When true
, respond with only “complete” DistributedToDos. When false
, respond with only “incomplete” DistributedToDos. When not present, do not filter on completeness.tags
: Only return DistributedToDos that are tagged with all of the specified tags.late
and complete
can be combined to filter:
late=false&complete=false # incomplete and on time
late=false&complete=true # completed and on time
late=true&complete=false # incomplete and late (what most users will want)
late=true&complete=true # completed and late
{
"distributed_to_dos": [
// Content from GET /v1/distributed_to_dos/:uuid
]
}
distributed_to_dos
: an Array of DistributedToDos, or an empty array []
if none match the given criteriaget '/distributed_to_dos' do
one_week_ago_params = { :created_after => Date.today - 7 }
filter_params = params.empty? ? one_week_ago_params : params
distributed_to_dos = ControlAPI.get('/v1/distributed_to_dos', :query => filter_params)
erb :distributed_to_dos, :locals => distributed_to_dos
end
Webhooks provide information about events in near real-time. You provide a URL, and we’ll POST
to it as events take place. When a HTTP 5XX
response occurs, the Webhook is retried with an incremental backoff.
Our webhooks have the following format:
{
"event": "EventName",
"fired_at": "2014-06-24T15:32:05Z",
"data": {
// Depends on event, see below
}
}
event
: A named event, as documented belowfired_at
: When the webhook was fireddata
: an Object of data for the given eventThe receiver of a webhook MUST check event
on each POST
. An unknown event
MUST be ignored.
Examples of why this behavior is required:
event
is not checked, and the receiver only looks at the data.name
attribute, it could be a ToDo’s name instead of a user’s name.event
is not checked, a user could have been updated instead of created. The receiver could then take action on an “updated” event that was only intended for a “created” event (e.g., sending a welcome email).For a contrived example, if there were a VoteCast
event, the webhook would provide data like the following in two separate POST
s:
First POST
:
{
"event": "VoteCast",
"fired_at": "2000-11-07T15:32:05Z",
"data": {
"full_name": "Al Gore",
"party": "Democrat"
}
}
Second POST
:
{
"event": "VoteCast",
"fired_at": "2000-11-07T15:42:05Z",
"data": {
"full_name": "George W Bush",
"party": "Republican"
}
}
The UserCreated
event fires when a new user is created on Control.
{
"full_name": "George Washington",
"first_name": "George",
"last_name": "Washington",
"email": "gwashington@example.com"
}
full_name
: Formatted name, may be null
first_name
: Personal name, may be null
last_name
: Surname, may be null
email
: Primary emailThe DistributedToDoCompleted
events fires when all the assignments of a ToDo are completed. That is, when the ToDo as a whole is completed, rather than an individual user’s assignment.
The data is the same for GET /v1/distributed_to_dos/:uuid
. Please refer to its documentation.
post '/webhook' do
event = parsed_body['event']
data = parsed_body['data']
case event
when 'DistributedToDoCompleted'
"Good job, team! We completed the #{data['name']} ToDo!"
when 'UserCreated'
"Nice to meet you, #{data['full_name']}!"
end
end