Troubleshoot device connectivity in Zendesk Support

Follow the Zendesk Help guide to add a new custom ticket field named ICCID. Select Number (without decimals) as the field type.

Add a Display name to clarify the field’s purpose for your team.

Integrated circuit card identifier (ICCID), a 19-digit code used to identify a SIM card. This value doesn't include the final Luhn check digit.

Complete the configuration and save the custom field by following the Adding custom ticket fields to your tickets and forms Zendesk guide.

Create the app files. Use the following values when prompted:

• Directory: emnify-support-app
• Author’s name: Your name
• Author’s email: Your email address
• Author’s website: Leave blank and press Enter
• App name: emnify Support App

After completing this step, the Zendesk Command Line Interface (ZCLI) generates starter files in the emnify-support-app folder.

Check the app’s location.

Run the app locally to test it in your Zendesk Support account before deployment.

Open the iframe.html file in a text editor.

Remove the h2 element:

1
<h2 class="u-semibold u-fs-xl">Hello, World!</h2>

Ensure the file includes the ZAF SDK library with the following script tag:

1
<script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>

Create a file named main.js in the assets folder.

Add this asynchronous function to main.js to initialize the ZAF JavaScript API client:

1
(async function () {
2
  const client = ZAFClient.init();
3
})();

Add a line to resize the app UI:

1
(async function () {
2
  // Initialize the Zendesk app framework (ZAF) client
3
  const client = ZAFClient.init();
4
  // Resize the app UI
5
  client.invoke("resize", { width: "100%", height: "500px" });
6
})();

In the iframe.html file, delete the inline script initializing the ZAF client and replace it with:

1
<script src="main.js"></script>

In iframe.html, add the following footer block before the script tags:

1
<footer>
2
  <a href="https://github.com/org/emnify-support-app/issues/new" target="_blank">Report bugs</a>
3
</footer>

Refresh the app in Zendesk to see the changes.

Create a new file named main.css in the assets folder.

Replace the Zendesk Garden stylesheet link in iframe.html with:

1
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"
2
crossorigin="anonymous">

Add a link to main.css:

1
<link rel="stylesheet" href="main.css">

Add the following styles to main.css for the app interface:

1
/* General Body Styles */
2
body {
3
  color: #343a40;
4
  font-family: Arial, sans-serif;
5
  font-size: 14px;
6
  margin: 0;
7
  padding: 0.5rem;
8
}
9
10
/* Button Container */
11
.button-container {
12
  display: flex;
13
  justify-content: center; /* Center buttons horizontally */
14
  flex-wrap: wrap; /* Allow buttons to wrap on small screens */
15
  gap: 0.5rem; /* Increase spacing between buttons */
16
  margin: 1rem 0; /* Add more vertical spacing above and below the buttons */
17
}
18
19
/* Buttons */
20
.btn {
21
  font-size: 12px;
22
  padding: 0.25rem 0.5rem;
23
  border-radius: 0.25rem;
24
}
25
26
.btn-secondary {
27
  background-color: #6f42c1;
28
  border-color: #6f42c1;
29
  color: #fff;
30
}
31
32
.btn-secondary:hover {
33
  background-color: #5a379c;
34
  border-color: #5a379c;
35
}
36
37
.btn-danger {
38
  background-color: #e83e8c;
39
  border-color: #e83e8c;
40
  color: #fff;
41
}
42
43
.btn-danger:hover {
44
  background-color: #d63384;
45
  border-color: #d63384;
46
}
47
48
/* Status Text */
49
#reset-connectivity-status {
50
  margin-top: 0.5rem;
51
  font-size: 12px;
52
  text-align: center; /* Ensure text is centered under buttons */
53
  color: #6c757d;
54
  display: block; /* Ensure it appears as a block element */
