User Platform Outbound Writer¶

Reference for App\Integrations\UserPlatform\UserPlatformOutboundWriter, the first writer built against the Outbound Writer Contract that creates a record rather than only updating one. It puts a canonical CustomerData record into a Positive User (user.com) workspace as a contact, writes that contact's email and SMS consent onto it (see Consent), and puts a ProductData record into the workspace as a product (see Products). See ADR-0031 for why it creates its own contact rather than upserting one keyed by custom_id.

Classes¶

The split follows the domain. For records with a payload of their own, the writer names a domain in exactly two places. A consent has no payload or collection of its own: performUpdate() sends it down the consent flow before either is asked.

Adding a domain costs a mapper class and one arm in each — no verb, no payload method on the writer, and nothing inherited from contacts about which verbs that domain's API offers. collection() is a match without a default arm, so a new SystemCapability is a static-analysis error here rather than a request to a path the writer invented; the one domain Conflux does not write to this target (orders) is refused by name. Deliberately not a resource interface with one implementation: what a second domain needs from this class is a path and a payload, and whether it has the same three verbs as a contact is a question about that domain's API, which a type built from this one would answer in advance.

payload() reads the record's type rather than the projection's domain, although the question is about the domain: Projection rejects a pair that disagrees on every construction path, so the two are the same question, and asking it this way also narrows the record for the mapper.

Declared verbs¶

The writer never searches the workspace for an existing contact and never decides between create and update itself — the delivery ledger has already answered that from a local row before either method is called (ADR-0015).

Endpoints¶

Authentication and rate limiting¶

Field mapping¶

CustomerData → User.com contact payload, in UserPlatformContactMapper. A field the record does not carry is left out of the payload entirely, never sent as an explicit null — the target merges what it receives, and a null would clear a value the workspace filled in itself.

What the payload deliberately does not write¶

Consent¶

The writer's second domain is customer_consents, a dependent domain (ADR-0041). A consent has no record of its own in the workspace. It is fields and events on its contact, so delivery only ever asks for an update(), with the anchor's contact id as the remote id (ADR-0042). The flow follows the one User.com documents for a backend integration (ADR-0045).

It is part of this writer rather than a second one because the registry holds one writer per driver, and the contact and its consent are one record. UserPlatformContactMapper sends no consent, and its reserved keys (email_opt_in, sms_opt_in, unsubscribed, unsubscribed_from_sms) keep a custom attribute from ever overwriting one. UserPlatformConsentMapper::callsFor() sorts a consent into a UserPlatformConsentCalls (fields, suppression flag, events), and the writer sends exactly those.

What accepts() refuses¶

A refused candidate is recorded suppressed before any request and before a budget token is taken; see accepts(). Writing an unknown subscription as false would unsubscribe the person. writeConsent() keeps the same guard as a second line, as the shop writers do. The check comes from the App\Services\Concerns\AcceptsConsentChannels trait. This writer renames it to acceptsConsent() and lets every customers projection through ahead of it.

The calls per consent state¶

An SMS consent takes the same branches with unsubscribed_from_sms as its only field, the SMS suppression flag. The contact has no SMS opt-in field.

An SMS consent never touches email_opt_in or unsubscribed, and an email consent never touches unsubscribed_from_sms. The SMS flag needs no mass update because the contact endpoint accepts it. No shop produces SMS consent today, so this path waits for a source that does.

A withdrawal is verified on its own: confirmed describes an opt-in, and an opt-out needs no confirmation to be honoured. An unconfirmed subscription writes no field at all. It asks Positive User to run its own double opt-in. A shop reports confirmed: null, so every shop subscription takes that branch.

For email, the confirmation comes back over the consent webhook: the double opt-in sets email_opt_in, the automation reports it, and the Positive User mirror holds the confirmed subscription. For SMS it never comes back. All a confirmation can do on the contact is clear unsubscribed_from_sms, and the webhook reads unsubscribed_from_sms: false as nothing, because it is every contact's default. consent_requested is still fired for an unconfirmed SMS subscription: an automation in the workspace may run its own SMS double opt-in on it, even though Conflux never hears the outcome.

