A use case model

Use Case: Access Provisioning to a Client Application via eSwit

[!NOTE] Here one sky-level Cockburn-style use case combines the separate user stories as alternative scenarios.

[!TIP]
Add the SVG Navigator extension to your Chrome to comfortably view the diagrams with zoom and pan in the separate tab.

[!WARNING] The "Client" prefix describing eSwit client organization and its actors bears the naming conflict with SWE client-server terminology. [TBC Val] to confirm w/Anthony if the ubiquitous language actually uses "Client". Align all naming against the real ubiquitous language.

Diagrams

[!WARNING] The activity diagram still shows the instant happy path only. The sequence, class, state, and container diagrams cover the generalized provisioning flow.

Coarse Model, С4 Container Diagram

[!WARNING] The diagram is intentionally limited by the use case described here. Must be expanded as the system grows and moved to the entire model level.

Finer UML Models

Database Models

Summary

• Title: Provision Access for Client Member to Client Application
• Level: Sky
• Subdomain: Access Provisioning
• Narrative: A Client wants to provide a new employee with access to its applications in a strictly controllable way. The use case implements eSwit process automation that provisions the required access to the Client Member either immediately or through an invitation flow, while keeping the decision, result, and audit trail visible to the client.

Scope

eSwit Access Provisioning.

This use case covers eSwit's responsibility for receiving a client access request, validating it against client access rules, coordinating provisioning through an integration, tracking the outcome, and preserving visibility and auditability.

The client_application_uuid identifies a configured Client Application record inside eSwit. eSwit resolves that record through Client Application Service before provisioning and uses its provisioning_type to decide whether the external Client Application should be called for immediate access or invitation creation. The same record also contains non-secret provisioning call configuration used by the Client Application Access Provisioning Adapter.

Actors

Primary

• Client Access Provisioning Operator: client-side eSwit role allowed to initiate, monitor, and handle access provisioning for Client Members to Client Applications

Supporting

• Client Member: employee, contractor, student, staff member, or external collaborator who may receive or lose access to client applications
• Client Application: application owned or used by the eSwit client where access must be created; it is external to eSwit
• eSwit Frontend: user interface used by the Client Access Provisioning Operator
• eSwit Backend: access management system coordinating validation, provisioning, persistence, audit, and integration calls

Stakeholders and Interests

• Client organization: wants new employees to receive required access quickly, consistently, and under control.
• Client Access Provisioning Operator: wants to request and observe access provisioning without manually coordinating with every application administrator.
• Client Member: wants the required application access to be available when work starts.
• Client security/compliance team: wants access decisions, results, and changes to remain visible, governed, and auditable.
• eSwit operations: wants provisioning outcomes and integration problems to be tracked clearly enough for support and remediation.

Preconditions

• The Client Access Provisioning Operator is authenticated in eSwit and is allowed to request access for the Client Member.
• The Client Member exists or is identifiable in eSwit.
• The Client Application is configured in eSwit with a provisioning integration.
• The Client Application record is available through Client Application Service and contains a provisioning type of INSTANT or BY_INVITATION.
• The Client Application record contains provisioning call configuration for the adapter, including endpoint and credential reference metadata.
• Client access rules for the requested application access are available to eSwit.

Minimal Guarantees

• eSwit rejects invalid or unauthorized requests before starting access provisioning.
• eSwit records accepted provisioning attempts and their latest known provisioning status.
• eSwit preserves enough information to show the latest known provisioning status.
• eSwit records provisioning error details when provisioning fails after the request is accepted, including eSwit's HTTP status and any observed Client Application HTTP status.
• eSwit preserves audit information for the request and outcome available at the time of processing.

Success Guarantees

• The Client Member has active access in the Client Application, or provisioning is tracked as pending through an invitation flow.
• eSwit records the provisioning result.
• eSwit updates access visibility for the Client Access Provisioning Operator.
• eSwit records audit evidence for who requested access, what access was requested, when it was processed, and what result was received.

Trigger

The Client Access Provisioning Operator requests access for a Client Member to a Client Application.

