bassgPushy

Overview

This pod helps to integrate Pushy mobile notifications with SkySpark. It delivers Sparks and Arc Notes as push notifications to iOS/Android devices and provides device registration, topic creation/subscription, consoles, and history.

Supported Platforms

• iOS (Pushy SDK)
• Android (Pushy SDK)
• Pushy REST API

Configure Pushy Account

You will need a Pushy account and API key. Obtain an API key from your Pushy dashboard and keep it secure. Do not commit secrets to source.

Configure SkySpark (bassgPushy)

Provide API key

In code, PushyClient is initialized with a base URL and API key. Replace the API key with yours and rebuild/publish the pod as needed.

- Location                : `fan/BassgPushyLib.fan`
- Client initialization   : `PushyClient("https://api.pushy.me", "<YOUR_PUSHY_API_KEY>")`
- Security                : Use secure config/secrets management in production

Application views

After installation, an app named "Pushy Class" appears with views for company management, Spark/Arc notify classes, consoles, device management, subscriptions, and history.

- App name                : `Pushy Class`
- Views                   : `Spark Notify Classes`, `Arc Notes Notify Classes`, `Sparks Console`, `Arc Note Console`, `Device Management`, `Subscription Management`, `Notification History`, `Company Management`
- Source                  : `lib/views/*.trio`

Create notify classes

Define which Sparks/Arc Notes should generate notifications. Creating these records also sets up background jobs/tasks.

- Create Spark notify     : `createNewNotifyRec(dis, sparkRuleRefs, siteRefs, companyRef)`
- Create Arc Note notify  : `createNewNotifyArcNotesRec(dis, siteRefs, companyRef)`
- Auto scheduler setup    : `createJobsAndTasks()`

Register devices

Register user devices with their Pushy device token.

- Register device         : `registerDevice("<device-token>", "John's iPhone", "john.doe", "ios")`
- Edit / Unregister       : `editDeviceAction`, `unregisterDevice(deviceToken)`
- List active devices     : `getActiveDevices()`

Create topic and subscribe

Create an encoded topic key for company/site/equip context and subscribe devices to receive notifications.

- Create topic            : `topic: createTopic([@siteRef], @companyRef, [@equipRef], "spark"|"arcNote")`
- Subscribe               : `subscribeDeviceToTopic("<device-token>", topic->dis)`
- Unsubscribe             : `unsubscribeDeviceFromTopic("<device-token>", topic->dis)`
- Encoding helper         : `escapePushyUriEncode(str, 100)`

Send notifications (manual)

You can also send notifications directly from Axon.

- Basic                   : `bassgSendNotification("<device-token>", "Spark Alert", "High temp at AHU-1")`
- With category/context   : `bassgSendNotificationWithCategory(to, title, data, "notification_actions", notificationId, equipName, equipType)`

Schedulers and Tasks

Background processing is handled by a job and a task. These are created automatically by createJobsAndTasks() and can be rebuilt using restartScheduler().

- Job                     : "Snooze Time Job" - runs every 1 minute (updates snooze and sends due notifications)
- Task                    : "Check Spark and arcNote Classes" - runs every 5 minutes (populates Spark/Arc Note consoles)

Troubleshooting

- Empty topic list        : Verify Pushy API key and internet access; check `PushyClient` logs
- No notifications        : Ensure device `subscriptions` contain the correct encoded topic; check `notificationSent` flags in consoles; verify schedulers
- Matching issues         : Always use keys produced by `escapePushyUriEncode`; site-level and equipment-level matches are supported

Axon functions (reference)

- Topics                  : `bassgTopics()`, `bassgSubscribers(topic)`
- Subscribe/Unsubscribe   : `bassgSubscribe(deviceToken, topics)`, `bassgUnsubscribe(deviceToken, topics)`
- Notifications           : `bassgSendNotification(...)`, `bassgSendNotificationWithCategory(...)`
- Admin                   : `createNewNotifyRec(...)`, `createNewNotifyArcNotesRec(...)`, `createJobsAndTasks()`, `restartScheduler()`
- Devices                 : `registerDevice(...)`, `unregisterDevice(...)`, `getActiveDevices()`, `getDevicesByUser(userId)`
- History/Console         : `getAllNotifications()`, `notificationsForDevice(deviceToken, span)`
- Snooze/Ack              : `snoozeNotification(id, mins)`, `unsnoozeNotification(id)`, `acknowledgeNotification(id, userId)`

License

Commercial - © Ankalabs Inc.

Versioning & Publishing

- Pod                     : `bassgPushy`
- SkyArc index            : `bassgPushy::BassgPushyExt`, `bassgPushy::BassgPushyLib`
- CI variables            : `StackhubUsername`, `StackhubPassword`, `RELEASE_STATUS`

Support

Contact your SkySpark administrator or vendor support.

bassgPushy delivers SkySpark Sparks and Arc Notes as push notifications to mobile devices. It includes device registration, topic creation/subscription, consoles and history views, plus Axon functions for full automation.

== Features

• Push notifications for Sparks and Arc Notes
• Device registry and management (iOS/Android)
• Topic creation and subscription (company/site/equip-aware)
• Snooze support and automatic dispatch
• Notification history and console views
• Axon API for automation and integrations

== Requirements

