Skip to Content

Changes for page How-To: Site Licenses

Last modified by Admin User on 2026/09/01 16:47
From version 8.1
edited by Admin User
on 2026/09/01 16:47
Change comment: There is no comment for this version
To 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].

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,0 @@
1 -How-To: Site Licenses
Content
... ... @@ -1,165 +1,0 @@
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,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -75.9 KB
Content
fulfillment-site-licenses_4a8d67282ca4569a.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -80.7 KB
Content
fulfillment-site-licenses_737296447e02486d.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -107.2 KB
Content
fulfillment-site-licenses_8e8e80905336a638.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -97.6 KB
Content