Integration: OpenFamily (open source family organization)

Hello,

I’m Quentin, I develop OpenFamily, an open-source, self-hosted family organizer (grocery list, tasks, calendar, weekly schedule, meals, budget), in French and seven other languages: GitHub - NexaFlowFrance/OpenFamily: The open-source, self-hosted family organizer. Keep full control of your family's data : run it on your own server. · GitHub

We already have integrations with Home Assistant, Nextcloud, Mealie, Grocy, and Immich, and I think Gladys and OpenFamily complement each other well: you manage the home, we manage the family life that takes place there. I read the spec for external integrations and the thread on task and shopping lists (10601): this is exactly what OpenFamily does.

What I imagine, on the Gladys side, in the form of an external integration published in your store (so no work for you):

- the family calendar as a Gladys calendar (type « calendar »), with appointments that trigger scenes;

- dashboard widgets: the day’s schedule, the shopping list, the tasks;

- scene actions « add to shopping list » and « add a task », and a trigger on appointment reminders.

Before coding, two questions:

1. Does this form seem right to you, or do you prefer another approach?

2. Are there any store or SDK constraints I should be aware of for a first draft?

I’m open to feedback, and open to broader collaboration between the two projects.

Hi Quentin, and welcome to the forum! :waving_hand:

Thanks for taking the initiative and for reading the spec before coding :slightly_smiling_face: I agree about the complementarity: Gladys manages the home, OpenFamily manages family life. The thread about shopping and task lists (10601) shows that there is a real demand.

1. The form: yes, that’s the right one

Make a single external integration of type: "calendar". It can also declare widgets, scene_actions, and scene_triggers, as all types can add these capabilities to their main role.