• SkySpark 3.x (aligned via SKYSPARK_VERSION at build time)
• Internet access (Pushy API: https://api.pushy.me)
• Pushy account and API key

Dependencies (auto-managed): sys, web, util, dom, domkit, afJson, sql, ui, connExt, axon, folio, skyarcd, skyarc, haystack (matched to your SkySpark version).

== Installation

1) Install from StackHub: add the bassgPushy pod to your project and restart SkyArc. 2) The app appears in the menu as "Pushy Class". 3) Provide your Pushy API key (see Configuration).

Note: This pod is "Commercial" licensed.

== Configuration

• Pushy API key: In the sample project it is configured in BassgPushyLib.fan via PushyClient("https://api.pushy.me", <API_KEY>). Replace with your own key and rebuild/publish the pod as needed.
  • Security tip: Don't hardcode secrets in production; use your organization's secure config/secrets management.
• Topic keys: Topic names are encoded via escapePushyUriEncode to ensure reliable client-side matching. Matching is also performed at site/equipment scope.
• Schedulers and tasks: Created automatically when you create notify classes; you can rebuild them using restartScheduler().

== App and Views

App name: "Pushy Class"

• Company Management: Create/delete company records
• Spark Notify Classes: Define Spark notify classes
• Arc Notes Notify Classes: Define Arc Note notify classes
• Sparks Console: Spark event records and state
• Arc Note Console: Arc Note event records and state
• Notification History: Unified notification history
• Device Management: Register/edit/delete devices
• Subscription Management: Pushy topics list and subscription helpers

Views are defined under lib/views/*.trio and wired to Axon functions via create/edit/delete actions.

== Typical Workflow

1) Add a company: Company Management > Create Rec (or addCompany("Acme")) 2) Create notify classes:

• Sparks: Spark Notify Classes > Create Rec (createNewNotifyRec)
• Arc Notes: Arc Notes Notify Classes > Create Rec (createNewNotifyArcNotesRec) These actions also set up schedulers (createJobsAndTasks). 3) Register devices: Device Management > Register Device (or registerDevice(...)) 4) Create a topic: Subscription Management > Create Rec (createTopic(siteRefs, companyRef, equipRefs, topicType)) – the result’s “dis” is the encoded topic key that devices must subscribe to. 5) Subscribe devices: subscribeDeviceToTopic(deviceToken, topicStr) or subscribe from the mobile client using the same key. 6) Automatic flow: "Check Spark and arcNote Classes" task (every 5 min) populates consoles; "Snooze Time Job" (every 1 min) sends notifications when due.

== Key Records

• bassgNotifyAlarmClass: Spark notify class
• bassgNotifyAlarmClassArcs: Arc Note notify class
• deviceRec: Registered devices (token, platform, subscriptions list)
• sparkConsole / arcNoteConsole: Event records with snooze/dispatch flags
• notificationHistory: Built by getAllNotifications() for the History view

== Axon Functions (selected)

Pushy API wrappers:

• bassgTopics(): List Pushy topics
• bassgSubscribers(topic): List subscribers for a topic
• bassgSubscribe(deviceToken, Str[] topics): Subscribe device to topics
• bassgUnsubscribe(deviceToken, Str[] topics): Unsubscribe device from topics
• bassgSendNotification(to, title, data): Send raw message
• bassgSendNotificationWithCategory(to, title, data, category, notificationId, equipName, equipType): Send with category/context

Administration & workflow:

• createNewNotifyRec(dis, sparkRuleRefs, siteRefs, companyRef)
• createNewNotifyArcNotesRec(dis, siteRefs, companyRef)
• registerDevice(deviceToken, deviceName, userId, platform) / unregisterDevice(deviceToken)
• getActiveDevices() / getDevicesByUser(userId)
• createJobsAndTasks() / restartScheduler()
• createTopic(siteRefs, companyRef, equipRefs, topicType)
• subscribeDeviceToTopic(deviceToken, topicStr) / unsubscribeDeviceFromTopic(deviceToken, topicStr)
• snoozeNotification(notificationId, minutes) / unsnoozeNotification(notificationId)
• acknowledgeNotification(notificationId, userId)
• notificationsForDevice(deviceToken, span)

Helper:

• escapePushyUriEncode(str, maxLength:100): Encode topic keys

Quick Examples

- Add a company:
	addCompany("Acme Corp")
- Create a Spark notify class (via UI or Axon):
	createNewNotifyRec("Spark Alerts", [@sparkRuleRef1, @sparkRuleRef2], [@siteRef], @companyRef)
- Register a device:
	registerDevice("<pushy-device-token>", "John's iPhone", "john.doe", "ios")
- Create a topic and subscribe a device:
	topic: createTopic([@siteRef], @companyRef, [@equipRef], "spark")
	subscribeDeviceToTopic("<pushy-device-token>", topic->dis)
- Send a manual notification:
	bassgSendNotification("<pushy-device-token>", "Spark Alert", "High temp at AHU-1")

== Schedulers and Tasks

• Job: "Snooze Time Job" - every 1 minute updates snooze progress and sends due notifications.
• Task: "Check Spark and arcNote Classes" - every 5 minutes scans for new Spark/Arc Note events and populates consoles.

Both are created by createJobsAndTasks(); use restartScheduler() to rebuild if needed.

== License

Commercial - © Ankalabs Inc.

== Versioning & Publishing

• Pod: bassgPushy
• SkyArc index: bassgPushy::BassgPushyExt (ext), bassgPushy::BassgPushyLib (lib)
• CI variables for StackHub publishing: StackhubUsername, StackhubPassword, RELEASE_STATUS