# Zendesk Input

## Overview

Inputter is an HTTP input which uses Python `zenpy` library. Because of that 
the configuration uses collections that `zenpy` library exposes in form of API.

For example: we want to access Tickets API and pull `tickets` using `incremental`.
The inputter configuration will look like this:
```json
{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"]
}
```

We use a `collection_path` parameter to allow access to nested collections.
For example: 
```json
{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"],
  "includes": ["user"]  // where 'user' is additianally requested to the 'tickets'
}
```
## Specific logic
CHATS 

All Chat related Endpoints require another type of authorization credentials.
We have to replace creds with auth2 token.

You must register your application to generate OAuth credentials 
that your application can use to authenticate API calls to Zendesk.
Docs: https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application#topic_pbc_cdl_1l

Example:
```json
{
  "subdomain": "test_subdomain",
  "auth2_token": "tyuinmf56789knbgf/knkjvjh"
}
```

SEARCH

In Search endpoint there is an extra field "search_query" where you can provide your search request:
Example:
```json
{
    "input": {
        "credentials": {},
        "use": "zendesk.io#ZendeskInput",
        "collection_path": [
            "search"
        ],
        "include": [],
        "search_query": "Please provide search query"
    }
  ```

ATTACHMENTS

In Attachment endpoint there is an extra field "id" where you can provide your attachment_id:
Example:
```json
{
    "input": {
        "credentials": {},
        "use": "zendesk.io#ZendeskInput",
        "collection_path": [
            "attachments"
        ],
        "id": ""
    }
  ```
## Site loading
Several Endpoints support extra parameter to get additional info during one job call.
List of supported:
https://developer.zendesk.com/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints

Example: `["talk", "calls", "incremental"]`.
## Upsert

Upsert can be used only for endpoints that support `start_time` parameter. Usually
it's used only with `incremental` endpoint.

## Tickets and Ticket Fields

For Tickets API the input will include `ticket_fields` and add every field to a 
ticket row (root row). The field has the following format:`"cr_" + field["id"])`.
And the ticket row will look like this:
```json
{
  ...,
  "cr_description": "field_value",
  "cr_status": false,
  "cr_subject": null,
  "cr...": "..."
}
```

## Extend Resources

It is possible to extend root record with result of another API resource using `extend_resources` configuration field.

Having the following inputter configuration

```
{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "incremental"],
  "extend_resources": [
    {
      "collection_path": ["tickets", "metrics"]
    }
  ]
}
```

`extend_resources` will be applied for each root record. In this example the input will make one additional HTTP requests per ticket record. The call list would look like this:

```
GET /tickets

GET tickets/1/metrics
GET tickets/2/metrics
GET tickets/.../metrics
```

The resulting inputter records will look like this:
```
[
  {
    "id": 1111,
    "title": "Ticket 1",
    "tickets_metrics": [
      {"id": 1, "ticket_id": 1111, "solved_at": "2020-07-20T06:21:26Z", ...},
      {"id": 2, "ticket_id": 1111, "solved_at": "2020-07-20T06:21:26Z", ...},
      ...
    ]
  },
  {
    "id": 1222,
    "title": "Ticket 2",
    "tickets_metrics": [
      {"id": 11, "ticket_id": 1222, "solved_at": "2020-07-20T06:21:26Z", ...},
      {"id": 12, "ticket_id": 1222, "solved_at": "2020-07-20T06:21:26Z", ...},
      ...
    ]
  },
  ...
]
```

## Configuration Errors

Invalid 'collection_path':
```json
{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "invalid_collection"]
}
```

'collection_path' is not callable;
```json
{
  "use": "zendesk.io.ZendeskInput",
  "collection_path": ["tickets", "non_callable_attribute"]
}
```

## Input reference:

* [ZendeskInputConfig](schemas/zendesk/config/index.md)