55
}
56
57
/* Info Blocks */
58
.info-blocks {
59
  margin-top: 1rem;
60
  padding: 0.5rem;
61
  background-color: #ffffff;
62
  border: 1px solid #dee2e6;
63
  border-radius: 0.25rem;
64
  box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
65
}
66
67
.info-blocks table {
68
  width: 100%;
69
  font-size: 12px;
70
}
71
72
.info-blocks td {
73
  padding: 0.15rem 0.1rem;
74
}
75
76
/* Footer */
77
footer {
78
  font-size: 10px;
79
  text-align: center;
80
  margin-top: 1rem;
81
}
82
83
footer a {
84
  color: #6f42c1;
85
  text-decoration: none;
86
}
87
88
footer a:hover {
89
  color: #5a379c;
90
}

Follow Authenticate with application tokens to generate your auth_token.

Save the auth_token for later use in your app.

Open the assets/manifest.json file.

Add the following line to allow your app to send requests to the emnify REST API:

1
{
2
  ...
3
  "domainWhitelist": ["cdn.emnify.net"],
4
  ...
5
}

Define settings using the parameters property in the manifest file. Add the following code:

1
{
2
  ...
3
  "parameters": [
4
    {
5
      "name": "authToken",
6
      "type": "text",
7
      "required": true,
8
      "secure": true
9
    }
10
  ],
11
  ...
12
}

Open your main.js file.

At the top, define global variables for the device ID and ICCID:

1
let deviceId;
2
let iccidFromCustomField;

Add a function to retrieve the ticket’s custom fields and extract the ICCID:

1
await client
2
  .get("ticket.customField:custom_field_ID")
3
  .then(data => {
4
    iccidFromCustomField =
5
      data["ticket.customField:custom_field_ID"];
6
});

Import the Handlebars library in your app by adding the following script to iframe.html (before the script importing your main.js file):

1
<script src="https://cdn.jsdelivr.net/npm/handlebars@4.3.3/dist/handlebars.min.js"></script>

Define templates in script tags with type="text/x-handlebars-template". The following is an example to create a table for device and SIM details:

1
<script id="device-details-template" type="text/x-handlebars-template">
2
  <strong>Device and SIM Details</strong>
3
  <table>
4
    <tr>
5
      <td>Name:</td>
6
      <td class="data">{{name}}</td>
7
    </tr>
8
    <tr>
9
      <td>Device ID:</td>
10
      <td class="data">{{device_id}}</td>
11
    </tr>
12
    <tr>
13
      <td>Device status:</td>
14
      <td class="data">{{device_status}}</td>
15
    </tr>
16
    <tr>
17
      <td>SIM ID:</td>
18
      <td class="data">{{sim_id}}</td>
19
    </tr>
20
    <tr>
21
      <td>SIM status:</td>
22
      <td class="data">{{sim_status}}</td>
23
    </tr>
24
    <tr>
25
      <td>Last updated:</td>
26
      <td class="data">{{last_updated}}</td>
27
    </tr>
28
  </table>
29
</script>

Add a div element with the ID device-sim-details in iframe.html after opening body tag:

1
<div id="device-sim-details" class="info-blocks"></div>

Start by defining the function before renderTemplate. It should accept the ICCID as an input parameter because the ICCID uniquely identifies the SIM card and is used in the API request.

1
const showDeviceDetails = async iccid => {
2
  // Implementation goes here!
3
};

Since this function makes a network request, it can fail for reasons like network issues or incorrect data. Use a try-catch block to handle both success and failure scenarios.

1
try {
2
  // Successful response handling
3
} catch (error) {
4
  // Error handling
5
}

Inside the try block, use the client.request method to call the emnify REST API. Pass the ICCID as part of the query parameter to filter the results and include authentication headers.

• URL: The base URL for the emnify Endpoint API.
• ICCID query: q=iccid:${iccid} filters results to find a specific SIM.
• Headers: Include the Authorization header with the JWT token.

1
const response = await client.request({
2
  url: `https://cdn.emnify.net/api/v1/endpoint?q=iccid:${iccid}`,
3
  type: "GET",
4
  headers: { Authorization: "Bearer {{setting.authToken}}" },
5
  secure: true,
6
  dataType: "json",
7
});

The API response contains the details you need, such as the device name, ID, SIM status, etc. Extract these details from the response.

