QGenda System API — Full REST v2 Coverage, Generated from the Vendor Spec Deliverable: A Mule 4 System API that exposes every documented QGenda REST API v2 endpoint (156 operations) behind one RAML contract, with managed authentication, token caching, gzip, date-range validation and consistent error mapping, so Process and Experience APIs can use provider scheduling data without touching QGenda directly. Objective: Healthcare organizations run provider scheduling, on-call, time tracking and credentialing in QGenda, but every team that needs that data ends up writing its own client: storing a QGenda user's credentials, working around inconsistent parameter casing, and finding out the hard way that QGenda silently truncates long date ranges. This Blueprint replaces those one-off clients with a single governed System API. It mirrors QGenda's API one-to-one and adds the safety rails QGenda doesn't provide. Because it's generated from QGenda's published Postman collection, it stays current with the vendor's docs. What's Getting Built /schedule (System API) — schedule entries, audit log, open shifts and rotations; ranges validated against QGenda's limits · GET /schedule, GET /schedule/auditlog, GET /schedule/openshifts, GET /schedule/rotations /staffmember (System API) — staff CRUD plus tags, skillsets, profiles, pay modifiers, badge IDs and locations · GET /staffmember, POST /staffmember, PUT /staffmember, GET /staffmember/{staffId}, PUT /staffmember/{staffId}, DELETE /staffmember/{staffId} /request (System API) — time-off and schedule requests, approved requests, request limits · GET /request, GET /request/approved, GET /requestlimit, POST /requestlimit /task (System API) — tasks, task shifts, task tags and task locations · GET /task, POST /task, POST /task/{taskId}/taskshift /location (System API) — locations, location staff, FTE, tasks and tags · GET /location, POST /location, PUT /location/{locationId}, GET /location/{locationId}/staff /timeevent (System API) — clocked and logged time · GET /timeevent, POST /timeevent, PUT /timeevent/{timePunchEventKey} /availableshifts (System API) — open available shifts and assignment · GET /availableshifts, GET /availableshifts/{shiftKey}, POST /availableshifts/{shiftKey}/assign /credentialing (System API) — provider records, appointments, files, workflows, privileges, payer enrollments, contacts, corporate entities · GET /credentialing/staff/{staffId}/records, GET /credentialing/staff/{staffId}/file, GET /credentialing/workflows /dailycase (System API) — daily cases, patient encounters, rooms and daily configurations · GET /dailycase, POST /dailycase, GET /daily/patientencounter /company (System API) — companies, organizations, tags, profiles, users, pay codes, pay rates, staff targets, notification lists · GET /company, GET /organization, GET /tags, GET /user, GET /paycode /health (System API) — liveness; deep=true also proves QGenda authentication works · GET /health qgenda-token-store (Object Store v2) — in-memory, non-persistent cache of the QGenda bearer token, refreshed before expiry · os:retrieve, os:store QGenda REST API v2 (System of record) — the vendor API at QGenda's documented base URL https://api.qgenda.com/v2 · POST /login (internal only) Prerequisites A QGenda API user (email and password) with API access to every company the API must read or write. Admin-tab access is required for Available Shifts, and the "Available Shifts API Access" company setting must be enabled. The companyKey GUID for each QGenda company you'll query. Anypoint Platform access to the target environments, and a Connected App (client credentials) for CI/CD deployment to CloudHub 2.0. Mule runtime 4.11.0 on Java 17, Maven, and access to the MuleSoft releases and Anypoint Exchange repositories. An AES encryption.key per environment, stored as a CloudHub secure property. Python 3, to re-run the generator when QGenda changes its API. Your organization's approval for an integration account to hold QGenda data, which may include PHI on daily cases and patient encounters. This approval usually takes longer than the build. (suggested) Choose your path Mirror QGenda (this Blueprint) — Choose this when several consumers need broad QGenda access and you want one governed client. Paths, parameters and bodies pass through, so QGenda's own docs remain the reference. Curated canonical model — Choose this when only a few consumers need a small part of QGenda (e.g. "who is on call now"). Put a thin Process API with a canonical Shift / Provider model on top of this System API instead of reshaping the System API itself. (suggested) Architecture 1. Generate the contract and flows from QGenda's spec QGenda's docs site (restapi.qgenda.com) is a Postman Documenter page. Download the collection JSON it loads and check it in as spec/qgenda-postman-collection.json. Write a generator (tools/generate.py) that emits four files from the collection: the RAML, one APIkit flow per operation, a DataWeave routing table (dwl/qgenda/operations.dwl), and an endpoint map. Exclude /login. Why generate: QGenda documents 156 operations. Hand-writing them causes drift and typos, while generating makes "pick up QGenda's new endpoints" a one-command change. Never hand-edit generated files. Lower-case static path segments. QGenda's casing is inconsistent (/PayCode, /Credentialing/...), and lower-casing merges variants into one clean resource tree. Keep the original QGenda path in the routing table for forwarding. RAML needs one URI-parameter name per tree position (:taskid vs :taskId, :staffKey vs :staffId). Pick the most common spelling per position and substitute by position. Make query parameters camelCase in the API and record QGenda's exact name (companyKey → CompanyKey). Expose OData as select/filter/orderby/expand and forward as $select etc. Mark parameters required only where QGenda's docs say REQUIRED without a condition ("REQUIRED if …" stays optional), so APIkit rejects bad calls before they reach QGenda. Escape $ in generated DataWeave strings. "$select" is string interpolation in DataWeave and compiles as a variable reference. 2. Build the shared proxy sub-flow Every generated flow does just two things: set vars.qgendaOperationId and flow-ref to qgenda-proxy. All behavior lives in one hand-written, tested place. proxy.dwl#buildRequest takes the operation's metadata and returns: method, QGenda path template, URI params, mapped query params, whether to send a body, and validation errors. Pass URI params through http:uri-params against the {name} path template, so the HTTP connector encodes values (e.g. ABC 123). Send the body for POST/PUT/PATCH. For DELETE, send it only if the caller sent one; some QGenda deletes, such as badge ID removal, take a body. Use two http:request operations with sendBodyMode="ALWAYS" / "NEVER" rather than relying on AUTO. Pass status codes (e.g. 201), Content-Type and Content-Disposition through unchanged, so binary credentialing files and multipart /integration/file uploads work without special flows. 3. Authenticate once and cache the token POST /login sends email and password form-encoded in the body. QGenda rejects credentials in the query string. Read access_token, token_type and expires_in. Cache {authorization, expiresAt} in a non-persistent Object Store, so the token never touches disk. Refresh qgenda.token.refreshSkewSeconds (default 120) before expiry. When QGenda returns 401, log in again and retry exactly once. A second 401 is a credentials problem, not an expired token, so it maps to 502. Don't use target/targetValue on the login request. Save the payload, call, read the status and body, then restore the payload. This is simpler and behaves the same under MUnit mocks. 4. Normalize dates and enforce QGenda's range limits Accept ISO yyyy-MM-dd and convert it to QGenda's documented MM/dd/yyyy. If the caller supplies dateFormat, forward dates unchanged, because QGenda will interpret them with that format. QGenda silently truncates ranges over its limits. Reject them with 400 instead, so no consumer gets partial data without knowing it: QGenda endpoint Max days between start and end schedule, schedule/auditLog, schedule/openshifts, request, request/approved, timeevent, dailycase, daily/patientencounter 100 schedule/rotations 380 AvailableShifts 30 (31 days counting both ends) The 100-day limits apply only when the response is compressed (31 otherwise). Always send Accept-Encoding: gzip and decompress with the Compression module. Wrap decompression in a try, so a body marked gzip but not actually compressed passes through. Reject impossible ISO dates (e.g. 2026-02-30) and end-before-start with 400. Keep QGenda's quirk as-is: GET /timeevent treats endDate as exclusive. Document it rather than silently changing the semantics. 5. Map errors consistently Accept every status from QGenda (success-status-code-validator values="0..599") and decide in one place. This avoids error-handler gymnastics and keeps upstream bodies readable. Return a JSON error body on every failure: code, message, correlationId, timestamp, plus upstream.status and upstream.body when the error came from QGenda. Situation Status APIkit validation or date rules 400 QGenda 4xx except 401/407 same status; Retry-After kept on 429 QGenda 401 after retry, or login failure 502 QGenda 5xx 502 HTTP:CONNECTIVITY / HTTP:TIMEOUT 503 / 504 Put the error handler only on the main listener flow, not as the app default, so each error is mapped and logged once. APIkit resets outboundHeaders when it routes. Set X-Correlation-ID inside the proxy and the error handler, not only before the router. 6. Configure, package and deploy Use config-common.yaml plus config-<env>.yaml, with env defaulting to local, and keep each key in only one file. Set qgenda.host/port/basePath, responseTimeoutMs (120000), maxConnections (20) and http.port (8081). Store qgenda.email and qgenda.password encrypted (AES, CBC) in config/secure/secure-config-<env>.yaml, and list encryption.key in mule-artifact.json secureProperties. Pin mule-http-connector 1.12.2 and mule-sockets-connector 1.2.9. Sockets 1.2.7 and earlier need commons-io, which Mule 4.11 no longer exports to plugins, so deployment fails with NoClassDefFoundError: org/apache/commons/io/output/ByteArrayOutputStream. Deploy to CloudHub 2.0 with a deploy-ch2 Maven profile and Connected App credentials taken from environment variables. The listener is plain HTTP because CloudHub 2.0 terminates TLS at its ingress. Mule 4.11 warns "Connection is not secure", which is expected here. 7. Security and compliance Daily cases and patient encounters can carry PHI, so treat the app as in scope for HIPAA. Apply client-id enforcement and rate limiting in API Manager, and allow-list only known Process APIs. (suggested) Use TLS 1.2/1.3 only to QGenda, which is what QGenda supports. Java 17 disables older protocols by default. Keep QGenda credentials only as encrypted secure properties, with the key supplied at runtime. Keep the bearer token in memory only. Never log request or response bodies, the login body, or Authorization. Keep HTTP wire logging (org.mule.service.http, org.mule.extension.http) at WARN. Log one INFO line per QGenda call: operation, method, path, status and latency. Errors log the mapped code and operation id. Sample payload — a schedule call and the error contract GET /api/schedule?companyKey={company_key}&startDate=2026-11-01&endDate=2026-11-30&includes=StaffTags&select=StaffId,TaskName → forwarded as GET https://api.qgenda.com/v2/schedule?companyKey={company_key}&startDate=11/01/2026&endDate=11/30/2026&includes=StaffTags&$select=StaffId,TaskName Authorization: bearer {token} Accept-Encoding: gzip { "code": "NOT_FOUND", "message": "QGenda rejected the request (HTTP 404).", "correlationId": "{correlation_id}", "timestamp": "2026-11-18T15:00:00Z", "upstream": { "status": 404, "body": { "Message": "{qgenda_message}" } } } Deterministic checks Every operation in the generated routing table is reachable: calling each one over HTTP with its required params against a mocked QGenda returns 200, and reaches QGenda through the flow for its own operation id. GET /schedule with ISO dates sends MM/dd/yyyy to QGenda, renames select/filter to $select/$filter, and sends Authorization: bearer {token} and Accept-Encoding: gzip. When dateFormat is supplied, dates are forwarded unchanged. A 101-day schedule range returns 400 with QGenda never called. A 31-day inclusive Available Shifts range returns 200, and 32 days returns 400. An end date before the start date, or 2026-02-30, returns 400. A missing REQUIRED param (e.g. companyKey on /request) returns 400, and an unknown path returns 404. Two calls in a row cause one login; the token is cached. A 401 from QGenda causes exactly one re-login and two QGenda calls, the second using the new token. If the 401 persists, the result is 502 UPSTREAM_UNAUTHORIZED. QGenda 404 → 404 with upstream.body; 429 → 429 with Retry-After; 5xx → 502; connectivity error → 503; failed login → 502 UPSTREAM_AUTHENTICATION_FAILED. A POST forwards the body, its Content-Type and QGenda's 201. /staffmember/{staffId} sends CompanyKey with QGenda's casing. The MUnit suite (src/test/munit/qgenda-sys-api-test-suite.xml, 20 tests) passes with application coverage ≥ {coverage_target}%. The reference build measured 98.91%. Testing and validation Run MUnit through the real HTTP listener and APIkit router, mocking only the three outbound http:request operations by doc:id (login, with-body, without-body). This proves routing, validation and error mapping end to end. Set munit.disable.lazy.initialization=true. With lazy init, APIkit can't find implementation flows, so every route returns 501. With eager init, all suites load into one app, so keep a single munit:config suite file. Mock payloads should be strings (#['[]']), not DataWeave streams. A stream mock reused across calls fails with "Cannot open a new cursor on a closed stream". Variables aren't visible inside mock then-return expressions. Use munit-tools:spy with store to capture vars.qgendaRequest and assert on it. The edge case that breaks a naive build: QGenda truncating a 100+ day pull, where the consumer silently loses data. The range test must assert that QGenda was never called. Against a real QGenda sandbox, compare GET /schedule row counts with the QGenda UI for the same company and range, and confirm includeDeletes=true returns IsStruck entries. (suggested) Phased rollout Phase 1 — Connect Get the API user and company keys, deploy to a non-production environment, and pass GET /health?deep=true. Smoke-test /company, /staffmember and a 7-day /schedule. (suggested) Phase 2 — Map and validate Onboard the first Process API. Validate schedule and staff data against the QGenda UI, test 100-day pulls and sinceModifiedTimestamp change tracking, and confirm write endpoints in a QGenda test company before allowing them in production. (suggested) Phase 3 — Production Apply API Manager policies, set alerting on 5xx/502 rate and QGenda latency, retire direct QGenda integrations, and add a CI step that re-runs the generator against QGenda's latest collection. (suggested) Success metrics Number of direct QGenda integrations retired: {current_direct_integrations} → 0. (suggested) Schedule pulls returning partial data because of truncation: none, since over-limit ranges are rejected. (suggested) p95 latency of GET /schedule for a {typical_range_days}-day range ≤ {target_p95_ms} ms. (suggested) Upstream error rate (502/503/504) below {target_error_rate}%. (suggested) Time to expose a new QGenda endpoint: one generator run plus tests. (suggested) Troubleshooting Deployment fails with NoClassDefFoundError: org/apache/commons/io/output/ByteArrayOutputStream — Likely cause: sockets connector ≤ 1.2.7, pulled in by an older HTTP connector, on Mule 4.11. Fix: pin mule-sockets-connector 1.2.9 and HTTP 1.12.x. Every route returns 501 NOT_IMPLEMENTED in MUnit — Likely cause: MUnit lazy initialization, so APIkit can't see the flows. Fix: set munit.disable.lazy.initialization=true and use one suite file. DataWeave compile error "Unable to resolve reference of: select" — Likely cause: "$select" in generated DataWeave is being interpolated. Fix: escape it as "\$select" in the generator. Schedule pulls stop at 31 days — Likely cause: something between this API and QGenda strips Accept-Encoding: gzip, so QGenda falls back to its 31-day limit. Fix: keep gzip end to end; check proxies and API policies. (suggested) Every call returns 502 UPSTREAM_AUTHENTICATION_FAILED — Likely cause: wrong or expired API-user password, wrong encryption.key, or the account lost API access. Fix: re-encrypt the credentials, then confirm with GET /health?deep=true. 403 on /availableshifts — Likely cause: the company setting "Available Shifts API Access" is off, or the API user lacks Admin-tab access. Fix: enable it in QGenda. Time events missing the last day — Likely cause: QGenda's timeevent endDate is exclusive. Fix: pass the day after the last day you want. "Unable to infer a output media type" in a set-variable — Likely cause: an object mixing Java and JSON values without an output directive. Fix: add output application/java ---.