Microapps

Integrate Zendesk

Integrate with Zendesk to submit and monitor requests from any device, intranet, or messenger.

Note:

We provide two Zendesk integration templates for your use. We recommend using the newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure. For full details of the microapps available in each integration, see Use Zendesk microapps.

Use the following process to enable the Zendesk Integration. Ensure you meet the prerequisites, and get your Client ID and secret token. After you complete this process, your existing level of audit logging persists, including any actions carried out by the use of Citrix Microapps.

For a comprehensive list of out-of-the-box Zendesk microapps, see Use Zendesk microapps.

Review prerequisites

Create a dedicated Zendesk account and use it to set up the Zendesk integration. This account must have a role assigned such as Administrator with full data access privileges. After you set up this integration in Zendesk, you will need these artifacts to add the integration in Citrix Workspace Microapps:

  • Base URL: The base URL follows this model: https://{customer-id}.zendesk.com/.
  • Customer ID: Use the customer ID part of the URL, as modeled above, to replace customer-id during set up process.
  • Client ID: The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Zendesk account.
  • Client Secret: The client secret is a unique string issued when setting up the target application integration.
  • Account: This is your service account username.
  • Password: This is your service account password.

The following prerequisites should be met before you begin the integration process:

  • Configure Citrix Gateway to support single sign-on for Zendesk so that once users log in they are automatically logged in again without having to enter their credentials a second time. Follow the instructions in Zendesk Single Sign-on Configuration. For more information about configuring SSO, see Citrix Gateway Service.

Zendesk has an option Enable On-hold status that allows users to assign a Hold status to tickets. Our microapp Tickets allows users to view Zendesk tickets with details, and the page Update ticket has a field Status where Holdis an option. If Hold is not allowed in your Zendesk instance, you need to remove the Hold item from the Status list. For more information, see Use Zendesk microapps.

Set up the Zendesk integration

  1. Log in to www.zendesk.com with the dedicated user account.
  2. Select Admin (the settings icon) on the left sidebar. Under Channels select API.
  3. Select the OAuth Clients tab, and then select the + (plus) icon.
  4. Enter a Client Name for your app.
  5. (Optional) Add a Description, Company, and Logo.
  6. Copy the auto-populated Unique Identifier value for later use.
  7. Set Redirect URLs as described below.
  8. Select Save and OK.
  9. After the page refreshes, a new pre-populated Secret field appears. Copy the Secret Token that is generated for later use. This is not available after you leave this screen.
  10. Select Save.

You are ready to complete the integration in Citrix Workspace Microapps.

Add callback URLs

Add a custom URL to your instance configuration to grant access to private data and enable OAuth authenticated user actions. The first callback that is listed does not change. The second callback depends on the target application, and can be found in your URL address bar when creating the integration. The section {yourmicroappserverurl} is composed of a tenant part, a region part, and an environment part: https://{tenantID}.{region(us/eu/ap-s)}.iws.cloud.com.

Log in to Zendesk as an admin and add the following authorized redirect URLs for this integration:

  • https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext
  • https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

Add the integration to Citrix Workspace Microapps

Follow these steps to set up the Zendesk HTTP integration. We recommend using the newer HTTP integration for most use-cases. The authentication options are preselected. Ensure that these options are selected as you complete the process. We recommend using this newer HTTP integration for most use-cases. The HTTP integration provides more power to configure the cached data structure.

Note:

By default, this integration synchronizes data for a three (3) month time period. We recommend that you modify this value based on your needs and usual age of your tickets. The filter is based on last updated, not created. To change this you must modify the start_time variable in a data loading endpoint. See Replace Data Loading variable.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the Zendesk tile under Integrations..
  3. Enter a Integration name for the integration.
  4. Enter Connector parameters.
    • Enter your Base URL or simply replace {customer-id} in the example with your customer ID.
    • Select an Icon for the integration from the Icon Library, or leave this as the default Zendesk icon.

    HTTP zendesk connector parameters

    • Enable the On-premises instance toggle if you are creating an on-premises connection. For more information, see On-premises instance.

    HTTP zendesk connector Onpremises

  5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Authorization code from the Grant type flow menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This display the Callback URL, which you use when registering your application
    2. Enter authorization_code in the Grant type value field.
    3. Select Authorization header from the Token authorization menu.
    4. Select URL encoded form from the Token content type menu.
    5. Enter your Authorization URL or simply replace {customer-id} in the example with your customer ID. This is the authorization server URL provided when setting up the target application integration.
    6. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    7. Ensure read write for Scope is entered to define the scope of the access request.
    8. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Zendesk account. You need to add the Callback URL you see on the integration configuration page.
    9. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    10. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.

    ZendeskHTTP service authentication

    1. If you selected OAuth 2.0 authentication method, you can select + Add Parameter to include Access token parameters. Access token parameters define the access token parameters as required by the target application authorization server if necessary.

    Zendesk HTTP token

  6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle Service action authentication authenticates at the service action level. Credentials are the same as at the Service Authorization level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Authorization code from the Grant type flow menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This display the Callback URL, which you use when registering your application
    3. Enter authorization_code in the Grant type value field.
    4. Select Authorization header from the Token authorization menu.
    5. Select URL encoded form from the Token content type menu.
    6. Enter your Authorization URL or simply replace {customer-id} in the example with your customer ID. This is the authorization server URL provided when setting up the target application integration.
    7. Enter your Token URL or simply replace {customer-id} in the example with your customer ID. This is the URL of the access authorization token.
    8. Ensure read write for Scope is entered to define the scope of the access request.
    9. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret by registering the OAuth client in your Zendesk account. You need to add the Callback URL you see on the integration configuration page.
    10. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.
    11. Enter your Header prefix. (optional) Enter the header prefix if your bearer prefix is different from the default header.

    HTTP zendesk Service Action Authentication

  7. The Request rate limiting toggle is enabled and the Number of requests per Time interval is set to 500 per minute.
  8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
  9. The Request timeout field is set to 120 by default.

    Rate limiting and logging toggles

  10. Select Save to proceed.
  11. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Webex login screen.
    1. Enter your Service Account user name and password and select Log in.
    2. Select Accept. Service Authentication

