Generalized emission calculation API

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.

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:

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.