# Connecting to Zendesk
Zendesk is a cloud-based help desk management solution offering customizable tools to build a customer service portal, knowledge base and online communities.
**Topics**
+ [AWS Glue support for Zendesk](zendesk-support.md)
+ [Policies containing the API operations for creating and using connections](zendesk-configuring-iam-permissions.md)
+ [Configuring Zendesk](zendesk-configuring.md)
+ [Configuring Zendesk connections](zendesk-configuring-connections.md)
+ [Reading from Zendesk entities](zendesk-reading-from-entities.md)
+ [Zendesk connection options](zendesk-connection-options.md)
+ [Limitations](zendesk-limitations.md)
# AWS Glue support for Zendesk
AWS Glue supports Zendesk as follows:
**Supported as a source?**
Yes. You can use AWS Glue ETL jobs to query data from Zendesk.
**Supported as a target?**
No.
**Supported Zendesk API versions**
The following Zendesk API versions are supported
+ v2
# Policies containing the API operations for creating and using connections
The following sample policy describes the required AWS IAM permissions for creating and using connections. If you are creating a new role, create a policy that contains the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
}
]
}
```
------
If you dont want to use the above method, alternatively use the following managed IAM policies:
+ [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole) – Grants access to resources that various AWS Glue processes require to run on your behalf. These resources include AWS Glue, Amazon S3, IAM, CloudWatch Logs, and Amazon EC2. If you follow the naming convention for resources specified in this policy, AWS Glue processes have the required permissions. This policy is typically attached to roles specified when defining crawlers, jobs, and development endpoints.
+ [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess) – Grants full access to AWS Glue resources when an identity that the policy is attached to uses the AWS Management Console. If you follow the naming convention for resources specified in this policy, users have full console capabilities. This policy is typically attached to users of the AWS Glue console.
# Configuring Zendesk
Before you can use AWS Glue to transfer data from Zendesk, you must meet these requirements:
## Minimum requirements
The following are minimum requirements:
+ You have a Zendesk account. For more information, see [Creating a Zendesk account](#zendesk-configuring-creating-account).
+ Your Zendesk account is enabled for API access.
+ Your Zendesk account allows you to install connected apps.
If you meet these requirements, you’re ready to connect AWS Glue to your Zendesk account.
## Creating a Zendesk account
To create a Zendesk account:
1. Go to https://www.zendesk.com/in/register/
1. Enter the details such as your work email, first name, last name, phone number, job title, company name, number of employees in company, password and preferred Language. Then choose **Complete trial Signup**.
1. Once your account is created, complete the verification link you received to verify your email address.
1. Once the work email address is verified, you are redirected to your Zendesk account. Choose the **Buy Zendesk option** for your preferred plan. Note: for the Zendesk connector it is recommended to purchase the Suite Enterprise plan.
## Creating a client app and OAuth 2.0 credentials
To create a client app and OAuth 2.0 credentials:
1. Log into your Zendesk account where you want the OAuth 2.0 app to be created https://www.zendesk.com/in/login/
1. Click the gear icon. Choose the **Go to admin center** link to open the admin center page.
1. Choose **Apps and integrations** in the left sidebar, then select **APIs** > **Zendesk API**.
1. On the Zendesk API page, choose the **OAuth Clients** tab.
1. Choose **Add Oauth Client** on the right side.
1. Complete the following fields to create a client:
1. Client Name - Enter a name for your app. This is the name that users will see when asked to grant access to your application, and when they check the list of third-party apps that have access to their Zendesk.
1. Description - Optional. A short description of your app that users will see when asked to grant access to it.
1. Company - Optional. The company name that users will see when asked to grant access to your application. The information can help them understand who they're granting access to.
1. Logo - Optional. This is the logo that users will see when asked to grant access to your application. The image can be JPG, GIF, or PNG. For best results, upload a square image. It will be resized for the authorization page.
1. Unique Identifier - The field is auto-populated with a reformatted version of the name you entered for your app. You can change it if you want.
1. Redirect URLs - Enter the URL or URLs that Zendesk should use to send the user's decision to grant access to your application.
For example: https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. Click **Save**.
1. After the page refreshes, a new pre-populated **Secret** field appears on the lower side. This is the "client\$1secret" value specified in the OAuth2 spec. Copy the Secret value to your clipboard and save it somewhere safe. Note: The characters may extend past the width of the text box, so make sure to select everything before copying.
1. Click **Save**.
# Configuring Zendesk connections
The Zendesk connector supports the Authorization Code grant type.
+ This grant type is considered "three-legged" OAuth as it relies on redirecting users to a third-party authorization server to authenticate the user. It is used when creating connections via the AWS Glue console. The user creating a connection may by default rely on an AWS Glue-owned connected app (AWS Glue-managed client application) where they do not need to provide any OAuth related information except for their Zendesk instance URL. The AWS Glue console will redirect the user to Zendesk where the user must login and allow AWS Glue the requested permissions to access their Zendesk instance.
+ You may still opt to create your own connected app in Zendesk and provide your own client ID and client secret when creating connections through the AWS Glue console. In this scenario, you will still be redirected to Zendesk to login and authorize AWS Glue to access your resources.
+ This grant type results in an access token. The access token never expires.
For public Zendesk documentation on creating a connected app for the Authorization Code OAuth flow, see [OAuth Tokens for Grant Types](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/).
To configure a Zendesk connection:
1. In AWS Secrets Manager, create a secret with the following details:
1. For the AuthorizationCode grant type: for a customer managed connected app the secret should contain the connected app Consumer Secret with `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` as key.
1. Note: You must create a secret per connection in AWS Glue.
1. In AWS Glue Glue Studio, create a connection under **Data Connections** by following the steps below:
1. When selecting a **Connection type**, select Zendesk.
1. Provide the INSTANCE\$1URL of the Zendesk you want to connect to.
1. Provide the Zendesk environment.
1. Select the AWS IAM role which AWS Glue can assume and has permissions for following actions:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. Select the `secretName` which you want to use for this connection in AWS Glue to put the tokens.
1. Select the network options if you want to use your network.
1. Grant the IAM role associated with your AWS Glue job permission to read `secretName`.
# Reading from Zendesk entities
**Prerequisite**
A Zendesk Object you would like to read from. You will need the object name such as ticket or user or article, as mentioned in the following table.
| Entity | Can be filtered | Supports limit | Supports Order by | Supports Select \$1 | Supports partitioning |
| --- | --- | --- | --- | --- | --- |
| Ticket | Y | Y | Y | Y | N |
| User | Y | Y | Y | Y | N |
| Organization | Y | Y | Y | Y | N |
| Article | Y | Y | N | Y | N |
| Ticket Event | Y | Y | N | Y | N |
| Ticket Metric Event | Y | Y | N | Y | N |
| Ticket Comment | Y | Y | Y | Y | N |
| Ticket Field | Y | Y | N | Y | N |
| Ticket Metric | Y | Y | N | Y | N |
| Ticket Activity | Y | Y | N | Y | N |
| Ticket Skip | N | Y | N | Y | N |
| Group | Y | Y | Y | Y | N |
| Group Membership | N | Y | Y | Y | N |
| Satisfaction Rating | Y | Y | N | Y | N |
| View | Y | Y | Y | Y | N |
| Trigger | Y | Y | Y | Y | N |
| Trigger Category | N | Y | Y | Y | N |
| Macro | Y | Y | Y | Y | N |
| Automation | N | Y | Y | Y | N |
**Example**:
```
Zendesk_read = glueContext.create_dynamic_frame.from_options(
connection_type="Zendesk",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v2"
}
```
**Zendesk entities and field details**:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/glue/latest/dg/zendesk-reading-from-entities.html)
**Note**
Struct and List data types are converted to String data type in the response of the connector.
## Partitioning queries
Partitions are not supported in Zendesk.
# Zendesk connection options
The following are connection options for Zendesk:
+ `ENTITY_NAME`(String) - (Required) Used for Read. The name of your Object in Zendesk.
+ `API_VERSION`(String) - (Required) Used for Read. Zendesk Rest API version you want to use. For example: v2.
+ `SELECTED_FIELDS`(List) - Default: empty(SELECT \$1). Used for Read. Columns you want to select for the object. For example: id, name, url, created\$1at
+ `FILTER_PREDICATE`(String) - Default: empty. Used for Read. It should be in the Spark SQL format. For example: group\$1id = 100
+ `QUERY`(String) - Default: empty. Used for Read. Full Spark SQL query. For example: "SELECT id,url FROM users WHERE role=\$1"end-user\$1""
+ `PARTITION_FIELD`(String) - Used for Read. Field to be used to partition query. Default field is `update_at` for entities supporting the incremental export API (`created_at` for `ticket-events` and `time` for `ticket-metric-events`).
+ `LOWER_BOUND`(String)- Used for Read. An inclusive lower bound value of the chosen partition field.
+ `UPPER_BOUND`(String) - Used for Read. An exclusive upper bound value of the chosen partition field. Optional; this option will be handled by the connector if not provided in the job option. Default value - "2024-05-01T20:55:02.000Z
+ `NUM_PARTITIONS`(Integer) - Default: 1. Used for Read. Number of partitions for read. Optional; this option will be handled by the connector if not provided in the job option. Default value : 1.
+ `IMPORT_DELETED_RECORDS`(String) - Default: FALSE. Used for read. To get the delete records while querying.
+ `ACCESS_TOKEN` - Access token to be used in the request.
+ `INSTANCE_URL` - URL of the instance where the user wants to run the operations. For example : https://\$1subdomain\$1/.zendesk.com
# Limitations
The following are limitations of the Zendesk connector:
+ Offset-based pagination limits the number of pages that can be fetched to 100, but it not recommended as the total number of records that can be fetched is 10,000. However, the cursor-based pagination that is implemented for the Zendesk connector overcomes this limitation. Only the EQUAL\$1TO filter operator is supported through the Zendesk API.
Because of this limitation, partitioning is not supported for the Zendesk connector.
+ For the "Ticket Event" entity the Rate Limit is 10 requests per minute. While running a AWS Glue ETL job you may receive a 429 (too many requests) error.