Changesets

Changesets are used to group sets of changes to any number of records. Changesets are automatically generated when making changes through the mobile and web apps (changeset_id), and are optional when updating records through the API.

Endpoints

Method	Endpoint	Description	Example
GET	/api/v2/changesets.json	Fetch all changesets.	Get All
GET	/api/v2/changesets/:id.json	Fetch a single changeset.	Get Single
POST	/api/v2/changesets.json	Create a new changeset.	Create
PUT	/api/v2/changesets/:id.json	Update a changeset.	Update
PUT	/api/v2/changesets/:id/close.json	Close a changeset.	Close

Query Parameters

Parameter	Type	Description
page	integer	The page number requested.
per_page	integer	Number of items per page. By default, all requests are paginated to the maximum value of 20,000 items per request.

Properties

Property	Type	Required	Readonly	Description
form_id	string	yes	no	The id of the form associated with the changeset.
metadata	object	no	no	An object containing arbitrary metadata describing the changeset. Often used to log comments, apps, versions and user agents.
min_lat	number	no	yes	The minimum latitude of the spatial extent of the changeset.
max_lat	number	no	yes	The maximum latitude of the spatial extent of the changeset.
min_lon	number	no	yes	The minimum longitude of the spatial extent of the changeset.
max_lon	number	no	yes	The maximum longitude of the spatial extent of the changeset.
number_of_changes	number	no	yes	The number of changed records included in this changeset.
id	string	no	yes	The id for this changeset.
created_at	string	no	yes	Timestamp when the changeset was created.
updated_at	string	no	yes	Timestamp when the changeset was last updated.
created_by	string	no	yes	The name of user who created the changeset.
created_by_id	string	no	yes	The ID of user who created the changeset.
updated_by	string	no	yes	The name of user who last updated the changeset.
updated_by_id	string	no	yes	The ID of user who last updated the changeset.
closed_at	string	no	yes	Timestamp when the changeset was closed.
closed_by	string	no	yes	The name of user who closed the changeset.
closed_by_id	string	no	yes	The ID of user who closed the changeset.
gravatar_email	string	no	yes	The email associated with the gravatar of the user who created the changeset.
number_created	number	no	yes	The number of records created in this changeset.
number_updated	number	no	yes	The number of records updated in this changeset.
number_deleted	number	no	yes	The number of records deleted in this changeset.

Validations

The following properties must be included in order to create/update a changeset object in our system. Any validation errors will return a 422 and an object with a list of validation errors.

Required Properties

Property	Type	Description	Example
form_id	string	The id of the form associated with the changeset.	"8821a0d5-e767-47a9-815b-c72bdfa64043"

Example validation response if form_id is not included:

{
  "changeset": {
    "errors": {
      "form_id": ["does not exist or you don't have access to it"]
    }
  }
}

Notes

• The entire changeset object is required when making an update. Omitting fields with existing data will result in data loss! The typical workflow for updating an existing changeset is to fetch the changeset object, modify it, and then submit the PUT request.

Response

{
  "changeset": {
    "metadata": {
      "comment": "Update record",
      "app_created_by": "Spatial Networks",
      "app_name": "Fulcrum Web",
      "app_version": "",
      "app_build": "",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/33.0.1750.152 Safari/537.36"
    },
    "min_lat": 42.82398681,
    "max_lat": 42.82398681,
    "min_lon": -73.89601931,
    "max_lon": -73.89601931,
    "number_of_changes": 1,
    "id": "8821a0d5-e767-47a9-815b-c72bdfa64043",
    "created_at": "2014-03-17T19:45:10Z",
    "updated_at": "2014-03-17T19:45:11Z",
    "created_by": "Bryan McBride",
    "created_by_id": "50633f84a934480d260001db",
    "updated_by": "Bryan McBride",
    "updated_by_id": "50633f84a934480d260001db",
    "closed_at": "2014-03-17T19:45:11Z",
    "closed_by": "Bryan McBride",
    "closed_by_id": "50633f84a934480d260001db",
    "form_id": null,
    "gravatar_email": "",
    "number_created": 0,
    "number_updated": 1,
    "number_deleted": 0
  }
}

Examples

Get all Changesets

cURL

Python

JavaScript

Ruby

curl --request GET 'https://api.fulcrumapp.com/api/v2/changesets.json?per_page=5&page=1' \
--header 'Accept: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

changesets = fulcrum.changesets.search(url_params={'per_page':5,'page':1})

for changeset in changesets['changesets']:
  # print(changeset) # entire changeset
  print(changeset['id']) # just the changeset ID

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

