Get started with mQuark Actionful

Alpha Stage Notice
Please be aware that Actionful is currently in its alpha stage. As an early version of the software, you may encounter bugs, unexpected behavior, or features that are still under development. Your feedback during this phase is invaluable as we work to improve and stabilize the platform for its official release.

Overview

Actionful, a product by software company mQuark, is a powerful web application for creating and managing workflows. Users can design workflows using a graphical interface, or a code-first approach, with predefined actions or custom code in languages like Node.js, TypeScript, Python, and C#. Once a workflow is designed, it can be triggered by an HTTP endpoint. The platform’s distributed and highly scalable architecture ensures that each request is processed efficiently, with the final result returned to the user.

Getting Started

To begin using the Actionful application, users must first create an account.

New Users: Click the Register button and complete the registration questionnaire. After an mQuark administrator approves the request, the user receives an invitation email with a link to set up their password.
Existing Users: Simply log in with your email and password.

Organizations and Workspaces

Upon logging in, you’ll see a dashboard listing your organizations and workspaces. To start working, you must either create a new organization or be invited to an existing one.

Organizations have three membership levels:

Owner: Full control over the organization, including user management, ownership transfer, and billing.
Admin: Full control except for ownership and billing changes.
Member: Can work within assigned workspaces based on their specific permissions but cannot add or delete workspaces.

Each Actionful organization has a subscription, with three distinct tiers:

Sandbox: A free tier with limited API calls and a shared resource pool. It’s perfect for testing and getting started.
Developer: A monthly paid subscription that offers higher API limits, elevated processing priorities, and reduced latency for improved performance.
Enterprise: A custom-priced plan tailored to client needs. It can include dedicated resources, no API rate limits, and the highest level of scalability.

Within an organization, access to a workspace is determined by three permission levels:

None: The user has no access to the workspace.
Reader: Provides read-only access.
Contributor: Grants full access to the workspace.

Once you have access to an organization and a workspace, you can begin creating artifacts such as Rules, Functions, Models, and Endpoints.

Core Building Blocks

Workflows in Actionful are constructed from three primary components: Models, Rules, and Functions.

Type System and Models

All elements within an Actionful workflow are strongly typed, meaning they are designed to handle data of a specific type. This ensures robust type validation during the design of a workflow and enables the seamless composition of different elements.

Supported Data Types

Actionful supports the following built-in data types:

Void (void): No Data.
Boolean (boolean): True/false values.
Numeric (numeric): Integer or decimal numbers.
String (string): Text values.
DateTime (datetime): Dates and times.
Object: Custom data structure (model), referenced by its custom name.

Defining Custom Models

Users can create their own custom data structures, called Models. These models can be defined using either a graphical designer or a code-first approach. Each model must have a name that is a lowercase alphanumeric string, at least three characters long, and can contain optional dashes.

A model can contain one or more properties. Each property can be any of the standard types (except void) or another user-defined model.

To mark a property as required, use the ! prefix.
To indicate a collection of objects, use the [] suffix.

Example Models:

Here are two examples of how you can define models:

// The `address` model
Building: numeric
Street: string
Town: string
Zip: !string

// The `person` model
FirstName: !string
LastName: !string
DateOfBirth: datetime
Address: address
Hobbies: string[]

In the address model, Zip is a required string. In the person model, Address uses the address model as its type, and Hobbies is a collection of strings.

The Rules Engine

In Actionful, workflows are built from predefined elements called Rules. You can create and edit these rules using either the graphical designer or a code-first approach. Actionful uses XAML, a dialect of XML, to define these workflows.

Rule Categories

Every rule is categorized based on the data type it returns. This categorization is key to ensuring that rules can be composed together logically. The available categories are:

Structural: These utility rules don’t have a specific data type and are used to help build complex structures within other rules.
Action: Returns void (no data).
Boolean: Returns a boolean (true/false) value.
String: Returns a string (text) value.
Numeric: Returns a numeric (number) value.
DateTime: Returns a datetime value.
Object: Returns an object of a user-defined type.
Array Rules: Returns a collection of a specific type (e.g., boolean[], string[], numeric[], datetime[], or a collection of user-defined objects).

Composing Rules

Each rule can have multiple properties, which can be either a primitive type (like string or numeric) or another rule. This powerful structure allows you to nest rules within each other, creating an expression tree. A workflow is essentially a rule composed of a large number of other rules, much like how a mathematical expression is built from operators and values.

For instance, a NumberToString rule has a Value property that expects a Numeric rule. This means you can provide any rule that returns a number — such as a NumericConstant or a NumericCodeRule (which executes custom code) — to its Value property.

Custom Rules (Sub-Workflows)

While Actionful’s built-in rules are essential for building workflows, complex or frequently used logic can make a single workflow difficult to manage. To simplify this, you can create custom rules, also known as sub-workflows.

These custom rules are reusable building blocks that encapsulate specific logic. They are designed just like any other rule, with a name and clearly defined input and output types, allowing them to function seamlessly alongside built-in rules.

