> For the complete documentation index, see [llms.txt](https://docs.osmosworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osmosworks.com/business-modules/service-configuration.md). # Service configuration This module covers how tenant administrators define services, stages, questions, documents, charges, value sets, and rules. ## Purpose A service is the blueprint for a customer request. It describes what information to collect, which documents to require, how much to charge, and how the flow progresses. Services are configured through the tenant-scoped API under `/api/v1/tenant/services`. ## Service lifecycle A service moves through these states: 1. **Draft** — created but not yet published. Can be edited freely. 2. **Published** — available for new customer requests. 3. **Archived** — read-only; cannot be edited or receive new requests. Allowed transitions: * Draft → Published (if validation passes) * Published → Archived * Archived → Restored (becomes draft/published state based on `published_at`) ## Creating a service A tenant admin creates a service with: * `name` (required, unique per tenant) * `currency` (defaults to tenant profile currency) * `partyRole` (label for the subject of the service, for example "Applicant") * `minParties` and `maxParties` (optional party count limits) * `description` and `hint` On creation, the service gets a default single ordinary stage. The admin can then add more stages. ## Stages Stages group questions, requirements, and charges into ordered steps. * **Ordinary stage** — collects answers and documents. * **Payment stage** — requires an invoice to be paid before it can be completed. Each stage has an `orderIndex` controlling display order, an optional `showRule`, and optional title/description. ## Questions A question belongs to a stage and has: | Field | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Stable identifier, unique within the service. Used by rules. | | `label` | Display text. | | `helpText` | Longer explanation. | | `hint` | Short admin-side note. | | `answerType` | One of `TEXT`, `LONG_TEXT`, `NUMBER`, `DATE`, `TIME`, `BOOLEAN`, `CONFIRMATION`, `SINGLE_CHOICE`, `MULTIPLE_CHOICE`, `EMAIL`, `PHONE`, `ADDRESS`. | | `appliesTo` | `REQUEST` (asked once) or `PARTY` (asked per party). | | `required` | Whether an answer is mandatory when the question is visible. | | `options` | Required for choice questions; list of `{label, value, active}`. | | `validation` | Optional validation rules stored as JSONB. | | `showRule` | Optional rule controlling visibility. | | `partyDetail` | Links a `PARTY` question to a party detail key for prefilling. | ## Requirements (documents) A requirement belongs to a stage and has: | Field | Description | | ---------------- | --------------------------------------------------------- | | `code` | Stable identifier, unique within the service. | | `name` | Display name. | | `instructions` | Guidance for the customer. | | `appliesTo` | `REQUEST` or `PARTY`. | | `required` | Whether the document is mandatory when visible. | | `reviewRequired` | Whether staff must review the document before completion. | | `needRule` | Optional rule controlling whether the document is needed. | ## Value sets Value sets are named lists of string values referenced by rules. A service can have many value sets. Each has a `code` unique within the service. Rules use `IN_SET` and `NOT_IN_SET` operators to test membership. ## Charges A charge belongs to a stage and has: | Field | Description | | ------------ | ------------------------------------------------------------------- | | `name` | Line item label. | | `basis` | `PER_REQUEST`, `PER_PARTY`, or `PER_QUANTITY`. | | `amount` | Unit price. | | `questionId` | For `PER_QUANTITY`, the number question that provides the quantity. | | `chargeRule` | Optional rule controlling whether the charge applies. | Pricing is calculated by `PricingService` from all charges whose rules pass. ## Rules Rules are JSONB conditions over answers. A rule is either: * A group: `all` (AND), `any` (OR), or `not` (NOT). * A condition: `answer` (scoped key), `operator`, and one operand (`value`, `values`, or `set`). Answer scopes are: * `request.` for request-scoped questions. * `party.` for party-scoped questions. Forward-only rule: a rule may only reference questions that come earlier in the flow. The `RuleValidator` enforces this and returns field-pathed errors such as `showRule.all[1].operator`. Operators by answer type are defined in `RuleOperatorCatalog`. Examples: * Text: `EQUALS`, `CONTAINS`, `IN`, `IS_ANSWERED`. * Number: `EQUALS`, `GREATER_THAN`, `BETWEEN`. * Date/Time: `BEFORE`, `AFTER`, `BETWEEN`. * Single choice: `EQUALS`, `IN_SET`. * Multiple choice: `CONTAINS_ALL`, `CONTAINS_ANY`. ## Publishing validation Before a service can be published, the backend checks: * The service is not archived. * Every ordinary stage has at least one question. * Every payment stage has at least one charge. ## Snapshots When a request is accepted, the application stores a `serviceSnapshot` JSONB containing the service's id, code, name, currency, party role, and party limits. This protects in-flight applications from later changes to the service definition. ## Permissions * `service.create` — create services. * `service.read` — list and view services. * `service.update` — edit services, stages, questions, requirements, charges, and value sets. ## Example: family visa service A tenant offering family visa assistance might configure: 1. Service "Family Visa" with currency `NGN`, party role "Traveller", min parties 1, max parties 6. 2. Stage "Traveler details" (ordinary): * Question `nationality` (single choice, options including `Nigeria`, `Ghana`). * Question `travel_date` (date). * Requirement `passport_copy` (required, review required). 3. Stage "Add-ons" (ordinary): * Question `express_processing` (boolean). 4. Stage "Payment" (payment): * Charge "Base fee" (`PER_PARTY`). * Charge "Express fee" (`PER_REQUEST`, chargeRule `request.express_processing == true`). 5. Value set `ECOWAS` listing member states. 6. Rule on the payment stage or charges using `request.nationality IN_SET ECOWAS`. This example is supported by the implementation as long as the service configuration endpoints are used. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.osmosworks.com/business-modules/service-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.