diff --git a/docs/auto-discovery/windows-and-hyper-v-auto-discovery.mdx b/docs/auto-discovery/windows-and-hyper-v-auto-discovery.mdx index 743c75618..4e502df0f 100644 --- a/docs/auto-discovery/windows-and-hyper-v-auto-discovery.mdx +++ b/docs/auto-discovery/windows-and-hyper-v-auto-discovery.mdx @@ -326,7 +326,7 @@ WinRM-specific items are listed where applicable, but the permissions must be en The following requirements represent the minimum user account permissions for Device42 to connect to and discover a Windows host. -1. Ensure that at least **Enable Account**, **Remote Enable**, **Read Security**, and **WMI permissions** are applied to the discovery user account and to the following WMI namespaces and sub-namespaces: +1. Ensure that at least **Enable Account**, **Remote Enable**, and **Read Security** WMI permissions are applied to the autodiscovery user account for the following WMI namespaces and sub-namespaces: diff --git a/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx b/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx index 41ff5902d..273e4cad1 100644 --- a/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx +++ b/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx @@ -5,6 +5,8 @@ sidebar_position: 3 import ThemedImage from '@theme/ThemedImage' import useBaseUrl from '@docusaurus/useBaseUrl' +import fsAdminImage from '/assets/images/freshservice-integration/fs-admin.png' +import fsInventoryMenuImage from '/assets/images/freshservice-integration/fs-inventory-menu.png' :::tip This page covers advanced data mapping customization and XML file editing. @@ -774,3 +776,276 @@ If you want Device42 to update `asset_state` values, set `skip-update` to `"fals ``` + +### Example 4: How To Sync Buildings, Rooms, and Racks From Device42 to Freshservice + +By default, the `mapping.xml` file does not sync Building, Room, or Rack data from Device42 to Freshservice. The following steps, based on version 6.0 of the default `mapping.xml` file, walk you through how to set this up: + +- Create Building and Room as custom asset types in Freshservice (Rack is available by default) +- Sync buildings, rooms, and racks +- Sync relationships between rooms and buildings, and between racks and rooms +- Delete buildings, rooms, and racks that no longer exist in Device42 +- Delete relationships that no longer exist in Device42 + +**Step 1:** Create Building and Room as custom asset types in Freshservice. Rack is already available by default under the **DataCenter** parent asset type and does not need to be created. + +1. Go to **Admin** in the ellipses menu (left panel). + + + +2. Search for "Asset Types & Fields" + + ![Asset Types & Fields](/assets/images/freshservice-integration/fs-search-asset.png) + +3. Find the **DataCenter** parent asset type and click the **plus symbol** to add the asset types. + + ![Add new asset types](/assets/images/freshservice-integration/fs-parent.png) + +4. Verify that the new asset types are added by going to **Inventory** and clicking **Add New**. + + + + The **Asset Type** dropdown will display the new asset types. + + ![New asset type dropdown](/assets/images/freshservice-integration/fs-dropdown.png) + +**Step 2:** To sync buildings, add the following `` element to your `mapping.xml` file before the `Delete assets from Freshservice that do not exist in Device42` cleanup task. + +The DOQL query fetches data from `view_building_v1`. The [`` element](#the-task-element-elements) maps the returned data to the `Building` asset type in Freshservice, grouping them under the **General** and **Building** sections. + +
+ Click to expand the Building task + +```xml + + + + + + + + + + + + + + + + + + + + +``` + +
+ +**Step 3:** Add the following `` element after the Building task to sync rooms. Similarly, the DOQL query fetches the room data, and the `` element maps the returned data to the `Room` asset type in Freshservice, grouping them under the **General** and **Room** sections. + +
+ Click to expand the Room task + +```xml + + + + + + + + + + + + + + + + +``` + +
+ +**Step 4:** To sync racks, add the following `` element after the Room task. + +
+ Click to expand the Rack task + +```xml + + + + + + + + + + + + + + + + + +``` + +
+ +**Step 5:** Add the following `` element after the three asset tasks above to sync relationships between rooms and buildings. The DOQL query joins `view_room_v1` and `view_building_v1`. The `` element uses `downstream-relationship` and `upstream-relationship` attributes to define the **Located In** – **Houses** relationship type between each room and its parent building. + +
+ Click to expand the Room to Building relationship task + +```xml + + + + + + + + + + + +``` + +
+ +**Step 6:** Add the following `` element after the Room to Building task to sync relationships between racks and rooms. The DOQL query joins `view_rack_v1` and `view_room_v1`, and the `` element follows the same pattern as Step 5 — `downstream-relationship="Located In"` on the rack side and `upstream-relationship="Houses"` on the room side. + +
+ Click to expand the Rack to Room relationship task + +```xml + + + + + + + + + + + +``` + +
+ +**Steps 7–9:** To delete buildings, rooms, and racks that no longer exist in Device42, locate the `Delete assets from Freshservice that do not exist in Device42` cleanup task near the bottom of your `mapping.xml` file (see [The `mapping.xml` File Tasks](#the-mappingxml-file-tasks) for an overview of how cleanup tasks work). + +Add the following `UNION` clauses to the end of its DOQL query, before the closing `"`. Each clause selects the Device42 IDs of all existing buildings, rooms, and racks so Freshservice can identify and remove any that have been deleted. + +
+ Click to expand the code block + +```sql +union + +select + format('Building-%s', b.building_pk) as device42_id +from view_building_v1 b + +union + +select + format('Room-%s', r.room_pk) as device42_id +from view_room_v1 r + +union + +select + format('Rack-%s', r.rack_pk) as device42_id +from view_rack_v1 r +``` + +
+ +**Steps 10–11:** To delete relationships between rooms and buildings, and between racks and rooms, that no longer exist in Device42, update both `Delete asset relationships from Freshservice that do not exist in Device42` tasks. The `mapping.xml` file contains two versions of this task for [version compatibility](#the-task-element-attributes) — one with `d42_min_version="19.05.00"` and one with `d42_max_version="19.04.99"`. + +Add the following `UNION` clauses to the end of each task's DOQL query, before the closing `"`. Each clause selects the current room-to-building and rack-to-room relationships in Device42 so Freshservice can identify and remove any that no longer exist. + +
+ Click to expand the code block + +```sql +union + +select + r.name as dependent_device_name, + format('Room-%s', r.room_pk) as dependent_device_device42_id, + 'Located In' as downstream_relationship, + b.name as dependency_device_name, + format('Building-%s', b.building_pk) as dependency_device_device42_id, + 'Houses' as upstream_relationship +from view_room_v1 r +inner join view_building_v1 b on r.building_fk = b.building_pk + +union + +select + rk.name as dependent_device_name, + format('Rack-%s', rk.rack_pk) as dependent_device_device42_id, + 'Located In' as downstream_relationship, + rm.name as dependency_device_name, + format('Room-%s', rm.room_pk) as dependency_device_device42_id, + 'Houses' as upstream_relationship +from view_rack_v1 rk +inner join view_room_v1 rm on rk.room_fk = rm.room_pk +``` + +
+ +Save the file and [reupload it to Freshservice](#reupload-the-mappingxml-file) using the **Upload Custom Mapping** button, then run a [full sync](index.mdx#run-the-data-synchronization) to populate the new building, room, and rack assets in Freshservice. diff --git a/static/assets/images/freshservice-integration/fs-add-asset-type.png b/static/assets/images/freshservice-integration/fs-add-asset-type.png new file mode 100644 index 000000000..f3f08d1c1 Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-add-asset-type.png differ diff --git a/static/assets/images/freshservice-integration/fs-admin.png b/static/assets/images/freshservice-integration/fs-admin.png new file mode 100644 index 000000000..45e76340d Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-admin.png differ diff --git a/static/assets/images/freshservice-integration/fs-dropdown.png b/static/assets/images/freshservice-integration/fs-dropdown.png new file mode 100644 index 000000000..117c02178 Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-dropdown.png differ diff --git a/static/assets/images/freshservice-integration/fs-inventory-menu.png b/static/assets/images/freshservice-integration/fs-inventory-menu.png new file mode 100644 index 000000000..15d372825 Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-inventory-menu.png differ diff --git a/static/assets/images/freshservice-integration/fs-parent.png b/static/assets/images/freshservice-integration/fs-parent.png new file mode 100644 index 000000000..ae79dcce9 Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-parent.png differ diff --git a/static/assets/images/freshservice-integration/fs-search-asset.png b/static/assets/images/freshservice-integration/fs-search-asset.png new file mode 100644 index 000000000..6cef4acd2 Binary files /dev/null and b/static/assets/images/freshservice-integration/fs-search-asset.png differ