zendesk_api 0.1.11 → 0.2.1

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

@@ -0,0 +1,505 @@
+## Views
+
+### JSON Format
+Views are read-only and 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
+| --------------- | ------- | -------
+| fields          | Array   | The ticket fields to display. System fields have a string id.
+| custom_fields   | Array   | The custom ticket fields to display. Custom fields have an id and url referencing the [Ticket Field](ticket_fields.md)
+| 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.
+
+#### Example
+```js
+{
+   "execution":{
+     "fields": [
+       { "id": "status",  "title": "Status" },
+       { "id": "updated", "title": "Updated" }
+     ],
+     "custom_fields": [
+       {
+         "id": 5, "title": "Account",
+         "url": "https://example.zendesk.com/api/v2/ticket_fields/5.json"
+       },
+       ...
+     ]
+     "group_by":null,
+     "sort_order":"desc",
+     "sort_by":"updated"
+   }
+}
+```
+
+### 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 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": { ... }
+  }
+}
+```
+
+### Executing Views
+`GET /api/v2/views/{id}/execute.json`
+
+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": [ ... ]
+}
+```
+
+### 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/rules/views/25/count.json",
+    "value":   719,
+    "pretty":  "~700",
+    "fresh":   true
+  },
+  {
+    "view_id": 78,
+    "url":     "https://company.zendesk.com/api/v2/rules/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/rules/views/25/count.json",
+    "value":   719,
+    "pretty":  "~700",
+    "fresh":   true
+  }
+}
+```