Manage step versions

Applications and processes are constantly changing, and the ability to create versions of steps helps you adapt them to meet the needs of the real world without disrupting your existing flows. Flow Designer includes a step versioning system so you can run a full development cycle for your steps.

This system allows you to have multiple versions of a step deployed, ready for use in flows, while others are still in development. For example, consider a "Create Service Desk Ticket" step — you might need to have versions that work with the ServiceDesk APIv1 and the ServiceDesk APIv2 both deployed; at the same time, you have a version in development to address your boss' request to complete additional fields in the service desk ticket.

Once you're ready to retire a step, you can mark it as deprecated and schedule when you plan to withdraw it from use. The planned withdrawal date is displayed to users so they can update to a more recent version and prevent errors when the step executes.

Anyone with permission to use the step can view deployed versions in the palette and drag them into a flow. Anyone with permissions to edit a step can also add in-development versions into a flow to test out changes. It's also easy to switch the version used by a step on the canvas.

Using different versions in a flow

There are a couple of ways to use a different version of a step in a flow, depending on whether you're adding the step for the first time or want to change the version of a step currently in use.

The default version of a step is the latest deployed version. This appears as the entry in the palette until you click the version icon, and if you drag the top-level step onto the canvas, this is the version used.

To see all the versions of a step that you can use in a flow, click the versions icon beside the step in the palette:

The other available versions are listed underneath the default version.

For steps you don't own, but have permission to use, the list includes all deployed versions. For steps you own, it also lists versions in development. Click the information icon to view version details, including the step owner and information on how this version is different from others.

To use one of the child versions, simply drag it onto the canvas and configure it like you would any other step.

As new versions of a step become available, you can easily switch which version a flow uses right from the step configuration dialog on the canvas.

  1. Double-click the step in the flow to open its configuration screen (or select it and click the pencil icon).
  2. Check which version of the step is in use. The version drop-down at the top of the window displays the current version number:

  1. Click the current version name to view a drop-down list of all the versions of the step you have permission to use in the flow.

  1. Select the version you want to use.
  2. Check the step configuration for any new inputs that need to be populated.
  3. Click OK on the step configuration dialog.

It's also a good idea to check other steps further down the flow for the alert badges that indicate missing configuration — changing the step version might remove outputs used by these steps. For example, in this flow, a change to the Email Parser step removed an output used in the Create Event step:

Create a new version of a step

When you create a new version, the version remains linked to the parent step. You might create a new version if your service desk application comes out with an update, and you need to make changes for the step to work with that update. If you want to use a step as a template to create a completely new step, not linked with the original, you can also copy a step.

To create a new version, you need edit permissions for the step. The default version in the palette is the latest deployed version.

If you have edit permissions on the step, you can view detailed version information in the step configuration dialog.

  1. Click the gear icon beside the default version of the step to open its edit dialog.
  2. Click Show versions to view any additional versions. Versions are listed by their state then in descending order of their version number.

The following items provide information about the version:

  • Current State: Displays the state of the version.
    • Deployed: Deployed versions are ready to use and available to anyone who has permission to use the step.
    • In Development: A version in development might not be ready to use, and is only available to the step owner and other users with edit permission.
    • Deprecated: Deployed versions that are planned for withdrawal. Deprecated versions used in flows continue to execute successfully, but users are no longer able to add them to flows from the palette.
    • Withdrawn: Withdrawn steps are no longer available for use in flows. Withdrawn steps that are used in flows fail to execute.
  • Version information:
    • Version Details: A description provided by the person who created the version to indicate how to use it or what might be different from a previous version.
    • Version Label: A short label to indicate the function of the version.
    • System-assigned version information: This includes the number assigned to the version by the system, if the step is the default (the version that appears first on the palette), and who created the version and when.
  • Usage: If a version in use, the Usage tab appears to display which flows it's used in. This lets you know which flows will be impacted by any changes you make and why you might get a message about not being able to make a change because it would break a flow.

