Skip to content

Commit

Permalink
More on tracking people's locations
Browse files Browse the repository at this point in the history
  • Loading branch information
@AndrewDonkin-Gallagher
AndrewDonkin-Gallagher committed Sep 25, 2024
1 parent 7ba9759 commit b4a5dd0
Show file tree
Hide file tree
Showing 4 changed files with 103 additions and 27 deletions.
11 changes: 10 additions & 1 deletion ref/cardholders.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2287,7 +2287,16 @@ <h2 class="operation-title">
<div class="prop-title">403 Forbidden</div>
</div>
<div class="prop-value">
<p>There is no such cardholder, or the operator does not have permissions to delete it, or the server is not licensed for cardholder operations.</p>
<p>The operator does not have permissions to delete that cardholder or the server is not licensed for cardholder operations.</p>
<p>In versions up to and including 9.20 403 also means that there is no such cardholder.</p>
</div>
</div>
<div class="prop-row prop-group">
<div class="prop-name">
<div class="prop-title">404 Not Found</div>
</div>
<div class="prop-value">
<p>New in 9.30. There is no such cardholder.</p>
</div>
</div>
<div class="prop-row prop-group">
Expand Down
43 changes: 35 additions & 8 deletions ref/events.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -547,6 +547,8 @@ <h1 id="topic-Event-field-specifiers" data-traverse-target="topic-Event-field-sp
</tr>
</tbody>
</table>
<h3 id="per-event-bookmarks">Per-event bookmarks</h3>
<p>If you are running 8.70 or later and you put <code>previous</code>, <code>next</code>, or <code>updates</code> in the field list of an event search, the server will add those fields to each event. All server versions include links with those names at the end of results, but they are not useful if you crash out half way through processing a batch. The per-event links, only available in 8.70 and later and only on request, give you a place to pick up from without being re-sent the events you already processed.</p>
</div>
</div>
</div>
Expand Down Expand Up @@ -2328,17 +2330,42 @@ <h4 id="searching-for-events-related-to-particular-cardholders">Searching for ev
<p>To further improve the efficiency of your search, filter by event types and a time range.</p>
<h4 id="searching-for-events-that-indicate-location-or-movement">Searching for events that indicate location or movement</h4>
<p>If your server is running 8.60 or earlier, use the search filter <code>type=20001,20002,20003,20047,20107,42415</code>. That is not a complete list of movement event types but it includes the popular ones.</p>
<p>If your server is running 8.70-8.90 inclusive, give your operator the &#39;View cardholder events&#39; privilege instead of &#39;View events&#39;. Then request all events, and the server will only send you movements.</p>
<p>If your server is running 9.00 or later, the &#39;View cardholder events&#39; privilege is still an excellent idea but you can also use the search filter <code>type=hasLocation&amp;fields=location</code> (with a leading <code>?</code> or <code>&amp;</code> of course, and more fields if you need them). That will limit the results to location events. Then look at the <code>type</code> field inside the <code>location</code> block:</p>
<p>If your server is running 8.70-8.90 inclusive, give your operator the &#39;View cardholder events&#39; privilege instead of &#39;View events&#39;. Then you can request all events, and the server will only send you movements because that is all your operator is permitted to see.</p>
<p>If your server is running 9.00 or later, the &#39;View cardholder events&#39; privilege is still an excellent idea to limit your operator&#39;s vision but you can also use the search filter <code>type=hasLocation&amp;fields=location</code> (with a leading <code>?</code> or <code>&amp;</code> of course, and more fields if you need them). That will limit the results to location events.</p>
<p>When using a server at version 9.00 or better:</p>
<ol>
<li>
<p><code>GET /api</code></p>
</li>
<li>
<p>Get the URL of the head of the event queue by following the link at <code>features.events.updates.href</code>
<a href="#operation--api-events-updates-get">↪</a> appending <code>type=hasLocation&amp;fields=location</code> with the appropriate query separator <code>?</code> or <code>&amp;</code> depending on whether there is a query parameter in the URL already. The call will block until a new location event arrives.</p>
</li>
<li>
<p>If this is your first time here you will have an array containing one event. If you looped up from a later step, the array may contain many more. In any case, process all the events in the results using the advice immediately below about interpreting the <code>location</code> block. Also follow the advice in
<a href="#downloading-the-entire-event-database">downloading the entire event database</a> about keeping track of your position if you might have to abort mid-batch. Note that that advises using the <code>next</code> field, but if you want long polls you will be using the <code>updates</code> field.</p>
</li>
<li>
<p>Sleep for a short time to reduce load on the server.</p>
</li>
<li>
<p>Follow the link at <code>updates.href</code> for a long poll that waits for new events to arrive, or follow <code>next.href</code> for a call that will return immediately even if there are no new events for you.</p>
</li>
<li>
<p>Loop up to process the events you received.</p>
</li>
</ol>
<p>Interpreting the <code>location</code> block:</p>
<ul>
<li>
<p>If you are simply after a person&#39;s location, use the <code>afterLocation</code> field inside the <code>location</code> block. That could be an access zone or division if they moved or attempted to move, or a workstation or alarms terminal if they logged into one of those. The <code>canonicalTypeName</code> field inside the block will tell you what kind of item it is. Future versions of Command Centre or customisations might add more.</p>
<p>If you are simply after a person&#39;s location and do not care how they arrived there, use the <code>afterLocation</code> block inside <code>location</code>. The <code>canonicalTypeName</code> field in there will tell you what kind of location it is. The
<a href="#definition-Event-detail">schema definition</a> describes <code>afterLocation</code> in more detail.</p>
</li>
<li>
<p>If you are after movements, which happen when a door grants a person access or an operator moves them on a tag board or via the API, and happen to some types of visitors when their host moves, ignore all events except those that have a <code>location.type</code> of <code>moved</code>. Look at the <code>afterLocation</code> to see where they landed. It will be an access zone or (for departing visitors) a reception. There will also be a <code>beforeLocation</code> if the door had two zones configured on it, in case you&#39;re interested in where they came from. The <code>canonicalTypeName</code> field in both blocks will tell you what kind of item it is.</p>
<p>If you are after movements, which happen when a door grants a person access or an operator moves them on a tag board or via the API, and happen to some types of visitors when their host moves, ignore all events except those that have a <code>location.type</code> of <code>moved</code>. Look at the <code>afterLocation</code> to see where they landed. There will also be a <code>beforeLocation</code> if the door had two zones configured on it, in case you&#39;re interested in where they came from. The <code>canonicalTypeName</code> field in both blocks will tell you what kinds of item they are.</p>
</li>
<li>
<p>If you are after denials, which happen when a person authenticates but fails the access check, look at the events that have a <code>location.type</code> of <code>denied</code>. Like &#39;moved&#39;-type events, <code>location.afterLocation</code> will show where they were. The difference is that with &#39;denied&#39;-type events, they started there too.</p>
<p>If you are after denials, which happen when a person authenticates but fails the access check, look at the events that have a <code>location.type</code> of <code>denied</code>. Like &#39;moved&#39;-type events, <code>location.afterLocation</code> will show where they ended up. The difference is that with &#39;denied&#39;-type events, they started there too.</p>
</li>
</ul>
<p>Each of those fields is covered in the
Expand Down Expand Up @@ -2823,7 +2850,7 @@ <h2 class="operation-title">
</div>
<div class="prop-value">
<p>Sets the fields you want in your results.</p>
<p>This is the list of valid fields for 8.40, but it is different for older server versions, so check with the topic
<p>This is the list of currently-valid fields, but it is different for older server versions so check with the topic
<a href="#topic-Event-field-specifiers">on event field specifiers</a>.</p>
</div>
</div>
Expand Down Expand Up @@ -3221,7 +3248,7 @@ <h2 class="operation-title">
</div>
<div class="prop-value">
<p>Sets the fields you want in your results.</p>
<p>This is the list of valid fields for 8.40, but it is different for older server versions, so check with the topic
<p>This is the list of currently-valid fields, but it is different for older server versions so check with the topic
<a href="#topic-Event-field-specifiers">on event field specifiers</a>.</p>
</div>
</div>
Expand Down Expand Up @@ -3468,7 +3495,7 @@ <h2 class="operation-title">
</div>
<div class="prop-value">
<p>Sets the fields you want in your results.</p>
<p>This is the list of valid fields for 8.40, but it is different for older server versions, so check with the topic
<p>This is the list of currently-valid fields, but it is different for older server versions so check with the topic
<a href="#topic-Event-field-specifiers">on event field specifiers</a>.</p>
</div>
</div>
Expand Down
7 changes: 6 additions & 1 deletion swagger/cardholdersApi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6010,8 +6010,13 @@ paths:
another construct (a personalised notification, for example).
403:
description: |
There is no such cardholder, or the operator does not have permissions to delete it,
The operator does not have permissions to delete that cardholder
or the server is not licensed for cardholder operations.
In versions up to and including 9.20 403 also means that there is no such cardholder.
404:
description: |
New in 9.30. There is no such cardholder.
409:
<<: *409CH

