60634: External Integrations: add prerequisites + intro improvements

docs/integration/external-integrations/azure-migrate.mdx

@@ -3,8 +3,19 @@ title: "Azure Migrate"
 sidebar_position: 2
 ---
 
+This page is for administrators who want to use Device42 as an assessment tool within Azure Migrate and export discovered business applications from Device42 to Azure for migration planning. By the end, your Device42 business application data appears in the Azure Migrate portal for assessment.
+
 You can get to Azure Migrate directly @ [https://portal.azure.com/#create/Microsoft.AzureMigrate](https://portal.azure.com/#create/Microsoft.AzureMigrate)
 
+## Prerequisites
+
+To export data from Device42 to Azure Migrate, make sure you have:
+- An Azure account with access to the Azure portal
+- An Azure Migrate project (created in the [Setting up Device42 from the Azure Migrate Portal](#setting-up-device42-from-the-azure-migrate-portal) section below)
+- An Azure Active Directory app registration with a client secret, assigned the **Contributor** role on the subscription
+- The following details collected from Azure: **Tenant ID**, **Subscription ID**, **Client ID**, **Client Secret**, and the **Migrate Project Name**
+- A running Device42 instance with business applications to export
+
 ## Setting up Device42 from the Azure Migrate Portal
 
 1\. Begin by signing up for an Azure account if you don’t already have one. You’ll have to provide a credit card to verify your identity, and agree to the conditions to continue: 
@@ -59,7 +70,7 @@ You’ll see confirmation the deployment has been initialized.
 
 For help installing Device42, head over to the Device42 documentation: [https://docs.device42.com](https://docs.device42.com). 1. The [Getting Started with Installation section is a great place to begin! [installation](getstarted/deploy-device42/index.mdx).
 
-2\. Once you’ve installed, you’ll want to begin discovering your environment. See the “Getting started with autodiscovery” section of the documentation here: [getstarted/getting-started-with-auto-discovery.mdx](/getstarted/getting-started-with-auto-discovery.mdx).
+2\. Once you’ve installed, you’ll want to begin discovering your environment. See the “Getting started with autodiscovery” section of the documentation here: [getstarted/getting-started-with-auto-discovery.mdx](getstarted/getting-started-with-auto-discovery.mdx).
 
 3\. When you’ve finished with discovery and assessment, you can export your discovered data back to Microsoft Azure. Instructions on exporting can be found here: [applications/business-services/building-business-services-in-device42.md#section-15](apps/business-services/building-business-services-in-device42.mdx#section-15).
 

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

@@ -3,9 +3,17 @@ title: "Cherwell Integration"
 sidebar_position: 4
 ---
 
+This page is for administrators who want to keep their Cherwell CMDB in sync with the infrastructure Device42 discovers. By the end, discovered assets and configuration items (CIs) from Device42 are synced into Cherwell, either once or on a schedule.
+
 Use the [Device42-Cherwell integration](https://www.device42.com/integrations/cherwell) to sync discovered infrastructure assets and configuration items (CIs) from Device42 to your Cherwell CMDB.
 
-The Device42-Cherwell integration requires a working Cherwell installation, Device42 instance, and assumes a Linux server with Python version 3.5 or later.
+## Prerequisites
+
+Before configuring the integration, make sure you have:
+- A working Cherwell installation, with administrator access to Cherwell Service Management Administrator
+- A running Device42 instance
+- A Linux server with Python version 3.5 or later to run the integration script
+- Network connectivity between the Linux server, Cherwell, and Device42
 
 ## Configuring Cherwell
 

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

@@ -7,6 +7,8 @@ import ThemedImage from '@theme/ThemedImage'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 import account from '/assets/images/cyberark-integration/create_account_for_d42_cyberark.png'
 
+This page is for Device42 administrators who use CyberArk as their secret manager and want Device42 to retrieve discovery credentials from CyberArk instead of storing them locally. By the end, Device42 will securely look up and use CyberArk-managed credentials for your discovery jobs.
+
 Each Device42 autodiscovery job is configured to use one or more sets of system credentials. If you already use CyberArk to manage passwords and other secrets, or simply don't want to use Device42 for this purpose, the Device42 CyberArk integration allows Device42 to securely store and retrieve these credentials externally as your primary secret management solution.
 
 CyberArk offers useful features such as automatic password rotation, which can be configured to rotate secrets per your specific corporate policies and industry guidelines.
@@ -15,9 +17,15 @@ CyberArk offers useful features such as automatic password rotation, which can b
 Passwords retrieved from CyberArk are not viewable in Device42.
 :::
 
-## Configure CyberArk
+## Prerequisites
 
-The CyberArk AIMWebService API is needed for the integration. To use the API, purchase and install the [Central Credential Provider (CCP) plugin](https://docs.cyberark.com/credential-providers/latest/en/content/ccp/installation.htm) on CyberArk.
+Before configuring the integration, make sure you have:
+- Administrator access to both CyberArk and Device42
+- The CyberArk AIMWebService API available, which requires the [Central Credential Provider (CCP) plugin](https://docs.cyberark.com/credential-providers/latest/en/content/ccp/installation.htm) purchased and installed on CyberArk
+- Your **CyberArk URL** and **App Id**
+- Network connectivity between the Device42 appliance and CyberArk
+
+## Configure CyberArk
 
 **Configuring CyberArk:**
 

docs/integration/external-integrations/delinea-secret-server-integration.mdx

@@ -3,6 +3,8 @@ title: "Delinea Secret Server Integration"
 sidebar_position: 8.5
 ---
 
+This page is for Device42 administrators who use Delinea Secret Server as their secret manager and want Device42 to retrieve discovery credentials from Delinea instead of storing them locally. By the end, Device42 will securely look up and use Delinea-managed credentials for your discovery jobs.
+
 Each Device42 Autodiscovery job is configured to use one (or more) sets of system credentials. If you already use Delinea Secret Server to manage passwords and other secrets or simply don't want to use Device42 for this purpose, the Device42 Delinea Secret Server integration allows Device42 to securely store and retrieve these credentials externally as your primary secret management solution.
 
 Delinea Secret Server offers useful features such as automatic password rotation, which can be configured to rotate secrets per your specific corporate policies and industry guidelines.
@@ -11,17 +13,18 @@ Delinea Secret Server offers useful features such as automatic password rotation
 Please note that passwords retrieved from Delinea Secret Server are not viewable in Device42.
 :::
 
-## Configure Delinea Secret Server
-
-Set up a user account and folder permissions in Delinea Secret Server before connecting to Device42.
+## Prerequisites
 
-### Pre-requisites
+Before configuring the integration, make sure you have:
+- Administrator access to both Delinea Secret Server and Device42
+- Network connectivity between the Device42 appliance and Delinea Secret Server
+- A user account in Delinea Secret Server with the **View Secret** permission, plus view access to the folders you want Secrets retrieved from
 
-For the Delinea Secret Server integration to work, you will need to create a user account in Delinea Secret Server with the **View Secret** permission. 
+While you can use any user account, it is _strongly recommended_ that you use a dedicated application account for Device42. Application accounts are restricted from logging into the UI and can only be used via the API.
 
-This user should also have view access to the desired folder(s) you would like Secrets retrieved from.
+## Configure Delinea Secret Server
 
-While you can use any user account, it is _strongly recommended_ that you use a dedicated application account for Device42. Application accounts are restricted from logging into the UI and can only be used via the API. 
+Set up a user account and folder permissions in Delinea Secret Server before connecting to Device42.
 
 ## Configure Device42
 

docs/integration/external-integrations/device42-confluence-connector.mdx

@@ -3,6 +3,8 @@ title: "Confluence Integration"
 sidebar_position: 7
 ---
 
+This page is for Confluence administrators who want to surface Device42 infrastructure data inside their Atlassian Confluence instance. By the end, you can display and link to Device42 objects within Confluence pages and keep that data synchronized.
+
 This integration connects Device42 to your Atlassian Confluence instance with the following features:
 
 - Display details of particular Device42 object (devices, racks, PDUs and parts are supported).
@@ -11,6 +13,13 @@ This integration connects Device42 to your Atlassian Confluence instance with th
 - Synchronize Device42 data with Confluence manually or periodically.
 - Filter set of Device42 CIs to display inside macros for specific space.
 
+## Prerequisites
+
+Before installing the add-on, make sure you have:
+- A Confluence user with the **Confluence System Administrators** global permission to install the add-on, and **Confluence Administrators** permission to configure it
+- A running Device42 instance
+- A stable network connection between the server hosting Confluence and the server hosting Device42
+
 ## Install the Confluence Integration Add-On
 
 Device42's Atlassian Confluence add-on (aka "Device42 CMDB Connector for Confluence") can be found [in the Atlassian Marketplace](https://marketplace.atlassian.com/apps/1213754/device42-cmdb-connector-for-confluence?hosting=server&tab=overview). You can easily install it using the UPM (Universal Plugin Manager) built in to Confluence. However, if you have some special requirements (e.g. an environment that blocks Confluence from access to the internet), it is possible to install the Device42 Confluence integration plugin manually. Please note that the plugin requires a stable connection between the servers hosting your Confluence application and that which is hosting Device42 for successful operation.

docs/integration/external-integrations/device42-stackstorm-integration.mdx

@@ -6,8 +6,17 @@ sidebar_position: 28.5
 import ThemedImage from '@theme/ThemedImage'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 
+This page is for automation engineers who want to drive Device42 actions from StackStorm workflows. By the end, StackStorm can query and update Device42 in response to trigger events, using the Device42 integration plugin.
+
 [StackStorm](https://docs.stackstorm.com/overview.html#about) is well suited to automate a range of IT-management workflows. In response to a trigger event, you can get the StackStorm-Device42 integration to update device details, set user permissions, send Device42 data to other systems, and more. 
 
+## Prerequisites
+
+Before setting up the integration, make sure you have:
+- A StackStorm instance. This guide runs StackStorm in a [Docker](https://docs.docker.com/get-docker/) container managed with [Docker Compose](https://docs.docker.com/compose/install/), which is suitable for testing but not production. See the [StackStorm installation options](https://docs.stackstorm.com/install/index.html) for production installs.
+- A running Device42 instance, with Device42 credentials to configure the integration plugin
+- Network connectivity between StackStorm and Device42
+
 ## Set Up the Integration
 
 The steps for setting up the StackStorm integration are:

docs/integration/external-integrations/device42-zendesk-connector.mdx

@@ -6,8 +6,17 @@ sidebar_position: 30
 import ThemedImage from '@theme/ThemedImage'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 
+This page is for administrators who want to give their Zendesk help desk access to Device42 infrastructure data through support tickets. By the end, you can link Device42 CIs to Zendesk tickets and view Device42 infrastructure details from within Zendesk.
+
 Device42 discovery keeps your infrastructure documentation up-to-date, and with the Zendesk connector, your help desk can access IT infrastructure information via support tickets. 
 
+## Prerequisites
+
+Before setting up the integration, make sure you have:
+- Access to Zendesk and Device42 to configure the integration
+- Your [Device42 Cloud Connector](integration/external-integrations/device42-cloud-connector-overview.mdx) configured (under **Tools > Integrations > Cloud Services**) to allow communication between Device42 and Zendesk
+- A Zendesk API token, created as described in [Create a Zendesk API Token](#create-a-zendesk-api-token) below
+
 ## Benefits of the Device42-Zendesk Integration
 
 With the Device42-Zendesk integration, you'll benefit from the ability to:

docs/integration/external-integrations/hashicorp-vault-integration.mdx

@@ -3,6 +3,8 @@ title: "HashiCorp Vault Integration"
 sidebar_position: 12.5
 ---
 
+This page is for Device42 administrators who use HashiCorp Vault as their secret manager and want Device42 to retrieve discovery credentials from Vault instead of storing them locally. By the end, Device42 will securely look up and use Vault-managed credentials for your discovery jobs.
+
 Each Device42 autodiscovery job is configured to use one (or more) sets of system credentials. If you already use HashiCorp Vault to manage passwords and other secrets, or simply don't want to use Device42 for this purpose, the Device42 HashiCorp Vault integration allows Device42 to securely store and retrieve these credentials externally as your primary secret management solution.
 
 HashiCorp Vault offers useful features such as automatic password rotation, which can be configured to rotate secrets per your specific corporate policies and industry guidelines.
@@ -11,6 +13,13 @@ HashiCorp Vault offers useful features such as automatic password rotation, whic
 Please note that passwords retrieved from HashiCorp Vault are not viewable in Device42.
 :::
 
+## Prerequisites
+
+Before configuring the integration, make sure you have:
+- Administrator access to both HashiCorp Vault and Device42
+- Network connectivity between the Device42 appliance and HashiCorp Vault
+- The Vault details listed under [Configuring HashiCorp Vault](#configuring-hashicorp-vault) below: an AppRole (Role ID and Secret ID) with read access to the required secret paths, the secret engine path, and the namespace if you use Multi-Tenancy
+
 ## Configuring HashiCorp Vault
 
 - **(Required) Role ID / Secret ID:** For the HashiCorp Vault integration to work, you will need to create an AppRole in HashiCorp Vault with a policy that grants "read" to the desired Secret Paths.