source is the consent's sourceSystem value (woocommerce, prestashop).

Requests¶

{id} is the anchor id the delivery layer hands over in the RemoteReference. Every request is built by UserPlatformClient::deliveryRequest(). No custom_id-keyed endpoint and no update_or_create is used.

Failure semantics¶

One delivery costs one token of the delivery budget, while User.com counts up to three requests. A burst can therefore meet a 429 the budget would have avoided, which the rate-limit handling catches (ADR-0036).

Products¶

The writer's third domain is products, a root domain like customers. The ledger holds the numeric id the app assigns, and every later write addresses the product by it. The decisions behind the shape are in ADR-0047.

The custom_id¶

POST products-by-id/ requires a custom_id and the app keeps it unique in the workspace. UserPlatformProductMapper::customId() takes the product's SKU, or its EAN where there is no SKU, trimmed and otherwise as the shop holds it. The EAN is ProductData::$ean, or the shop's custom attribute named ean where the field is empty. A product with neither is refused with an UndeliverableRecordException: the ledger row is undeliverable, last_error says what to fill in, and the rule's delivery records in the admin panel show it.

Every update sends the current custom_id as well, so a SKU changed at the source renames the remote product in place.

Only products Conflux created¶

The app answers 400 {"custom_id": ["product with this Custom ID already exists."]} when another product holds the key, on a create and on a rename. The writer turns that into an UndeliverableRecordException that names the key. Nothing is merged into the other product. Two source products with the same SKU end up as one delivered and one undeliverable.

An update the app answers with 404¶

A product deleted in the workspace is not created again. An update answered with the app's own 404 (a JSON body carrying detail, or no body) is a RemoteRecordGoneException, exactly as for a contact: the row becomes remote_gone and delivery of that product stops (ADR-0015). An HTML error page stays an ordinary, retryable failure.

The payload¶

The app turns every key a product is written with into an attribute of every product in the workspace, so writing what the shop holds would rewrite the workspace's product schema. A product attribute is therefore written only where the workspace already has it.

UserPlatformProductSchema reads the names from GET products/: the keys of the first result, minus the model's own keys. The answer is cached for 300 seconds per connection and subdomain, so an attribute the workspace owner just created is seen after at most five minutes. A workspace with no product yet answers an empty list. A schema read that fails fails the write as a retryable OutboundWriteException.

