Skip to content

How: Logic and Agile

💡 TL;DR - Collaboration drives Requirements, Tests, Logic Reports

Use API Logic Server with Behave: Working Software Now for Agile Collaboration, near instant iteration, and unified requirements capture / traceabilty / test suite development:

  1. Use the created Admin App as Working Software Now, enabling Business User Collaboration to capture logic requirements in Behave.

  2. Use these requirements to drive rule declaration, and develop tests that verify the scenarios work. Iterations are extremely rapid due to automatic logic ordering and optimization.

  3. Use the Behave Logic Report for requirements traceability: document the requirements, test results, including the rules that fired for each test.

This page describes an optional approach for using logic in a TDD-based Agile framework.

 

Automation + Collaboration: Fast, Right

Automated App Creation (Working Software Now) enables Collaboration to uncover Automated Rules.

API Logic Server Intro

This page explains how API Logic Server Automation, coupled with an Agile (TDD - Test Driven Development) Process, can dramatically improve Time to Market and reduce Requirements Risk:

  1. Automated App Creation: API Logic Server creates an API Logic Project with a single command. The project implements an Admin App and underlying API.

  2. Customer Collaboration: the Admin App (Working Software, Now) drives collaboration, resulting in Features (Stories), Scenarios (tests), and Logic Designs that define how data is computed, validated, and processed (e.g., issues email or messages, auditing, etc.).

  3. Automated Logic: the Logic Design often translates directly into Executable Rules, which can be entered as customizations into the created API Logic Project.

  4. Transparency: the Behave Logic Report documents the functionality of the system: Features (Stories) and Scenarios (tests) that confirm its operation. The report includes the underlying Rules, extending transparency to the implementation level.

  

Key Takeaway: automation drives Time to Market by providing working software rapidly; this drives agile collaboration to define systems that meet actual needs, reducing requirements risk.

Virtuous Cycle: the collaboration uncovers Logic Designs, which can be declared as spreadsheet-like rules for API Logic Server automation.

  

Resources

After you've reviewed the logic background, use this page to learn how to use logic. Key resources:

  1. Rule Summary
  2. Sample Database
  3. Behave is a framework for defining and executing tests. It is based on TDD (Test Driven Development), an Agile approach for defining system requirements as executable tests. * Here are some details for using Behave with API Logic Server.

  

Process Overview

The diagram below provides more detail on the development process, further explained in the sections below.

  

1. Create Api Logic Project

API Logic Server is used once you have a preliminary database design. Use your existing procedures for database design. Include at least minimal test data.

Then (presuming API Logic Server is installed), create the project with this command, using venv based installs:

ApiLogicServer create  --db_url= --project_name=

or, like this, using docker-based installs: 

ApiLogicServer create --db_url= --project_name=/localhost/ApiLogicProject

  

1a. Creates Admin App

The Agile objective of collaboration is typically best-served with running screens. The problem is, it takes quite a long time to create the API and screens to reach this point. And this work can be wasted if there were misunderstandings.

Ideally, User Interface creation would be automatic.

So, the API Logic Server create command above builds first-cut screens, automatically from the data model.

The app shown below (more detail here) is suitable for initial business user collaboration (further discussed below), and basic back office data maintenance.

You can customize it by editing a simple yamlfile (e.g, field captions, ordering etc.)

  

Key Takeaway: Admin App Automation enables collaboration, instantly.

  

1b. Also creates API

It is not difficult to create a single endpoint API. The problem is that it's quite a bit more work to create an endpoint for each table, with support for related data, pagination, filtering and sorting.

Ideally, API creation would be automatic.

So, the API Logic Server create command above builds such an API instantly, suitable for application integration, and creating custom User Interfaces. The API enforces the business logic described below.

The created project is customizable, using a standard IDE.

  

Key Takeaway: automatic API creation, with support for related data, pagination, filtering and sorting.

  

2. Collaborate with Admin App

As noted above, running screens are an excellent way to engage business user collaboration, and ensure the system meets actual user needs. Such collaboration typically leads in two important directions, described below.

  

2a. Iterate Data Model

You may discover that the data model is incorrect ("Wait! Customers have multiple addresses!!").

In a conventional system, this would mean revising the API and App. However, since these are created instantly through automation, such iterations are trivial. Just rebuild.

  

2b. Define Behave Scenarios

Running screens also spark insight about the Features ("Place Order") and Scenarios ("Check Credit"): "When the customer places an order, we need to reject it if it exceeds the credit limit". Capture these as described below.

Behave is designed for business user collaboration by making Features and Scenarios transparent. Start using Behave by defining one or more .feature files.

For example, see the place_order.feature, as tested by the Bad Order: Custom Service Scenario, below.

  

Add Custom Service

While the automatically-created API is a great start, you may uncover a need for a custom service. This is easy to add - it's only about 10 lines of Python (api/customize_api.py), since the logic (discussed below) is enforced in the underlying data access. For details, see here.

  

2c. Logic Design

We now choose a scenario (e.g, Bad Order), and engage business users for a clear understanding of check credit. This follows a familiar step-wise definition of terms:

Analyst Question Business User Answer
What do you mean by Check Credit? The balance must be less than the credit limit
What is the Balance? The sum of the unshipped order amount totals
What is the Order AmountTotal? The sum of the Order Detail Amounts
What is the Amount? Price * Quantity
What is the Price? It's copied from the Product (unaffected by subsequent changes)

We capture in text as shown below.

Note this "cocktail napkin spec" is short, yet clear. That's because instead of diving unto unnecessary technical detail of how (such as pseudocode), it focuses on what.

  

3a. Declare Logic (from design)

Business Logic is the heart of the system, enforcing our business policies. Logic consists of multi-table constraints and derivations, and actions such as sending email and messages. A core Behave objective is to define and test such behavior.

It's generally accepted that such domain-specific logic must require domain-specific code. The problem is that this is:

  • slow (it's often nearly half the system).
  • opaque to business users.
  • painful to maintain - it's no secret that developers hate maintenance, since it's less coding than "archaeology". A painful amount of time is spent reading the existing code, to understand where to insert the new logic.

Ideally, our logic design is executable.

So, API Logic Server provides Logic Automation, where logic is implemented as:

  • Spreadsheet-like rules for multi-table derivations and constraints, and

  • Python, to implement logic not addressed in rules such as sending email or messages

So, instead of several hundred lines of code, we declare 5 rules (more details here).

Rules are entered in Python, with code completion, as shown below. Observe how they exactly correspond to our design, and are executable by the API Logic Server rules engine:

Unlike manual code, logic is declarative:

  • automatically reused - re-use is usually achieved by careful design; rules make re-use automatic:
  • Since rules are about the data (not a specific transaction), they automate all the transactions that touch the data (add order, delete order, change order shipped date, etc). Even ones you might have overlooked (move order to different customer).
  • Since rules are enforced as part of the API, they are automatically shared across all screens and services.
  • automatically ordered - maintenance is simply altering the rules; the system computes their execution order by automatically discovering their dependencies. No more archaeology.
  • transparent - business users can read the spreadsheet-like rules. We'll exploit this in the Behave Logic Report, described below.

  

Key Takeaway: spreadsheet-like rules can dramatically reduce the effort for backend logic, and make it transparent

  

Key Takeaway: keep your Logic Design high level (what not how -- think spreadsheet), and your design will often map directly to executable rules.

  

3b. Code/Run Behave Scenarios

Implement the actual scenarios (tests) in Python (place_order.py), using annotations (@when) to match scenarios and implementations. In this project, the implementation is basically calling APIs to get old data, run transactions, and check results.

Execute the tests using the pre-supplied Launch Configurations:

  1. Run Launch Configuration API Logic Server
  2. Run Launch Configuration Run Behave Logic

The rules fire as transactions are run, and produce Logic Log files later used in Report Behave Logic (described below):

  1. test/api_logic_server_behave/behave.log - summarizes test success / failure
  2. api_logic_server_behave/scenario_logic_logs/Bad_Order_Custom_Service.log - Logic Log output.
  • The code on line 161 signals the name of Logic Log

  • Note the Logic Log actually consists of 2 sections:

    • The first shows each rule firing, including complete old/new row values, with indentation for multi-table chaining
    • The "Rules Fired" summarizes which rules actually fired, representing a confirmation of our Logic Design

You can use the debugger to stop in a test and verify results

  

4. Create Behave Logic Report

The log files are pretty interesting: a record of all our Features and Scenarios, including transparent underlying logic. The problem is that it's buried in some text files inside our project.

Ideally, publishing this in a transparent manner (e.g., a wiki accessible via the Browser) would be a great asset to the team.

So, API Logic Server provides report_behave_logic.py to create a Behave Logic Report - including logic - as a wiki file.

To run it, use Launch Configuration Behave Logic Report:

  1. Reads your current readme.md file (text like you are reading now), and

  2. Appends the Behave Logic Report: by processing the files created in step 3b

  3. Reading the behave.log, and

  4. Injecting the scenario_logic_logs files
  5. Creates the output report as a wiki file named report_behave_logic.md

  

Key Takeaway: Behave makes requirements and tests transparent; rules make your logic transparent; combine them both into the Behave Logic Report.

  

Process Summary: Automation + Collaboration

We've seen these key points:

  1. API Logic Server kick-starts projects with automated creation of Admin Apps.

  2. Working software promotes business user collaboration using Behave, to iterate the data model and create Logic Designs.

  3. Logic Designs are automated with spreadsheet-like rules.

  4. Behave creates an executable Test Suite.

  5. Test Suite execution creates a Behave Logic Report: your Features, Scenarios, Test Results, and the underlying rules-based logic.

Automation enables you to deliver projects faster; the Agile/Behave encourages collaboration to reduce requirements risk.

  

Appendix: Executing Basic Tests

In addition to Behave, you can use manual approaches for testing:

Click to see how to run Basic tests

After you've created the sample project, you can execute pre-defined tests as shown above:

  1. Start the Server (e.g., under VS Code, Launch Configuration ApiLogicServer)
  2. Open a terminal window, and cd test/basic; python server_test.py go
  3. Examine the log in the Debug Console

You can build similar tests for your systems as you would in any project, either in Python (as shown here), in shell scripts (see the supplied example), etc.