Main Success Scenario

User Story: As a Client Access Provisioning Operator, I want eSwit to provision a Client Member into a Client Application, so that the Client Member receives required access immediately during onboarding.

1. Client Access Provisioning Operator requests access for Client Member to a Client Application.
2. eSwit Backend validates that the request is allowed according to client access rules.
3. eSwit Backend gets the Client Application record by client_application_uuid.
4. eSwit Backend detects that the Client Application provisioning type is INSTANT.
5. eSwit Backend sends a provisioning request to the Client Application using the Client Application provisioning configuration.
6. Client Application returns a 2xx success response and provisions the Client Member immediately.
7. eSwit records the successful provisioning result.
8. eSwit Backend returns 201 Created with the provisioning record.
9. eSwit updates access visibility and audit trail.
10. Client Access Provisioning Operator sees that the Client Member has active access in eSwit Frontend.

Extensions

4a. Client Application requires invitation acceptance:

User Story: As a Client Access Provisioning Operator, I want eSwit to start provisioning even when the Client Application requires invitation acceptance, so that onboarding is tracked even before the Client Member completes the invite.

• 4a-1. eSwit Backend detects that the Client Application provisioning type is BY_INVITATION.
• 4a-2. eSwit Backend asks the Client Application to create an invitation using the Client Application provisioning configuration.
• 4a-3. Client Application returns a 2xx success response for the invitation workflow.
• 4a-4. eSwit records the provisioning status as PENDING_INVITATION_ACCEPTANCE.
• 4a-5. eSwit Backend returns 201 Created with the provisioning record.
• 4a-6. eSwit waits for webhook or polling confirmation.
• 4a-7. Client Member accepts the invitation.
• 4a-8. eSwit records the access as provisioned.

The following failure extensions apply when eSwit calls the Client Application in main step 5 or invitation extension step 4a-2.

F1. Client Application is unavailable:

User Story: As a Client Access Provisioning Operator, I want eSwit to detect provisioning failures, so that failed access automation remains visible instead of silently disappearing.

• F1-1. eSwit records the provisioning status as FAILED.
• F1-2. eSwit records error with UPSTREAM_UNAVAILABLE.
• F1-3. eSwit Backend returns 424 Failed Dependency with the provisioning record.
• F1-4. eSwit exposes the failed provisioning result to IT.

F2. Client Application rate limit is exceeded:

User Story: As a Client Access Provisioning Operator, I want eSwit to detect provisioning failures, so that failed access automation remains visible instead of silently disappearing.

• F2-1. eSwit records the provisioning status as FAILED.
• F2-2. eSwit records error with UPSTREAM_RATE_LIMIT_EXCEEDED and observed upstream status 429 Too Many Requests.
• F2-3. eSwit Backend returns 424 Failed Dependency with the provisioning record.
• F2-4. eSwit exposes the failed provisioning result to IT.

F3. eSwit integration lacks required permissions:

User Story: As a Client Access Provisioning Operator, I want eSwit to detect authorization failures during provisioning, so that I know the integration itself needs attention.

• F3-1. eSwit records the provisioning status as FAILED.
• F3-2. eSwit records error with UPSTREAM_WRONG_PERMISSIONS and observed upstream status 403 Forbidden.
• F3-3. eSwit Backend returns 424 Failed Dependency with the provisioning record.
• F3-4. eSwit exposes the integration configuration problem to IT.

F4. Integration credentials were revoked:

User Story: As a Client Access Provisioning Operator, I want eSwit to detect authorization failures during provisioning, so that I know the integration itself needs attention.

• F4-1. eSwit records the provisioning status as FAILED.
• F4-2. eSwit records error with UPSTREAM_CREDENTIALS_REVOKED and observed upstream status 401 Unauthorized.
• F4-3. eSwit Backend returns 424 Failed Dependency with the provisioning record.
• F4-4. eSwit exposes the integration credential problem to IT.

Modeling Plan:

Use case -> state diagram -> sequence diagrams -> domain objects -> ports/adapters -> tests