The Workflow System

Workflows are how ShipGenius takes the repetitive parts of order handling off your plate. You describe what should happen and when it should happen, and every order that matches gets the same treatment automatically, without anyone opening it.

What a Workflow Is

A workflow is a short set of instructions saved to your account. It waits for something to happen, checks whether the record in front of it is one you care about, and then carries out the steps you've listed.

Every workflow has three parts:

• A trigger. The event that starts it, such as an order arriving from one of your stores.
• A condition. The test that decides whether this particular order is one the workflow should touch. Leave it off and the workflow applies to everything its trigger sends it.
• Steps. What actually happens, carried out in the order you list them.

That's the whole idea. Everything below is detail on those three parts.

What Can Start a Workflow

A workflow can wait for any of these:

• Order events. An order is created, updated, held, canceled, shipped, or partly shipped.
• Item events. An item is added to your catalog or one of its details changes.
• Shipment events. A label is created, or a label is voided.
• A schedule. The workflow runs on a repeating timetable you set, rather than reacting to a record.
• You, by hand. You press Run yourself. This is useful while you're still testing, and for anything you'd rather start deliberately.

One workflow can wait for more than one of these. If you want the same handling whether an order arrives from a store or you start it yourself, list both.

Deciding Which Orders It Applies To

Most workflows shouldn't run on everything. A condition narrows things down, and you build one with the same filter builder you already use elsewhere in ShipGenius, so there's no new syntax to learn.

You can test against:

• Order details, such as the destination address, what the customer paid for shipping, order notes, or a service that's already been chosen.
• Line details, such as the quantity or price of something on the order.
• Item details, such as SKU, dimensions, customs information, or the packing materials an item needs.

In plain terms, conditions let you say things like "orders heading outside the country", "orders containing a SKU that starts with XL", or "orders where the customer paid more than $50 for shipping".

One thing worth knowing: a workflow can only test against information that's on the order at the moment it runs. Details that don't exist until a label has been bought aren't available to a workflow that runs when the order first arrives.

What a Workflow Can Do

The steps are where the work happens. A workflow can:

• Route the order. Send it to a facility you name, let a routing guide decide, or pick whichever facility is cheapest.
• Decide how it ships. Set a carrier service outright, or hand the order to a rate group or shipping plan and let rate shopping choose at fulfillment time.
• Check the address. Validate it, and decide what should happen when it doesn't come back clean.
• Fill in customs information. For orders crossing a border, including how duties and taxes are handled.
• Work out the packaging. Run cartonization so the boxes are decided before anyone reaches the pack station.
• Adjust the order itself. Add, remove, or change a line, set reference fields, arrange a pickup, or give the order a fulfillment priority.
• Hold it for a person. Put the order on hold with a reason, so anything unusual gets a human eye instead of a guess.
• Leave a note. Add an order note so whoever opens the order next can see what happened and why.
• Produce paperwork. Generate a pack slip or another warehouse document.
• Update the store. Send fresh order details back to the marketplace the order came from.
• Call one of your own systems. Make a web request out to something you run, keeping any credentials in Workflow Secrets rather than writing them into the workflow.

Steps run in the order you list them. Any step can carry its own condition, so something can happen in certain cases only, and you can loop over the lines on an order to handle each one in turn.

Workflows and Scripts

There are two kinds of document. A Workflow is the one described so far: it has triggers and runs on its own. A Script has no triggers and only runs when you or another workflow calls it, and it can take values you fill in at the time.

Scripts are handy for anything you'd otherwise repeat. Write the steps once, then call the script from several workflows instead of copying the same logic into each of them.

Building One

Go to Automation, then Workflows, and choose New workflow.

The editor gives you two views of the same thing. Builder lets you assemble the workflow visually, and it's where most people should start. Code shows that same workflow written out as text, which is useful for reading a whole workflow at a glance or for pasting in one that somebody sent you. Switching between the two changes nothing about the workflow itself.

Alongside the editor you'll find three more tabs:

• Problems lists anything that would stop the workflow being saved, and it updates as you work.
• Dry run tries the workflow against a real record and shows you what it would do.
• Reference describes every trigger, action, and setting available to you, without leaving the page.

Trying It Before You Turn It On

It's worth checking a new workflow before it starts touching live orders, and there are two easy ways to do that.

