DataversePython

A Python client for interacting with Microsoft Dataverse (Dynamics 365) Web API, supporting authentication via Azure Entra ID (formerly Azure Active Directory), and providing convenient methods for querying, inserting, upserting, merging, and managing many-to-many relationships in Dataverse entities using pandas DataFrames.

Features

• Authentication: Secure interactive login using MSAL and Azure Entra ID.
• Querying: Retrieve entity records as pandas DataFrames with flexible filtering and column selection.
• Insert/Upsert: Insert or upsert records from DataFrames into Dataverse entities.
• Merge: Merge duplicate records (accounts, contacts) programmatically.
• Many-to-Many: Manage many-to-many relationships between entities.
• Logging: Detailed logging to DataverseClient.log for all operations and errors.

Installation

Use the following command to install this module:

pip install DataversePython

After successfully installing it into your python environment you can import the "DataverseClient" class in your code or notebook:

from DataversePython import DataverseClient

Usage

1. Setup

   1. Create the required Azure app registration, see App Registration Guide.

   2. Add the created Service Principal (App Registration) as an application user your environments, see Add Application User Guide

   3. Create a JSON config file (see sample_config.json) with your Azure app registration and Dataverse environment details. The config JSON looks like this:

      {
      "environmentURI": "https://<your-org>.crm.dynamics.com/",
      "scopeSuffix": "user_impersonation",
      "clientID": "<your-client-id>",
      "authorityBase": "https://login.microsoftonline.com/",
      "tenantID": "<your-tenant-id>"
      }
      

2. Basic Example

   from DataversePython.DataverseClient import DataverseClient
   import pandas as pd
   
   # Initialize client
   client = DataverseClient('sample_config.json')
   
   # Get records
   df = client.get_rows(entity='accounts', top=50, columns=['name', 'emailaddress1'], filter='revenue gt 100000')
   
   print(df.head())
   

3. Get, Insert, Upsert, Merge, and Many-to-Many

   • See docstrings in DataverseClient.py for details on each method.
   • Go to my blog to see detailed examples:
     • get_rows()
     • insert_rows()
     • upsert_rows() (coming soon)
     • insert_m_n() (coming soon)
     • merge_rows() (coming soon)

Logging

All operations and errors are logged to DataverseClient.log in the project root. Reference this log file for troubleshooting.

Tips for Using DataversePython

• Visualize and Explore DataFrames Easily: Install the Data Wrangler extension in VS Code to interactively view, clean, and analyze pandas DataFrames. This makes it much easier to inspect and manipulate your data when working with Dataverse records.
• Work Interactively with Notebooks: For the best experience, use Jupyter (.ipynb) notebooks in VS Code. Notebooks allow you to run code in cells, visualize results, and document your workflow, making it ideal for data exploration and Dataverse integration tasks.

Resources

Below are some useful resources and documentation that were referenced during the development of this module:

• PyConnectDataverse
• Microsoft Dataverse documentation
• Azure App Registration documentation
• Pandas documentation