State Engine Tutorial

... we see, the updateRental and deleteRental mutations return a validationViolation stating that it is not allowed to be called when the state is confirmed.

Associated entities in context

Let's take this thought a bit further. Let's extend the business requirement

A Rental can only be confirmed when a car and 2 to 4 drivers are assigned and every driver has a firstname and a lastname

Take a moment to consider this. When you take a look at our Driver entity configuration you see that a Driver without a firstname would be a valid entity item and we have no reason to change that. When a Driver is assigned to a Rental however, the Rental's possible state transition are dependent on the fact whether a Driver meets certain conditions or not.

From this follows we need to consider any associated entity when validating the Rental's transitions. When we take a look at our current configuration you might now ask, what the context was that our validation expression uses. By default it is only the item of the StateEngine's entity. But now the context must also include some of the associated entities. Let's add context configuration to the stateEngine that has that.

entity:
  Rental:
    stateEngine: 
      initial: requested      
      transition:
        confirm:
          from: requested
          to: confirmed
          validation: 
            expression: >
              count(rental.drivers) in [2..4] and 
              count(filter(rental.drivers, "firstname")) = count(rental.drivers)
 
        reject:
          from: requested
          to: rejected
          
        cancel:
          from: 
            - requested
            - confirmed
          to: canceled
 
        conclude:
          from: confirmed
          to: concluded
 
      context: 
        assoc: drivers          

As you might see we stated in the context the foreignKey of the rental item just as we would in a query. We can now use the variable value in our expressions or decision tables. You can add as many associations also nested as deep as necessary, please refer to the documentation for more.

Variables in context

We validate again with a FEEL expression using the filter expression that filters a list for all items that contain a certain attribute. The expression starts getting complicated and we also may want to use the same expression at other places.

For this we can add variables to the context that we can use in our observers.

entity:
  Rental:
    stateEngine: 
      transition:
        confirm:
          from: requested
          to: confirmed
          validation: 
            expression: if driversValid then true else "must have 2-4 Drivers, all with firstname"
 
      context: 
        assoc: drivers
        variable: 
          - nrOfDrivers: 
              expression: count( rental.driverIds )
            nrOfDriversWithFirstname:
              expression: count(filter(rental.drivers, "firstname"))
          - allDriversHaveFirstname: 
              expression: nrOfDrivers = nrOfDriversWithFirstname
          - driversValid:
              expression: nrOfDrivers in [2..4] and allDriversHaveFirstname

Note how we added some variables in the context. We ordered them in a list since we use some of the earlier defined in the later expressions. We can use any variable in the validation as demonstrated here.

Observe associated entities

When relying on associated entities for deciding about transitions we're facing the same problem we had with updating or deleting the state entity itself. In our example an API client could update a Driver item that is referenced from a Rental with the state confirmed in a way that it would prevent that state.

Even when not relevant for validations there might be a business requirement that prohibits changing of associated entity items to a state entity when the latter is in a certain state.

To make sure this does not happen we can add the regarded mutations to our observe list and write the state values in which a referenced Rental item must be in order to allow updating or deleting a Driver.

entity:
  Rental:
    stateEngine:             
      observe: 
        - entity: Driver
          from: 
            - requested
            - rejected
            - canceled
            - concluded

When a Rental has the state value confirmed it should not allow any update or delete of an associated Driver. Let's see what happens when we try to update the Driver of the Rental that is in the state confirmed.

entity:
  Rental:
    stateEngine:             
      observe: 
        - mutation: deleteCar
          from: 
            - requested
            - rejected
            - canceled
            - confirmed
            - concluded
          to: canceled    

mutation{ deleteCar( id: "111") { id validationViolations  } }

entity:
  Rental:
    stateEngine:             
      transition:
        confirm:
          from: requested
          to: confirmOrReject
 
      context: 
        assoc: drivers
        variable: 
          - nrOfDrivers: 
              expression: count( rental.driverIds )
            nrOfDriversWithFirstname:
              expression: count(filter(rental.drivers, "firstname"))
          - allDriversHaveFirstname: 
              expression: nrOfDrivers = nrOfDriversWithFirstname
          - rentalValid:
              expression: nrOfDrivers in [2..4] and allDriversHaveFirstname
          - isAdmin: 
              expression: if includes( @principal.roles, "admin") then true else false
 
          - confirmOrReject: 
              input:  [ 'rentalValid',  'isAdmin' ]
              output:                               state
              rules:
                -     [ 'true',         '-',        '"confirmed"' ]
                -     [ 'false',        'true',     '"rejected"'  ]
                -     [ '-',            '-',        ''            ]