• Response parsing: The response is an array of devices. Use the first device (response[0]).
• Store device ID: Save the device ID globally for later use.
• Format the data: Create an object with the required fields to display in the template.

1
const lastUpdatedDate = new Date(); // Capture the time of the fetch
2
const device = response[0]; // Get the first device from the API response
3
4
deviceId = device.id; // Store device ID globally
5
6
const deviceDetails = {
7
  name: device.name,
8
  device_id: device.id,
9
  device_status: device.status.description,
10
  sim_id: device.sim.id,
11
  sim_status: device.sim.status.description,
12
  last_updated: lastUpdatedDate,
13
};

Pass the deviceDetails object to a Handlebars template to render the information in the app. Use the renderTemplate function you created earlier.

1
renderTemplate(
2
  "device-details-template", // Template ID
3
  deviceDetails,             // Data to populate
4
  "device-sim-details"       // Target element ID
5
);

If the API request fails, display an error message using a dedicated Handlebars template (defined in the next section). The error message can include the status and description to help debug.

1
catch (error) {
2
  renderTemplate("error-template", error, "device-sim-details");
3
}

Finally, call showDeviceDetails in main.js with your global ICCID variable:

1
showDeviceDetails(iccidFromCustomField);

Locate the following line in your showDeviceDetails function:

1
const lastUpdatedDate = new Date();

Replace it with:

1
const currentTime = new Date();
2
const lastUpdatedDate = formatDate(currentTime);

Add this function to your main.js and adjust the options as needed:

1
const formatDate = dateString => {
2
const options = {
3
  weekday: "short",
4
  day: "2-digit",
5
  month: "short",
6
  year: "numeric",
7
  hour: "2-digit",
8
  minute: "2-digit",
9
  timeZoneName: "short",
10
};
11
return new Date(dateString).toLocaleString("en-US", options);
12
};

Here’s an example date rendered with these options: Thu, Jan 16, 2025, 12:56 PM GMT+1

Add this script to your iframe.html file:

1
<script id="connectivity-template" type="text/x-handlebars-template">
2
  <strong>Device Connectivity</strong>
3
  <table>
4
    <tr>
5
      <td>Status:</td>
6
      <td class="data">{{connectivity_status}}</td>
7
    </tr>
8
    <tr>
9
      <td>Last updated:</td>
10
      <td class="data">{{last_updated}}</td>
11
    </tr>
12
  </table>
13
</script>

Add a div element with the ID device-connectivity-status after the opening body tag:

1
<div id="device-connectivity-status" class="info-blocks"></div>

Begin by defining the function in main.js. It accepts deviceId as a parameter, which is the unique identifier for the device obtained from the emnify REST API.

1
const showConnectivityStatus = async deviceId => {
2
  // Implementation goes here!
3
};

As with showDeviceDetails, network requests in this function may fail. Use a try-catch block to handle both success and error scenarios.

1
try {
2
  // Successful response handling
3
} catch (error) {
4
  // Error handling
5
}

Inside the try block, use client.request to call the emnify REST API for the device’s connectivity status.

• URL: The base URL for the emnify Endpoint API entrypoint.
• Headers: Include the Authorization header with the JWT token.

1
const response = await client.request({
2
  url: `https://cdn.emnify.net/api/v1/endpoint/${deviceId}/connectivity`,
3
  type: "GET",
4
  headers: { Authorization: "Bearer {{setting.authToken}}" },
5
  secure: true,
6
  dataType: "json",
7
});

The response contains the device’s connectivity status. Extract the status description and format the current date to show when the information was last updated.

• Use the formatDate function (defined earlier) to format the date.

