Vendor Integrations
      Back to home
      1. Gradient Support Center
      2. Vendor Integrations

      Creating Self-Hosted Integrations - Reconcile™ PowerShell SDK

      Building PowerShell Integrations with Reconcile™

      This walkthrough introduces you to building a custom integration with the Reconcile™ PowerShell SDK. It provides a high-level overview to help you get started. You’ll learn the fundamentals of connecting vendor platforms and systems, enabling you to synchronize usage data into Reconcile™ with minimal setup.

      Overview

      1. Getting Started
        1. Prerequisites
        2. Supporting Articles
        3. Folder & File Structure
        4. File Purpose
      2. Integration Breakdown
        1. Create Accounts
        2. Create Services
        3. Create Billing Items

      Getting Started

      Prerequisites

      • PowerShell 7+
      • Basic programming knowledge (variables, data types, truthy/false values, operators, conditionals, loops)

      For the latest version of the PowerShell SDK and reference integrations, contact us at support@meetgradient.com.

      Supporting Articles:

      Folder & File Structure

      Synthesize-SDK-PS
      └── Integrations
          ├── PSCreateAccountsFromVendor.ps1
          ├── PSCreateServicesFromVendor.ps1
          ├── PSCustomIntegrations.ps1
          ├── PSInit.ps1
          ├── PSMain.ps1
          ├── PSSyncUsage.ps1
          └── .env

      File Purpose

      • PSCustomIntegrations.ps1: Defines the logic for testing authentication, and for fetching and mapping customers, services, and usage data from the vendor API.
      • PSCreateAccountsFromVendor.ps1:  Calls the account-creation helper; expects a ready-to-use hashtable of customer objects passed to Invoke-CreateAccounts.
      • PSCreateServicesFromVendor.ps1: Calls the service-creation helper; expects a ready-to-use array of service objects passed to Invoke-SyncServices.
      • PSImports.psm1: Central import module that loads the SDK, integration scripts, and helper functions so they can be used across the project
      • PSInit.ps1: Loads environment variables, validates API keys, and initializes the SDK connection to https://app.usegradient.com.
      • PSMain.ps1: Entry point that initializes the Gradient connection, and routes the specified commends (e.g., authenticate, sync-accounts, sync-services, update-status, or sync-usage)
      • PSSyncUsage.ps1: Orchestrates the usage sync workflow by retrieving usage data (an array of billing items), mapping them to the correct service IDs, and pushing the usage data into Reconcile™.
      • .env: used to store configuration values and secrets.

      Integration Breakdown

      For each integration, we need to complete three key components:

      1. Customers - Fetch and transform customer data to create accounts for mapping in Reconcile™.

      2. Services - Fetch and transform service data to create services for mapping in Reconcile™.

      3. Usage - Fetch and transform usage data to map customers to their services in Reconcile™ and generate billing items for reconciliation.

      API Considerations

      • Each vendor API will vary.
      • Information may be centralized or dispersed across multiple endpoints.
      • Data may need to be stitched together from multiple endpoints.
      • How you fetch and combine data will depend on the vendor.

      Create Accounts

      Note: When creating accounts, services, and usage, you can structure your logic in the way that best fits your integration:

      • Single-function approach - One function for accounts, services, usage that handles both fetching and mapping logic.

      • Single-responsibility approach - Separate concerns by creating:

        • A dedicated function for fetching data from the vendor API

        • A dedicated function for mapping the fetched data

      Best practice: We recommend the single-responsibility approach.

      Reference Integration: Augmentt

      • Files: 

        • PSCustomIntegrations.ps1

        • PSCreateAccountsFromVendor.ps1
      • Functions:
        • Get-RawCustomersData
        • Get-MappedCustomers
        • Invoke-SyncAccounts
      1. Retrieve customer data (ID and name) from the vendor API.
      2. Transform the data into hash table objects that can be used to create accounts in Gradient with Invoke-CreateAccounts.
      3. Each object should follow this shape:

        @{
          id   = "123"                  # string - customer ID
          name = "Acme Corp"  # string - customer name
        }

        Create Services

          1. Retrieve service data from the vendor API.
          2. Transform the services data into an array of objects that can be used to create services in Gradient with Invoke-SyncServices.
          3. Each object should follow this shape:

            @{ 
              Name   = "Security Awareness Training"        # string  - service name
              Category = "other"                                         # string  - enumerable
              Subcategory = "other"                                   # number - enumerable
            }

        You can approach services in two ways:

        1. Dynamic Services: Generate services dynamically based on what you bill your customers, leveraging usage data.

        • Reference Integration: Augmentt

        • Functions:

          • Get-AllCustomerLicenses

          • Get-VendorServices

        2. Static Services: Predefine (hardcode) the services.

        • Reference Integration: ThreatLockerV2

        • Function:Get-VendorServices


        Create Billing Items

        1. Retrieve customer usage data from the vendor API.
        2. Transform the usage data into an array of objects that can be used to create billing items in Gradient with Invoke-SyncUsage.
        3. To generate billing items from Initialize-PSCreateBillingRequest each object should include:
          @{ 
            id   = "123"                                                    # string  - customer account ID
            name = "Security Awareness Training"         # string  - service name
            count = 12                                                    # number - usage quantity (must be > 0)
          }

        Defensive Logic
        When mapping objects for accounts, services, and usages, include only fields with valid values. Exclude any fields that are null or undefined.

        Filtering Logic
        Exclude usage objects with a count less than 1. Only include objects where the count is 1 or greater.