Skip to content

OP-006: Invoke job by client id, positional values (canonical flow)

This process backs the ExecuteJobWithValuesAndClientId operation. It is the canonical flow for this host; the other seven operations are documented as deltas against it on their own pages. Transaction boundary: none — the host opens no unit of work, no transaction, and no compensating path; the forward call to the downstream service is the only side effect and it is not undone if anything after it fails.

Field Value
Operation ID OP-006
Trigger SOAP caller invokes ExecuteJobWithValuesAndClientId
Entry operation ExecuteJobWithValuesAndClientId
Owning component UC4Service.ExecuteJobWithValuesAndClientId
Inputs environment (short), jobName (string), values (params 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 src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs:186 Client id identifying the environment
Request jobName string UC4Service.cs:186 The job to invoke
Request values params string[] UC4Service.cs:186 Positional parameters; empty array if omitted
Response <return> UC4Result* UC4Service.cs:186 Mapped downstream result, or an empty UC4Result if blocked

Steps

  1. WCF dispatcher activates UC4Service through the parameterless constructor, which builds WcfEnvironmentService(OperationContext.Current.RequestContext) and LogService(envSvc) (UC4Service.cs:31, 38).
  2. On failure: activation failure surfaces as a WCF default fault.
  3. UC4Service.Logging sets the trace threshold to INFO and emits method:{method},jobName:{jobName} (UC4Service.cs:187, 259-262) — BR-UC4-008.
  4. On failure: a logging exception propagates as a WCF default fault.
  5. Enforce.ArgumentNotNull rejects a null jobName (UC4Service.cs:189) — BR-UC4-004.

Origin: Step 3 is implemented in Enforce.ArgumentNotNull in SAIF.Services.Utilities (SAIF.Framework.Core, external, not documented by this run) and executed within this operation.* - On failure: throws; caller receives a WCF default fault with exception detail. 4. UC4Service.IsJobAllowed reads uc4.rules from the environment service and deserializes it to UC4JobRules (UC4Service.cs:55-56) — BR-UC4-001. - On failure: a missing or malformed document throws at an unguarded dereference of rules.UC4Rules.Environments (line 61) → WCF default fault.* 5. IsJobAllowed selects the rule set whose ClientId equals environment (UC4Service.cs:61) — BR-UC4-001. - Sub-step (no matching rule set): allow unless environment == 100 (UC4Service.cs:64-77) — BR-UC4-002. No fault; the decision and its (discarded) explanatory message are computed. - Sub-step (rule set found): take AllowByDefault.ToBoolean() as the baseline, then scan Rules in order; the first case-insensitive regex or literal match on jobName flips the baseline and breaks (UC4Service.cs:80-106) — BR-UC4-003. An invalid regex in the rule document throws → WCF default fault.* 6. IsJobAllowed composes the explanatory message for the decision (UC4Service.cs:108-128). 7. If not allowed: UC4Service returns new UC4Result() and discards message (UC4Service.cs:191-194) — BR-UC4-005. This is not a fault — the caller receives an empty result with no reason. - Otherwise: continue to step 8. 8. UC4Service.GetParameters converts the positional values to arg1, arg2, and subsequent key/value pairs (UC4Service.cs:195, 227-235) — BR-UC4-009. 9. The UC4Client constructor resolves uc4coreapi.url and uc4coreapi.schedulejobroute from the environment service, builds ClientInfo from the host's MachineName/UserName and ApplicationId = "wcf_uc4", and constructs the packaged Proxy (Uc4Client.cs:24-33) — BR-UC4-010, BR-UC4-011.

Origin: Step 9'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 → WCF default fault. 10. UC4Client.ScheduleJob projects the pairs to a dictionary and calls the downstream IUC4Service.ExecuteJob(jobname, parameters) (Uc4Client.cs:50-54). - On failure: a downstream exception propagates unchanged → WCF default fault with exception detail. 11. UC4Client.ConvertFromClientToCoreContractForUC4Results maps the downstream SAIF.Services.UC4.UC4Result field-by-field onto SAIF.Core.Contracts.UC4.UC4Result (Uc4Client.cs:55-74) — BR-UC4-012. - On failure: a NullReferenceException is possible if the downstream result is null.* 12. WCF dispatcher serializes the UC4Result onto the default basicHttpBinding endpoint.

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 -->|"ok"| D["Read uc4.rules,<br>select rule set"]
    D -->|"read/parse fails"| DFAULT["Detailed WCF fault"]
    D --> E{"Rule set found?"}
    E -->|"No"| F["Allow unless<br>environment == 100"]
    E -->|"Yes"| G["AllowByDefault baseline,<br>first match flips it"]
    G -->|"invalid regex"| GFAULT["Detailed WCF fault"]
    F --> H{"Allowed?"}
    G --> H
    H -->|"No"| I["Return empty UC4Result<br>message discarded"]
    H -->|"Yes"| J["Name positional values<br>as arg1, arg2, in order"]
    J --> K["Resolve downstream address,<br>stamp host identity"]
    K -->|"missing setting"| KFAULT["Detailed WCF fault"]
    K --> L["Forward job to<br>downstream service"]
    L -->|"downstream throws"| LFAULT["Detailed WCF fault"]
    L --> M["Map downstream result<br>to published UC4Result"]
    M -->|"null result"| MFAULT["Detailed WCF fault"]
    M --> N["Serialize and return"]
    I --> N

Transaction and side effects

Aspect Finding
Unit of work None
Commit point Not applicable — no persistence
Records written None locally — downstream persistence, if any, is out of scope
Downstream calls UC4Client.ScheduleJob → downstream UC4 scheduling service
Shared state touched None
Repeat-call behavior Not idempotent from the host's perspective — each call forwards a new job-execution request to the downstream scheduler

Faults and error handling

Failure Fault type the caller receives Produced by Source
jobName null Generic SOAP fault, full exception detail The WCF framework — no IErrorHandler is confirmed for this class UC4Service.cs:189
uc4.rules missing/malformed Generic SOAP fault, full exception detail The WCF framework UC4Service.cs:61
Invalid rule regex Generic SOAP fault, full exception detail The WCF framework UC4Service.cs:80-106
Downstream construction/call failure Generic SOAP fault, full exception detail The WCF framework Uc4Client.cs:24-54

UC4Service carries [LogErrorBehavior], an external IServiceBehavior whose implementation is not in this repository; by the shape of its in-repository sibling, 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:186 This operation

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
  • src/WCF/SAIF.Services.WCF.UC4.Host/UC4JobRules.cs