Custom factor mappings (preview)

Free trial

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change.

Microsoft Sustainability Manager uses built-in reference data in factor mappings. You can extend the available set of factor mappings with custom factor mappings. For example, you might want to pivot your activity calculations based on factors such as fiscal year or custom region. This article guides you through this advanced configuration, which you must complete in the Power Platform admin center.

Note

The procedures in this article require advanced expertise in Microsoft Dataverse management and APIs. This article doesn't describe common platform operations in detail. Only authorized administrators with full access to the Power Platform admin center can complete these configuration steps.

To extend Sustainability Manager to use custom factor mappings, follow these steps:

• Create extended factor tables
• Link factors to Sustainability Manager factor mappings
• Link Sustainability Manager reference data to new factors
• Authorize Sustainability Manager to access external tables
• Authorize users to access the tables
• Populate tables with extended factors
• Use extended factors in calculation models

Create extended factor tables

Create custom factor mappings types

1. In the Power Apps portal, create new tables to specify factor mappings options.

2. Rename the primary column to Name.

   The following example shows a new table for Custom Region.

   

   In our example, we also created a new custom factors table for Fiscal Year.

3. Set the Name column as an alternate key called naturalkey.

   

Create custom factors table

Because default entities are in a managed solution, you must create a new solution and import activities and new custom factor entities into it.

1. On the Solutions page, select New solution. Enter the information for your new solution, and then select Create.

   

2. On the Objects page, select Add existing, and then select Table.

   

3. On the Add existing tables page, select the activity and extended factor tables you created. In our example, we created a Purchased energy activity table and a Custom Region extended factors table.

   

   

Extend the activity table with lookups

1. Add a new many-to-one relationship from the activity table to the extended factors table. In our example, we're adding a many-to-one relationship from the Purchased energy activity table to the Custom Region extended factors table.

   

2. Add Sustainability Manager to the new solution and add the custom factor entities to the model-driven app to make them available to Sustainability Manager.

   

   The following example shows the new solution and its resources.

   

3. Select Sustainability Manager, and then select New. On the Add page window, select Dataverse table.

   

4. Select Select existing table. In the Select a table pane, select each of the custom tables you want to use for factor mappings. Uncheck the Show in navigation checkbox. Select Add.

   

   Under All other pages, the new added custom tables appear.

5. Save and publish your changes.

Link factors to Sustainability Manager factor mappings

This procedure requires developer expertise because it's only available via Dataverse APIs.

You need to customize multi-table lookups for factor mappings for your custom tables. You can use the Power Apps Web API with a tool like Insomnia or your preferred API client. For information about sending authenticated POST requests with Insomnia, go to Use Insomnia with Dataverse Web API.

For each custom table, you need to enable factor mappings in calculations. In our example, we need to do that for the Custom Region and Fiscal Year tables. You need the logical name for each table. For example, the logical name for Custom Region is cr040_newtable, and the logical name for Fiscal Year is cr040_newtable1.

For each custom table, we need to update each of the polymorphic lookups used for factor mappings, a table with the logical name msdyn_emissionlookup. These lookups have the following logical names:

• msdyn_referencedataid
• msdyn_referencedata2id
• msdyn_referencedata3id
• msdyn_referencedata4id

For a single custom table, you need to send four POST requests, one for each of the four lookups used in the factor mappings. Use an advanced tool such as Insomnia or your preferred API client to make the POST requests to your organization's RelationshipDefinitions API.

In our case, the endpoint is https://<orgurl>/api/data/v9.2/RelationshipDefinitions. We used the following sample payload for each of the eight POST requests (two tables with four requests each):

Note

"SchemaName" must be unique within your Dataverse environment.

{
  "SchemaName": "msdyn_msdyn_emissionlookup_<custom factor table name>",
  "@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",
  "CascadeConfiguration": {
    "Assign": "NoCascade",
    "Delete": "RemoveLink",
    "Merge": "NoCascade",
    "Reparent": "NoCascade",
    "Share": "NoCascade",
    "Unshare": "NoCascade"
  },
  "ReferencedEntity": "<custom factor table logical name>",
  "ReferencingEntity": "msdyn_emissionlookup",
  "ReferencingAttribute": "<polymorphic lookup name>",
  "Lookup": {
    "AttributeType": "Lookup",
    "AttributeTypeName": {
      "Value": "LookupType"
    },
    "SchemaName": "<polymorphic lookup name>",
    "@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata"
  }
}

The following table shows the values we used for <custom factor table name>, <custom factor table logical name>, and <polymorphic lookup name> for our eight POST requests.

