Last updatedJul 22, 2019

Cloud Admin APIs Cookbook

Here is a task you can do by combining two of the cloud admin REST APIs.

Update a user's department

To change information about specific users you can use the organizations REST API to get the users and then use the user management REST API to perform more detailed operations on each user. This example shows how to select a user by name and change the user's department value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// This code sample uses the 'request' library:
// https://www.npmjs.com/package/request
var request = require('request');
var users;
var newDepartment = "Marketing";

var orgsOptions = {
   method: 'GET',
   url: 'https://api.atlassian.com/admin/v1/orgs/<Org ID>/users',
   auth: { bearer: '<API key>' },
   headers: {
      'Accept': 'application/json'
   }
};

function getUsers(options, callback){ 
   users = request(options, function (error, response, body) {
      if (error) throw new Error(error);
      callback(null, JSON.parse(body)); 
   });
}

getUsers(orgsOptions, function(err, body) {
  if (err) {
    console.log(err);
  } else {
    for (var user in body.data){
      if(body.data[user].name == "Lila Smalls"){
        var bodyData = `{
          "extended_profile": {
          "department": "` + newDepartment + `"
            }
          }`;

        var usersOptions = {
          method: 'PATCH',
          url: 'https://api.atlassian.com/users/' + body.data[user].account_id + '/manage/profile',
          auth: { bearer: '4oJByAvTCS9o4o2ZVlI5' },
          headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
            },
          body: bodyData
        };

        request(usersOptions, function (error, response, body) {
          if (error) throw new Error(error);
        });
      }
    }
  }
});

Automate audit log backup exports

Audit logs allow admin users to track event activity in Atlassian products. You can export these logs as CSV files manually, or use the REST API to automatically export logs to another storage service or IT platform.

Audit logs in Atlassian track activity going back up to 180 days. To save logs past 180 days, you'll have to export and save the logs in another system.

The following example script uses the Organizations API to get an audit log of events, then creates a JSON file for each event. The event file names will follow the format <year>/<month>/<day>/<eventId>.json. Each event file from that day will be saved in a directory titled <year>/<month>/<day>/.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// This code sample uses the 'request' and 'fs' libraries:
// https://www.npmjs.com/package/request
// https://www.npmjs.com/package/fs
const request = require('request');
const fs = require('fs');

function getEvents(from, to, cursor) {
  return new Promise(function(resolve, reject) {
    var options = {
      method: 'GET',
      url: 'https://api.atlassian.com/admin/v1/orgs/<Org ID>/events',
      qs: {
        from: from,
        to: to,
        cursor: cursor
      },
      auth: { bearer: '<API key>' },
      headers: { 'Accept': 'application/json' }
    };

    request(options, function(error, response, body) {
      if (error) throw new Error(error);

      var body = JSON.parse(body);
      for(var i = 0; i < (body.data || []).length; i++) {
          saveEventToFile(body.data[i]);
      }

      if (body.meta && body.meta.next) {
        getEvents(from, to, body.meta.next)
          .then(resolve);
      }
    });
  });
}

function saveEventToFile(event) {
  var baseDirectory = '<Base Directory>';
  
  var eventDate = new Date(event.attributes.time);
  var year = eventDate.getFullYear();
  var month = eventDate.getMonth() + 1;
  var day = eventDate.getDate();
  var eventId = event.id;

  fs.mkdirSync(`${baseDirectory}/${year}/${month}/${day}/`, {recursive: true});
  fs.writeFileSync(`${baseDirectory}/${year}/${month}/${day}/${eventId}.json`, JSON.stringify(event));
}

var today = new Date();
today.setHours(0,0,0,0);
var yesterday = new Date(today.getFullYear(),today.getMonth(),today.getDate()-1,0,0,0,0);
getEvents(yesterday.getTime(), today.getTime(), null);

You can modify this example script to export weekly or monthly instead of every day.

If you decide to export logs to another system, you are responsible for maintaining security compliance within the exported data.