Adding a Custom Integration

Follow

Contents

BetterCloud’s Integration Center now allows you to add Custom Integrations beyond what is available in our native integrations. These integrations give you even more options for taking automated action in BetterCloud, as they expand the range of SaaS applications we can interact with, and give you full control over your environment. 

Getting Started

To get started, select “Create a Custom Integration” from the right side of the Integration Center.

AD.png

You will be prompted to enter a name for your new integration, and to select the provider. We’ve included the most popular integrations in the provider list. If you do not see the provider you are looking to add listed, you can select “Other” from the dropdown menu. Your custom integration will be given the BetterCloud logo, but will be able to be configured like any other custom integration.

AD1.gif

Authentication

Next you must select the authentication type. Depending upon the application you are connecting with some will require an API token, while others will use Basic HTTP Authentication, requiring only a username and password for an authenticating admin. You may also select "None" if the provider does not require authentication to access the endpoints you need to send requests to. With Custom Integrations, each authorization type has certain caveats and is explained in its entirety below.

Using an API Token

When building a custom integration, there are certain apps that will require the use of an API token to authenticate and access endpoints successfully. When choosing "Use an API Token" two (2) fields must be populated:

  • API Token Key - Enter the word "Authorization"
    • This tells BetterCloud that the information to follow is authorization information
    • Important: The "A" in Authorization must be capitalized for the authentication to be successful
  • API Token - This is where the API Token is entered
    • Important: Enter the word "Bearer" then add a space before entering the API token 

ACs.gif

Use Basic HTTP Authentication

Basic HTTP Authentication requires inputting a username and password and is the easiest authorization method for our users that just want to use/provide webhooks for the integration. Simply enter the username and password information for the custom application being integrated into your BetterCloud instance:

ACe.gif 

None

This "None" option is for APIs that do not require authentication information before accessing the endpoints. Simply choose "None" and begin configuring the application using the remainder of the options. 

Authenticating after Choosing "None"

When choosing "None" there is an option that allows for authentication information to be input later. This is done by going to "Extensions" creating an extension and placing the authentication information in the "Additional Headers" fields. The authorization information must be placed in the given fields with the format that the application's integration accepts. Typically, the information is entered as follows:

  • Header Key - Type "Authorization" with a capital "A"
  • Header Value - Enter "Basic username:password" in that specific way 
    • "Basic", a space and the username and password with a colon in between

Note: It is suggested that the grey drop-down menu displayed below is used to import basic authorization information, however, it is only usable for information that is placed as an "Environmental Variable" or created as Basic HTTP Authorization information on the "Basic Information" tab

AC.gif

 

Rate Limiting

Rate Limiting is controlled on the Basic Information tab. To do this, click the box next to "Limit Execution Rate" and enter the desired maximum number of requests per second. This prevents you from hitting API quotas in the provider when running actions through BetterCloud. Click “Save” when you’re ready to add your integration. The integration will show up under “My Integrations” in your Integration Center.

*Note: It is possible to add a custom integration with invalid authentication, or an authentication type that does not match what is required by the provider. Both authentication and rate limits can always be edited later from the Basic Information section.

Editing Your Custom Integration 

Click on your integration from the Integration Center to configure it further. Under Basic Information you can see or change the information you have already configured.

AD2.png

Note: Changing the authentication for integrations with existing actions may cause the action to stop working, if the authentication is no longer valid 

Environment Variables

Environment Variables allow you to define static, encrypted variables that can be called from a script or a webhook. Many providers require additional authentication beyond an API token or basic authentication, and may require you to make calls against a particular hostname. By defining environment variables within the integration’s configuration, you can reference these pieces of information easily. 

To get started, enter a Key Name and the value that the key will correlate to. For your security the value will be encrypted.

AD4.png

Once you save the environment variable, it will be added to the list of variables available for the integration.

AD3.png

Once you save the environment variable, it will be added to the list of variables available for the integration.

Extensions 

After entering Environmental Variables, you will be prompted to enter extensions for the integration. Extensions are Actions, Push Events and Data Transformation Scripts that can be added to an integration. After moving to the “Extensions” tab, click “Get Started” to begin creating extensions.

CII.png

On the Extensions screen, there are three (3) extensions that can be created for an integration:

  • Add an Action for Workflows
    • Used to expose a webhook within workflows as an action
  • Send a Push Event
    • Send a BetterCloud payload to an external API when BetterCloud triggers an event
  • Write a Data Transformation Script
    • Transform and normalize data before it is prepended to an action

Adding an Action for Workflows

Adding an action for workflows allows for webhooks to be exposed as an action and used dynamically in later workflows. To begin the process, select “Add an Action for Workflows” and click “Next”. Once this is completed, the following screen will be displayed requesting that more details to be entered:

CII1.gif

The following details are to be entered before creating an action from a webhook:

