Merge pull request #481 from ritza-co/19.07.10

Docs 19.07.10 release (Week 46, 2025)

Author: sixhobbits

docs/auto-discovery/enrichai-data/index.mdx

@@ -31,9 +31,7 @@ The EnrichAI Data service populates the following vendor attributes, operating s
 | OS Version Number           | The general version number of the release                          |
 | Key Support Dates  | See the details for the available date fields in the table below  |
 
-:::note
 The **OS Architecture: 32 vs 64 bit** field is no longer part of EnrichAI Data. The 32- and 64-bit architectures have been coalesced into a single entry, since the architecture does not affect OS dates, licensing, patches, or risk profiles.
-:::
 
 ### Key Support Dates
 
@@ -183,10 +181,9 @@ The image below shows a vendor view page with enriched data. Enriched data is al
 ## Data Handling and Security Practices
 
 1. No personal or personally identifiable data is maintained by the EnrichAI Data service.
-2. Data sent to EnrichAI Data is not associated with or tracked to the calling system or installation.
-3. Unmatched values (those without a corresponding match in EnrichAI Data) are stored for future mining and resolution. This storage has no association with the calling system or installation.
-4. Only Device42 personnel work with these non-identifiable data elements.
-5. Data collected for future enrichment mining is stored in the United States.
+2. Unmatched values (those without a corresponding match in EnrichAI Data) are stored for future mining and resolution. This storage has no association with the calling system or installation.
+3. Only Device42 personnel work with these non-identifiable data elements.
+4. Data collected for future enrichment mining is stored in the United States.
 
 :::note
 Device42 reserves the right to change and update the internal matching algorithm and the golden records provided with this service.

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

@@ -12,11 +12,19 @@ This page covers advanced data mapping customization and XML file editing.
 - For usage and operations, see [Using the Freshservice Integration](use-freshservice-integration.mdx).
 :::
 
-If you make an adjustment and use a custom XML file, Device42 will not update the custom XML during updates. 
+## Manage Customization with Newer Releases
 
-If you want to incorporate updates, you'll need to do so manually: Download the current XML file, compare it to your customized XML file, and add in the new items as needed.
+The Device42-Freshservice integration ships with a default mapping file. Newer versions of the mapping file may include sending additional elements to Freshservice (such as assets, devices, CIs, and metadata). We share these new additions in the [Freshservice mapping release notes](/release-notes/freshservice-mapping/mapping-4.0).
 
-## Custom Data Mapping
+If you make an adjustment and use a custom XML file, Device42 will not update the custom XML during updates.
+
+If you want to incorporate updates, you need to do so manually: Download the current XML file, compare it to your customized XML file, and add in the new items as needed.
+
+We recommend keeping track of your customizations so they can be added to the latest default mapping file. 
+
+## Get Started with Custom Data Mapping
+
+To get started, download the default mapping XML file and view the current mapping.
 
 ### Download the `mapping.xml` File
 
@@ -28,7 +36,7 @@ If you want to incorporate updates, you'll need to do so manually: Download the
 
 ### 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.
+- Explore the mapped fields and their data types by selecting a type (for example, **Devices**) from the **Data Mapping Chart**. Scroll to the bottom of the page to view the mapping table.
 
     ![View current mapping](/assets/images/freshservice-integration/view-mappings-2.png)
 
@@ -326,6 +334,42 @@ Use the following steps to verify that the field name is correct:
     }}
     />
 
