Choose what goes out to the address book: contacts, companies, departments and the person's own card #10

New issue

Open

opened 2026-09-30 20:30:03 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-09-30 20:30:03 +00:00

Owner

Today the plugin writes one kind of card: every contact of the owner is pushed to the one configured address book (src/postulo_dav/sync.py:425-457). Nothing chooses which go out; the only way to keep one contact off the phone is to delete its card there. Companies, departments and the person's own card are never written, and a contact's department is dropped, since ORG carries the company's name only (src/postulo_dav/sync.py:138, text.py:160-161). The ask:

export from postulo to CardDAV can also be possible.

Read here as: Postulo writes cards for the kinds of record the person picks, not only contacts; whether they then stay in step or are a one-off copy is decision 1.

What the plugin should do

Per connection, the person chooses what goes out, into a writable address book they chose (#13):

Contacts: all (today's behaviour, and the default for existing connections), none, or only chosen ones.
Companies as KIND:org cards (vCard 4, RFC 6350 §6.1.4), or with X-ABShowAs:COMPANY where the book takes only vCard 3 (Apple's property; not tried against iCloud). Name as FN and ORG, website as URL, notes as NOTE, and numbers, email and addresses once postulo/postulo#329 gives a company some. Nextcloud Contacts gives KIND:org no special treatment (nextcloud/contacts#302).
Departments as the ORG unit on their contacts' cards (ORG:Acme;Legal, RFC 6350 §6.6.4), which DAVx5's manual says becomes an Android contact's department (not tried; decision 2). Written only while employer_structure is on for the person: the core hides departments otherwise (src/postulo/jobs/structure.py in the core).
The person's own card, one way, Postulo → card, from what contact_details(owner) assembles in the core (src/postulo/documents/rendering.py): name, sign-in email, headline, primary number, location, primary links and identifiers (decision 4).

The vCard version follows the book's supported-address-data, and what is pushed becomes a pairing, both under #8's rules, unless decision 1 goes the other way.

The choice per kind fits the connection's settings as they are: a boolean or a fixed-choice FieldSpec works today. "Send this company to my address book" from a record's own page, and so "only chosen" contacts, needs a core-drawn action: postulo/postulo#327.

Decisions

Export and sync, or a one-off copy. A copy leaves no link: a later edit here never reaches the card, and deleting the record leaves it behind. Recommended: export and sync, as the rest of the plugin does; a one-off copy is still possible by unpairing afterwards.
Departments as a unit, or as cards of their own. A department card (FN:Legal, ORG:Acme;Legal) would carry nothing but a name: a department in Postulo has no number, address or website (src/postulo/jobs/models.py in the core). Recommended: the ORG unit on contacts' cards only.
Companies beside the people, or in a book of their own. Recommended: the same book by default, so a phone shows the employer next to the recruiter; another writable book chosen under #13 if the person asks.
The own card: a new card, or the one the server names as the person's. Writing to the card CARDDAV:principal-address points to (RFC 6352 §7.1.2) overwrites what the person keeps about themselves. Recommended: a separate card Postulo creates in the chosen book, unless the person paired their own card (#8), in which case only the properties Postulo owns are patched. Which email and number a CV prints is open as postulo/postulo#308; this card should follow that choice.
Switching a kind off. Dropping the links would let adoption in Postulo's own book bring those cards back as new records. Recommended: the cards and their links stay, nothing more is pushed, and the run's summary says how many were left; nothing is deleted unless the person asks.

Needs from the core

postulo/postulo#328: reading companies, departments and the person's own details, and whether departments are on for the person (structure_allowed, off the surface). Today only contact.company, contact.department and connection.owner.profile reach them: that passes the surface check, which looks at imports, but rests on attributes the surface never promised.
postulo/postulo#329: a company's numbers, email and addresses.
postulo/postulo#327: the per-record action.

Before they land, only the contacts choice (all or none) can ship; reaching companies and departments through a contact, as card_for reaches contact.company today (sync.py:138), would lean on that unpromised reach. Depends on #13 and #8.

Done when

A connection sends contacts (all or none, and chosen ones once the core's action exists), companies, departments and the person's own card, each switched separately; an existing connection keeps sending all its contacts and nothing more.
A company arrives as KIND:org in a vCard 4 book and with X-ABShowAs:COMPANY in a vCard 3 one, against the in-memory server; a contact in a department arrives with ORG:Company;Unit.
The person's own card is written one way and never read back into the profile.
Switching a kind off leaves its cards on the server, adopts none of them, and says so.
New strings go through uv run postulo-messages extract, fr-fr and pt-pt filled on the commit (the test gates them), the 23 EU catalogues before a tag (uv run pytest -m release). New surface names mean repinning the core (pyproject.toml's dev group pins 1d6cdd7e0) and extending tests/test_surface.py.

From the list of DAV plugin improvements of 2026-09-30.

Today the plugin writes one kind of card: every contact of the owner is pushed to the one configured address book (`src/postulo_dav/sync.py:425-457`). Nothing chooses which go out; the only way to keep one contact off the phone is to delete its card there. Companies, departments and the person's own card are never written, and a contact's department is dropped, since `ORG` carries the company's name only (`src/postulo_dav/sync.py:138`, `text.py:160-161`). The ask: > export from postulo to CardDAV can also be possible. Read here as: Postulo writes cards for the kinds of record the person picks, not only contacts; whether they then stay in step or are a one-off copy is decision 1. ## What the plugin should do Per connection, the person chooses what goes out, into a writable address book they chose (#13): - **Contacts:** all (today's behaviour, and the default for existing connections), none, or only chosen ones. - **Companies** as `KIND:org` cards (vCard 4, RFC 6350 §6.1.4), or with `X-ABShowAs:COMPANY` where the book takes only vCard 3 (Apple's property; not tried against iCloud). Name as `FN` and `ORG`, website as `URL`, notes as `NOTE`, and numbers, email and addresses once postulo/postulo#329 gives a company some. Nextcloud Contacts gives `KIND:org` no special treatment (nextcloud/contacts#302). - **Departments** as the `ORG` unit on their contacts' cards (`ORG:Acme;Legal`, RFC 6350 §6.6.4), which DAVx5's manual says becomes an Android contact's department (not tried; decision 2). Written only while `employer_structure` is on for the person: the core hides departments otherwise (`src/postulo/jobs/structure.py` in the core). - **The person's own card,** one way, Postulo → card, from what `contact_details(owner)` assembles in the core (`src/postulo/documents/rendering.py`): name, sign-in email, headline, primary number, location, primary links and identifiers (decision 4). The vCard version follows the book's `supported-address-data`, and what is pushed becomes a pairing, both under #8's rules, unless decision 1 goes the other way. The choice per kind fits the connection's settings as they are: a boolean or a fixed-choice `FieldSpec` works today. "Send this company to my address book" from a record's own page, and so "only chosen" contacts, needs a core-drawn action: postulo/postulo#327. ## Decisions 1. **Export and sync, or a one-off copy.** A copy leaves no link: a later edit here never reaches the card, and deleting the record leaves it behind. **Recommended:** export and sync, as the rest of the plugin does; a one-off copy is still possible by unpairing afterwards. 2. **Departments as a unit, or as cards of their own.** A department card (`FN:Legal`, `ORG:Acme;Legal`) would carry nothing but a name: a department in Postulo has no number, address or website (`src/postulo/jobs/models.py` in the core). **Recommended:** the `ORG` unit on contacts' cards only. 3. **Companies beside the people, or in a book of their own.** **Recommended:** the same book by default, so a phone shows the employer next to the recruiter; another writable book chosen under #13 if the person asks. 4. **The own card: a new card, or the one the server names as the person's.** Writing to the card `CARDDAV:principal-address` points to (RFC 6352 §7.1.2) overwrites what the person keeps about themselves. **Recommended:** a separate card Postulo creates in the chosen book, unless the person paired their own card (#8), in which case only the properties Postulo owns are patched. Which email and number a CV prints is open as postulo/postulo#308; this card should follow that choice. 5. **Switching a kind off.** Dropping the links would let adoption in Postulo's own book bring those cards back as new records. **Recommended:** the cards and their links stay, nothing more is pushed, and the run's summary says how many were left; nothing is deleted unless the person asks. ## Needs from the core - postulo/postulo#328: reading companies, departments and the person's own details, and whether departments are on for the person (`structure_allowed`, off the surface). Today only `contact.company`, `contact.department` and `connection.owner.profile` reach them: that passes the surface check, which looks at imports, but rests on attributes the surface never promised. - postulo/postulo#329: a company's numbers, email and addresses. - postulo/postulo#327: the per-record action. Before they land, only the contacts choice (all or none) can ship; reaching companies and departments through a contact, as `card_for` reaches `contact.company` today (`sync.py:138`), would lean on that unpromised reach. Depends on #13 and #8. ## Done when - A connection sends contacts (all or none, and chosen ones once the core's action exists), companies, departments and the person's own card, each switched separately; an existing connection keeps sending all its contacts and nothing more. - A company arrives as `KIND:org` in a vCard 4 book and with `X-ABShowAs:COMPANY` in a vCard 3 one, against the in-memory server; a contact in a department arrives with `ORG:Company;Unit`. - The person's own card is written one way and never read back into the profile. - Switching a kind off leaves its cards on the server, adopts none of them, and says so. - New strings go through `uv run postulo-messages extract`, fr-fr and pt-pt filled on the commit (the test gates them), the 23 EU catalogues before a tag (`uv run pytest -m release`). New surface names mean repinning the core (`pyproject.toml`'s dev group pins `1d6cdd7e0`) and extending `tests/test_surface.py`. From the list of DAV plugin improvements of 2026-09-30.

tiagoagueda added the

enhancement

label

2026-09-30 20:30:03 +00:00

tiagoagueda referenced this issue from Postulo/postulo

2026-09-30 20:30:05 +00:00

Put companies, departments and the person's own card on the plugin surface, with services to write companies, departments, contacts and their rows #328

tiagoagueda referenced this issue from Postulo/postulo

2026-09-30 20:30:06 +00:00

Give companies telephone numbers, postal addresses and an email address, and let two people record the same switchboard #329

tiagoagueda commented

2026-10-03 01:59:29 +00:00

Author

Owner

The maintainer's list of 2026-10-02 asks for vCard 4 as the format for contact details. Core issue postulo/postulo#660 covers the writing side with a .vcf export, through one mapping offered on the plugin surface.

Reusable here: a company as a KIND:org card, a department as the ORG:Company;Unit of its contacts, the person's own card limited to what the default CV prints (postulo/postulo#308) and never read back, and phone numbers in international form (postulo/postulo#304). One point to agree: the core leaves NOTE out unless chosen, as #8's decision 5 does, while company cards here carry it.

This issue keeps its own scope: the choice per kind of record, the chosen address book, the vCard 3 form with X-ABShowAs:COMPANY, and staying in step.

From the list of improvements of 2026-10-02.

The maintainer's list of 2026-10-02 asks for vCard 4 as the format for contact details. Core issue postulo/postulo#660 covers the writing side with a `.vcf` export, through one mapping offered on the plugin surface. Reusable here: a company as a `KIND:org` card, a department as the `ORG:Company;Unit` of its contacts, the person's own card limited to what the default CV prints (postulo/postulo#308) and never read back, and phone numbers in international form (postulo/postulo#304). One point to agree: the core leaves `NOTE` out unless chosen, as #8's decision 5 does, while company cards here carry it. This issue keeps its own scope: the choice per kind of record, the chosen address book, the vCard 3 form with `X-ABShowAs:COMPANY`, and staying in step. From the list of improvements of 2026-10-02.