Expand Down
69 changes: 52 additions & 17 deletions swagger/eventsApi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -345,32 +345,58 @@ tags:
types but it includes the popular ones.
If your server is running 8.70-8.90 inclusive, give your operator the 'View cardholder events'
privilege instead of 'View events'. Then request all events, and the server will only send you
movements.
privilege instead of 'View events'. Then you can request all events, and the server will only
send you movements because that is all your operator is permitted to see.
If your server is running 9.00 or later, the 'View cardholder events' privilege is still an
excellent idea but you can also use the search filter `type=hasLocation&fields=location` (with
a leading `?` or `&` of course, and more fields if you need them). That will limit the results
to location events. Then look at the `type` field inside the `location` block:
excellent idea to limit your operator's vision but you can also use the search filter
`type=hasLocation&fields=location` (with a leading `?` or `&` of course, and more fields if you
need them). That will limit the results to location events.
* If you are simply after a person's location, use the `afterLocation` field inside the
`location` block. That could be an access zone or division if they moved or attempted to
move, or a workstation or alarms terminal if they logged into one of those. The
`canonicalTypeName` field inside the block will tell you what kind of item it is. Future
versions of Command Centre or customisations might add more.
When using a server at version 9.00 or better:
1. `GET /api`
2. Get the URL of the head of the event queue by following the link at
`features.events.updates.href` [↪](#operation--api-events-updates-get) appending
`type=hasLocation&fields=location` with the appropriate query separator `?` or `&` depending
on whether there is a query parameter in the URL already. The call will block until a new
location event arrives.
5. If this is your first time here you will have an array containing one event. If you looped
up from a later step, the array may contain many more. In any case, process all the events
in the results using the advice immediately below about interpreting the `location` block.
Also follow the advice in [downloading the entire event
database](#downloading-the-entire-event-database) about keeping track of your position if you
might have to abort mid-batch. Note that that advises using the `next` field, but if you
want long polls you will be using the `updates` field.
4. Sleep for a short time to reduce load on the server.
5. Follow the link at `updates.href` for a long poll that waits for new events to arrive, or
follow `next.href` for a call that will return immediately even if there are no new events
for you.
6. Loop up to process the events you received.
Interpreting the `location` block:
* If you are simply after a person's location and do not care how they arrived there, use the
`afterLocation` block inside `location`. The `canonicalTypeName` field in there will tell you
what kind of location it is. The [schema definition](#definition-Event-detail) describes
`afterLocation` in more detail.
* If you are after movements, which happen when a door grants a person access or an operator
moves them on a tag board or via the API, and happen to some types of visitors when their host
moves, ignore all events except those that have a `location.type` of `moved`. Look at the
`afterLocation` to see where they landed. It will be an access zone or (for departing
visitors) a reception. There will also be a `beforeLocation` if the door had two zones
configured on it, in case you're interested in where they came from. The `canonicalTypeName`
field in both blocks will tell you what kind of item it is.
`afterLocation` to see where they landed. There will also be a `beforeLocation` if the door
had two zones configured on it, in case you're interested in where they came from. The
`canonicalTypeName` field in both blocks will tell you what kinds of item they are.
* If you are after denials, which happen when a person authenticates but fails the access check,
look at the events that have a `location.type` of `denied`. Like 'moved'-type events,
`location.afterLocation` will show where they were. The difference is that with 'denied'-type
events, they started there too.
`location.afterLocation` will show where they ended up. The difference is that with
'denied'-type events, they started there too.
Each of those fields is covered in the [schema definition](#definition-Event-detail).
Expand Down Expand Up @@ -735,6 +761,15 @@ x-spectacle-topics:
| 8.20 to 8.30 | defaults,cardholder.pdf_XXXX<br>or<br>defaults,details<br>or<br>defaults,cardholder.pdf_XXXX,details
| 8.40 and later | any
### Per-event bookmarks
If you are running 8.70 or later and you put `previous`, `next`, or `updates` in the field
list of an event search, the server will add those fields to each event. All server versions
include links with those names at the end of results, but they are not useful if you crash out
half way through processing a batch. The per-event links, only available in 8.70 and later
and only on request, give you a place to pick up from without being re-sent the events you
already processed.
x-common-blocks-this-is-made-up:
fds_ignored: &FIELDSDESC_SUM
description: |
Expand Down Expand Up @@ -895,7 +930,7 @@ parameters:
description: |
Sets the fields you want in your results.
This is the list of valid fields for 8.40, but it is different for older server versions, so
This is the list of currently-valid fields, but it is different for older server versions so
check with the topic [on event field specifiers](#topic-Event-field-specifiers).
paths:
Expand Down

0 comments on commit b4a5dd0

Please sign in to comment.