Utilities

Part of the IP4CMS portal. ← All module guides

What it's for — The Utilities module is where you set up and run utility metering for your tenant: water, electricity, gas or any other metered service. From here you define the kinds of utility you track (utility types), say which device types can measure each one (activation/device pairing), connect to the systems that supply meter readings (channels), and watch readings flow in (ingestion logs). Once a device is linked to a property and tagged with a utility type, the readings it produces become the member's utilities automatically.

Where to find it — Utilities lives under Settings. From the left navigation open Settings → Utilities. You'll see the catalog screens (Utility types and Activation) under Utilities, and the Channels screen at Settings → Utilities → Channels. Each channel has its own detail page with Configuration, Ingestion log and Remote files tabs.

Before you start

• Licence/module — Utilities must be enabled for your tenant. If the module isn't licensed the Utilities tabs won't appear in Settings (every Utilities settings tab requires the utilities module). If you don't see it, contact your administrator.
• Permissions — Each task needs its own permission (listed under each task below). Anyone with admin:full:access can do everything. The Devices module also needs to be enabled for device pairing and for readings to attach to members.

Key tasks

Define utility types

A utility type is a category of metered service — for example Water, Electricity or Gas. It's the foundation everything else hangs off.

To add one:

1. Go to Settings → Utilities and open the Utility types tab.
2. Click Add utility type.
3. Fill in the form:

• Code (required) — a short uppercase identifier, e.g. WATER. Letters, numbers and underscores only. The code can't be changed once saved, so pick carefully.
• Name (required) — the human-friendly label, e.g. Water.
• Description (optional) — a note about what this type represents.
• Identifier schema (JSON) (optional) — an advanced field that describes how readings for this type are identified (e.g. by meter ID or premise code). Leave it blank unless you've been given a schema. It must be valid JSON, e.g. { "fields": [{ "key": "meter_id", "label": "Meter ID" }] }.
• Display order — controls where the type appears in lists (lower numbers first).
• Active — untick to retire a type without deleting it. Inactive types are hidden from the activation matrix.

1. Click Create type (or Save changes when editing).

Permissions: utilities:types:read to view, utilities:types:create to add, utilities:types:update to edit.

Set device activation / pairing

The Activation screen is a matrix that says which device types are allowed to measure which utility type. A "utility device pair" simply links a utility type to a device type so that those devices can be used for that utility.

1. Go to Settings → Utilities and open the Activation tab.
2. You'll see a row per active utility type, each showing the device types currently linked to it.
3. Click a utility type's row (or its link/edit control) to open the link dialog.
4. Tick the device types that should be allowed for this utility, untick any that shouldn't.
5. Click Save — the portal applies only the changes you made and confirms "Utility device links updated".

The Activation screen needs the Devices module enabled. If Devices is off you'll still see your utility types listed, but there are no device types to pair with.

Permissions: utilities:activation:read to view, utilities:activation:write to change pairings.

Set up utility channels

A channel is a connection to an external source that supplies meter readings — for example an SFTP drop where a meter vendor leaves reading files. Each channel uses a handler (the integration type) that knows how to talk to that source.

1. Go to Settings → Utilities → Channels.
2. Click Add channel (or open an existing one and Edit).
3. Fill in the base fields:

• Code (required) — uppercase identifier (letters/numbers/underscore), e.g. VENDOR_SFTP. Can't be changed after creation.
• Name (required) — friendly label.
• Handler (required) — pick the integration type. The handler can't be changed once the channel is created — choose carefully. Selecting a handler reveals its own configuration fields.
• Active — whether the channel is enabled.
• Production — mark whether this is a live (production) connection or a test one.
• Display order — list ordering.

1. Complete the handler-specific configuration fields that appear below (these vary by handler — e.g. host, username, password, folder paths). Required fields are marked, secret fields like passwords are masked. Some fields only appear depending on other choices.
2. Click Create channel / Save changes.

The channels list shows each channel's name, code, handler, status and Last pull time. Click a channel to open its detail page.

Pulling readings: For handlers that fetch reading files, a Pull now action is available (on the list row and on the channel detail). Clicking it fetches and processes new files immediately and reports how many files and rows were inserted. Channels that support pulling are also pulled automatically on a schedule — Pull now is for when you don't want to wait.

