OP-004: Invoke job by client id, JSON parameters

This process backs the ExecuteJobWithJsonAndClientId operation. It follows the same shape as OP-006, the canonical flow, but replaces the positional-value naming step with a JSON-parsing step that runs before the allow/deny gate. Transaction boundary: none.

Field	Value
Operation ID	OP-004
Trigger	SOAP caller invokes ExecuteJobWithJsonAndClientId
Entry operation	ExecuteJobWithJsonAndClientId
Owning component	UC4Service.ExecuteJobWithJsonAndClientId
Inputs	environment (short), jobName (string), jsonKeyValuePairs (string)
Outputs	UC4Result — the mapped downstream result, or an empty result if the job is blocked
Failure behavior	An unhandled exception is surfaced by the WCF framework as a generic SOAP fault carrying full exception detail

Request and response

Direction	Element	Type	Declared in	Notes
Request	environment	short	UC4Service.cs	Client id identifying the environment
Request	jobName	string	UC4Service.cs	The job to invoke
Request	jsonKeyValuePairs	string	UC4Service.cs	JSON-encoded key/value parameters, parsed before the gate
Response	<return>	UC4Result*	UC4Service.cs	Mapped downstream result, or an empty UC4Result if blocked

Steps

1. WCF dispatcher activates UC4Service as in OP-006.
2. Log the invocation at INFO — BR-UC4-008.
3. Enforce.ArgumentNotNull rejects a null jobName — BR-UC4-004.
4. On failure: throws → detailed WCF fault.
5. Parse jsonKeyValuePairs into a parameter collection — before the allow/deny gate runs — BR-UC4-013.
6. On failure: malformed JSON throws → detailed WCF fault, even for a job the rule set would have blocked.
7. UC4Service.IsJobAllowed reads uc4.rules and evaluates the gate exactly as in OP-006 step 4-6 — BR-UC4-001, BR-UC4-002, BR-UC4-003.
8. On failure: a missing/malformed rules document or invalid regex throws → detailed WCF fault.*
9. If not allowed: return new UC4Result(), discarding the explanatory message — BR-UC4-005. Not a fault.
10. Otherwise: continue to step 7.
11. Resolve the downstream address and stamp the host identity, exactly as in OP-006 step 9 — BR-UC4-010, BR-UC4-011.

Origin: Step 7's downstream client construction is implemented in SAIF.Web.API.Clients / SAIF.Services.UC4 (external packages, not documented by this run) and executed within this operation.* - On failure: a missing setting or unreachable address throws → detailed WCF fault. 8. Forward the parsed parameters to the downstream IUC4Service.ExecuteJob. - On failure: a downstream exception propagates unchanged → detailed WCF fault. 9. Map the downstream result field-by-field onto the published UC4Result — BR-UC4-012. - On failure: a null downstream result may throw.* 10. WCF dispatcher serializes the UC4Result and returns it.

Process flow

flowchart TD
    A["Activate UC4Service"] --> B["Log invocation<br>at INFO"]
    B --> C["Enforce jobName<br>not null"]
    C -->|"null"| CFAULT["Detailed WCF fault"]
    C --> D["Parse jsonKeyValuePairs"]
    D -->|"malformed JSON"| DFAULT["Detailed WCF fault"]
    D --> E["Read uc4.rules,<br>evaluate gate"]
    E -->|"read/parse fails"| EFAULT["Detailed WCF fault"]
    E --> F{"Allowed?"}
    F -->|"No"| G["Return empty UC4Result<br>message discarded"]
    F -->|"Yes"| H["Resolve downstream address,<br>stamp host identity"]
    H -->|"missing setting"| HFAULT["Detailed WCF fault"]
    H --> I["Forward parsed parameters<br>to downstream service"]
    I -->|"downstream throws"| IFAULT["Detailed WCF fault"]
    I --> J["Map downstream result<br>to published UC4Result"]
    J --> K["Serialize and return"]
    G --> K

Transaction and side effects

Aspect	Finding
Unit of work	None
Commit point	Not applicable — no persistence
Records written	None locally
Downstream calls	UC4Client.ScheduleJob → downstream UC4 scheduling service
Shared state touched	None
Repeat-call behavior	Not idempotent from the host's perspective

Faults and error handling

Failure	Fault type the caller receives	Produced by	Source
jobName null	Generic SOAP fault, full exception detail	The WCF framework	UC4Service.cs
Malformed jsonKeyValuePairs	Generic SOAP fault, full exception detail (even for a job that would have been blocked)	The WCF framework	UC4Service.cs
uc4.rules missing/malformed or invalid regex	Generic SOAP fault, full exception detail	The WCF framework	UC4Service.cs
Downstream construction/call failure	Generic SOAP fault, full exception detail	The WCF framework	Uc4Client.cs

UC4Service carries [LogErrorBehavior], an external IServiceBehavior whose implementation is not in this repository; its contribution is observability, not fault shaping — see Faults and error pipeline.

Authorization

Requirement	Enforced by	Source	Applies to
None in code	Nothing — no attribute or programmatic check exists	UC4Service.cs	This operation

Related documentation

• Index
• Overview
• Architecture
• Activation and hosting
• Operations
• Faults and error pipeline
• Authentication and authorization
• Dependencies
• Configuration
• Operations and processes
• Business rules
• Operational runbook
• Tech debt

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

• src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs
• src/WCF/SAIF.Services.WCF.UC4.Host/Uc4Client.cs