Customer portal (eBOK) for an internet service provider: Skynet

What is eBOK and who did we build it for?

eBOK is an electronic customer service office: a site where subscribers handle their affairs without calling the operator. We built it for Skynet, an internet service provider. The portal runs in a browser, also on a phone, and talks to the operator’s system through its API.

Our part is the interface, the admin panel, the API integration and further releases. The brand and the content belong to the operator, who changes them in the panel.

The stack is React on the customer side, the operator’s REST API, and PHP with MySQL in the admin panel. Chatwoot, GenieACS (TR-069) and Redmine are used where the modules need them.

What can a customer do in the portal?

The things subscribers usually call the service office about, and a few that a phone call cannot do.

• Check the balance and invoices: amount due or overpayment, PDF preview and download, a QR code for the transfer, and reporting an invoice problem in one click.
• Read and accept documents: contracts, annexes and protocols with a preview, accepted with an SMS code.
• See the active TV package.
• Join the “Testuj Prędkość” (Test Your Speed) promotion: activation, a daily test result upload, and a clear message when a result does not pass.
• Measure the connection speed and send the result to the service office.
• Plan the home WiFi network in the planner (a separate case study).
• Order an equipment return: the portal issues a return number and the customer pastes it on the carrier’s site.
• See outages and maintenance work in their area, and write to the service office with a ready-made request text.

How does the portal connect to the operator’s system?

The customer portal talks to the operator’s REST API. Invoices, balance, documents, services and promotions come from there in real time. The portal changes only what the API lets a customer change: accepting a document, activating a promotion, uploading a result.

All communication sits in one layer (an adapter), so the screens know nothing about API details. Swapping the data source or moving to a new interface version does not mean rewriting the views.

• Tokens with refresh. The refresh token is single-use, so parallel requests wait for one shared refresh. A race between two requests can no longer invalidate a customer’s session.
• The API reports business errors with status 200 and the description in the body. The portal reads the body as well as the status code, so a rejected speed test never looks like a success.
• A missing endpoint or a status error does not break the screen. The promotion card just does not show.
• New API fields, such as the reason a promotion is blocked, work and stay compatible with the older backend.

How do we protect a customer’s account?

Login has two steps: the contract number and password, then a code sent by SMS or e-mail. At first login the portal forces a change of the starting password and ticks off the requirements as the customer types (length, upper and lower case, a digit, different from the starting password), rather than showing an error after submitting.

The admin panel has CSRF tokens, request limits on sensitive actions, an event log and parameterised queries. Customer data is held in the operator’s system, not in the portal.

What does the operator get?

An admin panel where staff change content without a developer: the offer, banners, questions and answers, announcements, service status, e-mail templates and the planner’s device catalogue. The service office phone number, e-mail address and the link to the promotion rules are settings, so changing them needs no rebuild of the portal.

• Customer requests and orders with preview and status change; optionally each one creates a task in Redmine.
• Outages and maintenance work with a map, statistics and lists of ongoing and completed items.
• Portal usage statistics.
• Two modules are built but switched off in the current release: live chat (Chatwoot, split into departments, working hours with public holidays) and remote router management (TR-069, GenieACS). A flag in the portal’s code turns them on when the operator decides.

How do we keep release quality up?

Every release gets a change list, a table of checks performed and a separate list of things we could not verify. The operator knows what to look at after deployment and does not have to assume everything was tested.

Three examples from the release notes:

• An overpayment never showed up. A regular expression removed the letter “s” instead of a space, so every balance with a unit produced an error. We rewrote it without a regular expression and checked it against twelve amount formats.
• The document preview on a phone in landscape showed a dead button, because a browser rotated to 844 px was treated as a desktop. The criterion is now device size, which does not change on rotation, so a customer can always open or download a document before accepting it.
• An API outage looked like an open-ended contract. The “Contract end” field now has three states: a date, indefinite term and no data. A server error shows as no data.