Synchronize teams efforts with your Time Tracking software

Context

This example will give you guidelines to:

Read your workspace's teams
Read and write efforts for a project, by team

It can be used in the following scenarios:

Extract projects efforts from AirSaas and push them to another tool
Synchronize the efforts you already track on your Time Tracking software with your AirSaas projects efforts
BI integration

Prerequisites

Before trying out this example, we suggest you to read those guides first:

Example 1

Let's say that you already use a Time Tracking software, like Gryzzly, Tempo or Lucca, where your track the time spent by your teams on each project. Using the APIs provided by those softwares and using AirSaas API, you will be able to push that information directly into AirSaas. Of course that also works with other time tracking tools, or your in-house platform.

In this example, we will see the overall logic to synchronize the time spent logged in another solution into AirSaas project efforts.

Step 1 - Read time spent on your Time Tracking software

Using the API of your Time Tracking software directly, or using an existing integration like Zapier, you need to fetch the time spent per project per team. Depending on the tool you're using and its complexity, you might need the help of developer. Anyhow, for each project that you track on your tool, you must extract the total time spent by your colleagues, consolidated by team.

Example of data you should be able to extract for one project:

{
    "project_name": "Projet A",
    "project_id": 425638,
    "time_spent": {
        "team_1": 12.5,
        "team_4": 24,
        "team_5": 33.5
    }
}

Of course, depending on the tool or the integration, the data structure might be totally different. It will be up to you to adapt the current example to your actual situation. The rest of this example will use the above structure to illustrate the synchronization logic.

Step 2 - Project Mapping

For each project on your time tracking software that you want to synchronize with AirSaas, you need to know which AirSaas project corresponds to it, so that you can update the right project on AirSaas. You need to do that mapping before you can synchronize any data between 2 platforms.

There are 2 ways you can do the mapping:

[preferred solution] if your time tracking software allows you to create custom properties for your projects, create a new one called AirSaas Id and then update manually all your projects by adding the Id of the corresponding AirSaas project. This Id will later be used with the AirSaas API to update the project. AirSaas conveniently allows you to use all the projects endpoints with either the UUID of the project (ex 4bc78756-0171-4667-be0f-4903f5186992) or its Short Id (ex: ACM-P42). We think that using the Short Id will make the experience better on your time tracking software. The above data example might look like this if you have a custom property:

{
    "project_name": "Projet A",
    "project_id": 425638,
    "airsaas_id": "ACM-P42",
    "time_spent": {
        "team_1": 12.5,
        "team_4": 24,
        "team_5": 33.5
    }
}

you can develop your own mapping table, outside of your tools, for example in the script responsible for the synchronization. The downside is that whenever you add a new project, you will also have to update that mapping table.

With both ways, when you start processing a project from your time tracking software, you will know which AirSaas project Id to update.

Step 3 - Teams mapping

On AirSaas, you will update efforts for a project by team. See the update effort endpoint that we will use for more details. The endpoint works by specifying for which team you would like to update the efforts. The team identification is using its AirSaas UUID. So in order to update the effort of a project for a team, when making the AirSaas API call, you will need to know the AirSaas team UUID.

Just like for the projects in step 2, you will need to have some sort of mapping for the teams, to map the teams present in your time tracking software with the ones present on AirSaas, using their respective Ids. There are several ways to manage such a mapping, like team custom properties or a custom script. This choice is outside the scope of this example, we will leave that to you.

To get all the AirSaas teams and their UUIDs, call the List all teams endpoint. Careful, the response is paginated, so might need to make several calls to get all teams. See Pagination for more details.

curl --request GET \
     --url https://api.airsaas.io/v1/teams/ \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

const axios = require('axios').default;

const options = {
  method: 'GET',
  url: 'https://api.airsaas.io/v1/teams/',
  headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

url = "https://api.airsaas.io/v1/teams/"

headers = {
    "accept": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

response = requests.get(url, headers=headers)

print(response.text)

You will get a response like:

[
    {
        "id": "5a55682d-1416-4398-96b6-2f7aef90e3ca",
        "name": "A Team",
        "created_at": "2022-06-23T19:34:44.984+00:00"
    },
    {
        "id": "a5c26750-e675-4c0a-bb16-8ba5ead5c688",
        "name": "B Team",
        "created_at": "2022-06-23T20:35:44.984+00:00"
    },
    {
        "id": "020e0f39-0d40-495d-97fb-651d5d29268a",
        "name": "C Team",
        "created_at": "2022-06-23T21:31:44.984+00:00"
    },
    etc...
]

Step 4 - Update a project efforts on AirSaas

Now that your mappings are in order, you can work on the synchronization.

Depending on your Time Tracking software capabilities, you will be able to either:

immediately trigger a synchronization with AirSaas whenever the time spent changes on your tool: that's possible if your tool has a webhook mechanism in place
synchronize all projects with a frequency of your choosing, for ex daily

The synchronization logic is as follow:

for each project to sync, fetch the data from your time tracking tool, including time spent per team on that project. Depending on the time spent unit exposed by your tool, you might need to convert it to a value compatible with AirSaas API. AirSaas only supports days, represented as a floating number.
then for each team of that project for which you have time spent to update, make a call to the Update project efforts endpoint. To make that call you will have to use your mappings to get the Ids that AirSaas can use:
- Convert your tool project Id to an AirSaas project UUID or project Short Id
- Convert your tool team Id to an AirSaas team UUID
For ex, to update project ACM-P42 for team 5a55682d-1416-4398-96b6-2f7aef90e3ca with a new consumed effort of 42 man-days, the API request is as follow:

curl --request POST \
     --url https://api.airsaas.io/v1/projects/ACM-P42/update_effort/ \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "effort_used": 42,
     "team": "5a55682d-1416-4398-96b6-2f7aef90e3ca"
}
'

const axios = require('axios').default;

const options = {
  method: 'POST',
  url: 'https://api.airsaas.io/v1/projects/ACM-P42/update_effort/',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: 'Api-Key YOUR_API_KEY_HERE'
  },
  data: {effort_used: 42, team: '5a55682d-1416-4398-96b6-2f7aef90e3ca'}
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

url = "https://api.airsaas.io/v1/projects/ACM-P42/update_effort/"

payload = {
    "effort_used": 42,
    "team": "5a55682d-1416-4398-96b6-2f7aef90e3ca"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

And that's it!

This API endpoint also allows you to define initial efforts for each project team. If you have that information in your external tool, you can also synchronize it if you want. The property to update is effort.

Example 2

You can of course synchronize the effort information the other way around, and use AirSaas as the reference to push it to an external service.

The above logic remains the same, you will need some sort of mapping for teams and projects.

To read all the projects of your workspace, you need to use the List all projects endpoint.

To read all the teams and efforts attached to a project, you will need to use the List a project efforts endpoint.