Request	Custom factor table name	Custom factor table logical name	Polymorphic lookup name
1	FiscalYear_RDId	cr040_newtable1	msdyn_referencedataid
2	FiscalYear_RDId2	cr040_newtable1	msdyn_referencedata2id
3	FiscalYear_RDId3	cr040_newtable1	msdyn_referencedata3id
4	FiscalYear_RDId4	cr040_newtable1	msdyn_referencedata4id
5	CustomRegion_RDId	cr040_newtable	msdyn_referencedataid
6	CustomRegion_RDId2	cr040_newtable	msdyn_referencedata2id
7	CustomRegion_RDId3	cr040_newtable	msdyn_referencedata3id
8	CustomRegion_RDId4	cr040_newtable	msdyn_referencedata4id

A successful POST request gives you an HTTP 204 response.

You can verify these operations by inspecting the relationships of the Factor mapping table.

If you want to export your changes to a different environment, you can include the relationships you added earlier into a solution and export that.

Link Sustainability Manager reference data to new factors

1. In Tables, select the All tab, and then select Reference data (msdyn_referencedata).

2. Add the following information for each new factor type:

   Field	Description
   Name	Plural name for your table. For example, Custom regions or Fiscal years.
   Category	Reference data
   Entity name	Logical name of your table, all lower case (not the schema name of the table). For example cr040_newtable or cr040_newtable1.

Authorize Sustainability Manager to access external tables

If not already provided, Sustainability Manager needs to be given access to external tables so it can use them in calculations.

1. Go to Solutions > Microsoft Sustainability Manager Application.

2. Select Security roles, and then select Sustainability Service Application Role – Custom. A new browser tab opens.

3. In the new browser tab, select the Custom Entities tab.

4. For each of the custom tables you want to use for factor mappings, provide Read and Append To privileges at the organizational level.

   Note

   For each custom table, you also need to give org-wide Read privileges to any table that it points to via a lookup. For example, if Custom Region has a lookup to the table Contoso SKU, you must give Read privileges to the Contoso SKU table.

5. Save and close.

Authorize users to access the tables

For each custom table, such as Custom Regions or Fiscal Year, make sure that the Power Apps user who ingests factor mappings or runs calculations has the following org-wide privileges for the table:

• Append To for ingestion

• Read for creating factor mappings or using factor mappings within a calculation that uses a custom table

Populate tables with extended factors

1. Publish all customizations in the Power Apps portal.

2. Import the factor types for the new tables (Custom Regions and Fiscal Year in our example) in the Power Apps portal.

   

3. Import emission factors with Sustainability Manager or the Power Apps portal.

4. Import factor mappings with Sustainability Manager or the Power Apps portal.

5. Import activity data with Sustainability Manager.

6. Map the custom factor mappings in Sustainability Manager.

   

The Extended Factors Library now has the new emission factors and the custom extended factor mappings.

Use extended factors in calculation models

In the Power Apps portal, design the calculation model and use it in the calculation profile.

Note

You can use filtering in the calculation profile to make sure the lookup has a value.

You can use extended attributes in the calculation profile as needed.

FAQ

Are records for custom tables considered "approved" or "pending" for purposes of data approval?

All records for custom tables are considered "approved" for purposes of data approval in the context of factor mappings for calculations.

My import of factor mappings failed saying there's a missing privilege prvAppendTo_[your custom table] for a user

The Sustainability Manager application user or the current user wasn't granted the Append To privilege for the custom table. Ensure that both Sustainability Manager and the user has the appropriate privileges, and then try the import again.

In the calculation model, I don't see my custom table as an option in the Factor mappings section of the Report node's Emission factor or Estimation factor node's Estimation factor dropdown

Make sure you added the msdyn_referencedata record for your custom table.

Check to make sure the value for Entity name in the msdyn_referencedata record for your custom table has the logical name of your table (case-sensitive), not the schema name. Go to Table > Properties, expand Advanced options, and view the logical name.

Make sure that the activity data for the source of your calculation has a lookup field that points to your custom table. For example, if you customized Stationary combustion to have a lookup to Custom Region, but not Mobile combustion, then calculations for Mobile combustion can't use factor mappings based on the Contoso region.

When I make factor mappings manually, I don't see my custom table as an option for Reference data

1. Make sure the user has proper privileges for the custom table.

2. Make sure that the custom table has at least one record.

3. Reload the page.

Customize multiple environments

You might need to make these customizations on one environment and then apply them to another. For example, you might make all your customizations in a dev environment and then need to import them into your production environment. In this case, you can follow these steps to minimize duplicating work.

1. For any solution you used to export changes from one environment to another, you need to include these customizations in that solution:

   • The additions of your custom tables to Sustainability Manager.

   • The additions of more relationships to factor mappings' polymorphic lookups.

   Then you can import the solution for application lifecycle management (ALM).

2. On a per-environment basis, perform the following actions:

   • Add the msdyn_referencedata records.

   • Customize the Sustainability Manager application security role.

📄 Product page
🎓 Training

✅ Free trial
🎥 YouTube channel

💻 Community
LinkedIn group