Channel detail tabs:

• Configuration — view/edit the channel settings.
• Ingestion log — every file this channel has processed (see below).
• Remote files — for pull-capable handlers, lists the files visible on the remote source, their processing status, and the last successful pull time. You can pull from here too.

Permissions: utilities:channels:read to view, utilities:channels:write to add/edit/pull, utilities:channels:delete to delete. Deleting a channel asks for confirmation and cannot be undone.

Review ingestion logs and readings

The ingestion log records every reading file that was processed, what happened to it, and the outcome of each row.

1. Open a channel and go to its Ingestion log tab (or the ingestion-log list).
2. Filter the list by:

• Channel — restrict to one channel.
• Status — tick any of Pending, Processing, Completed, Failed, Partial, Skipped.
• From / To dates.

Click Apply filters (or Clear filters to reset).

1. The grid shows, per file: Channel, File, Status, Total / Inserted / Failed row counts, and Started / Completed times.
2. Click a row to open the detail dialog. It shows the source, file name, file size, remote path, file hash, error message (if any), and a Row details table — one line per CSV row ingested, with its outcome, meter number, register, reading timestamp, value, link status and any error.

This is your main troubleshooting tool: a Failed or Partial status, or rows with an error outcome, tell you which readings didn't make it in and why.

Older logs may show "Reconstructed from stored meter readings (legacy log)" and may lack per-row detail. Re-pulling the file captures full row-level outcomes.

Permissions: utilities:ingestion_log:read.

How utilities link to members

There is no manual "link utility to member" step. A utility becomes a member's utility automatically:

• A device that has been tagged with a utility type is a utility.
• A member sees that utility at any property location they have an approved property claim on.

So when a metered device is installed at a property and that property is claimed/approved by a member, the member's utilities list (in the resident app) is derived from those devices. Readings ingested for that device's meter then belong to the member. Admins can view a member's utility links read-only via the member's record (permission utilities:links:read); members see and act on their own.

How the data connects (devices, members, usage billing)

The pieces fit together in a chain:

1. Utility type (e.g. Electricity) defines the category.
2. Activation says which device types are allowed to measure that utility type.
3. A device instance is installed at a property location and tagged with a utility type — that device now represents a real utility.
4. A channel connects to the meter-data source and ingests reading files. Each row is matched to a meter and stored as a reading.
5. A member with an approved claim on that property location automatically sees the device's utility and its readings.
6. Stored meter readings provide the consumption data that downstream usage billing / settlement processes use to bill members for what they consumed.

In short: types and activation are the catalog; channels and ingestion are the data pipe; devices + property claims are what tie readings to people; readings feed billing.

Permissions & access

• admin:full:access grants all of the above.
• The whole module requires the utilities licence/module to be enabled; Devices must also be enabled for pairing and member linking to work.
• Each screen hides actions you don't have rights for — e.g. without utilities:channels:write the Add channel, Edit and Pull now controls won't appear.

Tips & gotchas

• Codes are permanent. The Code on a utility type and the Code and Handler on a channel can't be changed after saving. Get them right the first time, or create a new record.
• Deactivate instead of delete. Untick Active to retire a utility type or channel without losing history. Channel deletion is permanent and confirmed.
• No member-linking screen. Don't look for a "link utility to member" button — links come from devices + approved property claims. If a member can't see a utility, check that the device is tagged with a utility type and that the member's property claim is approved.
• Pull now vs. schedule. Pull-capable channels are pulled automatically; Pull now just triggers an immediate run. Use it after fixing a channel's configuration to confirm files come through.
• Read the ingestion log for failures. A Failed/Partial file, or red row outcomes in the detail dialog, pinpoint exactly which readings were rejected and the error — start there when consumption looks wrong.
• Identifier schema is optional and advanced. Leave the JSON field blank unless you've been given a specific schema; it must be valid JSON.
• Activation needs Devices. If the Activation matrix shows utility types but no device columns, the Devices module is likely disabled.
• Secrets stay masked. Channel password/secret fields are hidden in the form; the latest stored values are loaded when you reopen a channel to edit.