Continue with the following procedures to finish the set-up process.

Replace Data Loading variable

By default during full synchronization this integration only loads tickets that are modified in the last three (3) months. If you need to change this, modify the start_time template variable parameter of the Ticket endpoint in this integration data loading setup. We recommend that you modify this value based on your needs and usual age of your tickets. The filter is based on last updated, not created.

  1. From the Microapp Integrations page, select the menu next to the Zendesk integration, and then Edit. The Data Loading screen opens. If you are in the configuration screen, select Data Loading from the left side navigation column.
  2. Select the menu next to the Ticket endpoint and then select Edit, or select the name of the endpoint: Ticket.
  3. In the Edit Data Endpoint screen, under Template variables replace the value for the start_time variable with the value that you want changing the time parameter and numerical value, as required.
  4. Select Apply at the bottom of the screen and confirm.

    Rate limiting and logging toggles

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Zendesk connector specifications.

Use Zendesk microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Note: We provide two Zendesk integration templates for your use. We recommend using the newer HTTP integration for most use-cases over the older java-based integration. The microapps that they contain differ slightly.

Use Zendesk microapps

Our Zendesk HTTP integration comes with the following preconfigured out-of-the-box microapps:

Zendesk microapp

Add Ticket: Submit Zendesk tickets.

Notification or Page Use-case workflows
Add Ticket page Provides a form for submitting a ticket.

Tickets: View Zendesk tickets with details. If Hold is not allowed in your Zendesk instance, you need to remove the Hold item from the Status list in the Update Ticket page.

Notification or Page Use-case workflows
New Ticket Assigned To You (changed) notification When an existing ticket is assigned to a user, they receive a notification.
New Ticket Assigned To You (new) notification When a new ticket is assigned to a user, they receive a notification.
Ticket Status Change notification When the status of a ticket is changed, the submitter of the ticket receives a notification.
Ticket Was Updated notification When a ticket is updated, the submitter receives a notification.
Add Comment page Provides a page for adding a comment to a ticket.
Comment Detail page Provides a read only view of a comment with its details.
My Tickets page Provides a personalized list of tickets related to a user, and a link to ticket details.
Ticket Detail page Provides a read only view of a ticket with details.
Update Ticket page Provides a page for admins to modify tickets. Fields include Priority, Type, and Status.

Add the Zendesk Legacy integration

Follow these instructions to set up the legacy java-based Zendesk integration.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Under Legacy, choose the Zendesk tile.
  3. Enter a name for the integration.

    zendesk connector parameters, URL, Client ID, Client Secret, Number of Months of Tickets to Load

  4. Enter the Connector parameters that you collected as prerequisites.
    • Enter the instance URL.
    • Enter the Client ID. This value is the Unique Identifier you obtained when you registered your application with Zendesk.
    • Enter the Client Secret. This value is the Secret you copied when you registered your application with Zendesk.
    • Select a value for the Number of Months of Tickets to Load.
  5. Select Log in with your Zendesk account to enable OAuth Authorization. A Zendesk sign-in page opens in a new tab. You are prompted to enter an account name, confirm access, and enter a password.
  6. Select Add.

The Microapp Integrations page opens with your added integration and its microapps. From here you can add another integration, continue setting up your out-of-the-box microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Zendesk connector specifications.

Legacy Zendesk microapps

Our java-based Zendesk integration comes with the following preconfigured out-of-the-box microapps:

Zendesk microapp

Add Ticket: Submit Zendesk tickets.

Notification or Page Use-case workflows
Submit Ticket page Provides a form for submitting a ticket.

Tickets: View Zendesk tickets with details.

Notification or Page Use-case workflows
New Ticket Assigned To You (changed) notification When an existing ticket is assigned to a user, they receive a notification.
New Ticket Assigned To You (new) notification When a new ticket is assigned to a user, they receive a notification.
Ticket Status Change notification When the status of a ticket is changed, the submitter of the ticket receives a notification.
Ticket Was Updated notification When a ticket is updated, the submitter receives a notification.
My Tickets page Provides a personalized list of tickets related to a user, and a link to ticket details.
Ticket Detail page Provides a read only view of a ticket with details.
Integrate Zendesk