Details

  • Action Name - Enter a name for the action being created
    • The name should be commensurate with the action taking place
  • Description - Enter a description for the action being created
  • Data Transformation Script (Optional) - Drop-down menu displaying the preloaded data transformation scripts available 

API Configuration

  • HTTP Method - Drop-down list displaying the list of possible API call methods to choose from
    • Post
    • Put
    • Get
    • Delete
    • Patch
  • Destination URL - Text field used to enter the URL that the API call(s) will be made to
  • Attempt Retry on Failure - Clickable box used to indicate whether the action should be reattempted after failure to execute

Additional Headers - Open text fields used to place additional script headers

  • Note: To add even more headers, click the “+” button next to the second header field

Test 

  • Payload - Text field used for entering a payload script to test 
  • Run Test - Click this button to test the payload entered in the “Payload” field 

After entering the necessary details for the action, a test must be run to ensure that the endpoint is hit successfully. Assuming that the test run doesn’t fail, the “Next” button will highlight and be clickable. Click “Next” to select the properties to be reused in later workflows:

CI.png

Select the properties that will be used in later workflows and click “Save”. Once saved, the action will become available to be modified or deleted from the Extensions tab:

CI2.png

Sending a Push Event

BetterCloud allows for a BetterCloud payload to be sent to an external API when an event occurs. To do so, select “Send a Push Event” and click “Next”. Once this is completed, the following screen will be displayed asking for more details to be entered:

CII2.gif

The following details are to be entered before creating a Push Event to be sent:

Details

  • Event Name - Enter a name for the event being created
    • The name should be commensurate with the event taking place
  • Description - Enter a description for the event being created
  • Data Transformation Script (Optional) - Drop-down menu displaying the preloaded data transformation scripts available 

API Configuration

  • HTTP Method - Drop-down list displaying the list of possible API call methods to choose from
    • Post
    • Put
    • Get
    • Delete
    • Patch
  • Destination URL - Text field used to enter the URL that the API call(s) will be made to
  • Attempt Retry on Failure - Clickable box used to indicate whether the action should be reattempted after failure to execute

Additional Headers - Open text fields used to place additional script/payload headers

  • Note: To add even more headers, click the “+” button next to the second header field

When should this event be triggered? - Used to select when the event being created is to take place

  • When any Event Log is written
  • When any Alert triggers
  • When any Workflow Status changes
  • When any Action Engine completes

Test your Push Event 

  • Drop-Down Menu - Used to select a trigger event to test
  • Run TestClick this button to test the payload entered in the “Payload” field

After entering the necessary details, click “Save” to save your Push Event. Any Push Event created will be displayed on the Extensions tab with the tag “Push Event” where they can be modified or deleted:

CI3.png

Writing a Data Transformation Script

Data Transformation Scripts are used to transform and normalize data and add it to the beginning of a script before executing the script. To begin the process, select “Write a Data Transformation Script” and click “Next”. Once this is done, the following screen will be displayed asking for more details to be entered:

CI3.gif

The following details are to be entered before Writing a Transformation Script:

  • Script Name - Enter a name for the script being written
  • Description - Enter a description of the script being written
  • Available Templates - Drop-down menu used to select from a list of supplied script templates 

Test

  • Payload - Text field used for entering a payload script to test 

Once all necessary information is entered, a template is selected and a test payload is entered, click “Run Test”. Assuming that the test is run successfully, the “Save” button will become selectable or will turn into a "Next" button. If the button is a "Save" button, click it to create the Data Transformation Script.

If the button turns into a "Next" button, this means that there is data returned from the webhook test that can be stored and used dynamically. After clicking "Next" the following screen will appear prompting you to select the data that you'd like to store as dynamic information:

 

Screen_Shot_2019-09-19_at_5.39.56_PM.png

Sharing an Integration

BetterCloud gives you the ability to share any integrations that are created using the Custom Integrations process. To do so, select “Share This Integration” from the Integration details menu.

CIII.png

After selecting “Share This Integration” BetterCloud’s Terms of Use will be displayed prompting you to select that the terms have been read and are agreeable. After reading the terms of use thoroughly, click “I represent that I have read and agree to these Terms and have authority to agree to these Terms.” Then click “I accept”.

CIII2.gif

After accepting BetterCloud’s Terms of Use, the option to submit your integration will be presented:

CIII3.png

Before an integration can be shared with all other BetterCloud users, it must first be submitted to BetterCloud for review. Click “Submit” to begin the review process. An email will be immediately sent to your inbox with the status of the submission. Emails will be sent periodically with any updates on the review progress.

Deleting an Integration

To delete an integration, select “Delete Integration”.

CIII43.png

Once this is selected, the next screen displays the following necessary before allowing the deletion of an integration:

  • Deleting an integration will permanently remove it from BetterCloud
  • This action cannot be undone once it is completed

CIIIIIII.png

After both of these boxes are checked acknowledging the full outcome of deleting a connecter, select “Delete This Integration”.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request