Device42 Freshservice Integration

Seamless ITSM and CMDB integration.

Device42 integrates with Freshservice to provide the following capabilities:

• Enhanced ITSM workflows with detailed device, user, and software information.

• An understanding of how changes to a particular application or network port could affect your business services.

• Flexible CMDB import options that ensure the right data is brought into the right place.

• A single login page for accessing both Device42 and Freshservice.

  

Install the Device42 Integration App on Freshservice

The installation process has three steps, which are discussed in more detail in the sections that follow.

1. Enable the Cloud Connector in Device42

Ensure that cloud services are enabled and configured:

1. Navigate to Tools > Integrations > Cloud Services.

2. Enter your externally accessible Device42 IP address or FQDN in the D42 URL for SaaS apps field. If you have configured a digital certificate, you can enter the name of the device instead.

3. Select your Cloud Connector location or environment. It's set to USA by default.

   

2. Create a Freshservice External Integration in Device42

1. Navigate to Tools > Integrations > External Integrations and click + Add External Integration.

   caution

   Please do not use the Verification Token generated when configuring the external integration, as this value will change when you save. Copy the token from the list page view after saving.

2. Enter the URL of your Freshservice instance.

3. Under Type, choose Freshservice.

4. You can optionally select Enable Freshworks SSO to activate single sign-on (SSO). We recommend using this feature for a seamless login experience when working with the integration.

   

   To enable the SSO feature, ensure that you have an administrator in your Device42 instance with the same email address as your Freshservice agent:

   • Navigate to Tools > Admin & Permissions > Administrators.
   • Click + Add Local Admin if you need to create an admin user with the email address associated with your Freshservice agent.
   

5. Click Save and copy the Verification Token from the table on the External Integrations list page.

   

3. Install the Marketplace Integration App in Freshservice

Enable the Device42 integration in Freshservice using the Discovery Hub setup wizard.

1. Log in to your Freshservice agent account.

2. Click the ellipsis menu (located at the bottom of the left panel) and select Admin. Use the "Search admin" search bar to search for hub.

3. From the Discovery Hub view, click Steps to configure trial.

   

4. Click Next three times to get to the Install the Device42 app section of the installation wizard.

5. Install the Device42 for Freshservice app.

   

