After subscribing to the Identity Cloud, an organization is typically given two environments to work in: a production environment and a development/staging environment. Each of these environments includes a flow (in each case a flow named standard). Flows are JSON files that contain configuration information for your Identity Cloud implementation: when it comes to an Identity Cloud-powered website or app, much of what users see, and much of what users are allowed to do, is determined by the flow. 

📘

An example? Well, does your sign-in screen appear in Norwegian? That can happen only if your flow contains Norwegian translations for all the sign-screen text elements.

Flows are also highly-customizable: by using either the Configuration APIs or Console’s Registration Builder, you can add or delete fields; change your forms; add translations; modify transactional email messages – the list goes on and on and on. The flow is a fundamental piece of the Identity Cloud infrastructure, and – with only an occasional exception – the flow is yours to do what you want with.

🚧

Of course, if you buy a car that car is also yours to do what you want with it: however, removing the engine or taking off all the tires leaves you with a car that isn’t especially useful. The same is true with a flow: yes, you can do almost anything you want with a flow, but unless you’re careful about what you’re doing you can also end up with a flow that, metaphorical-speaking, is missing an engine or a couple of tires. Your PRODUC_NAME representative can help if you aren’t sure whether or not you should be making a given change to a flow.

And while promotion is an extra step, it’s also a step that, from start to finish, can usually be carried out in less than a minute.

But even though the flows belong to you, there’s at least one major restriction imposed on your flows by ​Akamai​ organizations aren’t allowed to directly edit a production flow. Instead, if you need to make a change to a flow (even a minor change like correcting a misspelling), you must make that change to a copy of the flow (a copy stored in your development/staging environment), promote the flow to the production environment, and then configure your application/API client to use the newly-promoted flow. In other words, you can’t just change to the flow in the production environment and call it good.

So why not? Why can’t you directly edit a production flow? As it turns out, there’s a good reason for that: making production flows off-limits (or at least off-limits to direct editing) helps prevent you from inadvertently making a flow change that leaves your site in an unusable state. For example, suppose you’re editing a flow and, somehow, you delete the currentPassword field from the signInForm form. If you do that, here’s what your Hosted Login sign-in screen will look like when a user tries to log on:

As you can see, there’s a place for users to enter their email address, but there isn’t a place for users to enter their password. The net result? Anyone who logs on by using an email address and password won’t be able to log on.

Probably not the user experience you had in mind.

Preventing you from modifying a production flow decreases the chances of you making an … unfortunate … error such as the one we just showed you. Instead, any time you need to update a flow you first make your changes in the development or staging environment. That way, you can make – and test – all those changes before applying the update to your actual website. Suppose you did make a major mistake (like accidentally deleting the Password field). That’s OK: that mistakes affects only the dev environment, and you’ll have a chance to catch and to correct that mistake before it starts causing problems for your users.

After you’re satisfied that the flow has been correctly (and safely) updated, you can then promote the flow, which simply means moving a copy of the updated flow into your production environment.

A note about flow versions and version history

Each time you update a flow, a new version of the flow is created, and the old version is retained. That’s why flows have version numbers such as 20180625063027674812. The version number is actually a timestamp that indicates when the flow was created. For example, the version number (timestamp) 20180625063027674812 can be broken down as follows:

Or, because a picture can be worth a thousand words:

And if you update your flow on June 1, 2021 at 11:13 AM? In that case, the latest version of the flow will have a version number similar to this:

20210601111347768372

As mentioned a moment ago, each time you update a flow a new version of the flow is created and the older version of the flow is retained (the Identity Cloud saves the previous 100 versions of a flow). For example, the following flow has a total of five different versions, including the current version:

📘

Although it might look like we actually have 6 versions of the flow, HEAD is technically not a version; instead, HEAD is simply a way to refer to the latest version of a flow. In the preceding screenshot, HEAD refers to the flow 20180625063027674812, the latest version of the flow.

