Update a project budget from your financial tool

Context

This example will give you guidelines to:

Update a project data, like the budget

It can be used in the following scenario:

Synchronize the budgets you already track on your financial software with your AirSaas projects

Prerequisites

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

Example

Let's say that you use a financial software where your track the budget planned and spent on each project. Using the APIs provided by your software and using AirSaas API, you will be able to push that information directly into AirSaas.

In this example, we will see the overall logic to synchronize the capex and opex budgets logged in another solution into AirSaas project budgets.

Step 1 - Read budgets on your Financial software

Using the API of your Financial software directly, or using an existing integration like Zapier, you need to fetch the budget per project. 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 budget planned and consumed, by capex and opex, for each project.

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

{
    "project_name": "Projet A",
    "project_id": 425638,
    "capex": {
        "planned": 15000,
        "used": 12000
    },
    "opex": {
        "planned": 1000,
        "used": 0
    },
}

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. You will need to extract the totals for each value, not incremental values, as AirSaas only supports that at the moment.

Step 2 - Project Mapping

For each project on your financial 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 financial 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 financial 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",
    "capex": {
        "planned": 15000,
        "used": 12000
    },
    "opex": {
        "planned": 1000,
        "used": 0
    },
}

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 financial software, you will know which AirSaas project Id to update.

Step 3 - Update a project budgets on AirSaas

Now that your mapping is in order, you can work on the synchronization.

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

immediately trigger a synchronization with AirSaas whenever the budgets change 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 financial tool, including capex/opex budgets on that project. Depending on the budget unit exposed by your tool, you might need to convert it to a value compatible with AirSaas API. AirSaas only supports €uros, represented as a floating number.
then make a call to AirSaas API using the Update a project 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
- For ex, to update project ACM-P42 with all possible budgets values, the API request is as follow:

curl --request PATCH \
     --url https://api.airsaas.io/v1/projects/ACM-P42/ \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "budget_capex": 15000,
     "budget_opex": 1000,
     "budget_capex_used": 12000,
     "budget_opex_used": 200
}
'

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

const options = {
  method: 'PATCH',
  url: 'https://api.airsaas.io/v1/projects/ACM-P42/',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    Authorization: 'Api-Key YOUR_API_KEY_HERE'
  },
  data: {
    budget_capex: 15000,
    budget_opex: 1000,
    budget_capex_used: 12000,
    budget_opex_used: 200
  }
};

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/"

payload = {
    "budget_capex": 15000,
    "budget_opex": 1000,
    "budget_capex_used": 12000,
    "budget_opex_used": 200
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

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

print(response.text)

And that's it!

You don't have to provide all those values, they are all optional. Only the ones you provide will be use to update the project.