To use a custom rule, you simply call it from your main workflow using the special Call Rule. This rule acts as a bridge, connecting your custom logic to the rest of your workflow. This approach allows you to break down complex problems into smaller, more manageable components, making your workflows easier to design, read, and maintain.

User Functions: Extending with Code

While a workflow’s XAML definition can become complex, Actionful provides a powerful way to manage this complexity: User Functions. These functions allow you to implement intricate business logic using code, which you can then call directly from your workflows.

How User Functions Work

Each User Function has a defined name, clear input and output types, and a body of code written in one of the supported languages, such as JavaScript. You can even reference external packages (like NPM packages for JS) to extend their capabilities. These functions can be as simple or as complex as you need them to be.

Behind the scenes, your functions are deployed on the Azure cloud, leveraging the full potential of Azure Functions. This provides the performance and scalability profiles that correspond to your chosen subscription tier.

Integrating with Workflows

Once a User Function is defined, you can easily call it from your workflow using a Code Rule. This rule takes the function’s name as an input, acting as the bridge between your custom code and the visual workflow.

In short, Actionful allows you to seamlessly combine the best of both worlds: write code to handle complex business logic, and use the built-in rules to orchestrate the workflow’s execution.

Workflow Examples

Example 1: Calculating a Square and Sending a Notification

Here’s an example of a workflow that demonstrates composition. It takes a number as input, calculates its square, and sends a Slack message with the result.

// The `empty` model without properties

// The `slack-message` model
text: !string

<ToAction ValueType="empty">
  <Http BodyShapeId="slack-message" Method="Post">
    <ObjectBuilder ShapeId="slack-message">
      <KeyedRule Key="text">
        <StringFormat Template="The square of $(input) is: $(result)">
          <KeyedRule Key="input">
            <NumberToString>
              <GetInput />
            </NumberToString>
          </KeyedRule>
          <KeyedRule Key="result">
            <NumberToString>
              <NumericAggregate Operator="Product">
                <ArrayBuilder>
                  <GetInput />
                  <GetInput />
                </ArrayBuilder>
              </NumericAggregate>
            </NumberToString>
          </KeyedRule>
        </StringFormat>
      </KeyedRule>
    </ObjectBuilder>
    <Http.Url>
      <StringConstant Value="https://hooks.slack.com/services/some-webhook-id" />
    </Http.Url>
  </Http>
</ToAction>

Example 2: Reusable Custom Rules

Here is another set of rules that demonstrate reusable custom rules:

<!-- The `double` rule -->
<NumericAggregate Operator="Sum">
  <ArrayBuilder>
    <GetInput />
    <GetInput />
  </ArrayBuilder>
</NumericAggregate>

<!-- The `square` rule -->
<NumericAggregate Operator="Product">
  <ArrayBuilder>
    <GetInput />
    <GetInput />
  </ArrayBuilder>
</NumericAggregate>

<!-- The `square-or-double` rule -->
<!-- For a given number, square it if negative, or double otherwise -->
<Conditional>
  <NumericRelation Operator="LessThan">
    <NumericRelation.Left>
      <GetInput />
    </NumericRelation.Left>
    <NumericRelation.Right>
      <NumericConstant Value="0" />
    </NumericRelation.Right>
  </NumericRelation>
  <Conditional.IfFalse>
    <CallRule Reference="double">
      <GetInput />
    </CallRule>
  </Conditional.IfFalse>
  <Conditional.IfTrue>
    <CallRule Reference="square">
      <GetInput />
    </CallRule>
  </Conditional.IfTrue>
</Conditional>

Executing Workflows with Endpoints

To execute a workflow from an external application or service, you must first create an Endpoint. You can create as many endpoints as you need within a given workspace.

Creating an Endpoint

When you create an Endpoint, you select an entry rule — one of the rules you have defined in your workflow. The system then takes a snapshot of this entry rule and all other rules, models, and user functions it references. This process creates a unique HTTP endpoint that is ready to be called. The endpoint essentially encapsulates the business logic of its entry rule and inherits its input and output type signature.

Version Management with Immutable Endpoints

A key feature of endpoints is their stability: once created, an endpoint is immutable. This means that any subsequent changes you make to the rules, models, or user functions will not affect existing endpoints. To publish a new version of your workflow, simply create a new endpoint and, if necessary, remove the old one.

Calling an Endpoint

Endpoints are triggered using a standard HTTP POST request. Here is an example using cURL:

curl --location --request POST \
  'https://engine.mquark.com/api/endpoints/org.space.endpoint' \
--header 'Authorization: Basic <auth-token>' \
--header 'Content-Type: application/json' \
--data-raw '123'

Summary

Actionful is a scalable, strongly-typed workflow application from mQuark. Workflows are built from composable Rules using both graphical and code-first methods. For complex logic, users can define custom Models, code-based User Functions, and reusable Custom Rules. To execute a workflow, an immutable Endpoint is created, which ensures versioning stability. The platform leverages a high-performance, distributed cloud infrastructure, available through various subscription levels from free to enterprise.