Merge pull request #266 from ritza-co/add-zapier-integration

DOCS-141 create Zapier integration doc, zapier-integration

docs/integration/external-integrations/zapier-integration.mdx

@@ -0,0 +1,149 @@
+---
+title: "Zapier Automation Using Webhooks"
+sidebar_position: 29
+---
+
+import ThemedImage from '@theme/ThemedImage'
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
+[Zapier](https://zapier.com/) is a versatile workflow automation tool based on "if-this-then-that" logic. You can create an automation sequence, known as a "Zap", to perform actions in response to changes made to Device42 resources. Zapier supports response actions using features of a [variety of apps](https://zapier.com/apps), including Jira, MySQL Server, and Google products.
+
+In this example, we'll have Zapier create a new row in a Google spreadsheet of the webhook payload whenever a new device is added to the Device42 main appliance. The process consists of the following broad steps:
+
+- Generate the Zapier endpoint and add it to Device42.
+- Configure the Device42 trigger action. 
+- Configure the Zapier response action.
+- Test the automation.
+
+## Generate the Zapier Endpoint
+
+1. Log in to your Zapier account and click on the **+ Create Zap** button.
+2. Name your Zap at the top-left corner and then click on the **1. Trigger** box to open a window with a list of trigger options to choose from.
+
+    ![Set up Zap](/assets/images/zapier-integration/zap-create.png)
+
+3. Select the latest **Webhooks by Zapier** option.
+
+    ![Zapier trigger options](/assets/images/zapier-integration/zapier-webhook-option.png)
+
+4. Under the **Event** field, choose the **Catch Raw Hook** option to return header information with the response. For parsed data, select the **Catch Hook** option from the dropdown menu. Click on the **Continue** button.
+
+    ![Catch Raw Hook Event](/assets/images/zapier-integration/trigger-event.png)
+
+5. Copy the generated webhook URL to add as an endpoint in the Device42 main appliance.
+
+## Add the Endpoint to Device42
+
+1. Log in to your Device42 main appliance and navigate to **Tools > Webhooks > Endpoints**.
+2. Click the **+ Add Webhook Endpoint** button on the left.
+
+<ThemedImage
+alt="Webhook Endpoints list page"
+sources={{
+    light: useBaseUrl('/assets/images/zapier-integration/d42-webhook-list-page-light.png'),
+    dark: useBaseUrl('/assets/images/zapier-integration/d42-webhook-list-page-dark.png'),
+}}
+/>
+<br/><br/>
+
+3. Create a webhook endpoint by filling in the following:
+   - **Name:** A unique name for the endpoint.
+   - **URL:** The URL generated by Zapier in the previous section.
+   - **Endpoint:** Select **Zapier**.
+   - **Retry:** Select **After 5 and 15 minutes** from the dropdown menu. 
+   - **Ignore Certificate Errors:** Check this option.
+
+Optionally, you can add webhook headers to be included in the returned data when the Zap is triggered. Click the **+ Add another Webhook Header** button and provide the header name and value.
+
+<ThemedImage
+alt="Add webhook endpoint form"
+sources={{
+    light: useBaseUrl('/assets/images/zapier-integration/d42-add-webhook-form-light.png'),
+    dark: useBaseUrl('/assets/images/zapier-integration/d42-add-webhook-form-dark.png'),
+}}
+/>
+<br/><br/>
+
+## Configure the Device42 Action
+
+Actions define which targets to monitor for changes (known as events) that will trigger the webhook. For example, you can monitor all devices for any changes or monitor changes to specific device fields, like **Device Operating System**. 
+
+1. Navigate to **Tools > Webhooks > Actions** and click on the **+ Add Webhook Action** button.
+
+<ThemedImage
+alt="Webhook actions list page"
+sources={{
+    light: useBaseUrl('/assets/images/zapier-integration/webhook-action-list-page-light.png'),
+    dark: useBaseUrl('/assets/images/zapier-integration/webhook-action-list-page-dark.png'),
+}}
+/>
+<br/><br/>
+
+2. Provide a **Name** for your webhook action. If you want to include all IT resources managed by Device42 in the action, check the **Process All Categories** checkbox. Alternatively, add selected IT resources to the **Chosen categories** box. Use the search bar under **Available categories** to narrow down the options. 
+
+In addition to monitoring for adding, deleting, and updating events, you can trigger the action when a resource is viewed by selecting **Process View Events**, or when a login occurs by selecting **Process Login Events**. 
+
+<ThemedImage
+alt="Webhook action categories"
+sources={{
+    light: useBaseUrl('/assets/images/zapier-integration/webhook-action-categories-light.png'),
+    dark: useBaseUrl('/assets/images/zapier-integration/webhook-action-categories-dark.png'),
+}}
+/>
+<br/><br/>
+
+3. Add the endpoint you previously created to the action by clicking on the **Add another Webhook Action Endpoints** link. Click on the **magnifying glass icon** and select the endpoint from the list.
+
+<ThemedImage
+alt="Webhook action categories"
+sources={{
+    light: useBaseUrl('/assets/images/zapier-integration/action-endpoint-light.png'),
+    dark: useBaseUrl('/assets/images/zapier-integration/action-endpoint-dark.png'),
+}}
+/>
+<br/><br/>
+
+## Test the Trigger Action
+
+To test that the Device42 action triggers the webhook to send data to the Zapier endpoint, create a new device in the main appliance. 
+
+Return to Zapier and click the **Test trigger** button.
+
+![Test trigger action](/assets/images/zapier-integration/test-trigger-action.png)
+
+Zapier will look for data about the trigger event. A successful trigger test will display the returned data. You may have to wait a few moments and rerun the test before you begin seeing any data. Select a record and click on the **Continue with selected record button** to proceed with configuring the response action in Zapier.
+
+![Test trigger action](/assets/images/zapier-integration/select-request-data.png)
+
+## Configure the Zapier Action
+
+Now we'll configure the response action for Zapier to perform when the initial action triggers the webhook. In this example, the webhook data is added as a row in Google Sheets.
+
+1. In Zapier, click on the box labeled **2. Action** and select **Google Sheets** from the options. 
+2. Select the **Create Spreadsheet Row** as the **Event**. Click the **Continue** button and link your Google account to the Zap.
+
+    ![Select the spreadsheet action](/assets/images/zapier-integration/zapier-google-sheet-event.png)
+
+3. Fill in the **Action** section: 
+   - **Drive:** Select the Google Drive that the Google Spreadsheet is stored on.
+   - **Spreadsheet:** The name of the spreadsheet to add data to.
+   - **Worksheet:** Select the spreadsheet worksheet to target.
+   - **"Column Name":** Zapier will fetch the column headings in the spreadsheet and add them as fields. Select the data you want to add under the column from the dropdown menu. 
+
+   Click the **Continue** button.
+
+![Add Google Spreadsheet details](/assets/images/zapier-integration/configure-spreadsheet.png)
+
+4. Test that Zapier creates a new row in your spreadsheet as expected. Check your spreadsheet for the expected data.  
+
+![Test Zap](/assets/images/zapier-integration/test-create-row.png)
+
+5. When the test passes, click the **Publish** button. 
+
+## Test the Zap
+
+Test the Zap by making a change to the resource category you chose when setting up the action in Device42. In this example, Zapier added new rows containing data about new devices being added to the main appliance.
+
+![spreadsheet data](/assets/images/zapier-integration/spreadsheet-data.png)
+
+To view any webhooks that are triggered and pending, navigate to **Tools > Webhooks > Pending**.