Merge pull request #493 from ritza-co/19.07.16

Docs 19.07.16 release (Week 5, 2026)

Author: sixhobbits

.gitignore

@@ -16,7 +16,7 @@
 .env.production.local
 *.swp
 .vscode/
-CLAUDE.md
+.claude
 
 npm-debug.log*
 yarn-debug.log*

docs/auto-discovery/agent-based-discovery.mdx

@@ -6,15 +6,17 @@ sidebar_position: 3
 import ThemedImage from '@theme/ThemedImage'
 import useBaseUrl from '@docusaurus/useBaseUrl'
 
-There are special situations where using an agent for discovery makes more sense. The IT environment may be unreachable from the network or security-hardened rules may be in place that limit traffic flow. Device42 offers many optional auto-discovery agents across several [supported platforms](#supported-platforms).
+This page is for Device42 administrators who need to use agent-based discovery when their IT environment is unreachable from the network or security-hardened rules limit traffic flow. 
 
-As a best practice, we recommend using agentless discovery over agent-based discovery when possible. The information gathered is the same, but the agent does not support Resource Utilization (RU). 
+Device42 offers optional auto-discovery agents across several [supported platforms](#supported-platforms).
+
+Use agentless discovery over agent-based discovery when possible. Both methods gather the same information, but the agent does not support Resource Utilization (RU) or database discovery. 
 
 To learn about using the agent for **offline** discovery, see [Agent-Based Offline Discovery](agent-based-offline-discovery.mdx).
 
 ## Supported Platforms
 
-Device42 autodiscovery agents are available for deployment on the following platforms:
+Device42 offers autodiscovery agents for the following platforms:
 
 - Windows 64-bit (Recommended)
 - Windows 32-bit
@@ -32,22 +34,22 @@ Device42 autodiscovery agents are available for deployment on the following plat
 See **[Windows Discovery Agent Service Wrapper](/getstarted/deploy-device42/windows-service-installation.mdx)** and **[Mac Agent Service Launcher](/auto-discovery/mac-agent-service-launcher.mdx)** for information on installing versions of the Windows and Mac discovery agent as a service.
 
 :::warning
-Do not set up an autodiscovery scan using critical or production account credentials. Please create a separate, dedicated account to use only for discovery.
+Do not set up an autodiscovery scan using critical or production account credentials. Create a separate, dedicated account to use only for discovery.
 
-Doing so, depending on permissions granted and configured password policies could result in account lock-out, therefore causing an otherwise completely avoidable outage.
+Account lockout could occur depending on permissions and password policies, causing an otherwise avoidable outage.
 :::
 
-## Proxy Environment Variables
+## Configure Proxy Environment Variables
 
-Proxy settings are not required, but if you need the agents to access your network via a proxy, you can set the following environment variables, which the agents will respect:
+Proxy settings are not required, but if you need the agents to access your network via a proxy, set the following environment variables:
 
 - **HTTP_PROXY:** Define the HTTP proxy server.
 - **HTTPS_PROXY:** Define the HTTPS proxy server.
 - **NO_PROXY:** A comma-separated list of IP addresses that should not go through the proxy.
 
 On Windows, click the **Environmental Variables** button in the System Properties window to set environment variables.
 
-## Installation
+## Install the Agent
 
 Download the client from **Discovery > Agent Based Scans**. Enter the URL as it will be accessed by the agent from the remote machine, and choose your **Platform** from the dropdown: Windows, Mac, Linux, FreeBSD, and so on.
 
@@ -68,7 +70,7 @@ The agent can be run from the command line or can be scheduled using the relevan
     -capture-host-files
           capture hosts files
     -config-file string
-          reads the config from an encrypted file (Only works for signed binaries. Ignored Otherwise)
+          reads the config from an encrypted file (Only works for signed binaries. Ignored otherwise)
     -debug
           prints the data being sent and result of post operation
     -device-customer string
@@ -176,13 +178,13 @@ The agent can be run from the command line or can be scheduled using the relevan
   ```
 </details>
 
-## Scheduling With Crontab in Linux
+## Schedule the Agent With Crontab on Linux
 
-For best results, we recommend running the command with `sudo`. Make sure that `/home/system\_dev42/bin/d42agent` is owned by `root` with `\-rwx—— (0700)` permissions. This prevents the non-root user `system\_dev42` from overwriting the agent or adding it to `root`’s _crontab_ (or `cron.daily/hourly`) while allowing root to execute it.
+For best results, run the command with `sudo`. Make sure that `/home/system_dev42/bin/d42agent` is owned by `root` with `-rwx—— (0700)` permissions. This prevents the non-root user `system_dev42` from overwriting the agent or adding it to `root`’s crontab (or `cron.daily/hourly`) while allowing root to execute it.
 
-### Using a Limited Account
+### Use a Limited Account
 
-The Linux agent runs as `root` by default. However, it is possible to configure the agent to run with a limited, non-root account. Here's how you can create one:
+The Linux agent runs as `root` by default. However, you can configure the agent to run with a limited, non-root account.
 
 1. **Create a limited account**:
    - Create a new Linux account (for example, `d42_limited`) without root access.
@@ -205,7 +207,7 @@ The Linux agent runs as `root` by default. However, it is possible to configure
      d42_limited ALL=(ALL) NOPASSWD: /usr/sbin/arp, /bin/cat, /sbin/ifconfig, /usr/bin/curl, /usr/bin/wget, /bin/ls, /usr/sbin/dmidecode, /usr/bin/lsof, /usr/bin/ps, /usr/bin/python3, /bin/uname, /usr/bin/systemctl, /sbin/ip, /usr/bin/df, /usr/bin/free, /usr/bin/mount, /usr/sbin/iptables
      ```
 
-     Read the [Commands Required by the Discovery Agent](#commands-required-by-the-discovery-agent) section to see the full list of commands required by the agent.
+     Read the [Commands Required by the Discovery Agent](#required-agent-commands) section to see the full list of commands required by the agent.
 
 3. **Configure the file ownership and permissions**:
    - Make sure that the `d42agent` binary is still owned by `root` and has restricted permissions:
@@ -222,7 +224,7 @@ The Linux agent runs as `root` by default. However, it is possible to configure
      sudo -u d42_limited /home/system_dev42/bin/d42agent
      ```
 
-### Commands Required by the Discovery Agent
+### Required Agent Commands
 
 <details>
   <summary>Click to expand the code block</summary>
@@ -263,14 +265,14 @@ The Linux agent runs as `root` by default. However, it is possible to configure
   ```
 </details>
 
-We need to ensure the limited account can execute all these commands through `sudo` without requiring a password.
+Ensure the limited account can execute all these commands through `sudo` without requiring a password.
 
 Here's a shell script that can be used to check whether the limited account has access to the commands:
 
 <details>
   <summary>Click to expand the code block</summary>
 
-  ```py
+  ```bash
     #!/bin/bash
 
     # List of commands required by the discovery agent
@@ -294,21 +296,21 @@ Here's a shell script that can be used to check whether the limited account has
 
 You can run this script to verify that the limited account has access to all the required commands.
 
-## Linux and Mac Note
+## Run the Agent on Linux and Mac
 
 After downloading the agent, make it executable by running the command `chmod +x <agentname>` and use `sudo` for best results. Use the command `--sudo-password="password"` to pass in the password.
 
 You may experience an issue with opening the application on your Mac. If so, please use the following Apple support link to [open a Mac app from an unidentified developer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).
 
-## Windows Note
+## Schedule the Agent on Windows
 
-After downloading the agent, use the Windows Task Scheduler to schedule the executable file (\*.exe) to run at the intervals you define.
+After downloading the agent, use the Windows Task Scheduler to schedule the executable file (`*.exe`) to run at the intervals you define.
 
 ## View Agent Version and Agent Last Check-in Date
 
 The Devices list page now includes two columns that display the **Agent Version** and the **Agent Last Check-in Date** for devices discovered by the agent.
 
-- On the Devices list page under **Resources > Compute > All Devices**, click the **gear icon** below the Advanced button to display the column list.
+- On the Devices list page under **Resources > Compute > All Devices**, click the **gear icon** below the **Advanced** button to display the column list.
 
     <ThemedImage
     alt="Gear icon on Devices list page"
@@ -329,9 +331,9 @@ The Devices list page now includes two columns that display the **Agent Version*
     }}
     />
 
-- If you want to define a new column view, type a name for the view in the field to the right of the **Table Columns** dropdown and **Save** the view. Device42 displays the agent information for devices discovered by the agent.
+- If you want to define a new column view, type a name for the view in the field to the right of the **Table Columns** dropdown and **Save** the view. Device42 displays information for devices discovered by the agent.
 
-### Filtering with Agent Columns
+### Filter Devices Using Agent Columns
 
 You can use Agent Version and Agent Last Check-in Date to filter the devices list to look for devices found by specific agents or during certain periods.
 
@@ -355,7 +357,7 @@ You can use Agent Version and Agent Last Check-in Date to filter the devices lis
     }}
     />
 