So why are we telling you all this? Mainly to point out that, when you promote a flow, version information in not copied to the production version of the flow. For example, the preceding flow shows 5 different versions, any one of which can be restored and used as the current version. However, when we promote the flow (e.g., when we copy that flow from the development environment to the staging environment) version information doesn’t get copied. Instead, the new flow, the one in the production environment, will have a version history that looks like this:

That’s not a problem: it’s just something to be aware of. And note that this is true even if your development flow and your production flow share the same name (e.g., testFlow). Version information isn’t copied from the development/staging environment to the production environment.

The update-a-production-flow workflow

So what happens when you do need to update a production flow? Here are the steps you’ll need to follow:

1. Find the production flow’s counterpart in your development or staging environment.

2. Modify and test the flow in the development/staging environment.

3. Promote the flow to the production environment.

4. Configure your API client to use the new flow.

The following sections of the document explore each of these steps in more detail.

Step 1: Find the production flow’s counterpart in your development or staging environment

To begin with, each flow in your production environment needs a corresponding flow in the development/staging environment. For example, by default you’ll have a flow named standard in the production environment and an identical flow (also named standard) in the development/staging environment. If you need to make a change to the standard flow you’ll make that change to the standard flow in the development environment and then promote the updated version of that flow to the production environment.

Now, what if you need an additional flow, perhaps because you need a different set of fields or a different set of forms? In that case, you’ll start by creating the new flow (or copy an existing flow) in the development/staging environment. Let’s say you call this new flow southAmericanFlow. At that point, your environments will look like the following:

As you might expect, you don’t have a version of southAmericanFlow in the production environment. And you won’t have a version of southAmericanFlow in the production environment until you promote the development version of the flow.

Incidentally, the two versions of a flow don’t have to share the same name: when you promote southAmericanFlow you can actually name the production version anything you want. That said, however, there are at least two advantages to using the same name for the two different versions of the flow. For one, that makes it easy to know which development flow you should edit if you need to make changes to the production flow southAmericanFlow: just look for the development flow by the same name. 

Second, if you promote a development flow named southAmericanFlow and the production application already has a flow by that name then the development flow replaces the production flow (i.e., it becomes the latest version of southAmericanFlow). That means you don’t have to change the value of the default_flow_name setting: after all, you’re still using a flow named southAmericanFlow.(That’s something we discuss in a little more depth in Step 4.)

If you’re using Console, a development flow won’t automatically replace a production flow with the same name; instead, you’ll be asked to confirm this operation. For example, here we’re trying to promote the standard flow to a production environment that already has a flow named standard:

If you click Cancel in the Choose an Application dialog, the flow won’t be promoted; if you click Yes a new version of standard (based on the standard flow in the development environment) is created . Note, however, that this won’t be the case if you use the Configuration APIs to promote the flow: in that case, the development flow will automatically overwrite the production flow.

Just something to be aware of.

But what if your two flows have different names; for example, what if your production flow is named southAmericanFlow and your development flow is named flowX? That’s fine: when you do the promotion then your production environment will have one flow named southAmericanFlow (which is unchanged) and a second flow named flowX. To start using the new flow, you’ll then have to change the values of both the default_flow_name and default_flow_version settings to reference the name and version number of flowX. It requires a little bit more effort on your part, but it works.

Step 2: Modify and test the flow in the development/staging environment

As you should know by now, all your updates and modifications must be made on your development flow  Make your changes, verify those changes, and then promote the flow to the production environment.

Incidentally, before you begin editing a flow you might want to make a copy of that flow (e.g., copyOfSouthAmericanFlow). That way, you’ll have a version of the flow as it was before you started tinkering with it. Admittedly, you don’t have to do this; if something goes wrong with your modifications you can always restore a previous version of the flow. On the other hand, any time you make and save a change to your flow a new version of the flow is automatically generated. If you’re making a number of flow-related changes, that means you might generate dozens of new versions of the flow, making it more cumbersome to know which version should be restored if things don’t work out the way you hoped they would. If you have a copy of the “last-known-good” flow then you don’t have to worry about that.

📘

