Self-hosted Integrations
      Back to home
      1. Gradient Support Center
      2. Vendor Integrations
      3. Self-hosted Integrations

      Self-Hosted Integrations - Troubleshooting Guide

      This guide is here to help you troubleshoot common setup challenges and ensure your self-hosted integrations run smoothly.

      Quick Links:

      1. Checking PowerShell Version
      2. Installing PowerShell on Windows
      3. Update ExecutionPolicy
      4. Bypass Security Warnings
      5. Folder Structure

      Resources: 

      1. Setting Up a Custom Integration in Synthesize with Synthesize PowerShell SDK
      2. Creating Custom Integrations and Retrieving Synthesize API Credentials

      Prerequisites for Synthesize SDK: 

      1. PowerShell 7.0 or later

      2. Synthesize API credentials

      3. Vendor API credentials 

      Checking PowerShell Version: 

      To verify your PowerShell version: 

      Windows 

      1. Open the PowerShell 7 terminal and run cmd $PSVersionTable.PSVersion to check the exact version in any PowerShell session. 
      2. Alternatively, you can type in pwsh to display the current version, e.g., PowerShell 7.4.5. 

      Note: Ensure you're in a PowerShell 7 terminal. If you are currently in a PowerShell 5 terminal and want to run a script or command using PowerShell 7, prefix your commands with pwsh, e.g., pwsh -file "PSMain.ps1" sync-services.

      Installing PowerShell 7 on Windows: 

      If PowerShell 7 is not installed, run the following command in the terminal:

      winget install --id Microsoft.PowerShell --source winget

      MacOS 

      1. Open the terminal and run cmd pwsh to switch to PowerShell 7. 
      2. Once inside PowerShell, you can check the version by running: either pwsh or $PSVersionTable.PSVersion to display the current version.

      Update Execution Policy 

      These scripts are open source and provide our partners the flexibility to customize them for their specific use cases. To run these scripts, please set your PowerShell Execution Policy to Unrestricted.

      To check your current execution policy, run the following command: Get-Execution Policy`

      1. To change the execution policy for the current user, use the command:Set-ExecutionPolicy Unrestricted -Scope CurrentUser this sets the execution policy to Unrestricted for only the current user and may prompt for confirmation if necessary.
      2. To apply the execution policy system-wide without prompting, use the command: Set-ExecutionPolicy Unrestricted -Force the -Force flag suppresses any confirmation prompts. 

      Note: These changes may need to be made as an administrator – ensure you are running your terminal as admin. 

      Bypass Multiple Security Warnings

      Depending on your Execution Policy, running the commands below may trigger a security warning:

      • pwsh "PSMain.ps1" authenticate
      • pwsh "PSMain.ps1" sync-accounts
      • pwsh "PSMain.ps1" sync-services
      • pwsh "PSMain.ps1" update-status
      • pwsh "PSMain.ps1" sync-usage

      Security Warning: Run only scripts that you trust. While scripts can be useful, they can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow it to run without this warning message.Security Warning Run only scripts that you trust. While scripts can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message.

      [D] Do not run

      [R] Run once

      [S] Suspend

      [?] Help (default is "D"):

      1. To unblock a specific script and bypass warnings, run the following command: Unblock-File -Path "./psgradient/yourScript.ps1"
      2. To unblock all scripts in the psgradient folder, use this command: Get-ChildItem -Path "C:\PathTo\Synthesize-SDK-PS" -File -Recurse | Unblock-File

      Note: These changes may need to be made as an administrator – ensure you are running your terminal as admin. 

      Foder Structure 

      To ensure that the Import-Module .\PSMain.ps1 script command run correctly, the folder should be structured as follows: 

      Root directory:  

      1. PSGradient
      2. integrations – contains a list of pre-built integrations  
      1. README.md – setup information 

      Integrations directory: 

      1. ./integrations/<integration name>/ 

      Note: Ensure the specified vendor integration script resides within the Integrations directory.