Start with a dry run against a real order. It walks through your steps and reports what would have happened, without changing anything at all.

When that looks right, save the workflow but leave it disabled, and use Run to start it by hand against a single order. That's a real run with real effects, on a record you've chosen. Once you're happy with what it does, enable the workflow and it will start responding to its triggers on its own.

You can disable a workflow whenever you like. Disabling silences its triggers straight away, though a run that has already started will finish.

Keeping an Eye on What Ran

Every run is recorded. Open a workflow and you'll see its runs newest first, each with a status and a step-by-step log of what it did.

A run waits its turn as Pending, works as Running, and then finishes as Completed, Failed, or Timed out. When something goes wrong, the log tells you which step it was and what the trouble was.

You can also start a workflow from an order or another record using the Run Workflow action on that record. It's the quickest way to apply one workflow to one thing without leaving what you're looking at.

When Two Workflows Touch the Same Order

Workflows can overlap, and usually that's fine because each one is handling a different part of the order. Occasionally two of them run at the same time and both change the same field.

When that happens ShipGenius records a collision, so you can see it rather than wondering why a value isn't what you expected. If the two triggers have different priorities, the higher one wins and its value is the one that stays. Collisions are listed on the workflow, which makes a rule that keeps competing with another one easy to spot.

Every Change Is Kept

Saving a workflow creates a new version and keeps the previous one, so you can look back at what a workflow used to say. That matters when you're working out why an order from last month was handled the way it was.

A run always uses the version that was current when it started, so editing a workflow never changes what a run already underway will do.

A Practical Example

Here's how a business shipping both at home and abroad might set things up. Rather than one large workflow, it's usually clearer to write a few narrow ones:

• International, duties prepaid. Starts when an order is created, and applies to international orders where duties are prepaid. Fills in customs information, sets the service, and runs cartonization.
• International, duties unpaid. The same trigger with the opposite duties condition, and its own customs settings.
• Domestic. Starts when an order is created, and applies to anything going to a domestic address. Validates the address, routes to the nearest facility, and hands the order to a rate group so rate shopping picks the service.
• Anything unusual. Starts when an order is created, and applies to orders above a weight you'd rather look at yourself. Holds the order with a reason so someone reviews it.

Because each one's condition decides what it touches, they stay out of each other's way, and you can turn any single one off without disturbing the rest.

Best Practices

• Give each workflow one job. Several small workflows are easier to read, test, and switch off than one large one that tries to do everything.
• Write the condition before the steps. Being precise about which orders you mean is most of the work, and it's what keeps a workflow away from orders you didn't have in mind.
• Dry run first, every time. It costs nothing, and it's the difference between finding a mistake on your screen and finding it in a customer's package.
• Hold rather than guess. When a workflow can't be certain what to do, holding the order with a clear reason beats choosing something and hoping it was right.
• Say why in a note. An order note explaining what a workflow did saves the next person from working it out for themselves.
• Keep credentials in Workflow Secrets. If a workflow calls one of your own systems, store the credentials there rather than typing them into the workflow itself.

FAQs

Do I need to write code to use workflows?

Not at all. The Builder view covers everything, and conditions are built with the same filter builder you use elsewhere in ShipGenius. The Code view is there if you happen to like reading a workflow as text, but nothing asks you to use it.

Will a workflow run on orders that are already in my account?

No. A workflow reacts to events from the moment you enable it, so it won't sweep up orders that arrived beforehand. To apply one to an order you already have, open that order and use the Run Workflow action.

What happens if a workflow fails partway through?

The run stops at the step that failed and is recorded as Failed, and the log shows what went wrong. Steps that ran before it have already taken effect, so it's worth putting anything less predictable, such as a call out to another system, after the changes you definitely want. You can also tell an individual step to carry on rather than stop the whole run.

Can two workflows run on the same order?

Yes, and often that's exactly what you want, with each one looking after a different part of the order. If two of them happen to change the same field at the same time, the collision is recorded so you can see it and adjust.

Can one workflow start another?

Yes, by calling a script and passing values into it. There's a limit on how far that can chain, so a run caused by a run caused by a run will stop rather than carry on indefinitely.

How long can a workflow run for?

A couple of minutes by default, which is far longer than most workflows need. A run that goes past its limit stops and is recorded as timed out. When that happens it's usually because the workflow was waiting on a slow system somewhere else.