A shop custom attribute whose key collides with a reserved key (the model fields, the fixed attributes, conflux_source and the app's own keys) is refused as undeliverable, naming the key.

Deletion¶

DELETE products/{id}/ is a hard delete, because the app has no inactive state for a product either. The seeded Positive User products direction is push_out, with delivery_defaults of overwrite and delete. A mass deletion is held by the volume breaker like any other withdrawal (ADR-0035).

What a deletion at the source can do here¶

delete is declared, deactivate is not, so a rule has two outcomes to choose between for this target: remove the contact, or leave it untouched. There is no third state in between — the workspace has no inactive state of its own, and Conflux does not invent one in somebody else's schema.

The removal is the app's hard delete, the only one it offers: the contact and everything the workspace recorded about it are gone, and nothing Conflux holds can put either back. Declaring the verb says the target can delete, not that deleting is the right answer to a source record going away — that is the rule's delete_policy (ADR-0016), and a rule that leaves it at ignore never reaches the verb.

deactivate stays out because the only way to build the state it needs is a custom attribute the workspace would have to create before the first delivery, and reusing unsubscribed for it is ruled out by ADR-0016: a record leaving a shop says nothing about what that person agreed to, so an ordinary removal must not read as an objection.

A reference naming a domain other than customers or products is refused with an UndeliverableRecordException before the request leaves. A delete is handed a bare reference with no projection beside it, so that check is the only thing between a wrong domain and a DELETE on whichever contact happens to hold that number.

Response handling¶

$remoteId is what separates the two readings of a 404: passed for update and delete, null for create. The body separates them a second time — see the two update rows above.

Connections the writer refuses to deliver to¶

requireDeliverableConnection() (the AbstractOutboundWriter hook) asks UserPlatformClient::deliveryRequest() before the write enters the circuit breaker and the error mapping. Both of its refusals therefore keep their own type and travel to the caller untouched:

Neither is an OutboundWriteException and neither counts a circuit-breaker failure, which is the point of checking them there. Raised inside the breaker's callback — which is what happens when a writer only asks for its request inside performCreate()/performUpdate() — they would be rewrapped as retryable write failures, so a rotated token would put every record of a run on a retry schedule that cannot succeed and open the circuit over requests that never left.

Error message parsing¶

errorMessage() tries three response shapes, in order, then falls back to the raw body:

1. A single string under detail, error or message.
2. A field-to-messages map (what validation failures answer with) — folded into field: message pairs joined by ;. This is what makes a rejected custom attribute legible: User.com names the offending key.
3. A bare list of messages — folded the same way, without a field prefix.

Where none of the three matches, the message is the raw response body, trimmed and truncated to UserPlatformOutboundWriter::RAW_MESSAGE_LIMIT (1000) characters, or no message where the body is empty. The cap is what keeps a full HTML error page out of last_error, a text column an operator reads the first line of.

If the response carries a retry-after header (User.com sends it lowercase; header() compares case-insensitively), its value is appended to the message as (retry after {n}s) — so a rate limit carries its wait into the ledger's last_error, which is where an operator looks first. On a 429 the same value also travels as TargetRateLimitedException::$retryAfterSeconds, so the delivery layer reads it without parsing the message a second time.

Records the writer refuses to deliver¶

Each raises App\Exceptions\UndeliverableRecordException, not OutboundWriteException: the source row has to change first, so a retry asks the same question of the same row forever. The exception carries ReportsARecordFault, so the circuit breaker leaves its state untouched — a batch holding a few of these must not take a healthy connection down (ADR-0032).

Workspace prerequisites¶

The custom attribute conflux_source has to be declared in the target workspace before the first delivery, because it travels on every payload. Connecting declares it — see Declaring conflux_source — so a workspace that went through the handshake needs no preparation by hand.

It matters that this is handled rather than documented as a step, because the app gives no sign when it is missing: a contact carrying an attribute the workspace has not declared is accepted with 201 and the value is dropped without a word. A workspace nobody prepared would hold contacts with no source marker and nothing would fail to reveal it. A workspace this writer reaches without ever having been connected — a live test pointed at a fresh one, say — is the one case left where the attribute has to be declared by hand.

Test coverage¶

Running the live tests¶

The live tier needs a real User.com workspace with conflux_source declared in it — connecting declares it, so this only has to be done by hand for a workspace that has never been connected. Configure it with:

docker compose exec \
  -e USER_PLATFORM_LIVE_SUBDOMAIN=<workspace subdomain, without the apex> \
  -e USER_PLATFORM_LIVE_API_TOKEN=<64-char token> \
  php composer test:live -- --filter UserPlatformLiveCustomerWrite

The same pair UserPlatformLiveVerificationTest takes — it is the same credential in two parts. USER_PLATFORM_API_HOST has to be set in the container's environment as well, since the apex that completes the host has no default.

Both unset skips the whole file. The run creates real contacts and deletes each one again through the app's hard delete in afterEach(); every contact it creates carries conflux_source = live-test, which is what makes one left behind by a crashed run findable. See Run the Live Tests for the shared conventions this tier follows.

See also¶

• Outbound Writer Contract — the capability interfaces, traits, exceptions and registry this writer is built against
• ADR-0031 — why the writer creates and updates by numeric id rather than upserting by custom_id
• ADR-0047 — how a product is keyed, addressed and written
• ADR-0045 — the consent flow, and why it lives in this writer
• ADR-0015 — why Conflux creates a record in the target rather than resolving one
• ADR-0021 — why deactivate and bulk ingestion are simply absent from the type rather than refused at runtime
• ADR-0032 — why a record this writer refuses is neither retried nor counted against the connection's health
• Implement an Outbound Writer — the general how-to, now with this writer as the worked example