Articles in this section

RSS Data Feed Of Updated Documents

Avatar
Wes Winham
  • Updated

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&amp;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&amp;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&amp;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">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;The purpose of this policy is to describe the eligibility of overtime pay....&lt;/p&gt;&#10;</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&amp;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&amp;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&amp;next=/policy/0987654321/"></link>
    <content type="html">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;The purpose of this policy is to describe the eligibility of overtime pay.&lt;/p&gt;&#10;
    </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&amp;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&amp;next=/policy/654321/"></link>
    <content type="html">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;All employees are expected to have a professional appearance.&lt;/p&gt;&#10;
    </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&amp;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&amp;next=/policy/4321/"></link>
    <content type="html">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;All new employees must do this.&lt;/p&gt;&#10;
    </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&amp;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&amp;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&amp;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&amp;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&amp;next=/policy/654321/"></link>
    <content type="html">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;All employees are expected to have a professional appearance....&lt;/p&gt;&#10;
    </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&amp;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&amp;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&amp;next=/policy/123456/"></link>
    <content type="html">&lt;h2&gt;PURPOSE&lt;/h2&gt;&#10;&lt;p&gt;All employees are expected to have a professional appearance....&lt;/p&gt;&#10;
    </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.

Related articles

Comments

0 comments

Please sign in to leave a comment.