Integrations Page Documentation

Overview

The Integrations Page serves as a central hub for managing integrations between the Vantage analytics platform and various third-party services. It allows users to view and manage their credentials for these integrations, leveraging OAuth services for seamless API access. The page enforces permission checks to ensure that only authorized users can manage integrations, providing a secure and organized interface for configuration.

Workflow

1. Session Management: The page begins by retrieving the current user's session, ensuring they are authenticated to use the platform.
2. Permission Verification: It checks whether the user has the roles required to manage integrations through a combination of roles and specific permissions.
3. Service Retrieval: The system retrieves a list of available third-party services from the database, distinguishing between global and client-specific services.
4. Credential Management: It fetches the client's credentials, separating them into company-level and user-specific categories.
5. Data Structuring: The retrieved data is structured into a format suited for rendering on the front-end, differentiating between standard and custom services based on their association with the client.

Settings

The settings for the Integrations Page are derived primarily from user permissions and the service configuration stored in the database. Here’s an exhaustive breakdown:

1. Permission Check

• Name: canManageIntegrations
• Input Type: Boolean
• Description: Determines if the user has the necessary rights to manage integrations based on their assigned roles and permissions within the system.
• Default Value: true for users without roles; conditional based on permission for users with roles.

2. Service Retrieval

• Name: services
• Input Type: Array of Objects
• Description: An array of third-party service objects fetched from the database. Each object typically includes properties like id, displayName, client_id, description, configSchema, and serviceKey.
• Default Value: Dynamically populated based on the services defined in the database.

3. Credential Retrieval

• Name: rawCreds
• Input Type: Array of Objects
• Description: This represents the fetched credentials for the services the user has access to. Credentials can be user-specific or company-level, depending on the context in which they were created.
• Default Value: Functionally nil if no credentials exist for the user.

4. Credential Mapping

• Name: credMap
• Input Type: Object
• Description: A structured object mapping serviceId to an array of associated credential objects. Each credential includes information regarding its scope (personal or company), label, and potentially decrypted user info.
• Default Value: An empty object if no credentials are found or mapped.

5. Custom vs Standard Service Separation

• Name: customServices and standardServices
• Input Type: Arrays
• Description: Two separate arrays to store services that are either specific to the client (customServices) or available globally (standardServices). This improves organization and accessibility.
• Default Value: Population is based on the data fetched from the database.

Use Cases & Examples

Use Case 1: Company-Wide Integration Management

A company wants to consolidate its tools and ensure all departments have access to shared APIs like Google Drive and Microsoft Teams. The Integrations Page allows designated administrators to manage these integrations without complicated setups.

Use Case 2: Personal Credential Management

Individual users need to link their personal email accounts (like Gmail) to the analytics platform to integrate workflows. With the Integrations Page, users can securely manage their credentials and permissions without needing IT intervention.

Use Case 3: Dynamic Service Configuration

A tech firm frequently collaborates with varied partners needing access to custom APIs. By utilizing the Integrations Page, the firm can add and manage new services quickly, allowing teams to adapt their technical stack in real-time.

Example Configuration

For a scenario where a company wants to set up integrations for Google Drive and Outlook Mail for department-level access:

{
    "services": [
        {
            "id": "googledrive",
            "displayName": "Google Drive",
            "client_id": "client123",
            "description": "Storage and file management.",
            "configSchema": {
                "oauth": {
                    "clientId": "abc123",
                    "clientSecret": "secret",
                    "redirectUri": "https://myapp.com/oauth"
                }
            },
            "serviceKey": "123abc"
        },
        {
            "id": "outlookmail",
            "displayName": "Outlook Mail",
            "client_id": "client123",
            "description": "Email management.",
            "configSchema": {
                "oauth": {
                    "clientId": "xyz456",
                    "clientSecret": "secret",
                    "redirectUri": "https://myapp.com/oauth"
                }
            },
            "serviceKey": "456xyz"
        }
    ],
    "credMap": {
        "googledrive": [
            {
                "id": "cred1",
                "scope": "company",
                "label": "Shared Drive",
                "isDefault": true,
                "userInfo": {
                    "email": "user@company.com",
                    "name": "User Name",
                    "picture": "https://example.com/image.jpg"
                }
            }
        ],
        "outlookmail": [
            {
                "id": "cred2",
                "scope": "company",
                "label": "Dept Outlook",
                "isDefault": false
            }
        ]
    },
    "canManageIntegrations": true
}

This configuration gives department users access to the Google Drive and Outlook Mail services while ensuring that integrations are effectively managed and organized within the Vantage platform.