Beyond Fire-and-Forget: The Strongly-Typed Http Rule

In many workflow engines, an HTTP step is often just a “webhook”—a mechanism to fire data off to a third party and hope for the best. But in complex orchestrations, you rarely just need to send data; you need to exchange it. You need to fetch a user profile, confirm a payment status, or retrieve a weather report to decide the next logic branch.

At mQuark, we designed the Http Rule to be a first-class citizen of our type system. It isn’t just a side-effect; it is a full functional component that can send requests, process responses in a safe scope, and return strongly-typed data back to your workflow.

The Architecture: Request, Scope, and Result

The fundamental difference in the Actionful Http rule is that it supports Scoped Execution.

When you define an Http rule, you aren’t just defining a URL and a Method. You are defining a Result block. Here is the sequence of events that happens when the rule executes:

1. Request: The engine constructs the HTTP request (with your headers and typed body) and sends it.
2. Scope Activation: Upon receiving a response, the engine opens a temporary “Http Scope.”
3. Result Execution: The logic defined in your Result property is executed inside this scope.
4. Return: The value produced by the Result logic becomes the return value of the entire Http rule.

This means your Http rule effectively “morphs” its return type to match whatever you return from the Result block. If your Result logic processes a JSON response and returns a Number, your Http rule returns a Number.

A Real-World Example

Let’s look at a comprehensive example. In this workflow, we are sending a person object to an external API. Crucially, we want to capture both the HTTP Status Code and the raw response body, combining them into a single summary string.

Here is the XAML definition:

<Http BodyType="person" Method="Post" SkipStatusCodeCheck="True">
  <Http.Url>
    <StringConstant Value="https://webhook.site/a0ffd635..." />
  </Http.Url>

  <Http.Headers>
    <KeyedRule Key="some-header">
      <StringConstant Value="header-value" />
    </KeyedRule>
  </Http.Headers>

  <Http.Body>
    <ObjectBuilder ShapeId="person">
      <KeyedRule Key="Name">
        <GetInput />
      </KeyedRule>
      <KeyedRule Key="Age">
        <NumericConstant Value="45" />
      </KeyedRule>
    </ObjectBuilder>
  </Http.Body>

  <!-- The Result section -->
  <StringFormat Template="HTTP Status: $(status), Result: $(result)">
    <KeyedRule Key="status">
      <NumberToString>
        <GetHttpStatusCode />
      </NumberToString>
    </KeyedRule>
    <KeyedRule Key="result">
      <GetHttpResponse />
    </KeyedRule>
  </StringFormat>
</Http>

Breaking Down the Mechanics

1. Strongly-Typed Body Construction

Notice BodyType="person". Actionful enforces that the content inside <Http.Body> matches the person Model definition. We use an ObjectBuilder to construct this data on the fly. In this example, the Name property is dynamically pulled from the workflow input (<GetInput />), while Age is hardcoded. If you attempt to pass an invalid data type here, the workflow will fail validation before it ever runs.

2. Configurable Error Handling

We set SkipStatusCodeCheck="True". By default, the Http rule throws a workflow exception if the remote server returns a 4xx or 5xx error. However, in this scenario, we want to handle the error gracefully. By skipping the check, the rule proceeds to the Result block regardless of the outcome, allowing us to capture the failure details manually.

3. Scoped Result Processing

The <StringFormat> element represents the Result of this operation. Because it runs inside the Http Scope, it has access to two special context-aware rules:

• GetHttpStatusCode: Retrieves the integer status (e.g., 200, 404).

• GetHttpResponse: Retrieves the raw response body.

The rule formats these two values into a single string: “HTTP Status: 200, Result: { …json… }”. Because the StringFormat returns a string, the parent Http rule also returns a string.

Summary

The Http rule in Actionful is designed for transactional integrity. By executing your result logic within the context of the HTTP response, we ensure that data is validated and processed exactly where it matters — at the edge of your integration.

Whether you are building simple webhooks or complex state synchronizations, the combination of SkipStatusCodeCheck and the Result scope gives you full control over your external data exchanges.