Internal tools & business software

Separate the caller from the person being assigned

Wonder Todos demonstrates this distinction in its ASSIGN_LEAD operation. This selected entry comes from its operation map; imports and the surrounding resource declaration are omitted.

[Todos_Operations.ASSIGN_LEAD]: {
  variants: [{
    variantType: ResourceOperationVariantType.API_CALL,
    isDefault: true,
    roles: [CORE_ORG_ROLES.ORG_ADMIN],
    riskLevel: ResourceOperationRiskLevel.MEDIUM,
    resourceOperationLike: CoreResourceOperation.UPDATE,
    requestDto: z.object({
      assignedToUserId: z.string().min(1),
    }),
    referenceConstraints: {
      assignedToUserId: {
        qualifyingStatuses: [OrganizationMemberStatus.ACTIVE],
        requiredRoles: {
          scope: ResourcePrimaryScope.ORGANIZATIONS,
          roles: [CORE_ORG_ROLES.ORG_ADMIN],
        },
      },
    },
  }],
},

roles restricts the caller. referenceConstraints restricts the assignee to an active member with the required organization role. The existing update mechanism performs the change; the registered field and relationship give that reference its meaning.

An internal tool can use the same pattern with its own roles and actions. Approval thresholds, transitions and external checks need the corresponding application-authored behavior. The name approve does not create an approval policy.

Shape the working surface

Resource UI behavior chooses how operations appear, including addressable and embedded surfaces. Custom views can combine standard layouts with resource-owned views. Keep these presentation choices separate from backend permission checks.

Choose which changes need auditable events and configure or emit them through the relevant mechanisms. Verify the actual event and actor attribution; a visible activity panel does not itself prove every custom action is recorded.

Declare how a user type may be acquired

The SaaS skeleton declares registration inside userTypes.member.auth. This illustrative replacement for that registration block chooses invitation-only acquisition. The enums are exported by @wildo-ai/saas-models; surrounding authentication settings remain application-owned.

registration: {
  mode: RegistrationMode.INVITATION_ONLY,
  allowedMethods: [AuthMethod.PASSWORD],
  emailVerification: EmailVerificationMode.REQUIRED_BEFORE_ACCESS,
  blockForSSODomains: false,
},

The acquisition policy accepts invitation and administrative-provisioning channels in this mode. It does not admit self-registration or SSO just-in-time acquisition. Existing holders of a user type are evaluated differently from people acquiring it for the first time: acquisition policy is not a blanket login prohibition.

allowedMethods governs registration methods; it does not replace the configured authentication methods or MFA policy. Configure the invitation messages and their provider where invitations are part of the chosen journey.

Model organizational context deliberately

User types, organization memberships and operation roles have different jobs. Use an organization where it represents a real boundary. Declare resource scopes and relationships so reads and mutations carry that boundary into execution.

Verify the joiner, mover and leaver journeys

Test invitation or provisioning, first access, membership change and removal. Check direct API calls after a role changes. For SSO, exercise the selected provider and existing-user versus new-user paths separately; domain configuration and acquisition policy must agree.

Read users, organizations and security for the underlying identity and authorization mechanisms.

Declare the system once

Wonder Todos declares its Odoo instance once, as a named system of record in wildo.saas.config.ts. This excerpt omits its comments and its privacy-notice declaration:

systemsOfRecord: {
  odoo: {
    vendor: 'odoo',
    dialect: HttpApiTransportDialect.ODOO_JSONRPC,
    partition: true,
  },
},

The name odoo identifies the instance; resources bind it with system: 'odoo', and a second deployment would be a second name. Each environment supplies the address and the service account’s credential under names derived from that name, so nothing about access is committed in a resource. An environment without access declares the instance absent: the tool still starts, and reads of bound resources are refused rather than answered empty.

partition: true says this Odoo holds several companies. Rows are then confined to the organization units an operator assigns each Odoo company to, so a subsidiary’s staff see and change only their own company’s records; a record that belongs to no company is shared by everyone. This confinement exists for Odoo only.

What each vendor supports differs, and startup refuses a declaration the vendor cannot honour rather than letting it fail at the first request:

Sending, in either sending direction, accepts only records that hold no personal data, because no erasure reaches a record once it has been sent. Every vendor’s reads, writes and pipelines are tested against simulators of its protocol. Odoo is the only one the dogfood application declares, and the shape of its company field was measured on a live Odoo; no vendor has been driven end to end against a live tenant.

Read and change records in place

The billable-services resource binds that instance by name. This selected configuration excerpt shows identity, field mapping and the writes it opens; source comments, the schema, relationships and operation declarations are omitted.