6. Fill in the fields on the form. Enter your Freshservice Domain Name.

   

   • From the dropdown, choose the Cloud Connector region that matches the option you selected under Cloud Services in Device42 (see step 3 of the Enable the Cloud Connector in Device42 section above.
   • Enter the Verification Token generated from the Device42 external integration you added. Make sure you're using the token from the External Integrations view page and not the token from the + Add External Integrations form.

7. Open the Freshservice Default Approver dropdown and select your admin user from the list. If the list is populated, then the information you've entered so far should be correct. If you are unable to select a user, check the URL and Cloud Connector.

   

8. Click Install to add the app to your Freshservice instance.

Complete the Single Sign-On Setup

To set up SSO, you need a user account in Device42 that mirrors your Freshservice user account and associated email address. That is, you need to have an admin user in Device42 with the same email address as your Freshservice agent.

After installing the integration app in Freshservice, set up an External Integration in Device42 and complete the SSO configuration in the Device42 Appliance Manager:

1. Ensure that you have checked the Enable SSO option on the Device42 External Integration. See Step 4 of the Create a Freshservice External Integration in Device42 section above.

2. From the Appliance Manager, navigate to Global Settings > SAML/SSO Settings.

3. Check the Enable Freshworks SSO and choose between the login options:

   

• Auto Login: Device42 will try to log you in automatically, without first directing you to the login page. If the automatic login fails, you will be directed to the login page.
• Show Login Page: Device42 will always direct you to the login page (with buttons for normal and SSO login).

4. Restart your Device42 instance. From the Appliance Manager, go to Application > Restart Application and check the confirmation box before restarting Device42.

   

Test the SSO as follows:

1. Log in to your Freshworks instance with the same email address as your Device42 admin user.

2. Log out of Device42 and refresh the page. Click on the new Freshworks Login button.

   

3. Authorize the Freshworks SSO the first time you use it.

   

Now, when you're logged out of both Device42 and Freshservice, clicking the Freshworks Login button in Device42 will direct you to the Freshworks sign-in page.

Using the Integration App

Configure the Device42 for Freshservice app to sync data from Device42 to Freshservice and view and edit the fields mapped between Device42 and Freshservice.

Find the Settings Tab

Make your way to the Settings tab, located on the configuration page of the Device42 integration app:

1. Click the ellipsis menu (located at the bottom of the left panel) and select Admin (1). Enter apps in the "Search admin" search bar to quickly bring up the Apps option.

2. From the Apps page, click Manage Apps.

3. Under the Installed Apps tab, find the Device42 for Freshservice app and select Settings > Edit settings (2).

   

Run the Data Synchronization

Data synchronization (sync) imports new CIs and updates the existing ones within Freshservice. Locate the synced data under Assets > Inventory in Freshservice.

You can schedule a daily sync and run the sync immediately. We recommend that you run a full sync after installing the integration app.

From the Settings tab, scroll down to the Schedule Synchronization section.

To automatically fetch data from Device42 daily, check the Use Schedule checkbox and enter a Sync Time (UTC) at which to perform the sync.

To run the sync immediately, click the Manual sync button to reveal the options:

• Select Run Full Sync (blue button) to sync all items from Device42 to Freshservice, regardless of when the items were added or updated in Device42.
• Select Run Partial Sync (green button) to sync only the items that have been changed in Device42, either added or updated, since the last successful sync.

View Sync History Logs

From Freshservice, go to Admin, search for apps, and click Manage Apps. Find the Device42 for Freshservice app, open the Settings dropdown, and select Edit Settings.

The synchronization history is useful for debugging issues and seeing the number of devices brought into Freshservice. You can view the previous and currently running syncs.

Select a row from the sync history table to view the logs associated with it (if there are any). The displayed text is limited to 4,000 characters.

Scroll down to view error messages and other details.

To download the full logs, use the Download Full Log button in the lower-left corner of the text area.

note

A full sync will be forced during upgrades to get new data from Device42. The sync history type will listed as a full upgrade instead of an incremental one until a successful sync has been performed.

View Mapped and Unmapped Data for Specific Assets

We understand that some fields within Device42 may not easily translate to fields within Freshservice. We’ve added the ability to view these fields from one location, eliminating the need to navigate between applications. To view the mapped and unmapped data for a device within Freshservice, follow the steps below.

1. Navigate to Assets > Inventory from the Freshservice dashboard. On the Inventory screen, select the asset (imported from Device42) for which you want to view mapped and unmapped data.

   

2. On the right panel of the page, under Apps, you will see the Device42 application. Click the box to expand it and click the View Device42 Data button.

   

3. A window will open, and the current device's mapped and unmapped data will be displayed.

   

4. Click View Asset in Device42 to be redirected to the asset in Device42.

   

Custom Data Mapping

Download the mapping.xml File

• From the Settings tab of the Configuration page, scroll down to the Schedule Synchronization section and click the Data Mapping button to reveal the custom mapping buttons.

• Click the Download Default Mapping button to download the mapping.xml file. Customize the mapping between fields in Device42 and Freshservice by downloading, editing, and reuploading the mapping.xml file.

  

View the Current Mapping

• Explore the mapped fields and their data types by selecting an asset type (for example, Devices) from the Data Mapping Chart. Scroll to the bottom of the page to view the mapping table.

  

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.

You can customize the data mapping between Device42 and Freshservice by modifying and adding to these tasks. Refer to The mapping.xml 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:

Click to expand the code block

<tasks>
    <task enable="true" name="Products" type="product" description="Copy Product info from Device42 to Freshservice" d42_min_version="16.19.00">
        <api>
            <target asset-type="Hardware"/>
            <resource
                doql="
                select distinct
                    view_vendor_v1.name as manufacturer,
                <!-- ... -->
                "
            />
        </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>
    </task>

Let's take a closer look at the attributes and elements of the <task> elements so you can understand what to adapt or emulate to suit your particular case.

The <task> Element Attributes

• enable: You can turn off syncing for individual tasks by setting the enable attribute to false. For example:

  <task enable="false" name="Products" type="product" description="Copy Product info from Device42 to Freshservice" d42_min_version="16.19.00">

  Note that if you turn off a task that has asset or asset_relationship as its corresponding Freshservice type (for example, devices, business apps, 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.

• name: You can edit the task name. Task names appear in the integration app's Data Mapping Chart.

• type: Holds the Freshservice classification of the data. The valid types are:

  • product
  • asset
  • software
  • software_installation
  • asset_relationship
  • contract
  • contract_asset
  • component
  • deployment
  • service
  • daemon_set
  • stateful_set

• description: You can write and edit a brief task description.

• d42_min_version and d42_max_version: These attributes specify the minimum and maximum Device42 versions required to run a task. Tasks may have a maximum version, a minimum version, both, or neither. You can generally leave this out when creating new tasks.

The <task> Element Elements

The <api> and <mapping> elements are nested in each task. Think of the <api> element as relating to Device42 data and the <mapping> element as relating to the Freshservice fields.

The <api> element contains:

• <target>: This holds any additional asset-type classifications from Device42 and will be empty in most cases. For example, Hardware refers to the Hardware Model under which the details of physical devices are organized.
• <resource>: This is the DOQL query used to fetch data from Device42.

The <mapping> element contains:

• key: This is used to look the item up in Freshservice. It usually has name as its value.
• doql-suffix: A query condition used to fetch data that has been updated since the last sync. Omitting this value results in a full data sync.

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.
• 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.
• 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.

tip

Use our InsightsAI chat under Analytics > InsightsAI to interpret DOQL query snippets quickly in the context of the Device42 data tables.

Additional Matching Criteria for Updating Existing Items

Some <task> elements in mapping.xml have a helper <matching> element for updating synched data that currently exists in Freshservice but may have slightly different name formats. For example, asset-type syncing tasks include the <matching> element to determine which query fields are used to match which asset attributes when trying to find a match. For example:

Click to expand the code block

<task enable="true" name="Devices" type="asset" description="Copy Servers from Device42 to Freshservice ..."> 
<!-- Device42 query -->
    <matching>
        <source-1 
                device42-id="device42_id" 
                name="name" 
                serial-number="serial_no" 
                uuid="uuid" 
                item-id="instance_id"
                mac-address="snmp_device_mac_address"
                imei-number="imei" 
        />
    </matching>
    <mapping ...>
    <!-- and so on... -->

Reupload the mapping.xml File

Save the file and reupload it to Freshservice, using the Upload Custom Mapping button in the Settings tab of the Configuration page.

The mapping.xml File Tasks

Use this table to look up the mapping tasks in the mapping.xml file.

Each <task> element has the following Freshservice type, description, and (d42_min_version and d42_max_version) version attributes.

For a quick look at all the valid Freshservice types, see the The <task> Element Attributes section above.

description=	type=	d42_min_version=	d42_max_version=
Copy Product info from Device42 to Freshservice	product	16.19.00
Copy Product info from Device42 to Freshservice	product		16.18.02
Copy Servers from Device42 to Freshservice using DOQL v2	asset	19.04.00
Copy Servers from Device42 to Freshservice using DOQL v2	asset	16.19.00	19.03.99
Copy Servers from Device42 to Freshservice using DOQL v1	asset		16.18.02
Copy Softwares from Device42 to Freshservice using DOQL	software
Create Software Install from Software In Use	software_installation	16.19.00
Create Software Install from Software In Use	software_installation		16.18.02
Create Relationship from Service Communication	asset_relationship
Create Relationship from Business Apps	asset_relationship
Copy Business Application from Device42 to Freshservice	asset	16.19.00
Copy Business Application from Device42 to Freshservice	asset		16.18.02
Create Relationship from Devices to Business Apps	asset_relationship
Copy contract info from Device42 to Freshservice	contract
Create association between asset and contract	contract_asset
Copy Software Licensing info from Device42 to Freshservice	contract
Create relationship between Host and Virtual Machine	asset_relationship
Create relationship between cluster and device	asset_relationship
Copy AWS ALB from Device42 to Freshservice	asset	19.04.00
Copy AWS Subnet from Device42 to Freshservice	asset	19.04.00
Copy AWS Security Group from Device42 to Freshservice	asset	19.04.00
Copy AWS VPC from Device42 to Freshservice	asset	19.04.00
Copy AWS RDS from Device42 to Freshservice	asset	19.04.00
Copy AZURE Subnet from Device42 to Freshservice	asset	19.04.00
Copy Azure Disk from Device42 to Freshservice	asset	19.04.00
Copy Azure Security Group from Device42 to Freshservice	asset	19.04.00
Copy Azure Subscription from Device42 to Freshservice	asset	19.04.00
Copy Azure Application Gateway from Device42 to Freshservice	asset	19.04.00
Copy AWS EBS from Device42 to Freshservice	asset	19.04.00
Copy AWS Key Pair from Device42 to Freshservice	asset	19.04.00
Copy AWS S3 from Device42 to Freshservice	asset	19.04.00
Copy AWS Public IP from Device42 to FreshService	asset	19.04.10
Copy Azure VPC from Device42 to Freshservice	asset	19.04.00
Copy GCP Subnet from Device42 to Freshservice	asset	19.04.00
Copy GCP VPC from Device42 to Freshservice	asset	19.04.00
Copy GCP Disk from Device42 to Freshservice	asset	19.04.00
Copy GCP Firewall Rules from Device42 to Freshservice	asset	19.04.00
Copy CPU Parts from Device42 to Freshservice using DOQL	component
Copy RAM Parts from Device42 to Freshservice using DOQL	component
Copy Network Adapter from Device42 to Freshservice using DOQL	component
Copy Hard Disk Parts from Device42 to Freshservice using DOQL	component
Copy Mount Point(Logical Drive) from Device42 to Freshservice using DOQL	component
Copy Mount Point(Datastore) from Device42 to Freshservice using DOQL	component
Copy Printer Input Parts from Device42 to Freshservice using DOQL	component
Copy Printer Output Parts from Device42 to Freshservice using DOQL	component
Copy Printer Marker Parts from Device42 to Freshservice using DOQL	component
Copy Interface Component from Device42 to Freshservice using DOQL	component	19.04.00
Copy GCP LB from Device42 to Freshservice	asset	19.04.00
Copy Azure Images from Device42 to Freshservice	asset	19.04.00
Copy Azure Network Interface from Device42 to Freshservice	asset	19.04.00
Copy AWS Network Interface from Device42 to Freshservice	asset	19.04.00
Copy GCP Network Interface from Device42 to Freshservice	asset	19.04.00
Copy Azure Resource Group from Device42 to Freshservice	asset	19.04.00
Copy AWS Image from Device42 to Freshservice	asset	19.04.00
Copy Azure Public IP from Device42 to FreshService	asset	19.04.10	19.04.99
Copy Azure Public IP from Device42 to FreshService	asset	19.05.00
Copy GCP Image from Device42 to Freshservice	asset	19.04.00
Copy GCP BigQuery Table from Device42 to FreshService	asset	19.04.10
Copy Azure Key Vault from Device42 to Freshservice	asset	19.04.00
Copy VMware VCenter Resource Pool from Device42 to Freshservice	asset	19.04.10
Copy VMware VCenter Network from Device42 to Freshservice	asset	19.04.10
Copy VMware VCenter Disk from Device42 to Freshservice	asset	19.04.10
Copy VMware VCenter Datastore from Device42 to Freshservice	asset	19.04.10
Copy VMware VCenter Datacenter from Device42 to Freshservice	asset	19.04.10
Copy AWS K8 Pod from Device42 to FreshService	asset	19.04.10
Copy AWS K8s Namespace from Device42 to Freshservice	asset	19.04.10
Copy AWS K8s Deployment from Device42 to Deployment	asset	19.04.10
Copy AWS K8s Service from Device42 to Service	asset	19.04.10
Copy AWS K8s Daemon Set from Device42 to Daemon Set	asset	19.04.10
Copy AWS K8s Replica Set from Device42 to FreshService	asset	19.04.10
Copy AWS K8s Cron Job from Device42 to FreshService	asset	19.04.10
Copy GCP Public IP from Device42 to Freshservice	asset	19.04.10
Copy AWS K8s Config Map from Device42 to Config Map	asset	19.04.10
Copy AWS K8s Stateful Set from Device42 to Stateful Set	asset	19.04.10
Create Relationship from Azure Public IP to Azure Subscription	asset_relationship	19.05.00
Create Relationship from Azure Network Interface to Azure Subscription	asset_relationship	19.05.00
Create Relationship from Azure Subnet to Azure Subscription	asset_relationship	19.05.00
Create Relationship from Azure Public IP to Azure Resource Group	asset_relationship	19.05.00
Create Relationship from Azure Network Interface to Azure Resource Group	asset_relationship	19.05.00
Create Relationship from Azure Subnet to Azure Resource Group	asset_relationship	19.05.00
Create Relationship from Azure Resources to Azure Subscription	asset_relationship	19.05.00
Create Relationship from Azure Resources to Azure Resource Group	asset_relationship	19.05.00
Create Relationship from Azure Image to Azure VM	asset_relationship	19.05.00
Create Relationship from Azure Disk to Azure VM	asset_relationship	19.05.00
Create Relationship from Azure Network Interface to Azure VM	asset_relationship	19.05.00
Create Relationship from Azure Public IP to Azure VM	asset_relationship	19.05.00
Create Relationship from Azure VM to Azure Subnet	asset_relationship	19.05.00
Create Relationship from Azure VM to Azure Subscription	asset_relationship	19.05.00
Create Relationship from Azure VM to Azure Resource Group	asset_relationship	19.05.00
Create Relationship from Azure VM ( netport ) to Azure Security Group	asset_relationship	19.05.00
Create Relationship from Azure VM ( subnet ) to Azure Security Group	asset_relationship	19.05.00
Create Relationship from Azure Network Interface to Azure Subnet	asset_relationship	19.05.00
Create Relationship from Azure Public IP to Azure Network Interface	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Disk	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Network	asset_relationship	19.05.00
Create Relationship from AWS Network Interface to AWS Public IP	asset_relationship	19.05.00
Create Relationship from AWS Public IP to AWS VM	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Application LB	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Key Pair	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Subnet	asset_relationship	19.05.00
Create Relationship from AWS VM to AWS Security Group	asset_relationship	19.05.00
Create Relationship from AWS Subnet to AWS Network	asset_relationship	19.05.00
Create Relationship from AWS RDS to AWS Subnet	asset_relationship	19.05.00
Create Relationship from AWS Image to AWS VM	asset_relationship	19.05.00
Create Relationship from AWS K8s Namespace To AWS K8s Pods	asset_relationship	19.05.00
Create Relationship from AWS K8s Node To AWS K8s Pods	asset_relationship	19.05.00
Create Relationship from AWS K8s Daemon Set To AWS K8s Config Map	asset_relationship	19.05.00
Create Relationship from AWS K8s Deployment To AWS K8s Replica Set	asset_relationship	19.05.00
Create Relationship from GCP Network Interface to GCP Public IP	asset_relationship	19.05.00
Create Relationship from GCP Network Interface to GCP VM	asset_relationship	19.05.00
Create Relationship from GCP Public IP to GCP VM	asset_relationship	19.05.00
Create Relationship from GCP Disk to GCP VM	asset_relationship	19.05.00
Create Relationship from GCP Image to GCP VM	asset_relationship	19.05.00
Create Relationship from GCP VM to GCP Security Group	asset_relationship	19.05.00
Create Relationship from GCP Subnet to GCP VM	asset_relationship	19.05.00
Create Relationship from GCP Subnet to GCP Network Interface	asset_relationship	19.05.00
Sync Device42 VMWare Datacenter to Datastore relationship	asset_relationship	19.05.00
Sync Device42 VMWare Datacenter to Virtual Machine relationship	asset_relationship	19.05.00
Sync Device42 VMWare Datacenter to Host relationship	asset_relationship	19.05.00
Sync Device42 VMWare Datacenter to Network relationship	asset_relationship	19.05.00
Sync Device42 VMWare Datastore to Host relationship	asset_relationship	19.05.00
Sync Device42 VMWare Datastore to Virtual Machine relationship	asset_relationship	19.05.00
Sync Device42 VMWare Host to Virtual Machine relationship	asset_relationship	19.05.00
Sync Device42 VMWare Network to Host relationship	asset_relationship	19.05.00
Sync Device42 VMWare Network to Virtual Machine relationship	asset_relationship	19.05.00
Sync Device42 VMWare Resource Pool to Virtual Machine relationship	asset_relationship	19.05.00
Sync Device42 VMWare Resource Pool to Resource Pool relationship	asset_relationship	19.05.00
Sync Device42 VMWare Virtual Machine to Disk relationship	asset_relationship	19.05.00
Delete assets from Freshservice that do not exist in Device42	asset
Delete asset relationships from Freshservice that do not exist in Device42	asset_relationship		19.04.99
Delete asset relationships from Freshservice that do not exist in Device42	asset_relationship	19.05.00

Syncing to Custom Field Names in Freshservice

When creating a custom field in Freshservice that corresponds with a Device42 field, you need to set the target field in the XML file to match Freshservice naming conventions. Verify the correct field names via the Freshservice API endpoint before running the sync.

Field names in Freshservice are automatically generated according to the following conventions:

• Using lowercase characters
• Replacing spaces with underscores
• Appending the asset type ID to the end of the field name (this suffix provides a means of verifying the field name, and is visible in the Freshservice interface but not required in the XML file)

For example, the custom field with the Used By label in Freshservice is represented internally as used_by_12345467, but you'll use used_by in the mapping.xml file.

Use the following steps to verify that the field name is correct:

1. Navigate to the edit page for the asset type under the Freshservice Settings (if you need help locating the asset type's edit page, consult the Freshservice Assets page). Copy the asset type ID, which appears in the URL of the edit page.
2. Open your browser to access the API endpoint. Replace <Freshservice-Instance> with your Freshservice instance and <Asset-Type-ID> with the asset type ID from the URL.

<Freshservice-Instance>/api/v2/asset_types/<Asset-Type-ID>/fields

3. Search the returned JSON for the field label you are interested in to verify the field name.

   

Data Mapping FAQs

This section answers some common questions about data mapping between Device42 and Freshservice. We're actively improving the integration and this documentation. Please contact support if you have technical questions, and use the Page Feedback button at the top of this page to leave feedback about the documentation.

Syncing a Custom Device42 Field to Freshservice (Overview)

To add a custom field to Freshservice, modify the mapping.xml file and reupload it. You'll need to modify the <task> that's most closely related to the custom field you want to create.

Find an existing task with a query related to the field you want to map to Freshservice. For example, if you want to add a custom field about servers, inspect and modify the Copy Servers from Device42 to Freshservice using DOQL v2 task. Add new <field> elements (one for Device42 and one for Freshservice) to the <mapping> element of the <task>.

Depending on the custom field you want to add, you may have to modify the DOQL query in the <resource> element to fetch that data from Device42. If needed, use the InsightsAI chat under Analytics > InsightsAI to help you find the tables and fields you need to query.

If you can't find a task related to your custom field, you can create a new <task> element in the mapping.xml file.

How Do I Sync a Device42 Custom Field to Freshservice? (Detailed Steps)

1. First, create and add the new custom field in Device42. You can create a custom field for any CI type using either the UI or the API. In this example, we'll use the UI to create a custom field called Name in the Devices section of Custom Fields in the Main Appliance.

   

   

2. You should now see the custom field available for all device types. Navigate to the details page for one of your devices and set a value for the custom field. The example below shows the new Name field in the Custom Fields section for a Server device named centos-884163.device42.testing.

   

3. Next, add the new custom field to the mapping.xml file. Change the DOQL query in the Copy Servers from Device42 to Freshservice using DOQL v2 task to map the new custom field to Freshservice. (There are normally three types of task with different d42_min_version parameters; update the DOQL for each task type, in case you’re using older or different versions.)

   

   Click to expand the code block

   -- The DOQL snippet pictured above:
   SELECT
       -- ... existing fields ...
       view_device_v2.details->>'used by' AS used_by,
       cf."Name" as cf_name
   FROM 
       view_device_v2
   LEFT JOIN 
       view_hardware_v2 
       ON view_device_v2.hardware_fk = view_hardware_v2.hardware_pk
   LEFT JOIN 
       view_device_custom_fields_flat_v2 cf 
       ON view_device_v2.device_pk = cf.device_fk
   LEFT JOIN 
       network_ip
       ON view_device_v2.device_pk = network_ip.device_fk
   LEFT JOIN 
       network_hw
       ON view_device_v2.device_pk = network_hw.device_fk

   Explanation of the DOQL changes:

   • The custom field Name is added to the SELECT statement. Syntax notes: You need to escape the double quotes (”) by using the &quote; HTML entity. The greater-than (>) and less-than (<) symbols also need to be escaped. The equality operator works without special quotes. Please check existing DOQL for examples.
   • A LEFT JOIN is added because all custom fields in Device42 are stored in the {CI name}_custom_fields views. For example, the Devices CI is stored in view_device_custom_fields_flat_v2.

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.

   

   <!-- 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"/>
   <!-- Custom Fields -->

   Explanation of the XML changes:

   • The resource= argument is set to the name of the custom field in Freshservice. The custom field name in this example is cf_name, which follows the Freshservice convention of using the display name (label) in snake case for the field name, occasionally with the ID of the asset type as a suffix. (See Syncing to Custom Field Names in Freshservice for more details).
   • The target-header= argument is set to the name of the CI properties section of the heading name under which the custom field will appear in Freshservice. In this case, target-header=“Server” refers to the “Server Properties” heading — there's no need to use "Properties", as it’s automatically added to every asset type.

5. In the Freshservice Asset Types & Fields section, find the asset field to which you are mapping the Device42 custom field. In this case, our example device is of the Server type, so we find it under Hardware > Computer > Server.

   

6. Now, edit the asset type by clicking on the pencil icon all the way on the right, as highlighted below in the screenshot of the Server asset type.

   

   Set the 'target' directive to the Device42 field you are mapping to Freshservice.

   

7. Finally, run the sync in Freshservice’s Device42 integration app. You should end up with the custom field you created and set in Device42:

   

How Do I Change an Existing Mapping to Pull From a Different Device42 Field?

In the <task> that corresponds with the Device42 field you want to pull from, change the resource and target attributes of the <field> elements in the <mapping> element.

Refer to The <task> Element Elements section for a description of the <field> element attributes.

How Do I Prevent a Relationship Between Two Device42 Asset Types From Syncing to Freshservice?

You need to modify two <task> elements within the mapping.xml file.

• In your mapping.xml file, find the <task> element that creates the relationship between the asset types you want to disable. Set the enable attribute from true to false to disable the relationship. For example:

  <task enable="false" name="Create relationship between cluster and device" type="asset_relationship" description="Create relationship between cluster and device">

• Remove the corresponding relationship query from the last <task> with the attribute <description="Delete asset relationships from Freshservice that do not exist in Device42">, which is nested in the description="D42 AWS ALB to Freshservice AWS ALB"> <task> element.

  

  For example, if you want to disable the relationship between clusters and devices, remove the following query snippet from the <resource doql=" attribute:

Click to expand the code block

<task enable="true" type="asset_relationship" description="Delete asset relationships from Freshservice that do not exist in Device42">
            <api>
                <target
                        delete="true"/>
                <resource
                    doql="
                            <!-- ... other queries -->

                            <!-- remove or comment out this cluster and device relationship query -->

                            select 
                dc.name as dependent_device_name,
                format('Device-%s', dc.device_pk) as dependent_device_device42_id,
                            'Member of' as downstream_relationship,
                dp.name as dependency_device_name,
                format('Device-%s', dp.device_pk) as dependency_device_device42_id,
                            'Includes' as upstream_relationship
                            from view_devices_in_cluster_v1 dic
                            inner join view_device_v2 dp on dic.parent_device_fk = dp.device_pk
                            inner join view_device_v2 dc on dic.child_device_fk = dc.device_pk
                            where lower(dp.type) = 'cluster'
                        "
                />
            </api>

• Save the file and reupload it to Freshservice with the Upload Custom Mapping button.

How Do I Troubleshoot Data Mapping and Syncing Issues?

From Freshservice, go to Admin, search for apps, and click Manage Apps. Find the Device42 for Freshservice app, open the Settings dropdown, and select Edit settings. Under the Schedule Synchronization, click the Sync History button and click on a row to view details of the errors.

To download the full logs, scroll down and click the Download Full Log button in the lower-left corner of the text area.

Examples of Changing the mapping.xml File for Specific Use Cases

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.

Example 1: How Can I Stop the Sync From Importing Contracts From Device42 to Freshservice?

In the mapping.xml file, do a text search for tasks containing the word contract in their description attribute. You can also search for contract-related tasks in The mapping.xml File Tasks table.

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):

   

   Change enable="true" to enable="false":

   <task enable="false" name="Copy contract info from Device42 to Freshservice" type="contract" description="Copy contract info from Device42 to Freshservice">

2. Find the Create association between asset and contract task (around line 2413):

   

   Change enable="true" to enable="false":

   <task enable="false" name="Device Contract Associations" type="contract_asset" description="Create association between asset and contract">

3. If you want to disable Software Licensing from being synced, find the Copy Software Licensing info from Device42 to Freshservice task (around line 2437):

   

   Change enable="true" to enable="false":

   <task enable="false" name="Software Licensing" type="contract" description="Copy Software Licensing info from Device42 to Freshservice">

4. Save the file and reupload it to Freshservice using the Upload Custom Mapping button. The Contracts option will no longer appear in the Data Mapping Chart box

   

5. Run a partial sync to confirm that contract items are no longer being synced, or wait until the scheduled sync runs.

Example 2: How Do I Prevent Software Imports From Syncing to Freshservice?

In the mapping.xml file, do a text search for tasks that contain the word software in their description attribute. You can also search for contract-related tasks in the The mapping.xml File Tasks table.

Set the enable attribute to false on those <task> elements:

1. Find the task with the description Copy Softwares from Device42 to Freshservice using DOQL (around line 2087).

   

   Change enable="true" to enable="false":

   <task enable="false" name="Software" type="software" description="Copy Softwares from Device42 to Freshservice using DOQL">

2. There are two Create Software Install from Software In Use tasks; one with a d42_min_version attribute and one with a d42_max_version. Set the enable attribute to false on both of them:

   • The first task is around line 2102:

   

   Change enable="true" to enable="false":

   <task enable="false" name="Software In Use" type="software_installation" description="Create Software Install from Software In Use" d42_min_version="16.19.00">
   • The second task is around line 2172:

   

   Change enable="true" to enable="false":

   <task enable="false" name="Software In Use" type="software_installation" description="Create Software Install from Software In Use" d42_max_version="16.18.02">

3. Software Licensing from Device42 syncs to contract in Freshservice. Find and disable the Copy Software Licensing info from Device42 to Freshservice task (around line 2437):

   

   Change enable="true" to enable="false":

   <task enable="false" name="Software Licensing" type="contract" description="Copy Software Licensing info from Device42 to Freshservice">

4. Save the file and reupload it to Freshservice with the Upload Custom Mapping button.

5. Run a partial sync to confirm that software items are no longer being synced, or wait until the scheduled sync runs.

   • Go to Assets > Software in the integration app. The page is populated before you disable software imports:

   

   • After you've disabled software imports, the page will be empty:

   

Example 3: How To Ensure Device42 Correctly Updates the Hardware asset_state

By default, Device42 does not update asset_state values in Freshservice (in Device42, the field is called in_service).

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:

1. Find the attribute on line 493 (for DOQL v2).

   

   Change skip-update to "false":

   Click to expand the code block

   <field resource="in_service" source-type="boolean" target="asset_state" target-type="string"
   target-header="Hardware" skip-update="false">
       <value-mapping default="Retired">
           <item key="true" value="In Use"/>
       </value-mapping>
   </field> 

2. Find the attribute on line 1302 (also for DOQL v2).

   

   Change skip-update to "false":

   Click to expand the code block

   <field resource="in_service" source-type="boolean" target="asset_state" target-type="string"
       target-header="Hardware" skip-update="false">
       <value-mapping default="Retired">
           <item key="true" value="In Use"/>
       </value-mapping>
   </field>

3. Find the attribute on line 1878 (for DOQL v1).

   

   Change skip-update to "false":

   Click to expand the code block

   <field resource="in_service" source-type="boolean" target="asset_state" target-type="string"
       target-header="Hardware" skip-update="false">
       <value-mapping default="Retired">
           <item key="true" value="In Use"/>
       </value-mapping>
   </field>

Data Types Transferred From Device42 to Freshservice

D42 Data Type	Freshservice Type (General)	Type (Specific)
Device with physical type and Laptop subtype	Assets/Inventory	Laptop
Device with physical type and WorkStation subtype	Assets/Inventory	Desktop
Device with physical type and Network Printer subtype	Assets/Inventory	Printer
Device with physical type and Router subtype (this is not a built-in subtype and would need to be created by the user)	Assets/Inventory	Router
Device with physical type and Firewall subtype (this is not a built-in subtype and would need to be created by the user)	Assets/Inventory	Firewall
Device with OS of F5 or NetScaler	Assets/Inventory	Load Balancer
Device with Network Device flag set	Assets/Inventory	Switch
Device with physical type and Windows Server OS	Assets/Inventory	Windows Server
Device with physical type and Unix or Linux OS	Assets/Inventory	Unix Server
Device with physical type and AIX OS	Assets/Inventory	AIX Server
Device with physical type and SunOS or Solaris OS	Assets/Inventory	Solaris Server
Device with Virtual/Container Host flag set and ESXi OS	Assets/Inventory	VMware VCenter Host
Device with Virtual/Container Host flag set	Assets/Inventory	Host
Device with virtual type and VMWare subtype	Assets/Inventory	VMware VCenter VM
Device with virtual type and Amazon EC2 Instance subtype	Assets/Inventory	AWS VM
Device with virtual type and Azure Virtual Machine subtype	Assets/Inventory	Azure VM
Device with physical type and does not match one of the more specific asset types above	Assets/Inventory	Server
Device with virtual type and does not match one of the more specific asset types above	Assets/Inventory	Virtual Machine
Device that doesn't match one of the more specific asset types above	Assets/Inventory	Computer
Business Applications	Assets/Inventory	Business Service
Software	Assets/Software	Desktop
PO Line Item/Contract Type: Warranty	Assets/Contracts	Warranty
PO Line Item/Contract Type: BASE (IBM & Lenovo vendors)	Assets/Contracts	Warranty
PO Line Item/Contract Type: UPGRADE (IBM & Lenovo vendors)	Assets/Contracts	Warranty
PO Line Item/Contract Type: Lease	Assets/Contracts	Lease
PO Line Item/Contract Type: Service and all others	Assets/Contracts	Maintenance
Software Licensing (only for managed software and can come from software or the PO line item)	Assets/Contracts	Software License
Business Applications Device to Device relationship	Relationships between assets	Sends Data To / Receives Data From
Business Application to Device Relationships	Relationships between assets	Hosted On / Hosts
Application Group Device to Device Relationships	Relationships between assets	Depends On / Used By
VM to Host Relationships	Relationships between assets	Virtualized by / Virtualizes

Mandatory Attributes Required From Device42 During Sync

The following attributes are required from Device42 during the sync process:

Entity	Mandatory Fields
Asset	Name, Asset_type_id, Product_id
Software	Name, Application_type
Contract	Name, Contract_id, Contract_type
Software Installation	Application_id, Asset_id
Relationships	Relationship_type_id, Primary_id, Secondary_id
Vendors	Name
Products	Name, Asset_type_id
Component Entities
Processor	Manufacturer, Model
Memory	Manufacturer, Model
Network Adapter	Manufacturer, Model, Mac_address
Hard Disk	Capacity, Model
Logical Drive	Drive_name
Datastore	Name, Capacity
Interface	Name, Type
Input Units	Name, Type
Output Units	Name, Type
Marker Supply Units	Name, Type

Freshservice Contract Types

Navigate to Assets > Contracts in Freshservice to view the available contract types.

Freshservice contract types are mapped from Device42 types as follows:

The Contract Type dropdown in Freshservice displays the available contract types:

Freshservice Contract Type	Corresponding Device42 Type
Lease	Purchase Line Item type: Lease
Warranty	Purchase Line Item type: Warranty
Maintenance	Purchase Line Item types: Service, In-Service, Subscription, (none)
Software License	Software Licensing

Sync Purchase Line Items Types to Contracts

In Device42, a Purchase Line Item is an individual entry associated with a larger Purchase (located under Infrastructure > Purchases). Contract Purchase Line Item sub-types include Lease, Warranty, Subscription, Service, and In-Service. The sub-type (None) is used for unspecified types:

The Purchase Line Item Lease and Warranty contract types map to the Freshservice Lease and Warranty types. The other Purchase Line Item contract types (Service, In-Service, Subscription, and (None)) are assigned to the Freshservice Maintenance type.

For example, this Purchase Line Item with an unspecified contract type in Device42 is synced to Freshservice as a Maintenance contract:

• Purchase Line Item in Device42:

  

• Synced Maintenance Contract in Freshservice:

  

The Warranty Contract Type in Freshservice

Warranty information from Device42 is brought into Freshservice, with Warranty as the Contract Type.

• Warranty items in Device42:

  

• Warranty items synced to Freshservice:

  

Software Licensing Syncs to Contracts

Software Licensing contracts in Device42 are synced to Freshservice as Software License contracts when a Software Component has an associated Purchase Line Item or License Count that is not null (empty).

For reference, the DOQL query in the mapping.xml file for Software Licensing is:

Click to expand the code block

<task enable="false" name="Software Licensing" type="contract" description="Copy Software Licensing info from Device42 to Freshservice">
    <api>
        <target/>
        <resource
            doql="
            select 	case when p.order_no is null then s.name else s.name || '-' || p.order_no || '-' || pli.line_no end as name,
                    'Software License' as contract_type_name,
                    case when v.name is not null then v.name else sv.name end vendor_name,
                    pli.cost unit_cost, pli.start_date, pli.end_date,
                    s.name software_name,
                    case when pli.quantity is not null then pli.quantity else s.licensed_count end licensed_count,
                    case when pli.quantity is not null then pli.quantity else s.licensed_count end * pli.cost as cost,
                    pli.contract_id,
                    case when slm.is_free = true then 'Free' else 'Volume' end license_type,
                    pli.frequency,
                    'per_unit' as pricing_model,
                    case when pli.notes is not null and pli.notes &lt;&gt; '' then pli.notes else s.notes end as notes
            from view_software_v1 s
            left outer join view_softwarelicensemodel_v1 slm on s.softwarelicensemodel_fk = slm.softwarelicensemodel_pk
            left outer join view_purchaselineitems_to_softwares_v1 plis on s.software_pk = plis.software_fk
            left outer join view_purchaselineitem_v1 pli on plis.purchaselineitem_fk = pli.purchaselineitem_pk
            left outer join view_purchase_v1 p on pli.purchase_fk = p.purchase_pk
            left outer join view_vendor_v1 v on p.vendor_fk = v.vendor_pk
            left outer join view_vendor_v1 sv on s.vendor_fk = sv.vendor_pk
            WHERE
                lower(s.software_type) = 'managed' and
                (pli.purchaselineitem_pk is not null or s.licensed_count is not null) and
                (v.name is not null or sv.name is not null)
            "
        />
    </api>

Syncing Business Applications to Freshservice

Using the default mapping, Business Applications in Device42 are synced to Freshservice as the Business Service asset type. The Business Application relationships are also synced.

• In Freshservice, navigate to Assets > Inventory (1) and select Business Service as the Asset Type (2) to view the synced Business Applications. Click on an item to view its details.

  

• Click Relationships to see a Mini map of the selected Business Service.

  

• When viewing the full map, you can select the Level of Relationships to display.

  

The example Business Service in Freshservice above looks like this as a Business Application in Device42:

Deleting the Freshservice External Integration

Before deleting the Freshservice external integration in Device42 or making changes to your Cloud Services configuration, first uncheck the Enable Freshworks SSO option in the Appliance Manager, under Global Settings > SAML/SSO Settings.