Generalized emission calculation API

Microsoft Cloud for Sustainability Tech Summit November 2024.

You can use the msdyn_runEmissionCalculationService API to calculate emissions for activities using a calculation model without creating a calculation profile. As a subscriber of the Microsoft Sustainability Manager, you can use this URL to access the API:

{organization url}/api/data/v{version}/msdyn_runEmissionCalculationService

In this URL, organization url refers to the base URL of the organization Microsoft Sustainability Manager is installed on and the user can access. Version refers to the web API version (for example, 9.2).

Getting entity IDs

There are many ways you can get the IDs for entities such as activity data and calculation model. These include XRM WebAPI, the client API, and directly through the entityโ€™s URL on Microsoft Sustainability Manager.

Input parameters

As a Dataverse custom API, the runtime of the generalized emission calculation API is capped at two minutes. Longer calculations time out, so the input size is restricted according to the following table.

Name Type Required? Description
activityIds String array Yes List of IDs of the activity data records to be used in calculation. Up to 500 activity IDs can be included in the input.
calculationModelId String Yes ID of the calculation model to be used in emission calculation.
version String No The version number of the API identifies the version of the API that should be invoked. Currently 1.0.0 is the only available version. If unspecified, the latest version is used.

Output parameters

At the highest level, the output is a JSON string containing a list of generalized emission output entities. For each eligible activity, the output entity might contain evaluated emissions, or the errors encountered during calculation based on if the calculation was successful. Always check the IsErrorRecord flag of an output record before trying to access it.

Generalized emission output entity

The generalized emissions output entity doesn't exist in Dataverse. It's a collection of relevant attributes from the emission entity and the calculation error entity. The generalized emission calculation API returns a list of these entities, with each entity corresponding to an eligible activity data record in the input.

The output entity has the following attributes:

Name Type Description
ActivityId String The ID of the activity data record used for the calculation.
ActivityName String The name of the activity data record used for the calculation.
IsErrorRecord Boolean A boolean value indicating whether the calculation for this given activity encountered errors. If true, calculation failed and the errors encountered can be viewed through the ErrorJson attribute.
ErrorJson String JSON string representing any calculation errors encountered while processing this given activity. This value is null if IsErrorRecord is false.
Name String Name of emission calculated for this activity. This value is null if IsErrorRecord is true.
CH4 Decimal CH4 value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain CH4.
CH4Unit String Name of unit for CH4 value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain CH4.
CO2 Decimal CO2 value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain CO2.
CO2Unit String Name of unit for CO2 value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain CO2.
CO2e Decimal CO2e value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain CO2e.
CO2eUnit String Name of unit for CO2e value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain CO2e.
HFCs Decimal HFCs value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain HFCs.
HFCsUnit String Name of unit for HFCs value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain HFCs.
N2O Decimal N2O value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain N2O.
N2OUnit String Name of unit for N2O value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain N2O.
NF3 Decimal NF3 value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain NF3.
NF3Unit String Name of unit for NF3 value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain NF3.
PFCs Decimal PFCs value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain PFCs.
PFCsUnit String Name of unit for PFCs value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain PFCs.
SF6 Decimal SF6 value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain SF6.
SF6Unit String Name of unit for SF6 value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain SF6.
OtherGHGs Decimal Other greenhouse gases value of emission calculated for this activity. This value is 0 if IsErrorRecord is true or if emission doesn't contain other GHGs.
OtherGHGsUnit String Name of unit for other greenhouse gases value of emission calculated for this activity. This value is null if IsErrorRecord is true or if emission doesn't contain other GHGs.

Examples

In the following example, the API is invoked with a valid activity data ID resulting in a nonerror response.

Input:

{

  "activityDataIds": [
    "decc7c96-9180-ed11-aacf-000d3a1477fdโ€
  ],

  "calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",

  "version": "1.0.0"

}

Output:

[
{
"ActivityId": "decc7c96-9180-ed11-aacf-000d3a1477fd",
"ActivityName": "Passenger car",
"IsErrorRecord": false,
"ErrorJson": null,
"Name": "Employee Commuting 526",
"CH4": 2267.832,
"CH4Unit": "g",
"CO2": 107560.032,
"CO2Unit": "kg",
"CO2e": 108292.541736,
"CO2eUnit": kg,
"HFCs": 0,
"HFCsUnit": null,
"N2O": 2267.832,
"N2OUnit": "g",
"NF3": 0,
"NF3Unit": null,
"PFCs": 0,
"PFCsUnit": null,
"SF6": 0,
"SF6Unit": null,
"OtherGHGs": 0,
"OtherGHGsUnit": null
}
]

In the following example, the API is invoked with an invalid activity data ID resulting in an error response. The activity record in question is missing the cost field, which the calculation model requires in the input. As a result, the output record has an error JSON containing the stack of calculation exceptions encountered while evaluating the record. The service error code of the encountered exceptions can help the user understand what went wrong. In this case, EmissionCalculationActionFieldValueNullBlankException indicates a required field is blank.

Input:

{

  "activityDataIds": [
       "22a8b098-4b8b-ed11-aad1-000d3a5bc56a"
  ],

  "calculationModelId": "0b533a50-399e-ec11-b400-00224823f2de",

  "version": "1.0.0"

}

Output:

[
{ 
    "ActivityId": "22a8b098-4b8b-ed11-aad1-000d3a5bc56a", 
    "ActivityName": null, 
    "IsErrorRecord": true, 
    "ErrorJson": { 
      "ServiceErrorCode": "ActivityCalculationModelExecutionException", 
      "UserMessageParameters": [ 
        "Invalid Fugitive Emissions" 
      ], 
      "InnerException": { 
        "ServiceErrorCode": "EmissionCalculationActionFieldValueNullBlankException", 
        "UserMessageParameters": [ 
          "Action 1" 
        ], 
        "InnerException": { 
          "ServiceErrorCode": null, 
          "UserMessageParameters": null, 
          "InnerException": { 
            "ServiceErrorCode": null, 
            "UserMessageParameters": null, 
            "InnerException": null 
          } 
        } 
      } 
    }, 
    "Name": null, 
    "CH4": 0, 
    "CH4Unit": null, 
    "CO2": 0, 
    "CO2Unit": null, 
    "CO2e": 0, 
    "CO2eUnit": null, 
    "HFCs": 0, 
    "HFCsUnit": null, 
    "N2O": 0, 
    "N2OUnit": null, 
    "NF3": 0, 
    "NF3Unit": null, 
    "PFCs": 0, 
    "PFCsUnit": null, 
    "SF6": 0, 
    "SF6Unit": null, 
    "OtherGHGs": 0, 
    "OtherGHGsUnit": null 
  }] 
]

Invoking Custom APIs

For more information, go to Create and use Custom APIs.