diff --git a/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx b/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx index 83e5e5522..cb1684367 100644 --- a/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx +++ b/docs/integration/external-integrations/freshservice-integration/customize-freshservice.mdx @@ -12,6 +12,7 @@ import fsInventoryMenuImage from '/assets/images/freshservice-integration/fs-inv This page covers advanced data mapping customization and XML file editing. - For initial setup and installation, see [Setting Up the Device42 Freshservice Integration](index.mdx). - For usage and operations, see [Using the Freshservice Integration](use-freshservice-integration.mdx). +- For help with sync and connection issues, see [Troubleshoot the Freshservice Integration](mapping-integration-troubleshooting.mdx). ::: ## Manage Customization with Newer Releases diff --git a/docs/integration/external-integrations/freshservice-integration/index.mdx b/docs/integration/external-integrations/freshservice-integration/index.mdx index ae5dc97bb..dfd18940d 100644 --- a/docs/integration/external-integrations/freshservice-integration/index.mdx +++ b/docs/integration/external-integrations/freshservice-integration/index.mdx @@ -10,6 +10,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl' This page covers the initial setup and installation of the Freshservice integration. - For daily usage and operations, see [Using the Freshservice Integration](use-freshservice-integration.mdx). - For advanced data mapping customization, see [Advanced Freshservice Mapping and Customization](customize-freshservice.mdx). +- For help with sync and connection issues, see [Troubleshoot the Freshservice Integration](mapping-integration-troubleshooting.mdx). ::: ## About the Device42 Freshservice Integration @@ -162,22 +163,7 @@ Now, when you're logged out of both Device42 and Freshservice, clicking the **Fr ## Troubleshooting -### Secure Tunnel Connection Error - -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. 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 the GUID on all instances except the primary one. -4. Restart Device42 services on the instances where you changed the GUID. +If you run into problems during or after setup, such as sync job errors or Cloud Connector connection issues (including the "secure tunnel already established with same instance ID" error), see [Troubleshoot the Freshservice Integration](mapping-integration-troubleshooting.mdx) for diagnostic steps and solutions. ## Next Steps @@ -185,3 +171,4 @@ 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. +- [Troubleshoot the Freshservice Integration](mapping-integration-troubleshooting.mdx) for help diagnosing sync and connection errors. diff --git a/docs/integration/external-integrations/freshservice-integration/mapping-integration-troubleshooting.mdx b/docs/integration/external-integrations/freshservice-integration/mapping-integration-troubleshooting.mdx new file mode 100644 index 000000000..5d304db7e --- /dev/null +++ b/docs/integration/external-integrations/freshservice-integration/mapping-integration-troubleshooting.mdx @@ -0,0 +1,519 @@ +--- +title: "Troubleshoot the Freshservice Integration" +sidebar_position: 4 +--- + +import ThemedImage from '@theme/ThemedImage' +import useBaseUrl from '@docusaurus/useBaseUrl' + +The Device42 Freshservice integration synchronizes Device42 data with Freshservice through the Device42 Cloud Connector. This page helps Device42 and Freshservice administrators identify sync and connection problems, test likely causes, and apply the appropriate fix. + +## Start With the Symptom + +Use the error text or behavior to go directly to the most relevant section. + +| Symptom or log message | Start here | +| --- | --- | +| The sync does not start, or Freshservice cannot reach Device42 | [Cloud Connector Connection Errors](#cloud-connector-connection-errors) | +| `there is no dependent asset`, `there is no dependency asset`, or `there is no asset` | [Missing Asset Errors](#missing-asset-errors) | +| `connection aborted` or `gateway timeout` during a sync | [Connection Aborted or Gateway Timeout Errors](#connection-aborted-or-gateway-timeout-errors) | +| Freshservice API status `400`, `404`, `409`, `429`, or `500` | [Freshservice API Errors](#freshservice-api-errors-400-404-409-429-and-500) | +| `%d format: a real number is required, not NoneType` | [None Asset Type Errors](#none-asset-type-errors) | +| Status `500` with `syntax error at or near "where"` | [DOQL PostgreSQL Syntax Errors](#doql-postgresql-syntax-errors-status-500) | +| The asset syncs, but its components do not | [Components Not Syncing for Custom Asset Types](#components-not-syncing-for-custom-asset-types) | +| `secure tunnel already established with same instance ID` | [Duplicate Instance Errors](#duplicate-instance-errors) | +| Another sync error | [Other Sync Errors](#other-sync-errors) | + +:::tip Related Freshservice integration pages +Use the following pages for tasks outside troubleshooting: + +- For initial setup and installation, see [Set Up the Freshservice Integration](integration/external-integrations/freshservice-integration/index.mdx). +- For daily usage and operations, see [Use the Freshservice Integration](integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx). +- For advanced data mapping customization, see [Customize the Freshservice Integration](integration/external-integrations/freshservice-integration/customize-freshservice.mdx). +::: + +## Collect the Error Details + +Most sync problems can be traced from the sync history logs: + +1. From Freshservice, go to **Admin**, search for `apps`, and click **Manage Apps**. +2. Find the **Device42 for Freshservice** app, open the **Settings** dropdown, and select **Edit settings**. +3. Click the **Sync History** button and select a row to view the errors associated with that sync run. +4. Use the **Download Full Log** button to get the complete log. + +Record the task name, exact error text, and sync time. You will use the task name to locate the corresponding query in the mapping file. + +See [View Sync History Logs](integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx#view-sync-history-logs) for more details. + +### Understand Item-Level Errors + +A single item-level error does not stop an entire sync. The integration logs the failed item and continues to the next one. The only events that stop the entire sync are user cancellation, the stuck-sync detector (a two-hour threshold), and a [Cloud Connector deployment](integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx#cancelled-syncs). + +## Work With DOQL Queries From the Mapping File + +Many sync errors require you to inspect or run the DOQL query from the affected mapping task. Use this process to find and prepare a query before running it. + +### Find the Right Mapping File + +Use the mapping file that the integration used for the failed sync: + +1. In the Freshservice integration app, go to **Configuration > Data Mapping**. +2. Look for the message **A custom mapping is being used** at the top of the tab. +3. Download the applicable file: + + | What the tab shows | File to download | + | --- | --- | + | **A custom mapping is being used** | Click **Download Custom Mapping**. | + | No custom-mapping message | Click **Download Default Mapping**. | + +### Extract and Prepare the Query + +Each task in the mapping XML file has a `` element with a `doql` attribute containing the SQL query: + +
+ Click to expand the mapping task example + +```xml + + + + + + ... + +``` + +
+ +Queries can be very long, sometimes hundreds of lines, with CTEs, JOINs, and subqueries. To prepare a query for testing: + +1. Copy the query from the `doql` attribute of the `` element for the affected task. +2. Replace XML-escaped characters with their actual characters: + + | Escaped | Actual | + | --- | --- | + | `<` | `<` | + | `>` | `>` | + | `&` | `&` | + | `'` | `'` | + | `"` | `"` | + +3. Do not include the value of the `` element's `doql-suffix` attribute. The integration appends this value during incremental syncs, but you should test the base query by itself. + +![The doql-suffix attribute on a mapping element in mapping.xml](/assets/images/mapping-integration-troubleshooting/mapping-xml-doql-suffix.png) + +### Test the Query + +Run the prepared query in **Standard Reports** in Device42 and check the output. You can export the results to an XLSX file to inspect them or share them with Device42 Support. If you have access to the appliance terminal, you can also run the query directly in `psql`. To check query performance in `psql`, prefix the query with `EXPLAIN ANALYZE`. + + + +## Sync Job Errors + +Use the task name and exact message from the sync log to select an error below. + +### Missing Asset Errors + +You may see one of the following errors in the sync log: + +- `there is no dependent asset (...) in FS` +- `there is no dependency asset (...) in FS` +- `there is no asset (...) in FS` + +The value in parentheses is the identifier of the missing asset. Record it together with the task name from the same log entry. + +**What it means:** The referenced asset does not exist in Freshservice, so the integration cannot create its relationships, components, software installations, or contract associations. These errors come from relationship, component, software installation, or contract asset tasks, not from the asset creation task itself. + +The most common cause is that another asset with the same matching-criteria value overwrote the asset. For example, another device with the same serial number or UUID may have replaced the original device. + +**Identify the missing asset.** Use the task type and wording of the error: + +- **Component and software installation tasks:** The missing asset is the device that the component or software should be attached to. +- **Contract asset tasks:** The missing asset is the asset being associated with the contract. +- **Relationship tasks:** The missing asset could be either side of the relationship. The error message tells you which one: + - `there is no dependency asset(eni-05b21e16f18910416) in FS` means the **dependency** (right side) is missing. + - `there is no dependent asset(eni-003bbe9db34bf7c27) in FS` means the **dependent** (left side) is missing. + + The task name tells you the asset types on each side. For example, in the task `AWS VM to AWS Network`, the left side (dependent) is the AWS VM and the right side (dependency) is the AWS Network. + +**Check the cause.** + +1. Identify the missing asset and its type from the error message. +2. Find the asset creation task for that asset type in the mapping file. +3. [Extract and prepare the DOQL query](#work-with-doql-queries-from-the-mapping-file) from the asset creation task. +4. Run the query in **Standard Reports** and check whether the missing asset appears in the output. If it doesn't, the asset doesn't exist in Device42 or is filtered out by the query. +5. If the asset does appear, check the matching criteria fields for other assets sharing the same values. + +By default, the integration uses the following [matching criteria](integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx#asset-matching-logic) for devices: + +- Device42 ID +- Item ID +- Serial Number +- UUID +- IMEI Number +- MAC Address (only for SNMP devices) +- Hostname (positive match only if the matching asset does not have an Item ID) + +**Fix the issue.** Correct the duplicate values in Device42. This is the preferred approach. + +:::caution +Changing the matching criteria in a custom mapping file is possible but should be the last resort, as changed criteria can create duplicates if you later use the Freshservice Discovery Probe or another data source. Please [contact support](mailto:support@device42.com) to discuss the pros and cons before changing matching criteria. +::: + +### Connection Aborted or Gateway Timeout Errors + +**What it means:** The Cloud Connector could not retrieve data from Device42. A slow or inefficient task query is the most common cause. + +**Check the cause.** + +1. Check which task produced the error in the sync log. +2. [Extract and prepare the DOQL query](#work-with-doql-queries-from-the-mapping-file) from that task. +3. Run the query in **Standard Reports** to confirm that it is slow or times out. + +**Fix the issue.** Modify the query to improve its performance, and verify the revised query in **Standard Reports** before uploading the change. + +### Freshservice API Errors (400, 404, 409, 429, and 500) + +These errors occur when the integration successfully retrieves data from Device42 but gets an error response from the Freshservice API when trying to create or update items. Each HTTP status code has a different meaning and retry behavior. + +| Status | What it means | Integration behavior | +| --- | --- | --- | +| `400` | Freshservice rejected the data during validation. | The integration logs and skips the item without retrying, except for the duplicate-value case below. | +| `404` | The item to update no longer exists in Freshservice. | The integration logs and skips the item without retrying. | +| `409` | A validation conflict or infrastructure error occurred. | The response format determines the retry behavior. Inspect the response as described below. | +| `429` | Freshservice is rate limiting requests. | The integration retries indefinitely and respects the `Retry-After` header, defaulting to 10 seconds if the header is missing. | +| `500` | A problem occurred on the Freshservice side. | The integration retries up to six times after 2, 4, 8, 16, 32, and 64 seconds. If every retry fails, it logs and skips the item. | + +**HTTP `400`: Validation error.** + +**What it means:** Freshservice rejected the data because it failed server-side validation. Common causes include: + +- Invalid field values, for example, sending a value that doesn't match the allowed options for a dropdown field. +- Field type mismatches, for example, sending a string to an integer field. +- Values violating field constraints, for example, zero sent to a positive-number field. + +**Investigate the issue.** Check the sync log for the field or value that failed validation. + +There is one special case: if the `400` error says the serial number or item ID `must be unique` or `asset already exists`, the integration retries once. It removes fields marked with `error-skip="duplicate value"` in the mapping file before retrying. If the retry still fails, the integration silently drops the item. + +**HTTP `404`: Item not found.** + +**What it means:** The item that the integration tried to update does not exist in Freshservice. Common causes include: + +- The asset was deleted in Freshservice between when the sync loaded its cache and when it tried to update the item. +- For asynchronous jobs (relationships and software installations), the job took over one hour and Freshservice discarded it. + +**Integration behavior:** The integration logs and skips the item without retrying it. + +**HTTP `409`: Conflict.** + +**What it means:** A `409` error indicates one of two scenarios: + +- **A JSON response containing `Validation failed`:** A Freshservice validation error similar to a `400` error. The item is skipped without a retry. +- **An HTML response (not JSON):** Typically a Cloudflare infrastructure error. The integration retries it the same way as a `500` error. + +### None Asset Type Errors + +You may see the following error when the integration updates an asset: + +``` +%d format: a real number is required, not NoneType +``` + +**What it means:** A default Freshservice asset type has been renamed or deleted, for example, **Server** was renamed to **Physical Server**. The integration cannot find the expected asset type and tries to create the asset with a `None` type. + +**Check the cause.** + +1. Identify which task produced the error from the sync log. +2. [Extract the DOQL query](#work-with-doql-queries-from-the-mapping-file), run it in **Standard Reports**, and check the `asset_type` column in the output. +3. Compare the values against the asset types in Freshservice, which you can list via the API: + + ``` + GET {{freshservice_url}}/api/v2/asset_types?page=1&per_page=1000 + ``` + +4. Identify values in the query output that do not match an asset type in Freshservice. + +**Fix the issue.** Restore the original asset type name in Freshservice, create the missing asset type, or adjust the mapping file to use the new name. The integration does not create asset types automatically. + +### DOQL PostgreSQL Syntax Errors (Status 500) + +**Symptom:** A task fails to retrieve data from Device42 with an HTTP `500` response whose body contains this PostgreSQL error: + +``` +syntax error at or near "where" +``` + +The error typically appears twice in the sync log, once for each version variant of the affected task. The **Devices** task is most commonly affected because the Device42 19.04.00-and-later variant and the older-version variant share the same `doql-suffix`. + +**What it means:** The base DOQL query already contains a `WHERE` clause, and the `doql-suffix` attribute on the `` element also starts with `WHERE`. During an incremental sync, the integration appends the suffix directly to the query and produces two `WHERE` clauses, which PostgreSQL rejects. + +For example, the base query in a custom mapping ends with a filter on `last_discovered`: + +```sql +where view_device_v2.last_discovered >= NOW() - INTERVAL '3 days' +``` + +And the `doql-suffix` attribute starts with `where`: + +```sql +where view_device_v2.last_edited>'2024-01-01 12:00:00' +``` + +Combined, these produce two `WHERE` clauses and invalid SQL. + +**Fix the issue.** In the custom mapping XML file, change `where` to `AND` in the `doql-suffix` attribute of each affected `` element: + +
+ Click to expand the corrected mapping example + +```xml + + + + + +``` + +
+ +Apply the change to every affected task variant. Then [reupload the custom mapping file](integration/external-integrations/freshservice-integration/customize-freshservice.mdx#reupload-the-mappingxml-file) from **Configuration > Data Mapping > Upload Custom Mapping**. + +### Components Not Syncing for Custom Asset Types + +**Symptom:** The asset exists in Freshservice after a sync, but it has no CPU, RAM, hard disk, network adapter, or other component records. + +**What it means:** By default, the integration syncs components only to assets whose Freshservice type is **Computer** or a sub-type of **Computer**. If you create a top-level asset type such as **POS Terminal** outside the **Computer** hierarchy, the integration silently skips components for assets of that type. + +**Check the cause.** In Freshservice, go to **Admin** and search for **Asset Types & Fields**. Check whether the custom asset type is nested under **Computer** or appears as a separate top-level type. + +**Fix the issue.** Use one of the following options: + +1. **Preferred:** Recreate the custom asset type in Freshservice as a sub-type of **Computer**. This option requires no mapping changes. +2. Add the custom type name alongside `Computer` in the `asset-type` attribute on the `` element of every component task in the custom mapping file. Update the CPU, RAM, Hard Disk, Network Adapter, Logical Drive, and Datastore tasks: + + ```xml + + ``` + + This setting retains component sync for **Computer** assets and adds it for the custom type. [Reupload the mapping file](integration/external-integrations/freshservice-integration/customize-freshservice.mdx#reupload-the-mappingxml-file). + +### Other Sync Errors + +For a sync error not covered above, use the following diagnostic sequence: + +1. Identify which task produced the error from the sync log. +2. Find that task in the mapping file and inspect its query and field mappings. +3. Note the field or value named in the error. +4. [Extract and test the query](#work-with-doql-queries-from-the-mapping-file) to inspect the source data. Replace XML-escaped characters and omit the `doql-suffix` before testing. + +If the issue continues, [contact support](mailto:support@device42.com). + +## Cloud Connector Connection Errors + +If syncs fail to start at all, or the integration can't reach your Device42 instance, the problem is usually the connection between the Main Appliance and the Cloud Connector. + +### How the Cloud Connector Connection Works + +The Cloud Connector uses a persistent outbound WebSocket Secure (WSS) connection on port 443: + +- **Endpoint:** `wss://connect-.device42.io:443/ws` (for example, `wss://connect-au.device42.io/ws`) +- **Bidirectional tunnel:** Once established, requests from the cloud (such as API calls to Device42) also flow through this same single connection. The cloud server pushes HTTP requests down the tunnel, and the client executes them against the local Device42 appliance and sends responses back up. + +Your firewall needs to allow the following outbound traffic only: + +- **Destination:** `*.device42.io` (or the specific regional endpoint) +- **Port:** `443` (WSS traffic looks like regular HTTPS to firewalls) + +### Identify Connection Issues + +Check the connection log file on the Main Appliance: + +``` +/var/log/rc/http-ws-proxy-client.log +``` + +If there is a connection issue, you will find errors like the following: + +
+ Click to expand the example log output + +``` +Connection read error (was connection just closed?) for trackingID: Not Available, error: websocket: close 1006 (abnormal closure): unexpected EOF +Websocket Connection for trackingID: Not Available has been closed +Status checker ping error for trackingID: Not Available, error: write tcp 10.201.18.250:46804->104.20.27.167:443: write: connection reset by peer +[INFO] main.go:308: Connection attempt url: wss://connect.device42.io/ws +[ERROR] main.go:327: Connection error, error: dial tcp: lookup connect.device42.io: i/o timeout, response: +[INFO] main.go:491: Attempting to connect +``` + +
+ +Two possible causes on your network are: + +- A firewall between the Main Appliance and the Cloud Connector that blocks outbound traffic. +- A DNS server that cannot resolve the Cloud Connector FQDN, `connect.device42.io`, to an IP address. + +For the error `secure tunnel already established with same instance ID`, go to [Duplicate Instance Errors](#duplicate-instance-errors). + +### Resolve Connection Issues + +Work through the following steps in order. + +**1. Test network connectivity.** + +Run the following commands from the Main Appliance: + +```bash +curl -I https://connect.device42.io +curl -kv https://connect.device42.io +nc -v connect.device42.io 443 +``` + +**2. Regenerate the Instance GUID.** + +After testing network connectivity: + +1. Go to **Tools > Integrations > Cloud Services** in Device42. +2. Click **Regenerate Instance GUID**. + + + +3. Restart the `connect_d42_client` service from the appliance terminal. + +**3. Recreate the integration.** + +If regenerating the Instance GUID does not restore the connection: + +1. Recreate the Freshservice external integration in Device42. See [Create a Freshservice External Integration in Device42](integration/external-integrations/freshservice-integration/index.mdx#2-create-a-freshservice-external-integration-in-device42) for the steps. +2. Update the verification token in the Device42 app in Freshservice. + + + +3. Restart the `connect_d42_client` service from the appliance terminal. + +If the issue persists after all steps, [contact support](mailto:support@device42.com). + +### Duplicate Instance Errors + +You may see the following error in `/var/log/rc/http-ws-proxy-client.log`: + +``` +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? +``` + +Another Device42 instance is already connected to the Cloud Connector using the same Instance GUID. This typically happens when a Device42 appliance was cloned or restored from a backup without regenerating the GUID. Each Device42 instance must have a unique GUID. + +**Fix the issue.** Identify which Device42 instance should own the connection, then regenerate the Instance GUID on that instance under **Tools > Integrations > Cloud Services > Regenerate Instance GUID**. If the other instance also needs to connect, assign it a unique Instance GUID. + +## Avoid Common Customization Pitfalls + +Mapping file customizations can cause sync errors. The sections below cover the general customization process and details that are easy to miss. For more information, see [Customize the Freshservice Integration](integration/external-integrations/freshservice-integration/customize-freshservice.mdx). + +### Follow the General Customization Process + +Use the following process to sync additional data from Device42 to Freshservice: + +1. Update the task's DOQL query to include the required column. +2. Create a field in Freshservice if you need one for the data. +3. Check the field's internal name in Freshservice. The internal name may differ from the display label. Retrieve it with `GET {{freshservice_url}}/api/v2/asset_types/{{asset_type_id}}/fields`. +4. Create or update the task mapping. Ensure that the mapped field types match, as a mismatch causes sync errors. + +See [Sync to Custom Field Names in Freshservice](integration/external-integrations/freshservice-integration/customize-freshservice.mdx#syncing-to-custom-field-names-in-freshservice) for the field naming conventions. + +### Find the Right Task Version + +Some tasks appear more than once with the same name. These are the same task with different DOQL queries tuned for specific Device42 versions. The integration picks the correct one at runtime, but when customizing, you need to find and edit the right variant manually. + +Each task has optional `d42_min_version` and `d42_max_version` attributes that control which Device42 versions it applies to: + +
+ Click to expand the version-gating example + +```xml + + + + + + + + +``` + +
+ +Edit only the task whose version range includes your current Device42 version. + +### Map Special Fields Without a Target Header + +A few fields are handled specially and must **not** include the `target-header` attribute. These fields are placed at the root level of the asset payload. + +The `user_email` field populates the **Used By** dropdown. The value must be an email address matching an existing requester or user in Freshservice: + +```xml + +``` + +The `product` field holds the product name and requires two field elements: + +```xml + + +``` + +### Use Foreign Key Lookups + +Some Freshservice fields expect a numeric ID, not a human-readable name. The `target-foreign` attribute tells the integration to look up the correct ID automatically. The following foreign key types are available: + +| Type | Match by | Auto-creates if not found? | Used in default mapping for | +| --- | --- | --- | --- | +| `vendors` | `name` | Yes | Devices, Network Devices, Business Applications, Contracts | +| `agents` | `email` | Yes | Business Applications | +| `groups` | `name` | Yes | Supported but not used in default mapping | +| `contract_types` | `name` | No | Contracts | +| `applications` | `name` | No | Software Licensing | + +### Know the Mapping Limitations + +Keep the following limitations in mind when customizing the mapping: + +- **`location_id` requires a hardcoded value mapping.** The Freshservice channel API has no working endpoint for locations, so `target-foreign` can't be used. Use `value-mapping` with hardcoded IDs instead. Get the IDs via `GET {{freshservice_url}}/api/v2/locations`. +- **`department_id` likely has the same limitation** as `location_id`. +- **Asset types must pre-exist in Freshservice.** The integration never creates asset types automatically. +- **Changing matching criteria is a last resort.** If you later use the Freshservice Discovery Probe or another data source, changed criteria could create duplicate assets. [Contact support](mailto:support@device42.com) to discuss the pros and cons first. + +## Useful Freshservice API Endpoints + +The Freshservice API is useful for verifying asset types, field names, and IDs. To get your API token in Freshservice, open **Profile settings** and find **Your API Key**. Authenticate with Basic Authentication, using the token as the username and `X` as the password. + +| Purpose | Endpoint | +| --- | --- | +| Get all assets | `GET {{freshservice_url}}/api/v2/assets` | +| Get assets of a certain type | `GET {{freshservice_url}}/api/v2/assets?filter="asset_type_id:{{asset_type_id}}"` | +| Get assets by name | `GET {{freshservice_url}}/api/v2/assets?include=type_fields&query="name:'test'"` | +| Get asset types | `GET {{freshservice_url}}/api/v2/asset_types?page=1&per_page=1000` | +| Get asset type fields | `GET {{freshservice_url}}/api/v2/asset_types/{{asset_type_id}}/fields` | +| Get locations | `GET {{freshservice_url}}/api/v2/locations` | +| Get contract type fields | `GET {{freshservice_url}}/api/v2/contract_types/4/fields` | +| Get asset relationships | `GET {{freshservice_url}}/api/v2/relationships` | + +For other API requests, refer to the [Freshservice API documentation](https://api.freshservice.com/). diff --git a/docs/integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx b/docs/integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx index 372a45081..fcf1fe2ef 100644 --- a/docs/integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx +++ b/docs/integration/external-integrations/freshservice-integration/use-freshservice-integration.mdx @@ -10,6 +10,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl' This page covers the usage and operations of the Freshservice integration. - For initial setup and installation instructions, see [Setting Up the Device42 Freshservice Integration](index.mdx). - See [Advanced Freshservice Mapping and Customization](customize-freshservice.mdx) for instructions and examples on modifying the default sync. +- For help with sync and connection issues, see [Troubleshoot the Freshservice Integration](mapping-integration-troubleshooting.mdx). ::: ## Using the Integration App diff --git a/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-dark.png b/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-dark.png new file mode 100644 index 000000000..e06c44174 Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-dark.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-light.png b/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-light.png new file mode 100644 index 000000000..ea91022fb Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/cloud-services-instance-guid-light.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-dark.png b/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-dark.png new file mode 100644 index 000000000..ee8086e16 Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-dark.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-light.png b/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-light.png new file mode 100644 index 000000000..4755e088e Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/doql-query-standard-reports-light.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-dark.png b/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-dark.png new file mode 100644 index 000000000..ab2970de7 Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-dark.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-light.png b/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-light.png new file mode 100644 index 000000000..9249bba4e Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/external-integrations-verification-token-light.png differ diff --git a/static/assets/images/mapping-integration-troubleshooting/mapping-xml-doql-suffix.png b/static/assets/images/mapping-integration-troubleshooting/mapping-xml-doql-suffix.png new file mode 100644 index 000000000..aa704b503 Binary files /dev/null and b/static/assets/images/mapping-integration-troubleshooting/mapping-xml-doql-suffix.png differ