zendesk_api 1.3.5 → 1.3.7

data/lib/zendesk_api/server/docs/views.md

@@ -1,644 +0,0 @@
-## Views
-
-A view consists of one or more conditions that define a collection of tickets to display. If the conditions are met, the ticket is included in the view. For example, a view can display all open tickets that were last updated more than 24 hours ago.
-
-For more information, see [Using views to manage ticket workflow](https://support.zendesk.com/entries/20103667).
-
-
-### JSON Format
-Views are represented as simple flat JSON objects which have the following keys.
-
-| Name            | Type                       | Comment
-| --------------- | ---------------------------| -------------------
-| id              | integer                    | Automatically assigned when created
-| title           | string                     | The title of the view
-| active          | boolean                    | Useful for determining if the view should be displayed
-| restriction     | object                     | Who may access this account. Will be null when everyone in the account can access it.
-| execution       | [Execute](#execution)      | An object describing how the view should be executed
-| conditions      | [Conditions](#conditions)  | An object describing how the view is constructed
-| created_at      | date                       | The time the view was created
-| updated_at      | date                       | The time of the last update of the view
-
-#### Example
-```js
-{
-  "view": {
-    "id": 25,
-    "title": "Tickets updated <12 Hours",
-    "active": true,
-    "execution": { ... },
-    "conditions": [ ... ],
-    "restriction": {
-      "type": "User",
-      "id": 4
-    }
-  }
-}
-```
-
-### Execution
-View Execution is a read-only object that describes how to display a collection of tickets in a View.
-
-| Name            | Type    | Comment
-| --------------- | ------- | -------
-| columns         | Array   | The ticket fields to display. Custom fields have an id, title, type and url referencing the [Ticket Field](ticket_fields.md)
-| group           | Object  | When present, the structure indicating how the tickets are grouped
-| sort            | Object  | The column structure of the field used for sorting.
-
-#### Example
-```js
-{
-   "execution":{
-     "columns": [
-       { "id": "status",  "title": "Status" },
-       { "id": "updated", "title": "Updated" },
-       {
-         "id": 5, "title": "Account", "type": "text",
-         "url": "https://example.zendesk.com/api/v2/ticket_fields/5.json"
-       },
-       ...
-     ]
-     "group": { "id": "status", "title": "Status", "order": "desc" },
-     "sort": { "id": "updated", "title": "Updated", "order": "desc" }
-   }
-}
-```
-
-### Conditions
-The conditions under which a ticket is selected.
-
-| Name         | Type    | Comment
-| ------------ | ------- | -------
-| all          | array   | Tickets must fulfill *all* of these conditions to be considered matching
-| any          | array   | Tickets may satisfy *any* of these conditions to be considered matching
-
-#### Example
-```js
-{
-   "conditions": {
-     "all": [
-       { "field": "status", "operator": "less_than", "value": "solved" },
-       { "field": "assignee", "operator": "is", "value": "me" },
-     ],
-     "any": [
-     ]
-   }
-}
-```
-
-<!---
-
-### View Rows
-
-View Rows are read-only and represented as simple flat JSON objects which have the following keys.
-
-| Name            | Type                        | Comment
-| --------------- | --------------------------- | -------------------
-| view            | Array                       | View that was executed. Consists of id and url.
-| rows            | Array                       | Array of tickets contained in the view, described by the fields.
-| columns         | Array                       | Array of [Fields](#execution) and [Custom Fields](#execution) representing the columns in each row.
-
-A row contains the data indicated by the idenitifiers in the columns array.
-
-| Name                   | Type                         | Optional  | Comment
-| ---------------------- | ---------------------------- | --------- | ----------------
-| ticket                 | Object                       | no        | Ticket id, url, subject, description, status, type, priority and comment this row is a subset of.
-| custom_fields          | Array                        | no        | Custom fields values.
-| group                  | Integer                      | yes       | Id of this ticket's group.
-| organization           | Integer                      | yes       | Id of this ticket's organization.
-| requester              | Integer                      | yes       | Id of this ticket's requester.
-| assignee               | Integer                      | yes       | Id of this ticket's assignee.
-| submitter              | Integer                      | yes       | Id of this ticket's submitter.
-| locale                 | String                       | yes       | Locale of the requester.
-| type                   | String                       | yes       | See [Ticket](tickets.md#json-format)
-| priority               | String                       | yes       | See [Ticket](tickets.md#json-format)
-| status                 | String                       | yes       | See [Ticket](tickets.md#json-format)
-| updated_by_type        | String                       | yes       | Last updated by 'agent' or 'end user'
-| subject                | DateTime                     | yes       | Ticket subject.
-| requester_updated_at   | DateTime                     | yes       | When the requester last updated the ticket.
-| assignee_updated_at    | DateTime                     | yes       | When the assignee last updated the ticket.
-| assigned               | DateTime                     | yes       | When the ticket was assigned last.
-| due_date               | DateTime                     | yes       | When the ticket is due.
-| solved                 | DateTime                     | yes       | When the ticket was solved.
-| created                | DateTime                     | yes       | When the ticket was created.
-| updated                | DateTime                     | yes       | When the ticket was updated.
-
-#### Example
-```js
-{
-  "view": {
-    "id": 5,
-    "url": "https://example.zendesk.com/api/v2/views/5.json"
-  },
-  "rows": [
-    {
-      "ticket": { ... },
-      "locale": "en-US",
-      "group": { ... },
-      ...
-    },
-    ...
-  ],
-  "columns": [
-    {
-      "id": "locale",
-      "title": "Locale"
-    },
-    {
-      "id": 5,
-      "title": "Account",
-      "url": ...
-    },
-    ...
-  ]
-}
-```
-
--->
-
-### List Views
-`GET /api/v2/views.json`
-
-Lists shared and personal Views available to the current user
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "views": [
-    {
-      "id":25,
-      "title":"Tickets updated <12 Hours",
-      "active":true,
-      "execution":{ ... },
-      "conditions": { ... },
-      "restriction":{ ... }
-    },
-    {
-      "id":23,
-      "title":"Unassigned tickets",
-      "active":false,
-      "execution":{ ... },
-      "conditions": { ... },
-      "restriction":{ ... }
-    },
-    ...
-  ],
-  "count": 7,
-  "next_page": null,
-  "previous_page": null
-}
-```
-
-### List Active Views
-`GET /api/v2/views/active.json`
-
-Lists active shared and personal Views available to the current user
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/active.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "views": [
-    {
-      "id": 25,
-      "title": "Tickets updated <12 Hours",
-      "active": true
-      "execution": { ... },
-      "conditions": { ... },
-      "restriction": { ... }
-    },
-    ...
-  ],
-  "count": 7,
-  "next_page": null,
-  "previous_page": null
-}
-```
-
-### List Views - Compact
-`GET /api/v2/views/compact.json`
-
-A compacted list of shared and personal views available to the current user
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/compact.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "views": [
-    {
-      "id": 25,
-      "title": "Tickets updated <12 Hours",
-      "active": true
-      "execution": { ... },
-      "conditions": { ... },
-      "restriction": { ... }
-    },
-    ...
-  ],
-  "count": 7,
-  "next_page": null,
-  "previous_page": null
-}
-```
-
-### Getting Views
-`GET /api/v2/views/{id}.json`
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "view": {
-    "id": 25,
-    "title": "Tickets updated <12 Hours",
-    "active": true
-    "execution": { ... },
-    "conditions": { ... },
-    "restriction": { ... }
-  }
-}
-```
-
-### Create View
-`POST /api/v2/views.json`
-
-#### Allowed For
-
- * Agents
-
-#### Using curl
-
-```bash
-curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/api/v2/views.json \
-  -H "Content-Type: application/json" -X POST -d '{"view":{"title":"Roger Wilco", "all": [{ "field": "status", "operator": "is", "value": "open" }]}}'
-```
-
-#### Example Response
-
-```http
-Status: 201 Created
-Location: /api/v2/view/{new-view-id}.json
-
-{
-  "view": {
-    "id":   9873843,
-    "title": "Roger Wilco",
-    ...
-  }
-}
-```
-
-### Update View
-`PUT /api/v2/view/{id}.json`
-
-#### Allowed For
-
- * Agents
-
-#### Using curl
-
-```bash
-curl -v -u {email_address}:{password} https://{subdomain}.zendesk.com/view/{id}.json \
-  -H "Content-Type: application/json" -X PUT -d '{"view":{"title":"Roger Wilco II"}}'
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "view": {
-    "id":   9873843,
-    "title": "Roger Wilco II",
-    ...
-  }
-}
-```
-
-### Executing Views
-`GET /api/v2/views/{id}/execute.json`
-
-You execute a view in order to get the tickets that fulfill the conditions of the view.
-
-The view execution system is designed for periodic rather than high-frequency API usage. In particular, views that are called very
-frequently by an API client (more often than once every 5 minutes on average) may be cached by our software. This means
-that the API client will still receive a result however that result may have been computed at any time within the last 10
-minutes.
-
-If you are looking for a method to get the latest changes to your Zendesk via the API we recommend the ticket export API
-which can be called as often as once a minute, and will return all the tickets changed since last poll.
-
-View output sorting can be controlled by passing the sort_by and sort_order parameters in the
-format described in the table under [view previewing](#previewing-views).
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}/execute.json \
-  -v -u {email_address}:{password}
-```
-
-With sort options:
-
- ```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}/execute.json?sort_by=id&sort_order=desc \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "view": {
-    "id": 25,
-    "url": ...
-  },
-  "rows": [
-    {
-      "ticket": { ... },
-      "locale": "en-US",
-      "group": 1,
-      ...
-    },
-    ...
-  ],
-  "columns": [
-    {
-      "id": "locale",
-      "title": "Locale"
-    },
-    {
-      "id": 5,
-      "title": "Account",
-      "url": ...
-    },
-    ...
-  ],
- "groups": [ ... ]
-}
-```
-
-### Getting Tickets from a view
-`GET /api/v2/views/{id}/tickets.json`
-
-#### Allowed For
-
- * Agents
-
-#### Using curl:
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}/tickets.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Responses
-
-```http
-Status: 200 OK
-
-{
-  "tickets": [
-    {
-      "id":      35436,
-      "subject": "Help I need somebody!",
-      ...
-    },
-    {
-      "id":      20057623,
-      "subject": "Not just anybody!",
-      ...
-    },
-  ]
-}
-```
-
-### Previewing Views
-`POST /api/v2/views/preview.json`
-
-Views can be previewed by constructing the conditions in the [proper format](#conditions) and nesting them under the 'view' key.
-The output can also be controlled by passing in any of the following parameters and nesting them under the 'view' key.
-
-| Name            | Type    | Comment
-| --------------- | ------- | -------
-| columns         | Array   | The ticket fields to display. System fields are looked up by name, custom fields by title or id.
-| group_by        | String  | When present, the field by which the tickets are grouped
-| group_order     | String  | The direction the tickets are grouped. May be one of 'asc' or 'desc'
-| sort_order      | String  | The direction the tickets are sorted. May be one of 'asc' or 'desc'
-| sort_by         | String  | The ticket field used for sorting. This will either be a title or a custom field id.
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/preview.json \
-  -v -u {email_address}:{password} -X POST -H "Content-Type: application/json" \
-  -d '{"view": {"all": [{"operator": "is", "value": "open", "field": "status"}], "output": {"columns": ["subject"]}}}'
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-
-{
-  "rows": [
-    {
-      "ticket": { ... },
-      "subject": "en-US",
-      ...
-    },
-    ...
-  ],
-  "columns": [
-    {
-      "id": "subject",
-      "title": "Subject"
-    },
-    ...
-  ]
-}
-```
-
-### View Counts and Caching
-
-The view count APIs allow an API consumer to estimate how many tickets remain in a View without having to retrieve the entire View.
-These APIs are intended to help estimate View size; from a business perspective, accuracy becomes less relevant as your View size increases.
-To ensure quality of service, these counts are cached more heavily as the number of tickets in a View grows.  For a View with thousands of tickets,
-you can expect its count to be cached for 60-90 minutes and may not reflect the actual number of tickets in your View.
-
-### View Counts
-`GET /api/v2/views/count_many.json?ids={view_id},{view_id}`
-
-Calculates the size of the view in terms of number of tickets the view will return.
-Only returns values for personal and shared views accessible to the user performing
-the request.
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/count_many.json?ids={view_id} \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-When you retrieve view counts that are not "fresh", it's recommended to wait for a short
-while an poll again for only the stale view counts.
-
-```http
-Status: 200 OK
-
-{
-  "view_counts": [{
-    "view_id": 25,
-    "url":     "https://company.zendesk.com/api/v2/views/25/count.json",
-    "value":   719,
-    "pretty":  "~700",
-    "fresh":   true
-  },
-  {
-    "view_id": 78,
-    "url":     "https://company.zendesk.com/api/v2/views/78/count.json",
-    "value":   null,
-    "pretty":  "...",
-    "fresh":   false
-  }
-]}
-```
-
-### View Count
-`GET /api/v2/views/{id}/count.json`
-
-Returns the ticket count for a single view.
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}/count.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Response
-
-```http
-Status: 200 OK
-{
-  "view_count": {
-    "view_id": 25,
-    "url":     "https://company.zendesk.com/api/v2/views/25/count.json",
-    "value":   719,
-    "pretty":  "~700",
-    "fresh":   true
-  }
-}
-```
-
-### Exporting Views
-`GET /api/v2/views/{id}/export.json`
-
-Returns the csv attachment of the current view if possible.
-Enqueues a job to produce the csv if needed.
-
-#### Allowed For:
-
- * Agents
-
-#### Using curl
-
-```bash
-curl https://{subdomain}.zendesk.com/api/v2/views/{id}/export.json \
-  -v -u {email_address}:{password}
-```
-
-#### Example Responses
-
-##### With available data
-```http
-Status: 200
-Content-Disposition: Attachment
-[CSV data]
-```
-
-##### Starting a CSV job
-```http
-Status: 201
-
-{
-  "export": {
-    "view_id": 25,
-    "status": "starting"
-  }
-}
-```