persistenceAdapter: PersistenceAdapter.HTTP_API,
httpApiBinding: {
  dialect: HttpApiTransportDialect.ODOO_JSONRPC,
  system: 'odoo',
  entityRef: 'product.template',
  keyFields: [{ localField: 'odooProductId', remoteField: 'id', codec: HttpApiKeyComponentCodec.INTEGER }],
  fieldMappings: [
    { localField: 'listPrice', remoteField: 'list_price' },
    { localField: 'unitOfMeasure', remoteField: 'uom_name' },
    { localField: 'lastUpdatedAt', remoteField: 'write_date' },
  ],
  subjectRights: { posture: SystemOfRecordSubjectRightsPosture.NO_SUBJECT_DATA },
  writableVerbs: [HttpApiWriteVerb.CREATE, HttpApiWriteVerb.UPDATE, HttpApiWriteVerb.DELETE],
  writeConcurrency: { mode: HttpApiWriteConcurrencyMode.VERSION_CHECKED, versionField: 'lastUpdatedAt' },
},

Remote field names are translated into the local schema, while the key mapping supplies stable record identity. writableVerbs opens creates, updates and deletes, each matched by a declared operation. Every write requires an idempotency key and is sent once: an interrupted write is reported as an unknown outcome rather than repeated. VERSION_CHECKED compares the write_date the caller read with Odoo’s own just before an update and refuses a stale one. A no-subject-data erasure declaration is only appropriate when the resource actually has that property; a product catalogue does.

An ERP operation that is not a row write, such as posting an invoice, is declared as a named action on the binding and runs through its own executor, with its own roles and audit record. Wonder Todos’ customer-invoices resource declares one; see actions in a system of record.

Keep a copy, in either direction

The external-customers resource keeps a local copy of Odoo’s client accounts. Source comments are omitted:

externalDataPipeline: {
  binding: {
    dialect: HttpApiTransportDialect.ODOO_JSONRPC,
    system: 'odoo',
    entityRef: 'res.partner',
    keyFields: [{ localField: 'id', remoteField: 'id', codec: HttpApiKeyComponentCodec.INTEGER }],
    subjectRights: { posture: SystemOfRecordSubjectRightsPosture.OWNED_COPY },
    purposeRefs: ['task-planning-service'],
  },
  remoteKeyLocalField: 'odooPartnerRef',
  partitionUnitLocalField: 'organizationUnitId',
  partitionKeyLocalField: 'odooCompanyRef',
  mapping: [
    {
      kind: ExternalDataMappingEntryKind.CONCATENATION,
      localField: 'name',
      parts: [
        { kind: ExternalDataConcatenationPartKind.REMOTE_FIELD, remoteField: 'name' },
        { kind: ExternalDataConcatenationPartKind.REMOTE_FIELD, remoteField: 'ref' },
      ],
      separator: ' · ',
    },
    { kind: ExternalDataMappingEntryKind.REMOTE_FIELD, remoteField: 'email', localField: 'email' },
  ],
  sourceFilter: { is_company: true },
  population: ExternalDataDestinationPopulation.CLOSED,
  orphanPolicy: ExternalDataOrphanPolicy.IMPERSONALIZE,
  scheduleCron: '0 * * * *',
},

The subject-rights posture says the tool keeps this copy itself: it holds the team’s notes, which Odoo does not, so its own erasure applies to the copy, while Odoo answers requests about the records it came from. Because a copied name and email can describe a person, NO_SUBJECT_DATA would be refused. The two partition fields are written by the engine: the organization unit the client’s Odoo company is assigned to, and Odoo’s own company id. The CONCATENATION entry is a declared expression that shows the client’s name followed by its finance reference. IMPERSONALIZE scrubs the name, email and note of a client that no longer appears in a complete pass, and keeps the row; it writes no suppression, so a record Odoo lists again loads as a new row. An erasure through the tool scrubs the row the same way and also records a suppression, so the next pass does not copy the client back.

The same declaration takes a direction. An outbound pipeline sends the rows the tool creates and changes, writing back the key the other system answers; a two-way pipeline declares each mapped field’s owner — the other system’s, the tool’s or both — and a conflict policy for a shared field changed on both sides. Neither sends a local delete. See sending local changes and two-way sync with field ownership.

Choose the storage consequence

A pipeline needs its own extraction, mapping and load contract. Do not infer successful synchronization from the existence of a resource declaration or copy a sample without checking its current integration status.

Make failure understandable to staff

Define what the user sees when the source is unavailable and how stale local data is identified. Verify authentication failure, pagination, mapping and repeat runs. A partial import must not be treated as a complete source inventory when deciding which existing rows to remove; the engine concludes that a record disappeared only after a completed pass.

Operators reach pipelines through an admin API behind the application’s admin secret: each pipeline’s health and its unreachable-source streak, a run on demand, the run history with the rows a run rejected and why, a reset, and the answers to conflicts and unknown outcomes. There is no operator screen; locally, wildo context pipelines reads the same listing. For writes, decide what staff see when an outcome is unknown, and which roles may change records in the other system: the tool’s permissions decide who may ask, and the service account’s permissions at the vendor decide what can be done.