1
const currentTime = new Date();
2
const lastUpdatedDate = formatDate(currentTime);
3
4
const connectivityData = {
5
  connectivity_status: response.status.description,
6
  last_updated: lastUpdatedDate,
7
;

Pass the connectivityData object to the renderTemplate function to populate and display the data in the app.

1
renderTemplate(
2
  "connectivity-template",   // ID of the Handlebars template
3
  connectivityData,          // Data object to populate the template
4
  "device-connectivity-status" // Target element ID
5
);

If the API request fails, render an error template. This ensures that the agent sees an informative message if something goes wrong.

1
catch (error) {
2
  renderTemplate("error-template", error, "device-connectivity-status");
3
}

Call showConnectivityStatus from within showDeviceDetails after retrieving the deviceId. This ensures that the connectivity status is displayed as soon as the device details are fetched.

1
const showDeviceDetails = async iccid => {
2
  try {
3
    ...
4
  showConnectivityStatus(deviceId);
5
  } catch (error) {
6
    ...
7
  }

Begin by defining the resetConnectivity function. By the end, this function:

• Updates the UI to indicate the reset process has started.
• Sends a PATCH request to the connectivity reset API entrypoint.
• Handles the response and update the UI accordingly.
• Display the updated connectivity status after a delay.

1
const resetConnectivity = async () => {
2
  // Implementation goes here!
3
};

Inside the function, access the status span element (reset-connectivity-status) to provide feedback to the agent. Update the text to “Processing…” and style it with a warning class to visually indicate that the reset process is ongoing.

1
const statusSpan = document.getElementById("reset-connectivity-status");
2
statusSpan.innerText = "Processing...";
3
statusSpan.classList.add("text-warning");

The emnify REST API requires a payload with location and pdp_context. For this guide, set these values to null. Serialize this data into JSON format using JSON.stringify.

1
const payload = JSON.stringify({
2
  location: null,
3
  pdp_context: null,
4
});

Next, prepare the headers for the API request. Include:

• An Authorization header with the bearer token for authentication.
• A Content-Type header specifying that the payload is JSON.

By storing these headers in a variable, you maintain compatibility with the Zendesk app framework.

1
const headers = {
2
  Authorization: "Bearer {{setting.authToken}}",
3
  "Content-Type": "application/json",
4
};

Use the client.request method to send a PATCH request to the emnify REST API. The deviceId is passed in the URL to specify the device to be reset.

1
await client.request({
2
  url: `https://cdn.emnify.net/api/v1/endpoint/${deviceId}/connectivity`,
3
  type: "PATCH",
4
  headers: headers,
5
  data: payload,
6
  secure: true,
7
});

If the request is successful:

1. Update the status span with a success message, informing the agent that the reset process has started.
2. Advise the agent to keep the tab open while waiting for the updated status.
3. Use a setTimeout function to fetch the new connectivity status after two minutes.
   When reset connectivity is triggered, the device detaches from the network and waits for the modem to connect again. Depending on the device and network conditions, this process can take a few seconds to a few minutes. The connectivity status fetched may not be accurate unless you add a delay.

1
statusSpan.innerText =
2
  "Connectivity reset. Updating status... Don't close this tab. The process may take a few minutes.";
3
setTimeout(() => {
4
  showConnectivityStatus(deviceId); // Refresh the connectivity status
5
  statusSpan.innerText = "Updated.";
6
  statusSpan.classList.remove("text-warning");
7
  statusSpan.classList.add("text-success");
8
}, 120000); // Delay for 2 minutes

To handle potential errors, the catch block needs to:

• Extract details from the error response (if available).
• Update the status span with a meaningful error message and apply a danger class to indicate failure.
• Log the error to the console for debugging purposes.

1
} catch (error) {
2
  const errorDetails = error.responseJSON
3
    ? `${error.responseJSON.message} (Status: ${error.status})`
4
    : error.statusText || "Unknown error occurred";
5
6
  console.error("Error resetting connectivity:", error);
7
  statusSpan.innerText = `Failed to reset connectivity: ${errorDetails}`;
8
  statusSpan.classList.remove("text-warning");
9
  statusSpan.classList.add("text-danger");
10
}

Finally, attach the resetConnectivity function to the “Reset Connectivity” button using an event listener. This ensures that the function is triggered when an agent clicks the button.

1
document
2
  .getElementById("reset-connectivity")
3
  .addEventListener("click", resetConnectivity);