Let’s say you make a copy of southAmericanFlow. You start making a bunch of changes to the flow, think the better of it, and decide to simply delete southAmericanFlow and use copyOfSouthAmericanFlow instead. That’s fine; that’s the whole idea of making a backup copy of the flow in the first place. However, you won’t be able to rename copyOfSouthAmericanFlow: you can’t rename flows. Instead, make a copy of copyOfSouthAmericanFlow and name your copy southAmericanFlow. You’ll then be back where you started.

Step 3: Promote the flow to the production environment

When you’ve signed off on your development flow, the next step is to promote that flow to the production environment. There are two ways to promote a flow:

• Using Console’s Registration Builder. This is usually the easiest and quickest way to promote a flow: locate the flow in Registration Builder, click the Actions icon, click Promote, select your production application from the Choose an Application dropdown, and then click Promote. See the article Promoting a Flow to a Different Application for more details.

• Using the Configuration APIs. Flows can also be promoted by using the Configuration APIs and the /promote operation. See the API reference documentation for details (and for sample code).

Step 4: Configure your API client to use the new flow

After a flow has been promoted to the production environment you must configure your API clients to use the new flow and the new version number (another task that can be done by using either Console or the Configuration APIs). To do that, you’ll have to modify both the default_flow_name setting and the default_flow_version setting:

📘

OK, you’re right: that isn’t always true. For example, suppose your production flow is named standard and your development flow is also named standard. In that case, when you promote the development flow you won’t have to change the value of the value of the default_flow_name setting:, you’ll still be using the standard flow. However, even in that case you still need to change the value of default_flow_version to reflect the version number of the newly-promoted flow.

Note that both default_flow_name and default_flow_version can be configured either at the application scope or at the individual API client scope. Does it make a difference where you configure these values? Well, it might. For example, suppose you have an application with 3 API clients: clients A, B, and C. If you configure these settings at the application scope, then, by default, clients A, B, and C will inherit those settings (which means all three clients will use the same version of the same flow). If you create a new client – client D – that client will also use that same version of that same flow. By default, settings configured at the application scope are inherited by all your API clients:

By comparison, settings configured at the client scope only affect that client: they aren’t inherited by or propagated anywhere else. So what happens if you configure a setting in both places; for example, what happens if you set the application’s default_flow_name to standard, then set an API client’s default_flow_name to test? That’s an easy one: any time there’s a conflict between setting values (standard vs. test) then the setting configured on the individual client “wins.” For example:

And, of course, if you don’t configure a setting at the application scope then the setting won’t be used unless you specifically configure it at the client scope:

What About HEAD?

As alluded to earlier, instead of setting default_flow_version to an actual flow version you can use the value HEAD; when you do this, your API client automatically uses the latest version of the flow specified in the default_flow_name setting. In a development environment, this is a good thing. After all, in a dev environment you’re likely to make a number of iterative changes to a flow, repeatedly making a change, saving that change, making a new change, saving that new change, etc. In a case like that, it makes sense to set default_flow_version to HEAD. If you didn’t then, then each time you make and save a change to the flow you’ll also need to go in and update the version number; that’s the only way to ensure that, for testing and verification purposes, your API client is using the latest version of the flow.

As a general rule, however, we don’t recommend using HEAD in your production environment. Why not? Well, imagine this scenario. You update a flow in the dev environment and you test it; unfortunately, however, your testing misses a problem that causes user logins to be rejected. Suppose you now promote this flow and your API clients are all configured to use HEAD. In that case, all your API clients will immediately begin using the new flow, and all your user logins will immediately begin to be rejected:

Again, not a good user experience.

If you don’t use HEAD, then, after you promote the new flow, all your API clients continue to use the flow previously assigned to them. That  gives you a chance to configure the flow on, say, one API client, do some additional testing in the production environment, and then make the decision whether or not the new flow should be out to more widespread use. Obviously there’s a little more work involved by not using HEAD. At the same time, however, there’s the potential to save a lot of trouble by not using HEAD.