Updated Documents RSS Feed¶
Purpose¶
The purpose of the document is to provide a description and sample of the information to be included in the updated documents RSS feed. This feed will contain all new, updated, and retired documents modified within the last 7 days.
Usage¶
The feed can be accessed at https://<your_site_name_here>.policystat.com/policy_reports/feeds/updated/<login_token>/. Replace ‘<your_site_name_here>’ with your site’s subdomain and ‘<login_token>’ with a valid login token.
Your current valid login token can be found at https://<your_site_name_here>.policystat.com/admin/login_token/. You will be presented with your site URL with an appended login token.
Example: https://example-site.policystat.com/admin/?lt=ABCDEFGHIJKLMNOPQRSTUV
ABCDEFGHIJKLMNOPQRSTUV is your login token in this example. Use this login token to access your feed without the need to log in.
Example: https://example-site.policystat.com/policy_reports/feeds/updated/ABCDEFGHIJKLMNOPQRSTUV/
Specification¶
The following sections go into more depth on the fields to be included in the feed. Fields designated as Required must be included to match the specification of an Atom feed. All other fields are open to modification.
Feed Fields¶
The following fields will be included with every feed:
id
Example
<id>https://your-site.pstattraining.com/?lt=123qkgp9u4ER8oafL7opSy&next=/</id>
Description
An identifier of the feed containing a URL to your PolicyStat site
Required
title
Example
<title>New/updated/archived policies</title>
Description
A short description of the feed
Required
updated
Example
<updated>2016-11-30T20:02:42-05:00</updated>
Description
A timestamp of when the feed was generated
Required
link
Example
<link href="https://your-site.pstattraining.com/policy_reports/feeds/latest/your-site/2685143/YZTxRcdafuh2123KL7-adfO5/" rel="self" type="application/rss+xml"></link>
Description
A URL link to the feed itself
Entry Fields¶
title
Example
<title>Overtime Pay</title>
Description
The document title found in PolicyStat
Required
updated
Example
<updated>2016-10-26T17:18:00-05:00</updated>
Description
A timestamp of when the document was last modified. If this has changed, it is possible that the content of the document has also changed.
Required
author
Example
<author> <name>Smith, John: Manager</name> <p:firstname>John</p:firstname> <p:lastname>Smith</p:lastname> <p:title>Manager</p:title> </author>
Description
The author’s first and last name, as well as title are included in the name field.
- This name field is further broken down into individual fields for:
- Firstname
- Lastname
- Title
category
Example
<category term="Administration"/>
Description
The area where the document is found in PolicyStat
applicability
Example
<p:applicability name="ABC Hospital"> <p:site>XYZ Hospital</p:site> <p:site>Doctors Office</p:site> <p:site>The Lab</p:site> ... </p:applicability>
Description
The applicability group that this document belongs to is specified in the name atribute of this field. All sites also in this applicability group are listed individually in the site fields. This is the same list that can be seen when hovering over the documents Applicability in PolicyStat.
status
Example
<p:status>Active</p:status>
Description
The current status of the document: active or retired.
change_type
Example
<p:change-type>2 Changes</p:change-type>
Description
The type of change the document experienced
Possible values include:
- Created
- x Changes
- Retired
id
Example
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/0987654321/</id>
Description
A URI to the updated document in PolicyStat. This URI contains a valid login token, (lt CGI parameter) which will change whenever the login token is updated.
Required
persistent-id
Example
<p:persistent-id>123456789</p:persistent-id>
Description
The unique id of the document across all versions of the document
policystat-id
Example
<p:policystat-id>987654321</p:policystat-id>
Description
The unique id of the current version of the document
link
Example
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/0987654321/"></link>
Description
A URI to the updated document in PolicyStat. This URI contains a valid login token, (lt CGI parameter) which will change whenever the login token is updated.
content
Example
<content type="html"><h2>PURPOSE</h2> <p>The purpose of this policy is to describe the eligibility of overtime pay....</p> </content>
Description
The full content of the document found in PolicyStat encoded as HTML.
Note: The content of retired documents will be empty.
Example Feed¶
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:p="https://your-site.pstatbeta.com/" xml:lang="en-us">
<link href="https://your-site.pstattraining.com/policy_reports/feeds/latest/your-site/2685143/YZTxRcdafuh2123KL7-adfO5/" rel="self" type="application/rss+xml"></link>
<id>https://your-site.pstattraining.com/?lt=123qkgp9u4ER8oafL7opSy&next=/</id>
<updated>2016-11-30T20:02:42-05:00</updated>
<title>New/updated/archived policies for </title>
<entry>
<title>Overtime Pay</title>
<updated>2016-12-26T17:18:00-05:00</updated>
<p:change-type>2 Changes</p:change-type>
<author>
<name>Smith, John: Manager</name>
<p:firstname>John</p:firstname>
<p:lastname>Smith</p:lastname>
<p:title>Manager</p:title>
</author>
<p:status>Active</p:status>
<category term="Administration"/>
<p:applicability name="ABC Hospital">
<p:site>XYZ Hospital</p:site>
<p:site>Doctors Office</p:site>
<p:site>The Lab</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/0987654321/</id>
<p:persistent-id>1234567890</p:persistent-id>
<p:policystat-id>0987654321</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/0987654321/"></link>
<content type="html"><h2>PURPOSE</h2> <p>The purpose of this policy is to describe the eligibility of overtime pay.</p>
</content>
</entry>
<entry>
<title>Dress Code</title>
<updated>2016-12-15T17:45:05-05:00</updated>
<p:change-type>3 Changes</p:change-type>
<author>
<name>Doe, John: CEO</name>
<p:firstname>John</p:firstname>
<p:lastname>Doe</p:lastname>
<p:title>CEO</p:title>
</author>
<p:status>Active</p:status>
<category term="Human Resources"/>
<p:applicability name="Medical Office Building">
<p:site>MedicalOffice Building</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/654321/</id>
<p:persistent-id>567890</p:persistent-id>
<p:policystat-id>654321</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/654321/"></link>
<content type="html"><h2>PURPOSE</h2> <p>All employees are expected to have a professional appearance.</p>
</content>
</entry>
<entry>
<title>New Employee Onboarding</title>
<updated>2016-12-14T16:58:49-04:00</updated>
<p:change-type>10 Changes</p:change-type>
<author>
<name>Smith, Joe: IT Admin</name>
<p:firstname>Joe</p:firstname>
<p:lastname>Smith</p:lastname>
<p:title>Nurse</p:title>
</author>
<p:status>Active</p:status>
<category term="Information Technology"/>
<p:applicability name="The Office">
<p:site>The Office</p:site>
<p:site>ABC Hospital</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/4321/</id>
<p:persistent-id>7890</p:persistent-id>
<p:policystat-id>4321</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/4321/"></link>
<content type="html"><h2>PURPOSE</h2> <p>All new employees must do this.</p>
</content>
</entry>
<entry>
<title>Cleaning the microwave</title>
<updated>2016-12-01T10:25:49-05:00</updated>
<p:change-type>Retired</p:change-type>
<author>
<name>Schmo, Joe: Janitor</name>
<p:firstname>Joe</p:firstname>
<p:lastname>Schmo</p:lastname>
<p:title>Janitor</p:title>
</author>
<p:status>Retired</p:status>
<category term="Admin"/>
<p:applicability name="ABC Hospital">
<p:site>Doctors Office 1</p:site>
<p:site>ABC Hospital</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/21/</id>
<p:persistent-id>90</p:persistent-id>
<p:policystat-id>21</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/21/"></link>
<content type="html"></content>
</entry>
</feed>
Feed Adaption to Document Changes¶
As a document experiences change over its lifetime in PolicyStat, such as making a new version or being retired, each feed entry will also change to reflect the current state of the document.
This section aims to describe how the feed will change as a result of changes to the document over time, and how these changes can be detected by looking at the data in the feed.
Detecting a document revision¶
Sometimes, a document’s content will change without going through a full approval cycle (which would create a new version). For example, an administrator override can bypass the approval process. In that case, the updated field of the document entry will change to the time of the most recent revision.
Detecting a new version of a document¶
Different versions of a document are linked together via a shared persistent-id. Each version will have a unique policystat-id. You can detect a new version of a document that has completed an approval cycle by noticing that the persistent-id is the same as a document you retrieved in a previous version of the feed, but the policystat-id has changed.
For example, in January you might have gotten a version of the feed that looks like this:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:p="https://your-site.pstatbeta.com/" xml:lang="en-us">
<link href="https://your-site.pstatbeta.com/collaboration/feeds/latest/your-site/2685143/YZTxRGNuh2HPnKL7-V7PO5/" rel="self" type="application/rss+xml"></link>
<id>https://your-site.pstatbeta.com/?lt=clkqkpp9uDER8oa7L7opSy&next=/</id>
<updated>2017-1-30T20:02:42-05:00</updated>
<title>New/updated/archived policies</title>
<entry>
<title>Dress Code</title>
<updated>2016-12-15T17:45:05-05:00</updated>
<p:change-type>3 Changes</p:change-type>
<author>
<name>Doe, John: CEO</name>
<p:firstname>John</p:firstname>
<p:lastname>Doe</p:lastname>
<p:title>CEO</p:title>
</author>
<p:status>Active</p:status>
<category term="Human Resources"/>
<p:applicability name="Medical Office Building">
<p:site>MedicalOffice Building</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/654321/</id>
<p:persistent-id>567890</p:persistent-id>
<p:policystat-id>654321</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/654321/"></link>
<content type="html"><h2>PURPOSE</h2> <p>All employees are expected to have a professional appearance....</p>
</content>
</entry>
...
</feed>
In February, you get another version of the feed that looks like this:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:p="https://your-site.pstatbeta.com/" xml:lang="en-us">
<link href="https://your-site.pstatbeta.com/collaboration/feeds/latest/your-site/2685143/YZTxRGNuh2HPnKL7-V7PO5/" rel="self" type="application/rss+xml"></link>
<id>https://your-site.pstatbeta.com/?lt=clkqkpp9uDER8oa7L7opSy&next=/</id>
<updated>2017-2-30T20:02:42-05:00</updated>
<title>New/updated/archived policies</title>
<entry>
<title>Dress Code</title>
<updated>2016-12-15T17:45:05-05:00</updated>
<p:change-type>3 Changes</p:change-type>
<author>
<name>Doe, John: CEO</name>
<p:firstname>John</p:firstname>
<p:lastname>Doe</p:lastname>
<p:title>CEO</p:title>
</author>
<p:status>Active</p:status>
<category term="Human Resources"/>
<p:applicability name="Medical Office Building">
<p:site>MedicalOffice Building</p:site>
</p:applicability>
<id>https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/123456/</id>
<p:persistent-id>567890</p:persistent-id>
<p:policystat-id>123456</p:policystat-id>
<link href="https://your-site.pstattraining.com/?lt==123qkgp9u4ER8oafL7opS&next=/policy/123456/"></link>
<content type="html"><h2>PURPOSE</h2> <p>All employees are expected to have a professional appearance....</p>
</content>
</entry>
...
</feed>
Notice that the two entries have the same persistent-id, but the policystat-id has changed since when the feed was retrieved in January.
This tells you that there is a new version of the document that was created since the last time the feed was generated in January. Because persistent-id is consistent across different versions of the same docuement, you can tell that this entry is referencing a different version of the same document from January.
The document with persistent-id 1354127 should therefore be updated to the new version and not duplicated as a new document.
Detecting a retired document¶
Sometimes, documents in PolicyStat are retired. Retired documents are removed without being replaced by a new version. You can detect that a document has been retired by looking at the status field in each feed entry.
If this field contains the value ‘Retired’, then this document has been retired.
If this field contains the value ‘Active’, then this document is active and can be found in PolicyStat.
Another way to determine that a document has been retired is to look at the entry’s content and check if it is empty.
Comments