Skip to main content
ShumoulShumoul Developer Portalplatform.shumoul.com
Version: Latest

13. Angular Integration Guide

13.1 Integration guidance​

Authentication​

Use the app's existing HTTP interceptor / auth service exactly as for any other ERP API call — attach the same Authorization: Bearer {jwt} from normal login. There is no separate onboarding token, login, or auth flow to build.

When to show the survey​

Call GET /api/v1/onboarding/status after first login completes (not during/instead of the login screen), and again on every subsequent login until it returns isRequired: false:

this.onboardingService.getStatus().subscribe(status => {
  if (status.isRequired) {
    this.router.navigate(['/onboarding'], { queryParams: { step: status.currentStep } });
  } else {
    this.router.navigate(['/dashboard']);
  }
});

Do not show the survey during the registration form — it belongs strictly after activation/first login (see Chapter 5).

Rendering the survey​

GET /api/v1/onboarding/survey?lang={ar|en} returns steps in order, each with its questions. Respect isRequired (block "Next" on unanswered required questions, per currentStep) and visibleWhen (hide a question until the referenced answer is given, matching the exact value).

Saving answers​

Call POST /api/v1/onboarding/answers per step or per question — it's additive, so partial saves as the admin progresses are safe and expected, not just a single submit at the end.

Recommendation review screen​

Before calling apply, show the admin the recommendation response: summary (human-readable, bilingual), warnings (things that couldn't be set automatically, e.g. "no default warehouse exists"), and optionally settingsPatch for a technical/advanced view. Treat this as a genuine confirmation step, not a silent pass-through — apply changes real tenant settings.

Apply​

POST /api/v1/onboarding/apply with { sessionId, acceptAll: true }. overrides exists in the contract but is not processed yet — don't build UI for partial acceptance in this phase (see Known Limitations).

Handling 403​

answers, recommendation, apply, and skip return 403 for any authenticated user who isn't the tenant's Admin. This is not an error to retry or show a generic failure toast for — the recommended UX:

  • Gate the "Complete Setup" / onboarding entry point in the UI to only appear for admin-role users to begin with (the app already knows the current user's roles from login).
  • If a 403 is received anyway (e.g. stale UI state, role changed mid-session), show a clear "Only your account admin can complete this step" message rather than a generic error.
  • status/survey remain callable by any authenticated tenant user (Permissions.Onboarding.View) — a non-admin user can still see onboarding status/progress read-only if that's useful in your UX, just not act on it.

Never call the internal endpoint​

POST /api/internal/onboarding/apply-settings-patch on the Shumoul.Api host is service-to-service only. It does not accept a user JWT, requires a shared internal key Angular will never have, and is hidden from Swagger. Always go through POST /api/v1/onboarding/apply on the MultiTenancy host instead.

13.2 Claude Code prompt for the Angular team​

The block below is a ready-to-paste prompt for a Claude Code session working in the Angular repository. It intentionally does not assume any particular component library or state-management choice — adapt the "Project conventions" placeholders to match the actual Angular codebase before running it.

# Task: Implement Business Onboarding & Smart Configuration UI

Implement the Angular UI for the Business Onboarding & Smart Configuration feature, calling the already-live
backend at `Shumoul.MultiTenancyApi`. The backend is complete, tested, and documented — do not modify or
assume any backend/API changes are needed. Full reference:
docs.shumoul.com → Frameworks → Business Onboarding & Smart Configuration.

## Hard rules
- Do not call `POST /api/internal/onboarding/apply-settings-patch` directly, ever — that is a
  service-to-service-only endpoint on a different host and does not accept a user token.
- Do not build a separate login/auth flow for onboarding — use the app's existing authenticated HTTP client.
- Do not show the onboarding survey during registration — only after first login (post-activation).
- `apply` requires `{ acceptAll: true }` in this phase; do not build partial/override-acceptance UI yet.
- Treat `403` from answers/recommendation/apply/skip as "not the tenant admin," not a generic error.

## Endpoints (base: `/api/v1/onboarding`, all require the standard Authorization: Bearer {jwt} header)
- `GET status` — check whether onboarding is required and which step to resume on.
- `GET survey?lang=ar|en` — fetch steps/questions.
- `POST answers` — `{ answers: { [questionKey]: value } }`, additive/mergeable.
- `POST recommendation` — no body; returns a preview (summary, warnings, settingsPatch) — nothing is applied yet.
- `POST apply` — `{ sessionId, acceptAll: true, overrides: null }` — writes real tenant settings.
- `POST skip` — no body.

## Project conventions to follow (fill in before running)
- HTTP client / API service pattern: {describe existing pattern, e.g. a shared `ApiService` base class}
- State management: {NgRx / signals / services — describe existing pattern}
- Routing structure: {describe where a new `/onboarding` route/module should live}
- Component library / design system: {describe existing UI kit}
- i18n approach: {describe how ar/en strings are normally handled — the API already returns both}

## What to build
1. An `OnboardingService` (or extend the existing API service layer) with typed methods for all 6 endpoints
   above, matching the request/response shapes in the API Reference chapter exactly.
2. A route guard (or a check inside the post-login flow) that calls `status` after login and redirects to the
   onboarding wizard when `isRequired: true`, resuming at `currentStep`.
3. A multi-step wizard component rendering `survey` steps/questions, respecting `isRequired` and
   `visibleWhen`, saving via `answers` as the admin progresses.
4. A recommendation review screen showing `summary`/`warnings` before the admin confirms `apply`.
5. A "Skip for now" action wired to `skip`, shown only when `status.canSkip` is true.
6. Gate the wizard's mutating actions (answers/recommendation/apply/skip) behind the current user having the
   tenant Admin role in the UI layer, and handle a `403` response gracefully if it happens anyway.

Report back: files created/modified, how the existing HTTP/auth layer was reused (not replaced), and any
assumption you had to make about project conventions that I should confirm.