Trailblazer 2.1: What you need to know.

Last updated 18 December 2017

After almost one year of development, the 2.1 release is very near, and we’re proud to tell you everything about the new features we were adding, and some internals we’ve changed.

Overall, the public APIs haven’t changed, or there are soft deprecations to explain what you need to do.

1. New call API

In versions before 2.1, the automatic merging of the params part and the additional options was confusing many new users and an unnecessary step.

# old style
result = Memo::Create.( params, "current_user" => current_user )

The first argument (params) was merged into the second argument using the key "params". You now pass one hash to call and hence do the merging yourself.

# new style
result = Memo::Create.( params: params, current_user: current_user )

Your steps use the existing API, and everything here is as it used to be before.

class Memo::Create < Trailblazer::Operation
  step :create_model

  def create_model(options, params:, **)
    # ..

The new call API is much more consistent and takes away another thing we kept explaining to new users - an indicator for a flawed API.

For a soft deprecation, do this in an initializer:

require "trailblazer/deprecation/call"

You will get a bunch of warnings, so fix all Operation.() calls and remove the require again.

2. Symbol vs. String Keys

If you mixed up :symbol and "string" keys when accessing the options context object, there are good news for you: we use symbol keys now wherever possible. Only namespaced keys like "contract.default.class" are still strings, but :model, :params or :current_user are all symbols.

result = Memo::Create.( params: params, current_user: current_user )

As always, you can still access the arguments via keyword arguments, as shown above. Nevertheless, these arguments must now be accessed and overridden with a symbol.

def my_step(options, **)
  options[:model] =

Nothing has changed in the implementation; we just changed the convention.

For a soft deprecation, do this in an initializer:

require "trailblazer/deprecation/context"

It will generate hundreds of warnings where you still use string keys but mustn’t, so change them and then remove the require.

2. Unlimited Wiring

Besides the fact that you can now use operations and activities in more complex compounds to model realistic applications and state machines, with 2.1 it’s possible to model flows in operations that go beyond the railway. This is often necessary when the control flow needs more than two track, or when extracting more complex flows into new operations is too complicated and thus not desirable.

Check the new → wiring docs.

For example, you can now actually use the failure track for logic, and easily deviate back to the right success track.

class Memo::Upload < Trailblazer::Operation
  step :upload_to_s3
  fail :upload_to_azure,  Output(:success) => :success
  fail :upload_to_b2,     Output(:success) => :success
  fail :log_problem
  # ...

This will result in the following diagram.

We call this the recover pattern.

However, you’re not limited to left and right track, you can connect arbitrary tasks, or solve more complex problems with branching circuits.

examples coming

For a more streamlined readability, we aliased the step DSL methods.

step :my_step
pass :always_success # alias success
fail :error_handler  # alias failure

Looking better, right?

3. Simpler Nested

in/out rewire

4. Tracing

The coolest feature.

4. Extended Macro API

6. Application Workflows and BPMN

Thanks to the refactored circuit engine in Trailblazer 2.1 and the new gem, any business process can be modeled and implemented now. Since we allow unlimited nesting of activities, it’s possible to start modeling from the domain level down to super low-level technical details.

Instead of reinventing, we make use of a subset of the BPMN standard that defines and structures workflows in hundred-thousands of applications world-wide. And, don’t you worry, you do not have to read 538 pages in order to use Trailblazer’s BPMN extension.

In this diagram, you can see a one-time-password signup process where the user needs to change the initial password after the first login, and then must log in again using those new credentials. Our new visual workflow editor and the trailblazer-workflow gem will help to plan, implement and maintain diagrams and logic. Both components are part of the new PRO plan launched in early 2018.

While you can model activities purely in Ruby, our editor will take away the pain of setting up application-wide workflows. And, naturally, all those “boxes” will still be Ruby code, exactly the way it is now, allowing you to focus on the implementation and us doing the control flow for you.

Once the new PRO version is ready for sign up, we will notify you on our Facebook page and link to it here.

New steps


10. New Gems