Concepts

Concepts

What’s an environment?

Each environment is isolated from the others to prevent unintended interference between development, testing, and production processes.

Each environment has its own API keys, and all the workflows in the environment share the same API key. Workflow executions in all environments are billed.

You can’t promote a workflow from one environment to another environment. Instead, you can leverage workflow versioning, rollouts , sanity test, backtesting, experiments, and deployments to safely apply changes.

What’s a workflow?

Sperta lets you build any decision workflow to make real-time decisions. Sperta workflows are powerful and support any DAG.

A workflow consists of nodes and connections. It starts at the start node and exits at one of the end nodes. There are one or more stages between the start node and end nodes.

The input features and decisions serve as the interface of the workflow.

A complex workflow
A complex workflow

What’s a feature?

Features are attributes such as name, age, credit score, and transaction amounts.

Each feature has a feature ID that uniquely identifies it in the workflow. The feature value has a data type, and the following data types are supported:

  • String: e.g., "john", "银联"
  • Double: Numbers with decimal places, e.g., -13.5, 0.95
  • Integer: e.g., 50, -100
  • Boolean: true or false
  • Timestamp: Timestamp represented in the RFC 3339 format, e.g., 2024-02-16T05:13:45Z . Use a string when passing it as an input feature.
  • JSON: JSON object, e.g., {"status": "pending", "amount": 51.3} . Numbers in the JSON will be assigned the Double type.
  • List: List of String, Double, Integer , Boolean, or JSON. All elements need to have the same data type. e.g., [150.0, 330.0, 200.0]
  • Person: a Person entity
  • Business: a Business entity

Features passed into the workflow are called input features. Before creating steps, you need to define the input features in the workflow.

Features generated by formulas or conditionals are called transformed features. To use transformed features in subsequent stages, you must put the transforms namespace in front of the step ID, for example, transforms.email_domain_in_block_list. Transformed features are also available in the output field of workflow execution results, where the transforms namespace will be omitted. Only three data types are supported for transformed features:

  • String
  • Double
  • Boolean

Features returned from data sources are called data source features. To use data source features in subsequent stages, you must put the sources namespace in front of the step ID, for example, sources.equifax_soft_pull.credit_score. Data source features are also available in the output field of workflow execution results, and the sources namespace will be omitted. To explore all available data source features, take a look at Data sourcesData sources

What’s a decision?

A decision is the primary outcome of a rule, a rule stage, and a workflow.

You can configure decisions at different levels:

  • In a workflow, you can decisions such as Decline, Review, and Approve.
  • In a rule stage, you can add a subset of decisions available in the workflow. In addition, you can also configure their priorities to resolve rule decision conflicts. For example, you can add Approve and Decline decisions and give Decline a higher priority. If the stage has two rules, one outputs an Approve decision, and one outputs a Decline decision, the final decision of the stage will be Decline.
  • In a rule, you can assign decisions to the If-Else statements.

What’s a stage?

A stage is a kind of node in the workflow, and it runs one or more steps.

Currently, Sperta supports the following kinds of stages:

  • Rule stage. A rule stage contains rule steps, and it outputs a single decision after resolving the decision conflicts among rules.
  • Transformation stage. A transformation stage contains formula steps and conditional steps, and it outputs features.
  • Data source stage. A data source stage contains data source steps, and it outputs features. Steps in the data source stage are run in parallel to reduce latency.
  • Sub-workflow stage. A sub-workflow stage contains sub-workflow steps. Take a look at Sub-workflowsSub-workflows to learn more.

What’s a step?

Steps are the smallest executable units of a stage.

Each update to a step results in a new version. Each version is immutable, which means you can’t update or delete a version. On the other hand, you can give each version a name.

Once you create or update a step, you also need to create a rollout to use the step version in the stage.

image

What’s a rule?

A rule consists of If-Else statements that outputs decisions depending on the true/false outcomes of expressions.

At a minimum, a rule should have one If statement with an expression and one Else statement.

image

You can add as many Else if statements as you want. Each decision you use in the rule must be defined in the rule stage.

What’s a formula?

A formula transforms one or more features into a new feature with an expression. You need to define the data type of a formula, and the output of the expression needs to match this data type.

image

To use the transformed feature in subsequent stages, put the transforms namespace in front of the formula ID, for example, transforms.email_domain_in_block_list.

What’s a conditional?

Similar to a decision table, a conditional outputs one or more features based on conditions.

image

To use the output features of a conditional in subsequent stages, put the transforms namespace in front of the conditional ID, for example, transforms.pricing.credit_limit.

What’s a data source?

Data sources let you call third-party APIs. Sperta provides pre-built integrations with popular data providers as well as HTTP connectors for any JSON APIs.

image

To use the data source feature in subsequent stages, put the sources namespace in front of the data source ID, for example, sources.ca_searches.match_status.

Take a look at Data sourcesData sources to learn more.

What’s an expression?

An expression combines features, literals, and operators to output a value.

Sperta has its own expression language, SEL. Take a look at Expression languageExpression language to learn more.

What’s a rollout?

A rollout adds a step version to the workflow. After creating or updating a step, you must create a rollout to use the new step version in the workflow.

Creating a rollout results in a new workflow version. You still need to deploy the workflow version to go live.

You can create a rollout in two modes:

  • Active mode. The step will be run, and the outcome of the step will be used in the workflow. For rules, you can also specify a rollout percentage from 1% to 100%.
  • Shadow mode. This mode is only available for rule steps. When a rule is in the shadow mode, the decision of the rule won’t impact the decision of the workflow. This way, you can analyze the performance of the rule before switching to active mode.
image

Note that the following restrictions apply to rollouts:

  • A rule can only have one Active rollout and one Shadow rollout. If you create a rollout in the same mode as an existing one, the new one will replace the old one.
  • A formula or conditional can only have one Active rollout, so a new rollout of the same step will replace the existing one.
  • You can’t delete the rollout of a formula, conditional, or data source if it’s used in subsequent stages.

What’s a workflow version?

Workflow versioning helps you audit changes to the workflow and deploy changes safely.

The following changes in a workflow will result in a new workflow version:

  • Changes to the workflow graph and its decisions
  • Changes to rollouts

The following changes will not result in a new workflow version:

  • Changes to steps
  • Changes to input features
  • Changes to the workflow name, description, or settings
  • Changes to the workflow version name
User actionDateWorkflow versionRule version
Create workflow
January 23, 2024
fe3146c4
Update workflow name
January 23, 2024
fe3146c4
Update workflow, add rule stage
January 24, 2024
06319d37
Create input features
January 24, 2024
06319d37
Create a rule
January 25, 2024
06319d37
9042d311
Create a rollout for the rule
January 25, 2024
d07a52db
9042d311
Deploy the latest workflow version
January 26, 2024
d07a52db
9042d311

What’s a deployment?

Once you’ve integrated with the Execute Workflow API, you can deploy a workflow version or an experiment by creating a new deployment. Take a look at DeploymentsDeployments to learn more.