Create a new version by copying an existing version if you want to use the inputs, outputs, and script of that version as a starting point.

  1. Locate the step you want to create a new version of in the palette.
  2. Beside the step name, click the gear icon and select Edit.
  3. Click Show versions in the bottom left of the edit dialog.
  4. Click the gear icon beside the version and select Copy Version, or click Create New Version and select the version you want to copy.
    • The name becomes "Copy of <step label>", the Current State is set to "In Deployment", and the Version Details and Version Label fields are blank. The rest of the step configuration is the same as the version you copied.

  1. Edit the name and description to reflect the version, if needed.
  2. Use the Version Details and Version Label fields to provide step users with information about how this version is different from others.
  3. Edit any settings in the inputs, outputs, and script that need to change from the version you copied.
  4. Test the step version in a flow.
  5. Once the step version is ready to go, set Current State to "Deployed" and click Save.

If needed, you can also edit an existing version of a step.

Create a blank version if you know you need significant changes to the step definition but want the version to remain linked to other versions of the step.

  1. Locate the step you want to create a new version of in the palette.
  2. Beside the step name, click the gear icon and select Edit.
  3. Click Show versions in the bottom left of the edit dialog.
  4. Click Create New Version and select Blank version. Click Create.
    • The name is set to "New Version" and the Current State to "In Deployment". All other step configuration is blank, include the settings, inputs, outputs, and the script.

  1. Configure the step like you would a new custom step.
  2. After you configure the step version as required, click Save (you can save as you go, since it won't impact any deployed steps).
  3. Use the Version Details and Version Label fields to provide step users with information on how this version is different from others.
  4. Test the step version in a flow.
  5. Once the step version is ready to go, set Current State to "Deployed" and click Save.

If needed, you can also edit an existing version of a step.

Deprecate and withdraw versions

As newer versions of a step become available, you may want to phase out older versions and eventually withdraw them from use in flows. You can deprecate a step version and optionally set the date that you plan to permanently withdraw it.

When you deprecate a version of a step, flows using that version continue to execute successfully, but the version is no longer available for use from the palette.

The configuration screen for a deprecated version of a step displays a recommendation to update to a newer version. This message includes the planned withdrawal date, if one was provided. This lets users know how long they have to update to a newer version before the version they're currently using is withdrawn, which will break their flow. Deprecated step versions with a set withdrawal date also display a warning badge on the canvas if they're used in a flow.

To deprecate a version of a step:
  1. In the palette, locate the parent step of the deployed version you want to deprecate.
  2. Beside the step name, click the gear icon and select Edit.
  3. Click Show versions in the bottom left of the edit dialog.
  4. Click the version you want to deprecate. Set the version's Current State to "Deprecated".
    • If the version is being used in any flows, a dialog shows you where it is being used. Although these flows continue to execute successfully once the version is deprecated, they will break when you withdraw the version. To continue, click Deprecate.
  5. To provide a planned withdrawal date (optional), click the Date field and select a date from the calendar.
    • Step versions are not automatically withdrawn on the specified withdrawal date. This date is displayed in a message on the step configuration screen to warn users to update to a newer version before the planned withdrawal date.
  6. Click Save.

Once you deprecate a step version, you cannot redeploy it.

Versions are not automatically withdrawn on the planned withdrawal date; to withdraw a version, you must manually change its current state to "Withdrawn".

  1. In the palette, locate the parent step of the deployed version you want to withdraw.
  2. Beside the step name, click the gear icon and select Edit.
  3. Click Show versions in the bottom left of the edit dialog.
  4. Click the version you want to withdraw. Set the version's Current State to "Withdrawn".
    • If the version is being used in any flows, a dialog shows you where it is being used. Since withdrawing the step will break these flows, you may want to update them to use a newer version of this step first. When you're ready, click Withdraw.
  5. Click Save.

Once you withdraw a step, you can no longer change its deployment state.

Delete a version

To permanently remove a version, you can delete it as long as it is not being used in a flow. To delete the base version (version 1), you need to delete the step entirely.

  1. Click Show versions in the Edit Step dialog.
  2. Click the gear icon beside the version and select Delete.
  3. Click Delete again to confirm (or Close to cancel).
    • If the version is used in any flows, a dialog shows you where the step is used. Remove it from those flows and try again.