Generalized emission calculation API

مقالة
01/17/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 will 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 may 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	ID of the activity data record used for the calculation.
ActivityName	String	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 non-error 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 is required by the calculation model 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.