Synthesize Billing Module - Guides and Resources
      Back to home
      1. Gradient Support Center
      2. Synthesize™
      3. Synthesize Billing Module - Guides and Resources

      Creating a Custom Integration with the Synthesize PowerShell SDK

      A Step-by-Step Guide for Seamless Integrating and Troubleshooting a Custom Integration in Synthesize.

      This comprehensive guide provides step-by-step instructions for implementing a custom integration using the Synthesize PowerShell SDK. Learn how to seamlessly connect your vendors and systems to synchronize vendor usage to Synthesize.

      We cover module installation, troubleshooting PowerShell issues, and automating usage synchronization, ensuring you can leverage the full capabilities of your custom integration.

      For any questions or issues with the SDK, please contact support@meetgradient.com.

      Requirements

      Before you can effectively utilize the Synthesize PowerShell SDK for your custom integration, make sure you have the following prerequisites in place:

      1. PowerShell 7.0 or Later: Ensure that you have PowerShell version 7.0 or a more recent version installed on your system. You can download and install PowerShell from the official website here: Installing PowerShell on Windows

      2. Synthesize API Credentials: Generate API Tokens from the Synthesize platform. These credentials are essential for communication between your custom integration and the Synthesize API. 

      3. Vendor API Credentials: Depending on the specific vendor you intend to connect with, you need to acquire API credentials from your vendor. These credentials are necessary for establishing communication between your integration and the vendor's API.

      4. Synthesize PowerShell SDK Installation: Download and set up the Synthesize PowerShell SDK by either cloning the SDK repository with Git or downloading the .zip repository from GitHub. Detailed installation instructions can be found in the SDK documentation.

      5. Synthesize Account: You must have an active Synthesize account. If you don't already have one, you can register for an account on the Synthesize platform or log in if you are an existing user. Access to the Synthesize platform is crucial for configuring and managing your custom integration.

      By meeting these requirements, you'll be well-prepared to begin building and managing your custom integration using the Synthesize PowerShell SDK, ensuring seamless communication with both Synthesize and your chosen vendor APIs.

      Step 1: Obtain the Repository

      Before you can begin utilizing the Synthesize PowerShell SDK for your custom integrations, you must obtain the SDK repository that houses your integration solutions. You have two primary options to obtain the necessary files and resources:

      Option 1: Clone the Repository with Git

      1. Open the PowerShell terminal.
      2. Navigate to the directory where you want to clone the repository.
      3. Run the following command to clone the repository: 
        git clone https://github.com/meetgradient/Synthesize-SDK-PS.git

      Option 2: Download the .zip Repository

      1. If you don't have Git installed, you can download the .zip repository from GitHub:

      Step 2: Configure Environment Variables

      Before executing any commands to interact with the Synthesize API and vendor APIs, it's essential to set up environment variables within the integration folder's .env file. Here's how you can do it:

      1. Locate the .env file within the integration folder. You may encounter a sample.env file; rename it to .env.

      2. In the .env file, add your vendor credentials. Note that this information should be input in plain text, so there's no need to enclose it in quotes or any other formatting.

      Generating Vendor and Partner API Keys in Synthesize

      These keys are necessary for establishing communication with the Synthesize API. Here are the steps to generate them:

      1. Login to your Synthesize account.

      2. Navigate to the 'Integrations' section.

      3. Click on 'Custom' to create a custom integration.

      4. Choose the integration type you wish to create.

      5. Enter the 'Custom Integration Name' and 'Vendor or Distributor Name'. The 'Vendor or Distributor Name' is used as a tag for any mapped service within the integration, making it easier to filter by vendor or distributor when viewing the 'Billing Reconciliation' page after usage synchronization.

      6. Accept the terms and conditions.

      7. Click 'Next'.

      8. Click 'Generate API Tokens'.

      9. Warning: Ensure you copy and securely save these generated tokens. The vendor token will be provided once generated.

      10. Add these Vendor and Partner Tokens to the .env file.

      Generating Vendor Keys in Vendor Account

      Vendor-specific API keys are specific to the vendor you are connecting to and are often detailed in their API documentation. If you need assistance in obtaining vendor API keys, it's advisable to contact your vendor for guidance.

      Once you have acquired all the required vendor keys and environment variables, insert them into the .env file for your integration. This configuration will enable seamless communication between your custom integration and the Synthesize and vendor APIs.

      Step 3: Custom Integration Configuration

      With your environment variables and credentials correctly set up, you are now ready to execute commands using .PSMain.ps1, located within the integration folder of your custom integration.

      Execute the subsequent commands to initiate the configuration of the custom integration:

      • sync-accounts: This command synchronizes accounts as part of the integration process.
      • sync-services: Initiates the synchronization of services within the integration.
      • update-status: This command is used to update the integration status to 'pending' during the initial setup of an integration. This update is performed only once as part of the setup process.

      After executing these three commands, you can proceed with the configuration of your custom integration. This is where you click 'Next' and map both accounts and services. Once the mapping is complete, click 'Finish,' and you are now ready to synchronize usage data using the following command in the PowerShell terminal:

      • sync-usage: This command syncs usage data across the mapped accounts and services.

      Note that the integration will remain in a 'pending' status until you successfully sync usage data. Once synced, you can configure the integration at any time.

      Note encountering 404 errors is entirely normal and expected. These errors indicate that there is no service mapping available for a specific account or service, and they do not signify any issue with the integration process.

      These commands provide you with the tools to efficiently manage your custom integration using the Synthesize PowerShell SDK, ensuring seamless communication between your integration, Synthesize, and your vendor APIs.

      Troubleshooting PowerShell Issues

      When executing and running the commands as outlined above, you may encounter certain errors. Here are of the main culprits and how to troubleshoot them effectively:

      1. Set Execution Policy

      If you encounter an execution policy error, you need to set the execution policy to 'Unrestricted' for the root folder:

      Set-ExecutionPolicy Unrestricted -Scope Process

      2. Unblock Files

      To unblock files recursively within the root folder and its subfolders, use the following command:

      Get-ChildItem -Path "C:\Path\To\Synthesize-SDK-PS" -File -Recurse | Unblock-File

      Automating Usage Sync (Optional)

      To automate the usage synchronization process on a recurring basis, you can use Task Scheduler or other scheduling methods. Configure a scheduled task that runs the sync-usage command at your desired intervals.

      Automating Usage Sync with Scheduled Task on Windows

      Prerequisites

      • Windows operating system with Task Scheduler.
      • Basic understanding of PowerShell and Task Scheduler.

      Step 1: Prepare Your PowerShell Script

      1. Script Location: Ensure your PSMain.ps1 is in an accessible location. For this example, let's assume it's located in C:\Scripts\PSMain.ps1.
      2. Modify the Script: If PSMain.ps1 doesn't already include the sync-usage command, add it. Also, ensure that any required modules are imported at the start of the script.

      Step 2: Open Task Scheduler

      1. Press Win + R, type taskschd.msc, and press Enter.
      2. In Task Scheduler, go to Action > Create Basic Task.

      Step 3: Create the Task

      1. Name and Description: Give your task a name, like Weekly Sync-Usage Task, and an optional description.
      2. Trigger: Choose Weekly and set the start date and time. Select the day of the week you want the task to run.
      3. Action: Select Start a program. In the Program/script field, type powershell.exe.
      4. Add Arguments: In the Add arguments field, input -ExecutionPolicy Bypass -File "C:\Scripts\PSMain.ps1".
      5. Finish: Review your settings and click Finish.

      Step 4: Test Your Task

      1. Right-click on your task in Task Scheduler and choose Run to test it.
      2. Verify that the sync-usage command executes as expected.

      Step 5: Monitoring and Troubleshooting

      1. Check Task History: In Task Scheduler, you can check the history tab for your task to ensure it's running as expected.

      Automating Usage Sync with Terminal on macOS

      Prerequisites

      • A Mac running macOS.
      • PowerShell installed on the Mac.
      • Basic understanding of Terminal and Cron Jobs.

      Step 1: Open Terminal

      1. Open the Terminal app on your Mac.

      Step 2: Edit the Cron Jobs

      1. In the Terminal, type crontab -e and press Enter. This opens the cron table in an editor.
      2. If you're unfamiliar with vi or vim (the default editors in Terminal), you can change the editor to something like nano by running export EDITOR=nano before crontab -e.

      Step 3: Schedule Your Script

      1. Cron Syntax: The general format of a cron job is: 
        * * * * * /path/to/command arg1 arg2
        The five asterisks represent minute, hour, day of the month, month, and day of the week, respectively.
      2. Setting Up Weekly Execution:
        • To run the script every week at a specific time, you need to modify the cron job line accordingly. For example, to run it every Monday at 8 AM, you would write:
          bashCopy code
          0 8 * * 1 /usr/local/bin/pwsh /path/to/PSMain.ps1
        • Replace /path/to/PSMain.ps1 with the actual path to your script.

      Step 4: Save and Exit

      1. Save the cron job. In nano, it's Ctrl + O, Enter, then Ctrl + X. In vi or vim, it's :wq and then Enter.

      Step 5: Confirm Cron Jobs

      1. Run crontab -l to list all cron jobs and confirm your new job is listed.

      Step 6: Permissions and Execution

      1. Ensure PSMain.ps1 has execute permissions: run chmod +x /path/to/PSMain.ps1.
      2. Make sure PowerShell can execute the script by setting the appropriate execution policies, if necessary.

      Note the specifics might vary slightly based on your macOS version and PowerShell setup. Ensure that PowerShell is correctly installed and accessible via the Terminal.

      Related Links