Integration from Pitcher to Microsoft Dynamics 365

This document explains how the integration between Pitcher and Microsoft Dynamics 365 works, focusing on authentication, data flow, and synchronization. It provides an overview of the architecture and the technologies used.

1. Architecture Overview

The integration between Pitcher and Dynamics 365 consists of the following components:

• Pitcher Connected App: A multi-tenant SaaS application already configured by Pitcher to interact with Dynamics 365 across different clients.
• Dynamics 365: Microsoft’s platform for managing customer relationships and business processes.
• OAuth 2.0: Authentication protocol used to secure the connection.
• OData Protocol: A web protocol used for querying and updating data.

2. Approving the Connected App in Azure AD

Since the connected app is a multi-tenant SaaS application managed by Pitcher, clients only need to approve the app once within their Azure AD environment to enable access. This one-time approval process grants the necessary permissions for all users within the organization.

2.1 Steps for One-Time App Approval

When the first user tries to login in a domain, an approval process will be triggered.

1. Initial Admin Consent:

   • The client’s administrator logs into the Azure portal (https://portal.azure.com).
   • Navigate to Azure Active Directory > Enterprise applications.
   • Locate the Pitcher connected app in the list of applications.
   • Review the permissions requested by the app, such as access to Dynamics 365 resources.

2. Granting Permissions (One-Time Process):

   • The administrator must grant consent to the app for the required permissions. This includes allowing the app to access Dynamics 365 data on behalf of users in the organization.
   • Granting admin consent is a one-time process that enables all users within the tenant to use the Pitcher app without individually consenting each time they access it.

3. Verification and Ongoing Access:

   • Once the app is approved, all users can log in and use the Pitcher app with Dynamics 365 access enabled without further admin intervention.
   • The admin can verify the granted permissions and monitor user activity in the Azure AD logs for compliance purposes.
   • No additional approval is required for subsequent logins or app usage by any user within the organization.

3. Integration Flow

The data flow between Pitcher and Dynamics 365 can be broken down into upstream and downstream processes:

3.1 Upstream Flow

1. Login & Authorization:

   • The user logs into the Pitcher app.
   • The app requests an OAuth token from Azure AD, using the pre-configured multi-tenant setup for Dynamics 365 authentication.

2. Data Upload:

   • The app sends data collected during meetings (e.g., notes, documents) to Dynamics 365 using REST APIs.
   • If structured data (like customer information) needs to be stored, it’s uploaded to Dynamics 365 via the OData protocol.

3. Synchronization:

   • The app periodically synchronizes data with Dynamics 365 to ensure that the local database on the Pitcher app is up-to-date.
   • It checks if the OAuth token is valid before every synchronization. If not, it initiates a reauthorization process.

3.2 Downstream Flow

1. Data Retrieval:

   • The Pitcher app fetches relevant information from Dynamics 365 to display customer data, documents, or updates.
   • The synchronization process uses OData queries to retrieve the latest information from Dynamics 365.

2. Data Storage in Local Database:

   • The data retrieved from Dynamics 365 is stored in the local database of the Pitcher app, ensuring offline availability.
   • The app regularly checks for updates from Dynamics 365 when online.

4. Technologies Used

• OAuth 2.0: For secure authorization and token management.
• OData: Protocol for data access and manipulation.
• Dynamics 365: For storing and managing structured customer relationship and business data.

5. Error Handling

• Token Expiry: If the OAuth token expires, the app prompts the user to reauthorize.
• Network Issues: If the device is offline or the network connection fails, the app retries synchronization once the connection is restored.

6. Security Considerations

• Data is encrypted during transmission using HTTPS.
• Sensitive information is stored securely in Dynamics 365 following industry best practices.
• The app uses token-based authentication, ensuring that user sessions are protected.

7. Troubleshooting

• Login Issues: Verify Azure AD settings and ensure that the OAuth token is properly configured for Dynamics 365 access.
• Data Sync Failures: Check network connectivity and validate the OData endpoint URL and access permissions in Dynamics 365.