-- You can also use the agent columns in **Advanced search**. For example, the query below searches for devices discovered with a **Agent Last Check-in Date** less than 365 days ago.
+- You can also use the agent columns in **Advanced search**. For example, the query below searches for devices discovered with an **Agent Last Check-in Date** less than 365 days ago.
 
     <ThemedImage
     alt="Advanced search"
@@ -364,3 +366,7 @@ You can use Agent Version and Agent Last Check-in Date to filter the devices lis
         dark: useBaseUrl('/assets/images/agent-based-discovery/advanced-search-dark.png'),
     }}
     />
+
+## Agent Update Behavior
+
+When a new version of the Main Appliance is installed, deployed agents automatically update to the latest version on check-in.

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

@@ -87,3 +87,9 @@ The following note in the UI describes how passwords are retrieved and matched b
 
 > By default, passwords are looked up by name in CyberArk by matching the Password label in Device42. If no label is provided then the username will be matched directly.
 You may also customize the Folder or Safe from which the password is retrieved by utilizing the Password Custom fields named Folder and Safe.
+
+### Long and Short Account Names
+
+If your CyberArk account uses a long account name, enter it in the Secret label field for matching purposes.  
+
+If your CyberArk account uses a short username, enter it in the Secret username field for the discovery job.

docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx

@@ -42,33 +42,30 @@ To get started, download the default mapping XML file and view the current mappi
 
 ## The `mapping.xml` File Structure
 
-Open the `mapping.xml` file in a text or code editor to view and edit the data mapping. Version 1.0 of the file has around 6010 lines. There are tasks for syncing data, tasks for syncing the relationships between Device42 CI types (by recreating them between the corresponding Freshservice types), and two cleanup tasks for deleting any assets or asset relationships from Freshservice that do not exist in Device42.
+Open the `mapping.xml` file in a text or code editor to view and edit the data mapping; there are tasks for syncing data, tasks for syncing the relationships between Device42 CI types (by recreating them between the corresponding Freshservice types), and cleanup tasks for deleting any assets or asset relationships from Freshservice that do not exist in Device42.
 
-    ![mapping.xml in VS Code](/assets/images/freshservice-integration/mapping-v1-annotated.png)
+    ![mapping.xml in VS Code](/assets/images/freshservice-integration/mapping-v5-annotated.png)
 
  You can customize the data mapping between Device42 and Freshservice by modifying and adding to these tasks. Refer to [The `mapping.xml` File Tasks](#the-mappingxml-file-tasks) table below for descriptions of the default mapping tasks, types, and their version requirements. 
 
-For example, the following `<task>` element copies product information from Device42 to Freshservice:
+For example, the following `<task>` element copies software information from Device42 to Freshservice:
 
 <details>
   <summary>Click to expand the code block</summary>
     ```xml
     <tasks>
-        <task enable="true" name="Products" type="product" description="Copy Product info from Device42 to Freshservice" d42_min_version="16.19.00">
+        <task enable="true" name="Software" type="software" description="Copy Softwares from Device42 to Freshservice using DOQL">
             <api>
-                <target asset-type="Hardware"/>
+                <target/>
                 <resource
-                    doql="
-                    select distinct
-                        view_vendor_v1.name as manufacturer,
-                    <!-- ... -->
-                    "
+                    doql="select * from (select trim(name) as name, 'discovered' as software_type, min(view_software_v1.notes) as notes, 'desktop' as application_type, min(last_changed) as last_changed from view_software_v1 group by trim(name)) a"
                 />
             </api>
-            <mapping key="name" doql-suffix=" where GREATEST(view_hardware_v2.last_changed, view_vendor_v1.last_changed, view_device_v2.last_changed) >'%s'">
-                <field resource="name" source-type="string" target="name" target-type="string" max-length="255" escape="true"/>
-                <field resource="manufacturer" source-type="string" target="manufacturer" target-type="string"
-                   not-null="true" set-space="true" min-length="1" max-length="255"/>
+            <mapping key="name" source="Softwares" doql-suffix=" where last_changed>'%s'">
+                <field resource="name" source-type="string" target="name" target-type="string" target-header="General" max-length="255" escape="true"/>
+                <field resource="notes" source-type="string" target="notes" target-type="string" target-header="General" max-length="2000"/>
+                <field resource="software_type" source-type="string" target="status" target-type="string" target-header="General"/>
+                <field resource="application_type" source-type="string" target="application_type" target-header="General"/>
             </mapping>
         </task>
     ```
@@ -86,7 +83,7 @@ Let's take a closer look at the attributes and elements of the `<task>` elements
 
     Note that if you turn off a task that has `asset` or `asset_relationship` as its corresponding Freshservice type (for example, devices, business services, and resources in Device42), you'll need to find and remove its corresponding query snippet in the `Delete` cleanup tasks. For an example, see [this answer in the FAQ section](#how-do-i-prevent-a-relationship-between-two-device42-asset-types-from-syncing-to-freshservice).
 
-- `name`: You can edit the task name. Task names appear in the [integration app's **Data Mapping Chart**](#data-mapping-between-device42-and-freshservice).
+- `name`: You can edit the task name. Task names appear in the integration app's **Data Mapping Chart**.
 - `type`: Holds the [Freshservice classification](https://api.freshservice.com/) of the data. The valid types are:
 
   - `product`
@@ -122,7 +119,7 @@ The `<mapping>` element contains:
 Typically, the first `<field>` represents the Device42 data returned from the query put in a field. The second `<field>` element describes the equivalent field in Freshservice.
 
 - `resource`: The same as the `target` value.
-- `source-type`: Not functionally critical; this provides the data type displayed on the [integration app's **Data Mapping Chart**](#data-mapping-between-device42-and-freshservice).
+- `source-type`: Not functionally critical; this provides the data type displayed on the integration app's **Data Mapping Chart**.
 - `target`: The Device42 field to be mapped to Freshservice. The Freshservice convention is to use the display name in snake case, occasionally with the ID of the asset type as a suffix. For example, `memory_max_usage` and `memory_reservation_used`. The sync process determines the ID. Please look up which target field names to use in the [Freshservice API documentation](https://api.freshservice.com/). 
 - `escape`: This is used on field elements where `target="name"`. Some characters used in Device42 names aren't supported in Freshservice and need to be substituted. When creating a new task, you can set this to `true`, but disable it if mismatching issues occur.
 
@@ -433,12 +430,10 @@ If you can't find a task related to your custom field, you can create a new `<ta
 
 4. Now it's time to map the custom field to Freshservice. Add a new `<field>` element in the `<mapping>` tag section of the XML file. You'll need to keep Freshservice open and follow the next step to get the exact Freshservice values to use in the new `<field>` element below.
 
-   ![Add a new field element](/assets/images/freshservice-integration/custom-field-map-code.png)
-
     ```xml
     <!-- Custom Fields -->
     <field resource="cf_name" source-type="string" target="cf_name" target-type="string"
-    target-header="Server" not-null="true" set-space="true" min-length="1" max-length="255"/>
+    target-header="Server" min-length="1" max-length="255"/>
     <!-- Custom Fields -->
     ```
 
@@ -615,7 +610,7 @@ To download the full logs, scroll down and click the **Download Full Log** butto
 
 This section provides specific examples of how to edit the `mapping.xml` file to change the data synced from Device42 to Freshservice.
 
-The line estimates in the examples are based on the default version 1.0 of the `mapping.xml` file and won't match your file exactly if you've customized the sync or used an updated version.
+The line estimates in the examples are approximate and may vary based on your mapping file version.
 
 ### Example 1: How Can I Stop the Sync From Importing Contracts From Device42 to Freshservice?
 
@@ -624,7 +619,7 @@ The line estimates in the examples are based on the default version 1.0 of the `
 Set the `enable` attribute to `false` on those `<task>` elements:
 
 1. Find the task with the description `Copy contract info from Device42 to Freshservice` (around line `2372`):
-   
+
     ![Line 2372](/assets/images/freshservice-integration/example-vscode-4.png)
 
    Change `enable="true"` to `enable="false"`:
@@ -724,7 +719,7 @@ By default, Device42 does not update `asset_state` values in Freshservice (in De
 
 The mapping file includes `<field>` elements with `asset_state` as the target. The `skip-update` attribute is set to `"true"` to prevent the overwriting of values that may trigger Freshservice workflow automations. 
 
-If you want Device42 to update `asset_state` values, set `skip-update` to `"false"`. There are three `<field>` elements to update in version 2.0 of the default `mapping.xml` file:
+If you want Device42 to update `asset_state` values, set `skip-update` to `"false"`. There are three `<field>` elements to update in the default `mapping.xml` file:
 
 1. Find the attribute on line 493 (for DOQL v2).