+
+## Control Updates 
+
+Control whether changes made to Device42 asset types and contracts will update the corresponding items in Freshservice during sync.
+
+### Control Asset Type Updates
+
+When you customize asset type mappings in the `mapping.xml` file, you can control whether your changes update existing assets in Freshservice. See [Asset-Type Update Behavior](use-freshservice-integration.mdx#asset-type-update-behavior) for more details about the **Update asset type for existing assets**  setting.
+
+### Control Contract Updates
+
+You can control whether Device42 contract updates sync to Freshservice. This applies to contract tasks with `name="Contracts"` and `name="Software Licensing"`.
+
+Add the `skip-update` attribute to the `<task>` element:
+
+- If `skip-update="false"`, contract updates in Device42 will be updated in Freshservice (if the contract exists).
+- If `skip-update="true"`, the contracts are created in Freshservice but will not be updated after initial creation.
+
+If the attribute is absent from the task element, the contracts in Freshservice will not be updated.
+
+- For example, add `skip-update="false"` to enable contract updates in mapping.xml v4.0:
+
+    ![Contracts task element with skip-update](/assets/images/freshservice-integration/vscode-contracts-skip-update.png)
+
+    ```xml
+    <task enable="true" name="Contracts" type="contract" description="Copy contract info from Device42 to Freshservice" skip-update="false">
+    ```
+
+- For example, add `skip-update="false"` to enable contract updates for software licensing in mapping.xml v4.0:
+
+    ![Contracts task element with skip-update](/assets/images/freshservice-integration/vscode-software-licensing-skip-update.png)
+
+    ```xml
+    <task enable="true" name="Software Licensing" type="contract" description="Copy Software Licensing info from Device42 to Freshservice" skip-update="false">
+    ```
+
 ## 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](mailto:[email protected]) if you have technical questions, and use the **Page Feedback** button at the top of this page to leave feedback about the documentation. 
@@ -419,6 +463,92 @@ If you can't find a task related to your custom field, you can create a new `<ta
 
     ![Custom field in Freshservice](/assets/images/freshservice-integration/device-custom-field-fs-final.png)
 
+### How Do I Sync a Device42 Field to a Custom Contract Field in Freshservice?
+
+You can map existing Device42 contract data to custom fields in Freshservice contracts. This allows you to sync Device42 contract information (either standard fields or existing custom fields) to new custom fields you create in Freshservice.
+
+**Prerequisites:**
+- You need to upload a custom mapping file in Freshservice to make these changes. 
+- For updating contracts to work, you need to add `skip-update="false"` to contract tasks. See [Control Contract Updates](#control-contract-updates) for details.
+
+**In Freshservice:**
+
+1. Create custom fields. Go to **Settings > Contract Types** in Freshservice and add custom fields to receive the Device42 contract data.
+
+    - Log in to your Freshservice instance.
+    - Click the **ellipsis menu** (bottom of left panel) and select **Admin**.
+    - In the search bar, type `contract type`.
+    - Click the **edit icon** to the right of the contract type name.
+
+        ![Edit icon for Lease contract type](/assets/images/freshservice-integration/fs-contract-edit-button.png)
+    
+    - Drag one of the data type buttons below the last input on the form to add the custom field. Freshservice supports the following custom field types: Single Line Text, Multi Line Text, Checkbox, Number, Dropdown, Phone Number, URL, and Date.
+
+        ![Drag custom field](/assets/images/freshservice-integration/fs-custom-field-drag.png)
+
+    - Label the custom field and set whether a value is required and whether the field should appear on renewal forms. If you don't send a value to the required field, you will get an error.
+
+        ![Configure custom field](/assets/images/freshservice-integration/fs-custom-field-properties.png)
+
+   You can create custom fields that exist in one contract type but not others, allowing you to customize each contract type independently.
+
+**In `mapping.xml`:**   
+
+2. Update the DOQL queries in the contract type tasks to select data that you will enter in the contract custom fields. For example, add the **Cancel Policy** field, `pli.cancel_policy`, from the purchase line item:
+
+    <details>
+        <summary>Click to expand the code block</summary>
+        ```sql
+        <task enable="true" name="Contracts" type="contract" description="Copy contract info from Device42 to Freshservice" skip-update="false">
+            <api>
+            <target/>
+            <resource
+                    doql="
+                    select plid.device_name, v.name vendor_name,
+                        v.name || '-' || p.order_no || '-' || pli.line_no as name,
+                        case
+                            WHEN lower(pli.contract_type_name) = 'warranty' THEN 'Warranty'
+                            WHEN lower(pli.contract_type_name) in ('base', 'upgrade') and lower(v.name) in ('ibm', 'lenovo') THEN 'Warranty'
+                            WHEN lower(pli.contract_type_name) = 'lease' THEN 'Lease'
+                            ELSE 'Maintenance'
+                        end as contract_type_name,
+                        pli.contract_id, pli.cost, pli.start_date, pli.end_date, pli.cancel_policy
+                    from view_purchaselineitems_to_devices_v1 plid
+                    inner join view_purchaselineitem_v1 pli on plid.purchaselineitem_fk = pli.purchaselineitem_pk
+                    inner join view_purchase_v1 p on pli.purchase_fk = p.purchase_pk
+                    inner join view_vendor_v1 v on p.vendor_fk = v.vendor_pk
+                    where lower(pli.line_type) = 'contract' and pli.start_date is not null and pli.end_date is not null
+        ```
+    </details>
+
+   :::tip
+   Use the **ERD Diagram** located under the **question mark icon** in Device42 to look up Device42 tables and fields for the DOQL query.
+   :::
+
+3. Add a field mapping to map the field from the DOQL query to the Freshservice contract custom field. For example:
+
+    ```xml
+    <field resource="cancel_policy" source-type="string" target="cf_cancel_policy" target-type="string"/>
+    ```
+
+   The Freshservice custom field `target` is `cf_cancel_policy`, following this pattern:
+
+   ```
+   cf_[lowercase with underscores replacing spaces]
+   ```
+
+    ![Custom Field mapping in mapping.xml](/assets/images/freshservice-integration/vs-code-custom-field-mapping.png)
+
+**In Freshservice:**
+
+4. [Reupload `mapping.xml` to Freshservice](#reupload-the-mappingxml-file) using the **Upload Custom Mapping** button.
+
+5. Verify that your custom field (`cf_cancel_policy`) appears in the **Data Mapping Chart** table.
+
+    ![Data Mapping Chart with custom field](/assets/images/freshservice-integration/fs-cancel-policy-mapping.png)
+
+6. Run the [sync](index.mdx#run-the-data-synchronization).
+
 ### 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.

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

@@ -134,8 +134,8 @@ After installing the integration app in Freshservice, set up an External Integra
 
     ![SAML/SSO settings](/assets/images/freshservice-integration/saml-sso-settings.png)
 
-- **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).
+    - **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.
 
@@ -160,7 +160,7 @@ Test the SSO as follows:
 
 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.
 
-    ![Freshworks sign-in page](/assets/images/freshservice-integration/freshworks-sign-in-2.png)  
+![Freshworks sign-in page](/assets/images/freshservice-integration/freshworks-sign-in-2.png)  
 
 ## Troubleshooting
 
@@ -172,16 +172,18 @@ If you see this error:
 [ERROR] 2025-06-30T19:06:37Z main.go:327: Connection error, error: websocket: bad handshake, response: Error: secure tunnel already established with same instance ID. Is there another D42 instance running with same settings?
 ```
 
-This means multiple Device42 instances are using the same GUID. To fix this:
+This means multiple Device42 instances are using the same GUID. Each Device42 instance must have a unique GUID. The primary should keep its GUID, and any duplicate GUIDs on other instances should be regenerated to be unique.
+
+To action this:
 
 1. Check the GUID on your primary Device42 instance at **Tools > Integrations > Cloud Services**.
 2. Check the GUID of your other Device42 instances (hot standby, development, and so on).
-3. If the instances have the same GUID, regenerate GUID on all instances except the primary one.
-4. Restart Device42 services on instances where you changed the GUID.
+3. If the instances have the same GUID, regenerate the GUID on all instances except the primary one.
+4. Restart Device42 services on the instances where you changed the GUID.
 
 ## Next Steps
 
 Once you have completed the setup, you can:
 
 - [Use the Freshservice Integration](use-freshservice-integration.mdx) for data synchronization, and understanding data flows.
-- [Customize the Freshservice Integration](customize-freshservice.mdx) for advanced data mapping and XML configuration.
+- [Customize the Freshservice Integration](customize-freshservice.mdx) for advanced data mapping and XML configuration.