Explore the declarative power of status-transition flows

This CDS model defines a simple service Morse that has a pass-through projection (an inferred signature) to a Controls entity, which has a position element that represents the control status at any given time. The projection defines three bound actions (engage...) each of which are for moving the control to a specific position.

Moving from the model to the physical world, the Controls entity represents a Morse control on a narrowboat, which has three positions, selectable by moving a lever. That lever controls the gearbox (and the throttle) and is how one selects forward gear, neutral, or reverse gear. With such controls, to get from forward to reverse, or vice versa, one must first go via neutral, so as not to damage the gearbox.

In other words:

• a control should start out in the neutral position
• can only be moved to forward, or reverse, from that neutral position
• can not be moved directly from forward to reverse, or from reverse to forward

This control state switching and limitation is what we will end up achieving, with help from the status-transition flow feature.

In this tutorial we’ll be testing the control state switching and limitations with unit tests, so we can cleanly describe them, run and re-run them as appropriate. We’ll use the cds test based harness which comes as a separate package @cds-js/cds-test.

👉 Install that package as a development dependency:

npm add @cap-js/cds-test

Let’s add some tests to check the basics of what we have defined, and also of what we expect, with regards to control state limitations.

👉 In a new test/ directory, create a file Basics.test.js with the following content:

import cds from '@sap/cds'

const { GET, POST, expect, defaults } = cds.test(import.meta.dirname + '/..')
defaults.path = '/odata/v4/morse'

describe('Basics', () => {

  it('allows the creation of new controls', async () => {
    const { status } = await POST('Controls', { ID: 1 })
    expect(status).to.equal(201)
  })

  it('gives new controls a Neutral default position', async () => {
    const { data } = await POST('Controls', { ID: 2 })
    expect(data.position).to.equal('Neutral')
  })

  it('prevents positions being specified on creation', async () => {
    const { data } = await POST('Controls', { ID: 3, position: "Reverse" })
    expect(data.position).to.equal('Neutral')
  })

})

There are three tests here, that check:

• the general creation of new controls
• that controls get a default position of Neutral
• that we cannot override that default and specify Forward or Reverse as the initial position for a new control

👉 Now put these tests to work:

cds test

You should see output that looks something like this:

  Basics
    ✔ allows the creation of new controls 
    ✔ gives new controls a Neutral default position 
    X prevents positions being specified on creation 

    Error [AssertionError]: expected 'Reverse' to equal 'Neutral'
        at TestContext.<anonymous> (file:///workspaces/cap-nodejs-dev-env/cap-status-transition-flows/test/Basics.test.js:20:30)
      actual: 'Reverse',
      expected: 'Neutral',
      showDiff: true,
      operator: 'strictEqual'
    }


 2 passed 
 1 failed 
 0.680s

OK, so our first two tests pass, but we’re not prevented from creating new controls with a non-Neutral position.

Let’s hold that thought.

Moving from creation to use of control instances, let’s add another batch of tests relating to transition. We’ll start with a single test.

👉 Create another new file Transitions.test.js, also in the test/ directory, with the following content:

import cds from '@sap/cds'

const { GET, POST, expect, defaults } = cds.test(import.meta.dirname + '/..')
defaults.path = '/odata/v4/morse'

describe('Transitions', () => {

  it('allows moving from Neutral to Forward', async () => {
    const { data } = await POST('Controls', { ID: 1 })
    const { status } = await POST(`Controls/1/engageForward`)
    expect(status).to.equal(204)
  })

})

Invoke this test with cds test Transitions, whereupon you should see something similar to this:

  Transitions
    X allows moving from Neutral to Forward 

    Error: 501 - Service "Morse" has no handler for "engageForward Morse.Controls".
        at async TestContext.<anonymous> (file:///workspaces/cap-nodejs-dev-env/cap-status-transition-flows/test/Transitions.test.js:10:22)
      response: {
        data: {
          error: {
            message: 'Service "Morse" has no handler for "engageForward Morse.Controls".',
            code: '501',
            '@Common.numericSeverity': 4
          }
        }
      },
      status: 501,
      code: '501',
      '@Common.numericSeverity': 4
    }


 1 failed 
 4.780s

If we take a step back we can see that:

• we can create new control instances
• new control instances by default have the Neutral position
• but we’re not prevented from creating instances with other positions
• there are no implementations for the bound actions such as engageForward

The status-transition flow feature can bring about what we want, and more. Even better, we can express our requirements purely declaratively, in the form of annotations.

👉 To the end of services.cds, add this:

annotate Morse.Controls with @flow.status: position;

annotate Morse.Controls actions {
  engageForward  @from: #Neutral  @to: #Forward;
  engageNeutral  @from: [
    #Forward,
    #Reverse
  ]                               @to: #Neutral;
  engageReverse  @from: #Neutral  @to: #Reverse;

};