THE PRK ADMIN APP AND THE OFFLINE CHANGE CYCLE ============================================== Parish Record Keeper members can use their phone to search the parish database WITHOUT a network connection, and record changes in the field that are later imported into the Parish Record Keeper application. The app that does this is called PRK ADMIN. THERE ARE TWO APPS, AND MOST PEOPLE NEED ONLY ONE OF THEM: - PRK ADMIN is this one: the parish team's app, for people who have their own member account at parishrecordkeeper.com. It holds everything - the whole register, the finances, the change notes, and the transport booking page as well. - PRK FINANCE is for the people who serve the parish WITHOUT having an account here: treasurers, church council members, section leaders, outstation committees and the catechists who take seat bookings. They sign in with one of the parish's shared usernames instead. It shows the MONEY only - contributions, account ledger, area sheet, balance sheet, and transport booking for a phone that switches it on. THE PARISH REGISTER IS NOT IN IT: no church records, no baptism book, and those records are not even sent to such a phone. It is described in "Sharing parish figures - reports logins". PRK Admin carries everything PRK Finance carries - the same money views, the same booking page - and the register besides, so nobody on the parish team needs both. If both are installed on one phone they do not disturb each other: each keeps its own sign-in, and signing into one never signs the other out. WHAT YOU NEED ------------- - A phone with a modern browser (Chrome, Firefox, Safari). - A member login at parishrecordkeeper.com. - One online visit to set everything up. PART 1 - SETTING UP THE PHONE (once, while online) -------------------------------------------------- 1. On the phone, log in at parishrecordkeeper.com. The workspace page opens; tap "PRK app" in the menu at the top. (Old bookmarks to the members page still work - they lead to the same place.) 2. Open the "Data" tab and tap "Download / refresh offline copy". The phone now holds a copy of the church records, the baptism book, the contribution accounts and the individual ledger. 3. Optional but recommended: set a PIN on the same tab. Anyone who picks up the phone then needs the PIN to open the parish data. 4. Install it like a normal app: - Android (Chrome): menu (three dots) -> "Add to Home screen" (sometimes shown as "Install app"). - iPhone (Safari): Share button -> "Add to Home Screen". A "PRK Admin" icon appears on the home screen (blue - PRK Finance is purple, so the two are told apart at a glance). From now on, tapping the icon opens the app DIRECTLY - no network, no login, no browser address bar. The app and its data live on the phone; being online is only needed to download or refresh the offline copy (and, when online and logged in, the app quietly picks up program updates for the next start). Refresh the offline copy whenever you are online again - after each new upload of the database, the copy on the phone is outdated. If the download says you are not logged in - the login on the website expires after a while - tap "Log in at parishrecordkeeper.com" on the Data tab. After the login the app comes back by itself and starts the download. PART 2 - USING THE APP OFFLINE ------------------------------ - The tabs across the top are Church, Baptism, Contri-butions, Account ledger, Area sheet, Balance sheet, Changes and Data. They are the same views as the online search page, and the same views the parish office uses on its own computer. "Finances" shows one person's transactions like the online financial record. - Church records / Baptism book / Contributions work like the online search page: same filters, same results. - "Use extended name search" also finds synonymous spellings (e.g. Peter / Petro / Petulo), using the same synonymous-names table as the Parish Record Keeper application. - The figures are always "as of the last download" - the status line at the top shows the date. Searching ALWAYS uses the offline copy on the phone, even when the phone is online; the network is only needed to download or refresh the copy (Data tab). EDITING (change notes): - "Edit" on a search result lets you correct fields of a church record or baptism entry. - "+ Contribution" records a contribution for a person (account, amount, date, for-year). - "+ New person" and "+ New baptism entry" record new records. IMPORTANT: nothing is changed in any database yet! Every edit is stored as a CHANGE NOTE on the phone (see the "Changes" tab). The search results show your pending corrections, but they only become real when they are imported into the Parish Record Keeper application on the computer (Part 3). PART 3 - GETTING THE CHANGES INTO PARISH RECORD KEEPER ------------------------------------------------------ THE SHORT WAY (parish with a workspace on parishrecordkeeper.com): 1. On the phone, open the "Changes" tab and tap "Send to the parish computer". This needs network and a login; the notes then wait on the server until the computer fetches them - no WhatsApp, no e-mail, no cable. If the login has expired, the app says so and offers the login page; the notes are sent by themselves once you are back. 2. On the computer, open the SERVER ACTIONS window in Parish Record Keeper. Its lower half, "Change notes from the phones", lists everything the phones have sent: how many notes, when, from whom, and how old the phone's copy of the data was. 3. Choose a file and press "IMPORT THE SELECTED CHANGE NOTES". A change file carries the identity of the parish it was made for, and the program refuses outright to import one belonging to a different parish - which matters most to anyone who looks after several parishes and has more than one change file on the same computer. Older files, made before this identity was included, cannot be checked automatically; for those the confirmation shows the parish named in the file next to the parish of the datafile now open, so a mismatch can be seen before anything is applied. This is open to every member of the workspace, not only the administrator. THE OLD WAY (no network on the phone, or no workspace at all): 1. On the phone's "Changes" tab tap "Export change file (_PRKCHG.txt)", or "Share..." to send it by WhatsApp / e-mail. 2. Bring the file to the computer (e-mail, WhatsApp, USB cable - any way you like). 3. In the Server Actions window press "IMPORT A CHANGE FILE FROM THIS COMPUTER" and pick the file. This button needs no server and no sign-in, so it works for a parish that does not use the server at all; such a parish is asked about a waiting change file automatically when Server Actions cannot open. (Technical alternative: press Ctrl+G, type importOfflineChanges and press Enter.) EITHER WAY, THE REVIEW IS THE SAME: 4. Every change note is shown to you in its own window: APPLY THIS CHANGE = write it into the datafile SKIP THIS CHANGE = leave it and go on to the next STOP THE IMPORT = stop here A value the phone sent can be corrected before it is applied: click the line, edit it, press "TAKE THE CORRECTED VALUE". The correction holds for this import only - nothing on the phone changes. The fields that say which record the note belongs to cannot be edited. The window warns you when the database value changed since the phone downloaded its copy ("ATTENTION: the database now holds ..."), when this exact note was ALREADY IMPORTED on this computer (with the date), and when a change looks like a duplicate - a person of the same name, or the same contribution already booked. All of these only inform; you decide. 5. A report file (_result.txt) is written next to the change file - in the Exports folder for a file that came from the server - listing what was applied, skipped or failed. 6. A file taken in from the server disappears from the list once the import has run to the end, so nobody imports the same edits twice. An import you STOPPED half way stays on the server and can be taken again later. "REMOVE FROM THE SERVER" throws a file away WITHOUT importing it, and then its notes are lost - a member may do that only for what they sent themselves, an administrator for anybody's. A note is not used up by being sent: it stays on the phone, and goes out again with every send, until it is deleted there ("Delete exported notes"). That is deliberate - the phone cannot know whether a file ever arrived - and it is why the computer keeps track of what it has already applied and warns instead of entering it twice. The changes are applied through the application's own machinery: edits go through the same code as typing in the forms (with the same logging and edit-time stamps), new persons get their personID and card the normal way, and contributions are booked like entries in the individual ledger. PART 4 - CLOSING THE CIRCLE --------------------------- After importing the changes: 1. Send the database up again: "UPLOAD THE DATABASE FOR ONLINE SEARCH" in the Server Actions window, which makes the export for you (or, from a browser, the workspace page - see UploadingToTheServer.txt). 2. On the phone, open PRK Admin while online and tap "Download / refresh offline copy". The phone now shows the corrected data, and the applied change notes can be deleted ("Delete exported notes" on the Changes tab). LONG STAYS WITHOUT NETWORK -------------------------- The app is built to stay available indefinitely without internet: nothing on the phone expires or deletes itself, and the app asks the browser to protect its storage from automatic cleanup (the Data tab shows "Storage is protected" once granted). For long visits outside network coverage observe these rules: - Set the app up properly BEFORE leaving: open it once online, download the offline copy, add the icon to the home screen, and check the Data tab says "Storage is protected". - Android with Chrome is the most dependable platform. On iPhone the app MUST be used from the home-screen icon (data of plain Safari tabs can be deleted by iOS after ~7 days of not using the site; home-screen apps are exempt). - Never "clear browsing data" / "free up space" for the browser while in the field - that deletes the offline copy AND any change notes that were not yet exported. - The "over 30 days old" notice is only a reminder that the data is getting stale; the app keeps working regardless. - If a PIN is set, do not forget it: there is no recovery in the field (removing the app data unlocks it but deletes the notes). SETUP ON THE COMPUTER --------------------- Nothing has to be set up any more: both ways of importing live on the Server Actions window, which every installation has. (Up to August 2026 the import sat on a Control Panel button added by running AddOfflineChangeImportButton once; that button is gone, and the Immediate-window call importOfflineChanges still does the same as "IMPORT A CHANGE FILE FROM THIS COMPUTER".) Sending from the phone to the parish's workspace additionally needs a workspace on parishrecordkeeper.com for this datafile, and the server must have had sql/19_workspace_changes.sql run on it. Without a workspace the old way keeps working unchanged. NOTES FOR THE ADMINISTRATOR --------------------------- - The offline copy on the phone is NOT encrypted; it relies on the phone's own screen lock plus the optional PIN of the app. Do not put the offline copy on phones that are shared with people who should not see the parish data. - The change file (_PRKCHG.txt) contains plain-text parish data. Delete it after the import. A file sent through the server is kept in the Exports folder with its report, as the record of what came off which phone; the copy on the server is removed the moment the computer reports the import. - The server's own limits on waiting change files are noted under "NOTES FOR THE ADMINISTRATOR" in ServerActions.txt. - Several phones can record changes independently; import the files one after the other. Conflicting edits are caught by the "ATTENTION: the database now holds ..." warning during review. APPENDIX - THE TECHNICAL SIDE: WHERE THE DATA SITS ON THE PHONE --------------------------------------------------------------- This appendix is for administrators, and for anyone who has to answer the question "but where exactly is our parish data on that phone?". Nothing here has to be set up; it describes what the app does by itself. THE APP IS A WEB PAGE THAT WAS KEPT ----------------------------------- PRK Admin does not come from Google Play or from the App Store. It is a page of parishrecordkeeper.com that the phone's browser is allowed to KEEP, together with a small helper of its own (a "service worker") that hands the page back when there is no network. "Add to Home screen" only creates an icon that opens that kept page directly, without the browser's address bar around it. What follows from this: - There is no installation file to distribute: a phone is prepared by visiting the website once and logging in. - The app keeps itself up to date silently. Whenever the phone is online, the helper fetches a fresh copy of the page in the background, and the new version is used at the NEXT start. There is no app-store update to wait for and no version number to chase. - The whole app - program and data together - is a few megabytes. THE FOUR THINGS THAT ARE STORED ------------------------------- 1. THE PROGRAM. The page itself, its icons and its description file are held in the browser's CACHE STORAGE under the name "prk-offline-v2" (PRK Finance uses "prk-finance-v1"). It contains NO parish data at all - which is exactly why the app can still refresh itself on a phone whose website login expired months ago. 2. THE PARISH DATA - "the offline copy". One single object, exactly as it came from the server, kept in a browser database called INDEXEDDB. The database is named "prk_offline" and has two shelves ("object stores"): kv - the offline copy, under the key "snapshot", and the PIN journal - the change notes The offline copy holds the church records, the baptism book, the accounts, the ledger rows and the synonymous-names table AS THEY WERE AT THE MOMENT OF THE DOWNLOAD. A parish of a few thousand records comes to a few megabytes; the Data tab shows the actual figure ("Offline data on this phone: ... MB"). 3. THE CHANGE NOTES. Each note is one record on the "journal" shelf, numbered in the order it was made, and each carries an identity number of its own so that the computer can recognise a note it has already imported. A download never touches them: refreshing the offline copy replaces the data and leaves the notes untouched. 4. THE PIN. Not the PIN itself - only a one-way fingerprint of it, kept beside the data under the key "pinHash". The app can therefore test a PIN that is typed but can never reveal it, which is also why a forgotten PIN cannot be recovered. The PIN hides the data; it does NOT encrypt it. (PRK Finance additionally remembers one yes/no answer - whether this phone also takes transport bookings - in the browser's "local storage". That is a preference, not parish data.) WHERE THAT PHYSICALLY IS ON ANDROID ----------------------------------- Both stores belong to the WEBSITE, not to the icon: the browser keeps them inside its own private data folder, filed under the site's address. With Chrome the place has the shape /data/data/com.android.chrome/app_chrome/Default/IndexedDB/ https_parishrecordkeeper.com_0.indexeddb.leveldb/ with the kept program beside it under .../Service Worker/CacheStorage/. What lies there is a database of Google's own kind - a handful of working files, not one readable document. What matters in practice: - That folder is inside Chrome's private area. No file manager, no "My Files", no USB cable and no other app on the phone can reach it. There is nothing to copy off the phone and nothing to hand over. - It is Chrome's storage, not the icon's. Installing the icon does not move anything, and a copy downloaded in a Chrome tab is the same copy the icon opens. - Because it is Chrome's storage, "Clear browsing data", "Clear storage" in Chrome's app settings, and cleaner apps that promise to "free up space" DELETE IT - offline copy and unsent change notes together. This is by far the most common way a parish loses field work. - Another browser means another store: a copy downloaded in Chrome is not visible in Firefox, and uninstalling the browser takes the data with it. WHERE THAT PHYSICALLY IS ON IPHONE ---------------------------------- On iPhone the keeper is WebKit, the engine behind Safari and behind every home-screen web app. It keeps the same two things - a cache for the program, a database for the data - in the website-data area of its own sandbox, in a place of the shape .../Library/WebKit/WebsiteData/ (per website: IndexedDB, CacheStorage) As on Android, this cannot be reached from the Files app, from a computer over the cable, or from any other app on the phone. Two peculiarities of iPhone decide how the app has to be used there: - A HOME-SCREEN WEB APP IS ITS OWN WORLD. It does not share the login of a Safari tab, and its stored data should not be assumed to be the same data either. Therefore: put the icon on the home screen FIRST, then open the app FROM THE ICON, log in there, and make the first download there. Everything afterwards - searching, editing, sending - from the icon as well. A copy downloaded in a Safari tab may simply not be there when the icon is tapped. - IOS THROWS AWAY THE DATA OF SITES THAT ARE NOT USED. The stored data of a website that has not been visited for about seven days is deleted. Home-screen web apps are exempt from that rule - the second reason why the app must be used from the icon and never from a browser tab. PROTECTING THE STORAGE ---------------------- At every start the app asks the browser to mark its storage as PERSISTENT. Storage marked in this way is not among the things a browser quietly clears when the phone runs short of space. Chrome grants it silently to an app that sits on the home screen and is opened now and then. The Data tab reports the answer: "Storage is protected: the browser will not delete the offline data by itself." Check for that line before a long stay outside network coverage; if it is missing, install the icon and open the app a few times. It protects against the phone's own housekeeping only - it is no protection at all against a person who taps "clear browsing data". HOW THE DATA IS READ BACK ------------------------- When the icon is tapped: 1. The helper hands over the kept copy of the page at once - no network, no login. If the phone happens to be online, a fresh copy of the PROGRAM is fetched quietly in the background for the next start. 2. The page opens the "prk_offline" database and reads, in this order, the PIN fingerprint, the offline copy, and every change note - all of it into the phone's MEMORY. 3. If a PIN is set, the gate appears. The data is by then already in memory, but nothing is drawn until the PIN matches. 4. From then on every search, every list and every total is worked out inside the phone, over the copy in memory. There is no server to ask and no database engine underneath: the app filters the lists exactly as the desktop forms do. That is why the searches are instant, and why they work with the aeroplane mode switched on. 5. Change notes are laid OVER the copy while results are drawn, so a record shows the correction that was made in the field even though the parish database knows nothing of it yet. The stored copy itself is never altered by a note. Searching ALWAYS uses the copy on the phone, even when the phone is online. The network is used for exactly three things: fetching a fresh copy, sending the change notes, and keeping the program up to date in the background. WHAT LEAVES THE PHONE, AND HOW ------------------------------ - "Download / refresh offline copy" asks the server for the whole bundle again and replaces the stored copy in one go. The old copy is gone; the change notes survive. - "Send to the parish computer" builds the change file in memory and posts it to the parish workspace. The notes are marked as sent only after the server has confirmed that it stored the file, so a reply lost on a bad line can never be mistaken for a delivery. The notes themselves STAY on the phone until they are deleted there. - "Export change file" writes a real file - _PRKCHG__