The closest model in the store is ICS Calendars (GitHub - guim31/gladys-ics-calendar: Remote iCalendar (.ics) calendars for Gladys Assistant: Google Calendar secret address, school, waste collection · GitHub). It does exactly that: a calendar, a “Next Events” widget, triggers, and an action. For lists, check out Bring! (https://github.com/LM1LC3N7/gladys-bring) and Todoist (GitHub - LM1LC3N7/gladys-todoist: Gladys Assistant external integration for Todoist: today’s tasks on the dashboard, add and complete tasks from scenes, a “task due” scene trigger. Unofficial, not affiliated with Doist. · GitHub). They already cover shopping and tasks, it’s a good source of inspiration for the user experience.

A few clarifications on each point:

  • The calendar works in “push” mode: your integration synchronizes, Gladys stores.
    • The calendars sent feed the calendar view and the scenes, like those of the native CalDAV.
    • It’s one-way: Gladys never writes to OpenFamily.
    • Each user activates the integration for themselves, in the “My Calendars” block. Calendars are private by default.
    • A calendar must be shared for the whole household to see it and for it to be able to trigger scenes.
    • Be careful with duplicates: if you send the family calendar to each member and each one shares it, it will appear multiple times. It’s better to send it to a single account.
  • Appointment reminders: you don’t need your own trigger.
    • The native trigger “An event in the calendar is coming up” works directly on the sent calendars. It can be set a little before the start or end of an appointment, with a filter on the name.
    • I would only create a home trigger if the OpenFamily reminders contain information that Gladys doesn’t have, for example a reminder set manually in OpenFamily. This avoids two ways of doing the same thing.
  • Widgets: they are declarative. Your integration returns content with a fixed vocabulary (list, list of states, tiles, buttons…) and Gladys takes care of the display (theme, dark mode, mobile). A widget is used to display data and to interact with it:
    • Adding an item or a task from the widget is possible: a button can open a small form (4 fields maximum) that your integration declares.
    • Checking an item: there is not yet a checkbox per line. You can work around this with a “Check” button that opens a selection list (select field) containing the current items, generated at the time of display. If it’s too limiting in use, open a topic: the forms behind the buttons were born from feedback like this.
    • Gladys retrieves the content and keeps it in cache for the duration you set (ttl_seconds). When a list changes on the OpenFamily side, send a widget.refresh to update the widgets.
  • Scene actions: “add to shopping list” and “add a task” are perfect for this, and the text fields accept scene variables.
    • Also think of an action “read the list” that returns a result (outputs). A scene could, for example, send the shopping list by message when you leave work.
    • Like triggers, “item added”, “task completed” or “task due” come naturally.

2. Store and SDK constraints for a first draft

  • Publication:

    • a public GitHub repository with the topic gladys-assistant-i* integration ;
    • the gladys-assistant-integration.json manifest at the root ;
    • mandatory documentation in French and English (docs/fr.md and docs/en.md), at least 300 characters each, with the sections Introduction / Prerequisites / Configuration / Troubleshooting ;
    • an optional cover image, 800×534 and maximum 150 Ko.

    Indexing is automatic, every hour, without validation on our part. If your integration does not appear, the reason is indicated in rejected.json. To test before indexing, simply use « Install from GitHub » with the repository URL.

  • Docker Image : it must be on a public registry and built for amd64 and arm64, as many Gladys instances run on Raspberry Pi. Start from the template GitHub - GladysAssistant/integration-template-js: Gladys Assistant Integration template for a JS external integration · GitHub : it already contains the build workflow for both architectures to GHCR.

  • Container :

    • non-root user, read-only file system ;
    • /data is the only preserved folder ;
    • CPU and memory limited.

    The outgoing network is open: a self-hosted OpenFamily instance on the local network is reachable by its URL. Only mDNS and incoming broadcasts do not pass.

  • SDK : the official SDK is in Node.js (@gladysassistant/integration-sdk). If you prefer another language, the REST/WebSocket API is documented. You can also develop outside Docker with a dev token.

  • Secrets : put the OpenFamily URL and token in the config_schema, with the secret type that is never sent to the browser. If each member has their own credentials, use the account_schema instead. Never put them in a widget’s settings or a scene’s fields: the manifest validation will reject it.

  • Calendar, technical side :

    • the external_id must start with ext:<selector>:<user>: ;
    • it’s up to you to calculate the occurrences of recurring events (we recommend 12 months in advance) ;
    • to delete events, you return a complete period (window) ;
    • limits: 500 events per request, 30 writes per minute, 50 calendars per user and 10,000 events per calendar.
  • Widgets : a maximum of 5 per integration and 8 elements per widget. Images must be served by your integration (PNG, JPEG or WebP, maximum 300 Ko), never via an external URL loaded by the browser.

  • gladys_version : indicate the minimum version of Gladys that supports what you use. An older version will reject a manifest whose fields it does not know.

All the documentation is here: Créer une intégration externe | Gladys Assistant (sections « Calendars: the calendar type », « Dashboard widgets » and « Scene triggers and actions »).

Thanks Pierre-Gilles, that’s very clear and it answers everything!
So we’re going with a calendar-type integration with widgets, actions, and triggers, inspired by ICS Calendars, Bring! and Todoist.
First step on our side: an API token in OpenFamily, so that the integration authenticates properly (config_schema as type secret).
Then the repository from the template, tested on a local Gladys via « Install from GitHub ».
I’ll come back here with a first repository to try.

If it works well, I’m interested in replacing the family wall app which is not open source

Hi Pierre-Gilles,

It’s done: the OpenFamily integration is live, GitHub - NexaFlowFrance/gladys-openfamily: OpenFamily for Gladys Assistant: the family calendar, shopping list and tasks on the dashboard and in scenes. · GitHub. It follows your brief: calendar type, three widgets (today, shopping, tasks) with forms to add and check, four scene actions and three triggers. On the OpenFamily side, we added API tokens for the occasion.

The template, the SDK and the store validator are very pleasant to use, thanks for this work. Tested on a Gladys 5.3.3 in Docker.

Two feedback points, if they can help:

  1. When the timezone is not set in the settings, the integration containers receive TZ=UTC while the core falls back to Europe/Paris. Local times are then offset. I added a timezone setting on my side.
  2. With Gladys in bridge mode under Docker Desktop (Windows), the integration couldn’t reach gladys:80, the gladys-integrations network being created without communication between containers. Not checked under Linux.

All feedback is welcome, from you and the community.

Thanks @QuentinCazier for this new integration!

I took the opportunity to change the title :slight_smile:
And I’ll test it soon :wink:

We’re eagerly awaiting the new integration :wink:

Well, I hadn’t seen the GitHub :sweat_smile:

A little patience please :smiley:
I’ve put Gladys at the top of the list, we will always prioritize applications and others that share the same philosophy as us :slight_smile:

Edit:
It’s all good :wink: