PolicyStat Secure Daily Policy Export Configuration

Overview

PolicyStat can provide a nightly JSON/Daily Policy Export of your active policies.
You can use this export to:

• Populate an internal search system (e.g., SharePoint, an intranet, or a custom search tool)
• Keep an internal index of current policies in sync with PolicyStat

The JSON file:

• Is generated once per night
• Contains all active policy content for your PolicyStat site
• Is made available via a secure, authenticated endpoint

This document explains how to:

• Access the JSON export
• Authenticate requests
• Handle responses and errors
• Follow best practices for automation

How the Integration Works

1. Once enabled for your organization, PolicyStat generates a JSON export of active policies every night.
2. The file is stored securely and is not publicly accessible.
3. Your system calls a PolicyStat URL to request access to the latest export.
4. If the request is authenticated and allowed:
   • PolicyStat returns a short‑lived download URL in a small JSON response.
   • Your system then uses that URL to download the file directly.

Your application never needs to know where the file is physically stored; it only needs to:

• Call the integration endpoint
• Provide the shared token
• Download the file from the URL returned in the response

Endpoint

Use the following endpoint to request the latest JSON export:

GET https://{tenant}.policystat.com/json_integration/

• {tenant} is your PolicyStat site subdomain (for example: https://examplehospital.policystat.com/json_integration/).
• This endpoint does not generate the JSON on demand; it provides access to the most recent nightly export.

Authentication

Access to the JSON export is protected by a tenant‑specific shared token.

Request Header

Include the following header in every request:

X-Authentication-Token: <your_json_integration_token>

• The token is unique per PolicyStat tenant.
• It is generated and stored by PolicyStat and must be provided to you through your account configuration/onboarding process.
• Treat the token like a password: store it securely and do not expose it in client‑side code or public repositories.

If this token is missing or invalid, the request will be rejected.

Response

If your request is valid and the feature is enabled for your account, the endpoint returns a JSON object with a temporary download URL:

{ "url": "https://example.generated-download-url" }

Key details:

• The URL is short‑lived (expires in approximately 5 minutes).
• It is intended to be used immediately by your integration to download the nightly JSON file.
• The file is served with HTTP cache headers that prevent caching on intermediate proxies.

Typical Integration Flow

1. Your integration sends a GET request with the authentication header.
2. It receives a JSON response containing the url.
3. It extracts the url value.
4. It performs a second GET request to that URL to download the JSON file.
5. It processes the file (e.g., updates your internal search index).

HTTP Methods

• Only the GET method is supported for the /json_integration/ endpoint.
• Other HTTP methods (POST, PUT, DELETE, etc.) are not allowed and will return an error.

Error Handling

Your integration should be prepared to handle the following common error scenarios.

Note: Exact status codes and messages may vary slightly based on your configuration, but these are the typical conditions.

1. Missing or Invalid Token

When it happens:

• The X-Authentication-Token header is not provided, or
• The provided token does not match the token configured for your tenant.

What you’ll see:

• HTTP 403 (Forbidden)

What to do:

• Confirm you are including the header:

X-Authentication-Token: <your_json_integration_token>

• Verify the token value matches the one provided by PolicyStat, with no extra spaces or formatting changes.

2. Feature Not Enabled

When it happens:

• The JSON integration feature has not been enabled for your tenant.

What you’ll see:

• HTTP 403 (Forbidden)

What to do:

• Contact your PolicyStat representative or support team to verify that:
  • JSON export is enabled for your organization, and
  • A token has been created for your tenant.

3. No Token Configured

When it happens:

• JSON integration is enabled for your tenant, but no token has been configured yet.

What you’ll see:

• HTTP 403 (Forbidden)

What to do:

• Contact PolicyStat support to have a token created and shared with you.

4. Export File Not Available

When it happens:

• The nightly JSON export is not yet available (for example, the first run hasn’t completed or there was an issue generating the file).

What you’ll see:

• Typically an HTTP 403 or similar error indicating the file could not be retrieved.

What to do:

• If this is a new setup, wait until after the first scheduled nightly generation time and try again.
• If the issue persists, contact PolicyStat support with the approximate time and your tenant name.

5. Invalid HTTP Method

When it happens:

• You send a request using a method other than GET (e.g., POST, PUT, DELETE).

What you’ll see:

• HTTP 403 (Forbidden)

What to do:

• Ensure your integration uses only GET for the /json_integration/ endpoint.

Security & Best Practices

To keep your integration secure:

• Protect the token
  • Store it in a secure location (e.g., environment variables, secrets manager).
  • Do not commit it to source control.
  • Do not expose it in client‑side JavaScript or publicly accessible logs.
• Use server‑to‑server integration
  • Call the endpoint from backend/server processes only.
  • Avoid calling it directly from browsers or mobile apps.
• Handle time‑limited URLs correctly
  • Use the returned download URL promptly.
  • Do not store or reuse the URL long‑term; request a new one for each integration run.
• Schedule appropriately
  • Schedule your integration to run after your expected nightly export time window.
  • If you experience repeated failures, check logs on your side and contact support as needed.

Getting Help

If you encounter issues integrating with the JSON export:

• Confirm:
  • You’re using GET.
  • You’re calling https://{tenant}.policystat.com/json_integration/.
  • You’re including a valid X-Authentication-Token header.
• Provide to support, if needed:
  • Your tenant name (subdomain).
  • Approximate timestamp (including timezone) of the failing request.
  • HTTP status code you received.