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.
| 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.
