Building a server-side app - Part 2: Displaying server-side content in a Zendesk app

In the previous tutorial in this series, you learned core concepts about server-side Zendesk apps. In this tutorial, you'll build a small web app that displays server-side content in a Zendesk app.

The tutorial covers the following tasks:

• Creating a basic framework app
• Creating a web application
• Displaying server-side content in the Zendesk app

This tutorial is the second part of a series on building a server-side Zendesk app:

• Part 1: Core concepts
• Part 2: Displaying server-side content in a Zendesk app - YOU ARE HERE
• Part 3: Accessing external APIs
• Part 4: Accessing framework APIs
• Part 5: Securing the app
• Part 6: Deploying the app

You'll build the web app using a Python micro web framework named Bottle. The framework helps keep technical details to a minimum so you can focus on the logic, which you can apply in another framework if you want.

Creating a basic framework app

Even when building a server-side web app, you still need to create a basic framework app with the required files and folders. You can generate these files using ZCLI.

1. Create a folder named tutorial_apps. Example:

   mkdir tutorial_apps

2. In your shell, navigate to the tutorial_apps folder. Example:

   cd tutorial_apps

3. In the tutorial_apps folder, run:

   zcli apps:new

4. When prompted, enter the following information:

   • Directory name: app_local
   • Author's name: Your name
   • Author's email: Your email address
   • Author's website: Leave blank and press Enter.
   • App name: Server-side App Tutorial

   ZCLI creates app starter files in the app_local folder.

5. In the app_local folder, open manifest.json in your text editor. In the file, replace the ticket_sidebar property's url value with the following:

   ...
   "location": {
     "support": {
       "ticket_sidebar": {
         "url": "http://localhost:8080/sidebar",
         "flexible": true
       }
     }
   },
   ...

   You'll need to change the URL again when you deploy the web app.

6. Save manifest.json

Creating a web application

Next, develop and test the web app using Python.

Setting up the web application

1. In your shell, run:

   pip3 install bottle requests

   The command installs the Bottle and Requests packages for Python.

2. In the tutorial_apps folder, create a folder named app_remote. Example:

   cd tutorial_apps
   mkdir app_remote

3. In the app_remote folder, create a text file named app.py.

4. Open app.py in a text editor and paste the following into the file:

   from bottle import route, run
   
   # app code goes here
   
   run(host='localhost', port=8080)

   The first line imports the Bottle route() and run() methods to create routes to pages and run the web app.

   The Bottle framework has a built-in development server you can use to test your changes. The run() method starts and runs the web server on port 8080.

   To learn more about the framework, see Bottle: Python Web Framework on the Bottle website.

Python gotchas

• Indentation matters in Python. When copying the examples in this tutorial, make sure to indent your lines appropriately. So far all the lines are flush with the left margin.
• Indent with 4 spaces, not a tab. Python will stop executing and report an indentation error if it encounters a tab character.

Displaying server-side content in the Zendesk app

To display server-side content in the iframe app in Zendesk Support, create a route in the web app to handle requests from the iframe. To refresh your memory, Zendesk Support makes an initial request to http://localhost:8080/sidebar, the URL specified in your manifest.json file.

1. In app.py, replace the # app code goes here comment with the following route:

   @route('/sidebar')
   def send_iframe_html():
       return '<p>App content from the server</p>'

   The send_iframe_html() function returns the line of HTML in response to any HTTP request to the /sidebar route. You can test it using the built-in development server in Bottle.

2. In your shell, navigate to the app_remote folder.

3. Run the following command to start the local server:

   python3 app.py

4. Wait a moment to allow the server to start, then open http://localhost:8080/sidebar in a browser.

   The following HTML page is displayed:

   

Testing the Zendesk app

You can already test the app in Zendesk Support's Agent Workspace:

1. Make sure your Bottle server is still running. Zendesk Support will request the initial page from it.

2. In another terminal session, navigate to the app_local folder.

3. Start a local ZCLI web server by running the following command:

   zcli apps:server

4. In your browser's private or incognito window, sign in to Zendesk Support and go to the Agent Workspace. From the workspace, open a new or existing ticket.

   The URL should look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}

5. Append ?zcli_apps=true to the ticket URL, and reload the page. The URL should look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}?zcli_apps=true

6. Click the Apps icon.

   

   The app displays the HTML served by the Bottle web server.

   

That's all there is to displaying server-side content in a Zendesk app. The rest is just the details of building the web app, including creating pages that can access both external and framework APIs.

In this tutorial, you built and ran a web app that displayed content in the iframe in Zendesk Support. In the next tutorial, you'll learn how to request and display external data in Zendesk Support. See Part 3 - Accessing external APIs.