client.changesets.all({'per_page':5,'page':1})
  .then((page) => {
    page.objects.forEach(changeset => {
      // console.log(changeset);  // entire changeset
      console.log(changeset.id); //  just the changesets ID
    });
  })
  .catch((error) => {
    console.log(error.message);
  });

require 'fulcrum'

client = Fulcrum::Client.new('{token}')

changesets = client.changesets.all({'per_page':5,'page':1})

for changeset in changesets.objects do
  # puts changeset # entire changeset
  puts changeset['id'] # just the changeset ID
end

Get a single Changeset by ID

cURL

Python

JavaScript

Ruby

curl --request GET 'https://api.fulcrumapp.com/api/v2/changesets/:id.json' \
--header 'Accept: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

changeset = fulcrum.changesets.find('{id}')

print(changeset['changeset'])

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

client.changesets.find('{id}')
  .then((changeset) => {
    console.log(changeset);
  })
  .catch((error) => {
    console.log(error.message);
  });

require 'fulcrum'

client = Fulcrum::Client.new('{token}')

changeset = client.changesets.find('{id}')

puts changeset

Create a new Changeset

cURL

Python

JavaScript

Ruby

curl --request POST 'https://api.fulcrumapp.com/api/v2/changesets.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: {token}' \
--data '{
  "changeset": {
    "form_id": "{id}",
    "metadata": {
      "comment": "Daily status update",
      "app_created_by": "ACME Engineering",
      "app_name": "Fulcrum Update Script"
    }
  }
}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

obj = {
  "changeset": {
    "form_id": "{id}",
    "metadata": {
      "comment": "Daily status update",
      "app_created_by": "ACME Engineering",
      "app_name": "Fulcrum Update Script"
    }
  }
}

changeset = fulcrum.changesets.create(obj)
print(changeset['changeset']['id'] + ' has been created!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

const obj = {
  "form_id": "{id}",
  "metadata": {
    "comment": "Daily status update",
    "app_created_by": "ACME Engineering",
    "app_name": "Fulcrum Update Script"
  }
};

client.changesets.create(obj)
  .then((changeset) => {
    console.log(changeset.id + ' has been created!');
  })
  .catch((error) => {
    console.log(error.message);
  });

require 'fulcrum'

client = Fulcrum::Client.new('{token}')

changeset = {
  "form_id"=>"{id}",
  "metadata"=>{
    "comment"=>"Daily status update",
    "app_created_by"=>"ACME Engineering",
    "app_name"=>"Fulcrum Update Script"
  }
}

response = client.changesets.create(changeset)

puts response['id'] + ' has been created!'

Update a Changeset

cURL

Python

JavaScript

Ruby

curl --request PUT 'https://api.fulcrumapp.com/api/v2/changesets/:id.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: {token}' \
--data '{
  "changeset": {
    "form_id": "{id}",
    "metadata": {
      "comment": "Update status",
      "app_created_by": "ACME Engineering",
      "app_name": "Fulcrum Update Script"
    }
  }
}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

obj = {
  "changeset": {
    "form_id": "{id}",
    "metadata": {
      "comment": "Update status",
      "app_created_by": "ACME Engineering",
      "app_name": "Fulcrum Update Script"
    }
  }
}

changeset = fulcrum.changesets.update('{id}', obj)
print(changeset['changeset']['id'] + ' has been updated!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');

const obj = {
  "form_id": "{id}",
  "metadata": {
    "comment": "Update status",
    "app_created_by": "ACME Engineering",
    "app_name": "Fulcrum Update Script"
  }
};

client.changesets.update('{id}', obj)
  .then((changeset) => {
    console.log(changeset.id + ' has been updated!');
  })
  .catch((error) => {
    console.log(error.message);
  });

require 'fulcrum'

client = Fulcrum::Client.new('{token}')

changeset = {
  "form_id"=>"{id}",
  "metadata"=>{
    "comment"=>"Update status",
    "app_created_by"=>"ACME Engineering",
    "app_name"=>"Fulcrum Update Script"
  }
}

response = client.changesets.update('{id}', changeset)

puts response['id'] + ' has been updated!'

Close a Changeset

cURL

Python

JavaScript

Ruby

curl --request PUT 'https://api.fulcrumapp.com/api/v2/changesets/:id/close.json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-ApiToken: {token}'

from fulcrum import Fulcrum
fulcrum = Fulcrum('{token}')

fulcrum.changesets.close('{id}')
print('{id} has been closed!')

const { Client } = require('fulcrum-app');
const client = new Client('{token}');
  
client.changesets.close('{id}')
  .then((changeset) => {
    console.log('{id} has been closed!');
  })
  .catch((error) => {
    console.log(error.message);
  });

require 'fulcrum'

client = Fulcrum::Client.new('{token}')

client.changesets.close('{id}')

puts '{id} has been closed!'