ticket_sharing 0.5.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/Readme.md +265 -1
- data/lib/ticket_sharing/client.rb +2 -1
- metadata +3 -16
data/Readme.md
CHANGED
@@ -1,2 +1,266 @@
|
|
1
|
+
Ticket Sharing
|
2
|
+
==============
|
1
3
|
|
2
|
-
|
4
|
+
Overview
|
5
|
+
--------
|
6
|
+
|
7
|
+
Typically, a company’s help desk is a silo. Tickets come in, they're assigned, prioritized,
|
8
|
+
answered and an email response is sent back to the customer. The same thing happens across
|
9
|
+
companies’ partners, but often with different software tools and solutions being used at the
|
10
|
+
help desk. When a customer needs help from a company and its partners at the same time, things
|
11
|
+
often get bogged down because of their use of different customer service software.
|
12
|
+
|
13
|
+
In today's world of high-speed communication that's not good enough. Ecosystems of partners,
|
14
|
+
sister companies and out-sourcing is very common across multiple industries.
|
15
|
+
|
16
|
+
The NetworkedHelpDesk.org ticket sharing API allows you to change that. The vision is that your
|
17
|
+
customers can share any ticket in your help desk with any other help desk, regardless of the software
|
18
|
+
being used. By sharing tickets, you're opening up collaboration with other help desks, companies and
|
19
|
+
software; breaking down the walls of the help desk silo.
|
20
|
+
|
21
|
+
|
22
|
+
Terminology
|
23
|
+
-----------
|
24
|
+
|
25
|
+
### General
|
26
|
+
|
27
|
+
* **Ticket** - A typical help desk terminology for a user submitted question, problem, etc. This is synonymous with case, story, issue, etc.
|
28
|
+
* **Ticket sharing** - This is the notion of actually taking a ticket (or case, story, issue, etc) and sending it elsewhere, be it another help desk, bug tracker or any other software.
|
29
|
+
* **Sender** - Is someone sending tickets to another location.
|
30
|
+
* **Receiver** - Is someone receiving tickets from a Sender. Note that either the Sender or Receiver may actually be on the same software provider, or completely different providers.
|
31
|
+
* **Agreement** - An agreement is a set of permissions (explained below) created by a Sender in order to control what it is the Receiver can actually do with tickets that the Sender shares.
|
32
|
+
* **Agreement Invite** - Simply the action of sending an invitation to a potential Receiver which outlines the permissions of the agreement for them to either accept or decline.
|
33
|
+
* **Full delegation** - When an agreement exists between a Sender and a Receiver, there are a set of permissions which restricnder. Note that either the Sender or Receiver may actually be on the same software provider, or completely different providers.
|
34
|
+
* **Agreement** - An agreement is a set of permissions (explained below) created by a Sender in order to control what it is the Receiver can actually do with tickets that the Sender shares.
|
35
|
+
* **Agreement** Invite - Simply the action of sending an invitation to a potential Receiver which outlines the pl,ined below) created by a Sender in order to control what it is the Receiver can actually do with tickets that the Sender shares.
|
36
|
+
* **Agreement Invite** - Simply the action of sending an i c the Receiver can actually do with tickets that the Sender st,e agreement for them to either accept or decline.
|
37
|
+
* **Full delegation** - When an agreement exists between a Sender and a Receiver, there are a se
|
38
|
+
|
39
|
+
### Technical
|
40
|
+
|
41
|
+
* **UUID** - A Universally Unique IDentifier.
|
42
|
+
* **Access Key** - A secret key which grants a help desk access to interact with tickets in another help desk. Do not share this key with anyone.
|
43
|
+
* **X-Ticket-Sharing-Token** - A combination of `UUID` and `Access Key` combined to form a single string, i.e. `UUID:Access Key`.
|
44
|
+
|
45
|
+
|
46
|
+
Generating UUIDs
|
47
|
+
----------------
|
48
|
+
[UUID: Universally Unique IDentifier](http://en.wikipedia.org/wiki/Universally_unique_identifier) (also commonly called GUID: Globally Unique IDentifier)
|
49
|
+
|
50
|
+
Every Ticket Sharing resource requires its own identifier that is unique across all systems
|
51
|
+
that share tickets. The primary resources in Ticket Sharing are agreements, tickets, authors
|
52
|
+
and comments. If your system is the origin of one of these resources, then your system is
|
53
|
+
required to generate the Unique Identifier.
|
54
|
+
|
55
|
+
A UUID is created by joining the following:
|
56
|
+
|
57
|
+
* a help desk's sharing uri (e.g. `mycompany.net/sharing`)
|
58
|
+
* a resource type (e.g. `tickets`)
|
59
|
+
* a resource's unique identifier (e.g. `1`)
|
60
|
+
|
61
|
+
(e.g.: `<helpdesk_uuid>/<resource_type>/<resource_id>`)
|
62
|
+
|
63
|
+
The first part, `mycompany.net/sharing`, uniquely identifies a particular organization.
|
64
|
+
More importantly, it is unique for a single system that is sharing tickets.
|
65
|
+
|
66
|
+
It is important that a resource's UUID is unique across all Ticket Sharing systems.
|
67
|
+
This value should describe one and only one resource. This will ensure that it can be
|
68
|
+
used across all systems as a unique identifier.
|
69
|
+
|
70
|
+
This value should be hashed with SHA-1, to make it suitable for use in URLS.
|
71
|
+
(e.g `mycompany.net/sharing/tickets/1` becomes `ed46838bfb41461e4f3b16ba471162c8e2764260`)
|
72
|
+
|
73
|
+
|
74
|
+
Agreements
|
75
|
+
----------
|
76
|
+
Agreements can be likened to a Facebook friend request. In Facebook, you can invite someone
|
77
|
+
to be your friend, which allows them to do certain things such as look at your photos or status updates.
|
78
|
+
|
79
|
+
In Zendesk it's very similar. You send an agreement invite to another software provider with
|
80
|
+
a set of permissions outlined, either Full Delegation or Partial Delegation.
|
81
|
+
|
82
|
+
If the Receiver accepts the agreement, then sharing can begin straight away under the permissions
|
83
|
+
set out in the agreement. If the Receiver declines the invitation, then sharing may not occur.
|
84
|
+
|
85
|
+
### Sending an agreement invitation (or creating an agreement)
|
86
|
+
|
87
|
+
To create an agreement, the sender must fist generate a `uuid` and an `access_key`.
|
88
|
+
Then the sender must post an agreement request to the receiver's helpdesk.
|
89
|
+
|
90
|
+
POST <partner_url>/agreements/<agreement_uuid>
|
91
|
+
|
92
|
+
{
|
93
|
+
"uuid": "23538de2af57572219a037c98aa4623a6767a498",
|
94
|
+
"name": "Sender Company Name",
|
95
|
+
"receiver_url": "http://mypartner.com/sharing",
|
96
|
+
"sender_url": "http://mycompany.net/sharing",
|
97
|
+
"access_key": "08a479474fc0c3fabfa2b7906f0ce5e55ad2d78f",
|
98
|
+
"status": "pending"
|
99
|
+
}
|
100
|
+
|
101
|
+
_NOTE: status should always be pending on creation._
|
102
|
+
|
103
|
+
### Agreement status
|
104
|
+
|
105
|
+
There are 4 statuses of which apply to an agreement:
|
106
|
+
|
107
|
+
**Pending** - An agreement in pending means the invitation has been sent to the "receiver" but not yet accepted or declined. This is the default state on creation.
|
108
|
+
**Accepted** - The agreement is active, the invite was accepted.
|
109
|
+
**Declined** - The agreement was never made active, the invite was declined.
|
110
|
+
**Inactive** - The agreement has been deactivated by either "sender" or "receiver".
|
111
|
+
|
112
|
+
### Authentication
|
113
|
+
|
114
|
+
Once an agreement has been established between two help desks, authentication credentials
|
115
|
+
must be provided for all other types of requests. Authenticating will be done by setting
|
116
|
+
the `X-Ticket-Sharing-Token` header.
|
117
|
+
|
118
|
+
The value of this header should be the uuid of the agreement, and the access_key joined
|
119
|
+
by a colon `<agreement_uuid>:<access_key>`.
|
120
|
+
|
121
|
+
### Updating an agreement
|
122
|
+
To update an agreement the receiver must set the `X-Ticket-Sharing-Token` header and provide
|
123
|
+
the sender with the updated agreement payload (e.g., the status is now "accepted").
|
124
|
+
|
125
|
+
PUT <partner_url>/agreements/<agreement_uuid>
|
126
|
+
X-Ticket-Sharing-Token: <agreement_uuid>:<access_key>
|
127
|
+
|
128
|
+
{
|
129
|
+
"uuid": "23538de2af57572219a037c98aa4623a6767a498",
|
130
|
+
"name": "Receiver Company Name",
|
131
|
+
"receiver_url": "http://mypartner.com/sharing",
|
132
|
+
"sender_url": "http://mycompany.net/sharing",
|
133
|
+
"status": "accepted"
|
134
|
+
}
|
135
|
+
|
136
|
+
### Sharing a ticket
|
137
|
+
|
138
|
+
To share a ticket, the sender must first generate a uuid for that ticket. For example:
|
139
|
+
|
140
|
+
uuid = 'mycompany.net/sharing/tickets/1' => ed46838bfb41461e4f3b16ba471162c8e2764260
|
141
|
+
|
142
|
+
That uuid should be included in the url as well as the ticket payload. A request that creates a ticket would take the following form...
|
143
|
+
|
144
|
+
POST <partner_url>/tickets/<uuid>
|
145
|
+
X-Ticket-Sharing-Token: <agreement_uuid>:<access_key>
|
146
|
+
|
147
|
+
{
|
148
|
+
// entire ticket payload
|
149
|
+
}
|
150
|
+
|
151
|
+
Sharing & Syncing tickets
|
152
|
+
-------------------------
|
153
|
+
|
154
|
+
The sharing of tickets is done by an agent on an individual ticket level, but could
|
155
|
+
also be done by automated workflow rules. In the ticket sharing API, it's done on
|
156
|
+
an individual ticket basis.
|
157
|
+
|
158
|
+
By pushing a ticket to be shared, you send the ticket from the receiver to the sender,
|
159
|
+
which will include all the details about the ticket.
|
160
|
+
|
161
|
+
### Pushing a ticket to be shared.
|
162
|
+
An example of this request:
|
163
|
+
|
164
|
+
POST http://mypartner.com/sharing/tickets/8c0c8a19a3c598be24047eee940c7ce4c259d1bb
|
165
|
+
X-Ticket-Sharing-Token: 23538de2af57572219a037c98aa4623a6767a498:08a479474fc0c3fabfa2b7906f0ce5e55ad2d78f
|
166
|
+
|
167
|
+
{
|
168
|
+
"uuid": "8c0c8a19a3c598be24047eee940c7ce4c259d1bb",
|
169
|
+
"subject": "Trial expiry time mismatch",
|
170
|
+
"requested_at": "2010-11-24 14:13:54 -0800",
|
171
|
+
"status": "open",
|
172
|
+
"requester": {
|
173
|
+
"uuid": "9b80c1331d9d746c493a8b8e6d3014347469615e",
|
174
|
+
"name": "Joe User"
|
175
|
+
},
|
176
|
+
"comments": [
|
177
|
+
{
|
178
|
+
"uuid": "59e8c53b5c39716e510127e004cc01fc7aaaecd2",
|
179
|
+
"author": {
|
180
|
+
"uuid": "9b80c1331d9d746c493a8b8e6d3014347469615e",
|
181
|
+
"name": "Joe User"
|
182
|
+
},
|
183
|
+
"body": "Hello Company Support, I would like some help."
|
184
|
+
"authored_at": "2010-11-24 14:13:54 -0800"
|
185
|
+
},
|
186
|
+
{
|
187
|
+
"uuid": "4a7542fc9267d94a532ab7221726bd81f087fc87",
|
188
|
+
"author": {
|
189
|
+
"uuid": "127fabf85992fd86091e5e449aa531d6c2eb8116",
|
190
|
+
"name": "Agent Smith"
|
191
|
+
},
|
192
|
+
"body": "Hello Joe, How can I help you?",
|
193
|
+
"authored_at": "2010-11-24 14:25:23 -0800"
|
194
|
+
}]
|
195
|
+
}
|
196
|
+
|
197
|
+
### Updating a ticket
|
198
|
+
|
199
|
+
The request to update a ticket is very similar in form to the request for sharing a ticket.
|
200
|
+
The actual endpoint is the same. However, the request should be an HTTP PUT, instead of an HTTP POST.
|
201
|
+
|
202
|
+
The update endpoint will accept changes and ignore previously set values. For example if a
|
203
|
+
ticket has a status of "pending" and no value for status is provided, the ticket's status
|
204
|
+
will remain "pending". If status is provided, and the value is "pending", the ticket's status
|
205
|
+
will again, remain unchanged. However, if status is provided and it contains an updated value (e.g "open"),
|
206
|
+
then the ticket's status will be updated (e.g. to "open").
|
207
|
+
|
208
|
+
For example if the status is already set, you are not required to send it. If it is omitted,
|
209
|
+
it will remain unchanged. If a status is provided, and it is different than the current status,
|
210
|
+
the status of the ticket will be updated.
|
211
|
+
|
212
|
+
The same goes for comments. If comments are already present on a ticket, they need not be passed
|
213
|
+
across again. If they are passed across, the uuid is usedicket's status will again, remain unchanged.
|
214
|
+
However, if status is provided and it contains an updated value (e.g "open"), then the ticket's
|
215
|
+
status will be updated (e.g. to "open").
|
216
|
+
|
217
|
+
For example if the status is already set, you are not required to send it. If it is omitted,
|
218
|
+
it will remain unchanged. If a status is provided, and it is different than the current status,
|
219
|
+
the status of the ticket will be updated.
|
220
|
+
|
221
|
+
The same goes for comments. If comments omments are already present on
|
222
|
+
|
223
|
+
An example update would look like:
|
224
|
+
|
225
|
+
PUT http://mypartner.com/sharing/tickets/8c0c8a19a3c598be24047eee940c7ce4c259d1bb
|
226
|
+
X-Ticket-Sharing-Token: 23538de2af57572219a037c98aa4623a6767a498:08a479474fc0c3fabfa2b7906f0ce5e55ad2d78f
|
227
|
+
|
228
|
+
{
|
229
|
+
"uuid": "8c0c8a19a3c598be24047eee940c7ce4c259d1bb",
|
230
|
+
"status": "pending",
|
231
|
+
"current_actor": {
|
232
|
+
"uuid": "7e806b7d962be5afdafcd95d9d53498af2ea5b1f",
|
233
|
+
"name": "Agent Name"
|
234
|
+
},
|
235
|
+
"comments": [
|
236
|
+
{
|
237
|
+
"uuid": "184313b9e6347dcade7245123b330af2a5b82a86",
|
238
|
+
"author": {
|
239
|
+
"uuid": "7e806b7d962be5afdafcd95d9d53498af2ea5b1f",
|
240
|
+
"name": "Agent Name"
|
241
|
+
},
|
242
|
+
"body": "Hi, I am the agent that will help you.",
|
243
|
+
"authored_at": "2010-11-24 15:14:24 -0800"
|
244
|
+
}]
|
245
|
+
}
|
246
|
+
|
247
|
+
Attachments
|
248
|
+
-----------
|
249
|
+
Attachments can optionally be included on each comment. An attachment consists
|
250
|
+
of a url* _(required)_ and a filename* _(required)_.
|
251
|
+
|
252
|
+
"comments": [
|
253
|
+
{
|
254
|
+
"body": "Hi, this is a comment with some attachments.",
|
255
|
+
// The rest of a typical comment payload ...
|
256
|
+
"attachments": [
|
257
|
+
{
|
258
|
+
"url": "http://example.com/foo.jpg",
|
259
|
+
"filename": "foo.jpg"
|
260
|
+
},
|
261
|
+
{
|
262
|
+
"url": "http://example.net/attachments/bar.jpg",
|
263
|
+
"filename": "bar.jpg"
|
264
|
+
}
|
265
|
+
]
|
266
|
+
}]
|
@@ -24,7 +24,6 @@ module TicketSharing
|
|
24
24
|
end
|
25
25
|
|
26
26
|
def success?
|
27
|
-
raise "No call made to determine success" unless @success
|
28
27
|
@success
|
29
28
|
end
|
30
29
|
|
@@ -53,6 +52,8 @@ module TicketSharing
|
|
53
52
|
when Net::HTTPMovedPermanently, Net::HTTPFound
|
54
53
|
request.follow_redirect!
|
55
54
|
handle_response(request)
|
55
|
+
when Net::HTTPNotFound, Net::HTTPServerError
|
56
|
+
@success = false
|
56
57
|
else
|
57
58
|
raise TicketSharing::Error.new(%Q{#{response.code} "#{response.message}"\n\n#{response.body}})
|
58
59
|
end
|
metadata
CHANGED
@@ -1,13 +1,8 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: ticket_sharing
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
hash: 9
|
5
4
|
prerelease:
|
6
|
-
|
7
|
-
- 0
|
8
|
-
- 5
|
9
|
-
- 1
|
10
|
-
version: 0.5.1
|
5
|
+
version: 0.5.2
|
11
6
|
platform: ruby
|
12
7
|
authors:
|
13
8
|
- Josh Lubaway
|
@@ -15,8 +10,7 @@ autorequire:
|
|
15
10
|
bindir: bin
|
16
11
|
cert_chain: []
|
17
12
|
|
18
|
-
date: 2011-06-07 00:00:00
|
19
|
-
default_executable:
|
13
|
+
date: 2011-06-07 00:00:00 Z
|
20
14
|
dependencies: []
|
21
15
|
|
22
16
|
description:
|
@@ -40,7 +34,6 @@ files:
|
|
40
34
|
- lib/ticket_sharing/ticket.rb
|
41
35
|
- lib/ticket_sharing/time.rb
|
42
36
|
- Readme.md
|
43
|
-
has_rdoc: true
|
44
37
|
homepage:
|
45
38
|
licenses: []
|
46
39
|
|
@@ -55,23 +48,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
55
48
|
requirements:
|
56
49
|
- - ">="
|
57
50
|
- !ruby/object:Gem::Version
|
58
|
-
hash: 3
|
59
|
-
segments:
|
60
|
-
- 0
|
61
51
|
version: "0"
|
62
52
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
63
53
|
none: false
|
64
54
|
requirements:
|
65
55
|
- - ">="
|
66
56
|
- !ruby/object:Gem::Version
|
67
|
-
hash: 3
|
68
|
-
segments:
|
69
|
-
- 0
|
70
57
|
version: "0"
|
71
58
|
requirements: []
|
72
59
|
|
73
60
|
rubyforge_project:
|
74
|
-
rubygems_version: 1.
|
61
|
+
rubygems_version: 1.8.7
|
75
62
|
signing_key:
|
76
63
|
specification_version: 3
|
77
64
|
summary: Ticket sharing
|