Skip to Content

Changes for page How-To: Site Licenses

Last modified by Admin User on 2026/09/01 16:47
From version 1.1
edited by Admin User
on 2026/09/01 16:46
Change comment: Changed document syntax from [XWiki 2.1] to [xwiki/2.1].
To version 8.1
edited by Admin User
on 2026/09/01 16:47
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +How-To: Site Licenses
Content
... ... @@ -1,0 +1,165 @@
1 += 1. Overview =
2 +
3 +Site licenses provide IP-based concurrent access for institutions such as libraries, universities, and corporate offices. An institution purchases a license for N concurrent seats, and anyone accessing gated content from the institution’s IP range gets transparent access — no login required, no forms to fill out — up to the concurrent seat limit.
4 +
5 +Key characteristics:
6 +
7 +* Access is determined by IP address, not by individual user accounts
8 +* Concurrent sessions are limited to the purchased seat count
9 +* Sessions are maintained by a heartbeat mechanism — if a user leaves, their seat is automatically released after a configurable timeout (default: 30 minutes)
10 +* When all seats are occupied, new visitors see a branded “seats full” message
11 +* Each seat is represented by a synthetic OCID for reporting purposes
12 +
13 +[[image:fulfillment-site-licenses_386f6176b5b0bbbe.png||height="430" width="586"]]
14 +
15 +//The Site Licenses list showing three demo institutions with concurrent seat counts and statuses.//
16 +
17 +In this example, Springfield Public Library has 15 concurrent seats (active), Metro University has 50 seats (active), and Horizon Aviation Museum is a cancelled license with 5 seats.
18 +
19 += 2. How Site Licenses Work =
20 +
21 +== 2.1 Access Flow ==
22 +
23 +When a visitor accesses a page with gated content, the following happens:
24 +
25 +* 1. The ONEcount widget (oc.min.js) loads and sends an access check request
26 +* 2. The gating layer checks the visitor’s IP against all active site license IP ranges
27 +* 3. If a match is found, the system checks for available concurrent seats
28 +* 4. If a seat is available, the visitor is silently assigned a synthetic identity and granted access
29 +* 5. The widget starts a heartbeat timer to keep the session alive
30 +* 6. When the visitor leaves (closes browser, navigates away), the seat is released
31 +
32 +== 2.2 Synthetic Identities ==
33 +
34 +Each concurrent seat maps to a pre-created synthetic user in the ONEcount database. These users have names like “Springfield Library, Seat 1” and internal email addresses like “sl-42-seat-1@sitelicense.internal.” They have real subscription records, which means they appear naturally in all standard reports.
35 +
36 +//Synthetic users are created automatically when the site license is created. You do not need to create them manually.//
37 +
38 +== 2.3 Session Lifecycle ==
39 +
40 +Sessions are tracked in Cassandra with a Time-To-Live (TTL). The TTL is set to the session_ttl value on the license (default: 1800 seconds / 30 minutes). Every heartbeat from the widget resets this TTL, keeping the session alive. If no heartbeat arrives within the TTL window, the session automatically expires and the seat becomes available.
41 +
42 +Additionally, when a user closes the browser tab or navigates away, the widget attempts to release the seat immediately using the browser’s sendBeacon API. This provides faster seat turnover in normal usage.
43 +
44 += 3. Creating a Site License =
45 +
46 +Navigate to Fulfillment › Site Licenses. Click the red “Create Site License” button to open the creation modal.
47 +
48 +[[image:fulfillment-site-licenses_8e8e80905336a638.png||height="411" width="586"]]
49 +
50 +//The Create Site License modal with institution name, seat count, product-or-package selection, and initial IP range.//
51 +
52 +|**Field**|**Required**|**Description**
53 +|**Institution name**|Yes|Display name (e.g., “Springfield Public Library”)
54 +|**Purchaser OCID**|Yes|The OCID of the billing contact at the institution
55 +|**Concurrent seats**|Yes|Maximum number of simultaneous users
56 +|**Product or Package**|Yes|Select a product or package from the dropdown (grouped by type)
57 +|**Term**|Yes|Select the term — cascades from the selected product or package
58 +|**Publication**|No|The fulfillment publication (for magazine content)
59 +|**Start date**|Yes|When the license becomes active
60 +|**End date**|No|When the license expires (empty = perpetual)
61 +|**IP range (CIDR)**|No|Initial IP range in CIDR notation. More can be added after creation.
62 +
63 +When you create the license, the system automatically:
64 +
65 +* Creates N synthetic users named “[Institution], Seat 1” through “[Institution], Seat N”
66 +* Creates subscription records for each synthetic user
67 +* Grants product access (user_product entries) so the gating layer recognizes them
68 +
69 += 4. Managing IP Ranges =
70 +
71 +Each site license can have multiple IP ranges. Ranges are specified in CIDR notation:
72 +
73 +|**Format**|**Example**|**Matches**
74 +|**Single IP**|192.168.1.100|Exactly one IP address
75 +|**Subnet /24**|192.168.1.0/24|192.168.1.0 through 192.168.1.255 (256 addresses)
76 +|**Subnet /16**|10.0.0.0/16|10.0.0.0 through 10.0.255.255 (65,536 addresses)
77 +|**Larger subnet**|172.16.0.0/12|172.16.0.0 through 172.31.255.255
78 +
79 +[[image:fulfillment-site-licenses_4a8d67282ca4569a.png||height="430" width="586"]]
80 +
81 +//Springfield Public Library detail page showing IP ranges (Main branch /24, Eastside annex /28), active sessions, and synthetic seats.//
82 +
83 +In this example, Springfield Public Library has two IP ranges configured: 198.51.100.0/24 for the main branch (256 addresses) and 198.51.101.0/28 for the Eastside annex (16 addresses). Each range shows the computed start and end IP and an optional label.
84 +
85 +IP ranges are managed from the site license detail page. Click the “+ Add” button to add a new range, or the × button to remove an existing one.
86 +
87 +//If an IP matches multiple site licenses, the system uses the most specific match (narrowest IP range).//
88 +
89 += 5. Session Management =
90 +
91 +== 5.1 Heartbeat Configuration ==
92 +
93 +The detail page header shows the heartbeat and session TTL values for the license. In the Springfield Public Library example:
94 +
95 +* Heartbeat interval: 120 seconds — the widget pings every 2 minutes
96 +* Session TTL: 1800 seconds (30 minutes) — sessions expire after 30 minutes without a heartbeat
97 +
98 +|**Parameter**|**Default**|**Description**
99 +|**heartbeat_interval**|120 seconds|How often the widget pings to keep the session alive
100 +|**session_ttl**|1800 seconds (30 min)|How long a session persists without a heartbeat before auto-expiry
101 +
102 +These values are set per-license and can be adjusted based on the institution’s needs. A shorter session_ttl frees seats faster but may cause disruptions for slow readers. A longer interval reduces server load but delays seat release for idle users.
103 +
104 +== 5.2 Seats Full Message ==
105 +
106 +When all concurrent seats are occupied, new visitors see a full-screen overlay with a customizable message. The default message is:
107 +
108 +“//All N seats for [Institution Name] are currently in use. Please try again later.”//
109 +
110 +You can customize this message per-license via the seats_full_message field. The page auto-retries every 30 seconds.
111 +
112 += 6. The User Experience =
113 +
114 +The site license experience is designed to be completely transparent to the end user:
115 +
116 +* No login form is displayed
117 +* No registration is required
118 +* No ONEcount branding is shown
119 +* Content loads normally as if it were unprotected
120 +* The only user-visible moment is when seats are full — a branded overlay appears
121 +
122 +Behind the scenes, the widget sets session cookies (~_~_oc_sl_session, ~_~_oc_sl_id, ~_~_oc_sl_hb) to maintain the session. These are automatically managed and do not require user interaction.
123 +
124 += 7. Monitoring Active Sessions =
125 +
126 +The site license detail page shows active sessions in real-time (visible in the “Active Sessions” card). For each session, you can see:
127 +
128 +* Seat number
129 +* Synthetic OCID
130 +* Visitor’s IP address
131 +* Session start time
132 +* Last heartbeat time
133 +
134 +You can force-release a session from this page if needed (e.g., if a session appears stuck). Click the “Release” button next to the session. The “Refresh” button updates the session list.
135 +
136 += 8. Reporting =
137 +
138 +Site license seats are represented by synthetic OCIDs with real subscriptions. They flow through all standard fulfillment reports:
139 +
140 +* RPT-01 (Circulation) — Synthetic OCIDs are counted in their classification bucket
141 +* RPT-09 (Adds & Removals) — Reason codes SITE_LICENSE_NEW, SITE_LICENSE_EXPIRED, SITE_LICENSE_CANCELLED track lifecycle events
142 +* RPT-19 (Mail File) — Site license seats typically do not receive mail (no physical address), but they appear in the serve log for audit purposes
143 +
144 +The subscription_source field on the serve log is tagged as “site_license” for these OCIDs, enabling easy filtering in custom reports.
145 +
146 += 9. Troubleshooting =
147 +
148 +|**Symptom**|**Likely Cause**|**Resolution**
149 +|**Users see login form instead of transparent access**|IP range not configured or doesn’t match the visitor’s IP|Check the IP ranges on the license detail page. Verify the visitor’s public IP matches a configured range.
150 +|**Seats fill up faster than expected**|session_ttl too long; idle sessions holding seats|Reduce session_ttl (e.g., to 900 seconds / 15 min)
151 +|**Sessions don’t release when users leave**|Browser doesn’t support sendBeacon or blocks it|Normal — sessions will auto-expire after session_ttl. Consider reducing the TTL.
152 +|“**Seats full” when seats should be available**|Stale sessions in Cassandra|Force-release sessions from the admin detail page. Sessions also auto-expire.
153 +|**Synthetic users not appearing in reports**|Migration not applied|Apply fulfillment/sql/034_site_license.sql and fulfillment/cql/010_site_license_session.cql
154 +
155 += 10. Permissions =
156 +
157 +Site license management requires the FULFILLMENT_SITE_LICENSE_MANAGE permission module. Creating site licenses additionally requires FULFILLMENT_SETUP. Superadmin users automatically have access to all functions.
158 +
159 += Appendix: Navigation =
160 +
161 +All three subscription model features are accessible from the Fulfillment section of the admin sidebar:
162 +
163 +[[image:fulfillment-site-licenses_737296447e02486d.png||height="430" width="586"]]
164 +
165 +//The Fulfillment sidebar menu showing Gift Subscriptions, Group Licenses, and Site Licenses navigation entries.//
fulfillment-site-licenses_386f6176b5b0bbbe.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.admin
Size
... ... @@ -1,0 +1,1 @@
1 +75.9 KB
Content
fulfillment-site-licenses_4a8d67282ca4569a.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.admin
Size
... ... @@ -1,0 +1,1 @@
1 +80.7 KB
Content
fulfillment-site-licenses_737296447e02486d.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.admin
Size
... ... @@ -1,0 +1,1 @@
1 +107.2 KB
Content
fulfillment-site-licenses_8e8e80905336a638.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.admin
Size
... ... @@ -1,0 +1,1 @@
1 +97.6 KB
Content