Lenses¶
A lens is a named group of processor templates, owned by one organization. Every subscription names exactly one lens by its alias, and the lens decides how raw sensor data becomes the events that subscription receives. Manage your organization's lenses on the Lenses page (permission lenses:read to open it, lenses:write to create and edit, lenses:delete to delete).
Private and public lenses¶
A lens is private or public:
- A private lens can be used only by your own organization's app clients.
- A public lens can be used by app clients in any organization. Only your organization can edit it.
- Another organization's private lens is refused when someone subscribes through it, with the same answer as an alias that does not exist. The platform does not reveal which of the two it was.
Aliases are unique across every organization, so an alias always names at most one lens. The Lenses page lists only your own organization's lenses. To use another organization's public lens, you need its alias, for example to type into the Request Builder.
Only members holding lenses:make_public can create a public lens or change a lens's visibility. Without it, a new lens is always created private, and an existing lens shows its visibility as a badge with a sentence explaining what that means.
The lenses list¶
The list shows each lens's name, alias, visibility, templates, description and last update. A creation date column can be switched on with the column picker. Search matches a lens's name, alias, description or the names of the templates it holds. The list otherwise works like every other portal list: see Working with lists.
Click a row, or its trailing Open button, to open the lens.
Creating a lens¶
- Choose Create lens at the top of the page.
- Enter a Name and an Alias. The alias may use lowercase letters, digits, underscores and dashes, and must start and end with a letter or digit. If the alias is already taken, anywhere on the platform, the dialog says so under the Alias field.
- Optionally add a Description, and tick Public lens if you hold the permission to.
- Choose the processor templates the lens should hold (see below).
- Choose Create lens. The new lens appears at the top of the list, marked New.
The alias is what app developers use: lens_alias in the Application SDK, lensAlias in the API, or the Lens picker in the Request Builder.
Choosing templates¶
The Processor templates picker in the lens dialog has two sections: Your organization, then Published by other organizations. Your own templates can be public or private. Other organizations' templates appear only if they are public.
- Search as you type. The picker searches the server and loads more templates as you scroll, so every template you may add is reachable. Searching narrows what is shown, never what is selected.
- The count reads "n of m selected · k shown", so you can see how many are ticked even when a search hides some of them.
- A public lens holds only public templates. While Public lens is ticked, your organization's private templates stay in the list but can't be ticked, and each one explains why: publish the template, or keep the lens private, to include it. A lens that still holds a private template can't be made public.
- "no approved version yet" marks a template with no approved, active version. You can add it, but no subscription will use it until one of its versions is approved.
- Several templates may produce the same event type. Nothing refuses that. When a subscription is matched, the platform picks, for each sensor type, the smallest set of the lens's templates that covers the requested event types.
If a lens holds a template your organization can no longer add, the dialog warns that it is no longer available in this organization.
The lens dialog¶
Each lens has one dialog that both shows and edits it, as described in Opening a record.
- Without
lenses:writeyou see the lens's name, alias, description, templates and visibility as values, with Close. - With
lenses:writethe same fields are inputs and the template picker is shown. Save changes becomes available once something differs from what was saved, and closing with unsaved changes asks you to confirm first. - Delete lens sits at the foot of the dialog for members holding
lenses:delete.
Platform administrators manage every organization's lenses under System Admin → All Lenses, with the same fields and template picker.
Editing a lens that subscriptions use¶
A lens can be edited, made public or private, or deleted at any time, even while subscriptions use it. None of these changes is refused because subscriptions use it. Subscriptions are tied to the lens itself, not to its alias.
Saving does not change running subscriptions straight away. Every hour the platform re-checks each active subscription against its lens as the lens then stands, and sends the subscriber an updated control message when the subscription's coverage changed. See The hourly re-check.
| What you change | What subscriptions using the lens see |
|---|---|
| Add or remove templates | At the next re-check the subscription is matched again against the lens's current templates. A newly added template can then be picked and its processors started or reused. A removed template's processors stop serving the subscription, and a processor no other subscription uses is removed. |
| Rename the alias | Nothing changes for existing subscriptions. New subscriptions must use the new alias. |
| Make it public | Other organizations can subscribe through it straight away. |
| Make it private | Your own organization's subscriptions are unaffected. Other organizations' subscriptions stay active, but at the next re-check every event type becomes uncovered (LENS_NOT_ACCESSIBLE) and they stop receiving events. They recover by themselves at the first re-check after the lens is public again. |
| Delete it | See below. |
Deleting a lens¶
Open the lens and choose Delete lens, then type the lens's name to confirm. Deletion is permanent. The lens's processor templates are not affected.
- A public lens can be deleted only by someone who also holds
lenses:make_public. Without it, the button is disabled and says so. Making the lens private first is no way around this, because changing visibility needs the same permission. - Subscriptions that used the lens stay active, but from the next re-check every event type is uncovered (
LENS_NOT_ACCESSIBLE) and they stop receiving events for good. A new lens with the same alias is not connected to them, and a subscription cannot be pointed at a different lens. To keep receiving events through another lens, delete the subscription and subscribe again.
Coordinate before deleting a shared lens
Deleting a public lens also affects subscriptions in other organizations that use it. Tell anyone you shared the alias with before you delete it.