Creating a Self-Hosted Integration with the Reconcile™ PowerShell SDK

A Step-by-Step Guide for Seamless Integrating and Troubleshooting a Self-Hosted Integration in Reconcile™.

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

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

Reconcile™ PowerShell SDK

• Requirements
• Step 1: Obtain the Repository
• Step 2: Configure Environment Variables
• Step 3: Custom Integration Configuration
• Troubleshooting PowerShell Issues
• Automating Usage Sync (Optional)
• Automating Usage Sync with Scheduled Task on Windows
• Automating Usage Sync with Terminal on macOS

Requirements

Before you can effectively utilize the Reconcile™  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. Reconcile™  API Credentials: Generate API Tokens from the Reconcile™  platform. These credentials are essential for communication between your custom integration and the Reconcile™  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. Reconcile™ PowerShell SDK Installation: Download and set up the Reconcile™  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 Reconcile™  PowerShell SDK, ensuring seamless communication with both Reconcile™  and your chosen vendor APIs.

Step 1: Obtain the Repository

Before you can begin utilizing the Reconcile™  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:
   • Visit https://github.com/meetgradient/Synthesize-SDK-PS
   • Click on the green "Code" button and choose "Download ZIP".
   • Extract the contents of the .zip file to your desired directory.

Step 2: Configure Environment Variables

Before executing any commands to interact with the Reconcile™ 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 Reconcile™ 

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

1. Login to your Reconcile™  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 Reconcile™  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.

• pwsh "PSMain.ps1" sync-accounts: This command synchronizes accounts as part of the integration process.
• pwsh "PSMain.ps1" sync-services: Initiates the synchronization of services within the integration.
• pwsh "PSMain.ps1" 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:

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

These commands provide you with the tools to efficiently manage your custom integration using the Reconcile™  PowerShell SDK, ensuring seamless communication between your integration, Reconcile™ , 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.

Top