|
| 1 | +# Event Target for Zendesk |
| 2 | + |
| 3 | +This event target receives [CloudEvents][ce] and uses the Zendesk API to either create a new ticket or tag an existing one. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +A Zendesk API token is required to utilize this Target. The steps to obtain a token are outlined in the [Zendesk API Docs](https://support.zendesk.com/hc/en-us/articles/226022787-Generating-a-new-API-token-) |
| 8 | + |
| 9 | +## Deploying an Instance of the Target |
| 10 | + |
| 11 | +Open the Bridge creation screen and add a Target of type `Zendesk`. |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +In the Target creation form, provide a name to the event Target, and add the following information: |
| 16 | + |
| 17 | +* **Default Ticket Subject**: An optional ticket subject fallback if one is not provided in an incoming event. |
| 18 | +* **Zendesk Subdomain**: Name of the Zendesk [Subdomain][zd-subdom], without the `zendesk.com` domain or `https://` scheme. |
| 19 | +* **Zendesk Email**: Email address associated with the Zendesk account. |
| 20 | +* **Zendesk API Token**: Reference to a [TriggerMesh secret][tm-secret] containing a [token][zd-token] to communicate with the Zendesk API, as described in the previous section. |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +After clicking the `Save` button, the console will self-navigate to the Bridge editor. Proceed by adding the remaining components to the Bridge. |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +After submitting the bridge, and allowing some configuration time, a green check mark on the main _Bridges_ page indicates that the bridge with a Zendesk event Target was successfully created. |
| 29 | + |
| 30 | + |
| 31 | + |
| 32 | +For more information about using Zendesk, please refer to the [Zendesk documentation][docs]. |
| 33 | + |
| 34 | +## Event Types |
| 35 | + |
| 36 | +A Zendesk event Target accepts the following [CloudEvent][ce] types: |
| 37 | + |
| 38 | +### com.zendesk.ticket.create |
| 39 | + |
| 40 | +Events of this type intend to create a new Zendesk ticket. |
| 41 | + |
| 42 | +This type expects a [JSON][ce-jsonformat] payload with the following properties: |
| 43 | +| Name | Type | Comment | |
| 44 | +|---|---|---| |
| 45 | +| **subject**| string | The value of the subject field for this ticket | |
| 46 | +| **body** | string | The value of the body field for this ticket | |
| 47 | + |
| 48 | +An example response from the Zendesk Target after consuming an event of this type: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "id":165, |
| 53 | + "url":"https://triggermesh.zendesk.com/api/v2/tickets/165.json", |
| 54 | + "subject":"Hello", |
| 55 | + "raw_subject":"Hello", |
| 56 | + "description":"World", |
| 57 | + "status":"open", |
| 58 | + "requester_id":412584624334, |
| 59 | + "submitter_id":412584624334, |
| 60 | + "assignee_id":412584624334, |
| 61 | + "group_id":360010761434, |
| 62 | + "due_at":"0001-01-01T00:00:00Z", |
| 63 | + "via": |
| 64 | + { |
| 65 | + "channel":"api", |
| 66 | + "source":{"from":{},"to":{},"rel":""}}, |
| 67 | + "satisfaction_rating":{"id":0,"score":"","comment":""}, |
| 68 | + "brand_id":360004879834, |
| 69 | + "allow_attachments":true, |
| 70 | + "is_public":true, |
| 71 | + "created_at":"2020-08-05T20:00:11Z", |
| 72 | + "updated_at":"2020-08-05T20:00:11Z", |
| 73 | + "collaborators":{}, |
| 74 | + "comment":{"created_at":"0001-01-01T00:00:00Z" |
| 75 | + } |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +### com.zendesk.tag.create |
| 80 | + |
| 81 | +Events of this type intend to assign a [tag][zd-tag] to a pre-existing Zendesk ticket. |
| 82 | + |
| 83 | +This type expects a [JSON][ce-jsonformat] payload with the following properties: |
| 84 | +| Name | Type | Comment | |
| 85 | +|---|---|---| |
| 86 | +| **id** | int64 | The value of the id field for the ticket to be updated | |
| 87 | +| **tag** | string | The value of the tag to assign to this ticket | |
| 88 | + |
| 89 | +[ce]: https://cloudevents.io/ |
| 90 | +[ce-jsonformat]: https://github.com/cloudevents/spec/blob/v1.0/json-format.md |
| 91 | +[tm-secret]:https://docs.triggermesh.io/guides/secrets/ |
| 92 | + |
| 93 | +[docs]: https://developer.zendesk.com/rest_api |
| 94 | + |
| 95 | +[zd-token]: https://support.zendesk.com/hc/en-us/articles/226022787-Generating-a-new-API-token- |
| 96 | +[zd-subdom]: https://support.zendesk.com/hc/en-us/articles/221682747-Where-can-I-find-my-Zendesk-subdomain- |
| 97 | +[zd-tag]:https://support.zendesk.com/hc/en-us/articles/203662096-About-tags |
0 commit comments