Set up your Zendesk integration

Updated Jun 17, 2019

This guide will walk you through the steps of setting up your Zendesk integration with ScreenSteps.

Note: You must have a Zendesk account and a ScreenSteps account with one available site for this integration to work.

Create the integration in ScreenSteps

1. Go to Account > Integrations

2. Click on Zendesk Help Center

Go to Account Management > Integrations

Enter your Zendesk account name

  1. Your Zendesk account name is the name at the front of your Zendesk URL. For example, if your help desk is at https://mycompany.zendesk.com then the account name would be mycompany.
  2. Your Zendesk host name is an optional parameter. This should be the host name where your customers come to view your Zendesk site.
Configure your connection
  1. Important: If you are using a custom domain name on your Zendesk account then you will need to enter the full domain name with protocol. For example: https://support.mydomain.com.

Enter your username and API Token

  1. The email should be the email address you use to login to Zendesk––Important: must be a Zendesk Admin login.
  2. You can retrieve your Zendesk API Token by following these instructions.
Configure your connection

Enter Locale and click Create

Configure your connection
  1. The Locale setting defaults to US English. If you would like to push to a different language in your Zendesk account then you should set the locale here. Note that ScreenSteps can only push content to a single locale.
  2. Select Create.

You will be taken to your newly created ScreenSteps site that is connected to Zendesk.

Do you already have existing content in Zendesk that you want to import into ScreenSteps?

Import the structure from Zendesk

First, let's import the structure.

1. Select Import structure from Zendesk

From the Manuals menu, select Import structure from Zendesk HC

Select Import structure from Zendesk
2. Select Import

Confirm that you want to import your structure from Zendesk.

Select Import
3. View imported manual

Select the manual title for one of the manuals that were imported from Zendesk.

Open imported manual

Before you import articles from Zendesk...

Importing an article from Zendesk will connect the ScreenSteps article to the Zendesk article so that when you publish updates from ScreenSteps, the updates will go to the correct page in Zendesk.

Important: If you further edit the article in Zendesk later on, the changes will not be imported back into ScreenSteps. You should make all edits in ScreenSteps going forward.

Import articles from Zendesk

Go to Imports and Select the Manual and Chapter you want to import from
Click on Import

Once the article is imported you will see the text "Connected". Clicking on the text will take you to the article in ScreenSteps.

This is what you will see after you click Connected.

The article shows as "Unpublished" in ScreenSteps, but...

The article will show as "Unpublished" in ScreenSteps. That does not mean that it is not published in Zendesk. It simply means that any updates you make in ScreenSteps will not be published until you "Save & Publish". The reason for this is to allow you to cleanup the article in ScreenSteps before you publish changes to Zendesk.

See how to create content in ScreenSteps

If you don't have any content in Zendesk already, no problem! These next few steps will show you how to create the basic structure in ScreenSteps (which will then be pushed to Zendesk).

You should also check out our documentation on creating content in ScreenSteps so that you can be proficient when building out your knowlede base.

Create a new Manual

A manual in ScreenSteps is the same as a category in Zendesk. When you create and publish a manual in ScreenSteps, it will create and publish a category in Zendesk.

Click on the dropdown arrow next to Manuals
Select New Manual
Give the manual a title and save
Your new manual appears (unpublished)

Your new manual will be unpublished so that your end users do not see it right away. You can publish and unpublish manuals at any time.

Create a new Chapter

Click New +

Creating a new ScreenSteps chapter will create a new Zendesk topic.

Include a title

A chapter title should be fairly broad. For example, if your manual is titled Account Settings, a chapter title might be something like Billing. Then, underneath the chapter, you could create articles that answer common questions about billing.

Create a new Article

An article in ScreenSteps is the same as an article in Zendesk. When you create and publish an article in ScreenSteps, it will create and publish an article in Zendesk.

Click New + in the Articles section

When you create a new article, it will be created in the Manual and Chapter that are selected. For example, in the screenshot below the new article will be created in the Billing chapter.

Write the title > click Create Article

Publish changes (when you're ready)

When you are ready to publish content to Zendesk, publish the manual.

Use manual menu to publish changes

From the manual menu you will see one of two options. Publish in Zendesk HC will appear if the manual hasn't been connected to Zendesk yet. Push update to Zendesk HC will appear if the manual is already connected to Zendesk.

Publish
  1. By default the chapter positions and titles will be updated along with other changes you've made to the manual. To only update the manual uncheck this checkbox. If you uncheck Update chapter positions and titles then only the Manual title and sort order will be updated in Zendesk.
  2. Click either the Publish (manual doesn't exist in Zendesk yet) or Push Changes (manual is connected to Zendesk already) button.

Add ScreenSteps styles and foldable sections to Zendesk

Add styles

ScreenSteps has a feature that allows you to add styles to text fields.

This is an example of a text style. It makes certain text stand out from the rest--helpful for warnings, tips, alerts, information, or introductions.

If you are publishing ScreenSteps articles to Zendesk Help Center, and you want these styles to appear in your Zendesk articles, follow these 3 steps.

Step 1: Add This CSS to Your Zendesk Help Center

See these Zendesk instructions to see how to add custom CSS and Javascript to your Help Center.

Add the following CSS to your Zendesk HelpCenter.

Step 2: Include Font Awesome to Use Icons

If you want the icons to appear in the styled text fields (e.g. light bulb), you must include FontAwesome in your Help Center theme. Follow >> these instructions for including FontAwesome in Zendesk.

Add foldable sections

ScreenSteps has a feature that allows you to create foldable sections. You can enable Zendesk so that foldable sections appear in your Help Center articles.

Step 3: Add Javascript for Foldable Sections
What is a foldable section?
This is an example of a foldable section

When you click on the link, more information folds down. It's a great way to gradually reveal documentation to your customers, and walk them through a process.

Enabling foldable section in Zendesk

In order for foldable sections to work inside of Zendesk you will need to add some javascript to your Help Center theme. Add the javascript below to Zendesk to make foldable sections work inside of Zendesk.

See these Zendesk instructions to see how to add custom CSS and Javascript to your Help Center.

Optional: Style foldable section titles

By default foldable section titles will appear as they do in this article, at standard font sizes. If you would like to style them as headings then you can use the selector:

.screensteps-foldable-title-depth-1 

.screensteps-foldable-title-depth-2 

.screensteps-foldable-title-depth-3 

.screensteps-foldable-title-depth-4

The depth value corresponds to the nesting level of the foldable title.

If you want to apply a style to all titles you can use the selector:

.screensteps-foldable-title

For example, if you would like to change the font size of a level 1 foldable heading you could add the following CSS to Zendesk:

.screensteps-foldable-title-depth-1 {
  font-size: 32px;
}

Still Need Help?

Contact Us