Changing action parameters & deprecating actions in Shortcuts-first apps

[czottmann]

(For the sake of simplicity, I’ll use Actions For Obsidian as example, but of course the same situation applies to all my apps.)

Changing parameters from one app version to the next, or sunsetting actions entirely, these are interesting topics, even more so since the main interface of my apps is Shortcuts, and therefore all action configuration is handled by Shortcuts. AFO receives no information about the workflows it’s used in, or the big picture. When an action is called by Shortcuts, it’s basically just a function call, where Shortcuts hands over the parameters set by the user but nothing else. The app can work with these parameters, but it can’t overwrite or change them, either.

If it were a standard application, AFO itself would store those values and configurations, and could then run a migration in case an app update would change the makeup of the action’s parameters, e.g. var “File path or title” would become variables “File path” and “title”. The same thing could be done with workflows: If a new action supersedes an old one, a migration could replace the old with the new, and massage the old config to fit the new action.

With Shortcuts, that’s impossible.

So I was pondering how to implement upgrade paths, both in terms of changing parameters, and updating and/or sunsetting actions. Because migrations are out of the question, how do you update something without instantly breaking all workflows relying on that thing?

Here’s what I came up with, an upgrade upgrade split into three phases:

1. Changing action parameters while using fallbacks / Adding deprecation notices to actions (current app version, e.g. 2024.2)
2. Notifications (current +1, e.g. 2024.3)
3. Removal of deprecations and fallbacks (current +X, e.g. 2025.1)

Naturally, when upgrading, AFO would show its change log, where the additions, adjustments, and deprecations are listed. (Ignore at your own leisure.)

Phase 1

Changing action parameters while using fallbacks

Using Get Note’s variable “File path or title” in v2024.1 as an example: If v2024.2 would just replace it with two new variables “File path” and “title”, then the first time you run an existing workflow under v2024.2, Get Note would ask for either file path or title (because both those vars were new and wouldn’t have any values yet), and it’d do that every time you run the workflow until you explicitly set the values in the Shortcuts editor.

Depending on the number of instances of the action in the customer’s workflows, this could get annoying fast, which is not what you want; I’d like to handle it a bit more gentle.

So v2024.2 would change that existing “File path or title” variable to “File path”, and introduce a new var, “Title”. Now the first time v2024.2 runs a workflow with Get Note that is configured to look up a note by its title, the action can fall back to the value of the existing var “File path” (formerly “File path or title”). This way, the execution wouldn’t halt, and we can be reasonably certain that this is what the user wanted because in the previous version, this var would hold the value for both lookup configurations, file path and title.

Adding deprecation notices to actions

Deprecated actions slated for future removal will continue to work until they are removed, but they’ll be marked, like this v2024.2 version of Get Periodic Note:

(Please ignore the styling of the notice, it might change.) So when the customer checks their workflows, the deprecation notice is clearly visible. If they pick it from the list of actions, it’s communicating clearly the preferred alternative.

Phase 2: Notifications

The changed parameters will continue to use fallback values if necessary but they’ll emit notifications now when used (“The parameter X was changed in update Y of AFO, and is currently using a fallback value, please set an explicit value.” or similar.)

Marked actions will continue to work but they, too, will emit notifications now when used (“The action X will be removed in the upcoming update Y of AFO, please replace it.” or similar.)

Phase 3: Removal of deprecations and fallbacks

What it says on the tin.

---

So that’s where I’m at right now. I just wanted to jot it down to have a post to point to in the future.

If you’re having thoughts on the matter, please voice them, I’m eager for input or maybe even better ways to handle these situations.

[doug78645]

This approach seems appropriate, and it makes sense. I’m glad you’re willing to provide a phased implementation for action API changes. I like having the fallback behavior where possible.

The deprecation notices in the actions are helpful when creating new actions. Would those be logged anywhere when existing shortcuts run either in the AFO app or in the Obsidian console (or log) from the Actions URI plugin. That would allow us to review these warnings (and errors), especially since it might be difficult to go through all our current workflows and shortcuts to detect such usage.

I think information in Release Notes could do a lot to let us know about potential impact of API action and/or parameter changes. Of course, the AFO documentation could clearly identify and explain such actions, parameters, objects, and results associated with API changes, complemented with examples and FAQ.

Thanks for thinking through all these issues. We appreciate your thoroughness and desire to minimize any impact for us.

[czottmann]

The deprecation notices in the actions are helpful when creating new actions. Would those be logged anywhere when existing shortcuts run either in the AFO app or in the Obsidian console (or log) from the Actions URI plugin. That would allow us to review these warnings (and errors), especially since it might be difficult to go through all our current workflows and shortcuts to detect such usage.

I thought about it but I don’t what to log since Shortcuts doesn’t tell the single actions anything about the workflow they are part of. So all that could be logged would be “action X with parameters A, B, and C” which wouldn’t be very helpful, I think.

Hence my idea about the notifications in Phase 2. When you run an affected shortcut, a notification would tell you about the deprecation. This way, you’d at least have some clear causality (workflow → notification).

Of course, the AFO documentation could clearly identify and explain such actions, parameters, objects, and results associated with API changes, complemented with examples and FAQ.

They will, here’s a screenshot of a v2024.2 action documentation page:

The same deprecation notice will be shown in the “Show Info” overlay in the Shortcuts editor.

Thanks for thinking through all these issues. We appreciate your thoroughness and desire to minimize any impact for us.

De nada. I’m just glad I got someone to bounce ideas with, so: right back at you

[doug78645]

That makes sense. I wasn’t sure if logging might be useful or not, but I understand that it doesn’t indicate anything except action/parameters; I was just wondering if there might be a way to flag those affected by deprecations similar to errors that are captured.

I didn’t realize that “notifications” refers to macOS or iOS notifications, so that might be helpful when running shortcuts that have deprecated actions or parameters. I guess I was getting these confused with the “notes” that appear for actions in the Shortcut editor, information overlay description, or AFO action documentation.

Too bad there’s no way to do search/find across shortcuts, like you can with Swift code in Xcode. Maybe if I documented my shortcuts better, I might be able to capture what actions I’m using. For example, if I created Obsidian notes for each shortcut, I might even use properties, tags, or fields that I could use with Dataview queries that might identify all the shortcuts using Get Periodic Note so I would know which ones to update for new APIs. Also, I could search/find my Obsidian Markdown files using other editors like Sublime Text. Maybe this would be more work than justified, but just a thought.

[czottmann]

@doug78645

I was just wondering if there might be a way to flag those affected by deprecations similar to errors that are captured.

There is, and it’s something I am considering for phase 2:

I can mark these actions as deprecated in code:

1. It won’t remove existing instances from any workflows
2. Any existing instances will be visibly marked in the editor (“This action won’t be supported in future versions of Actions For Obsidian.”) when you open a workflow
3. They won’t be included in the list of available actions anymore, and so can’t be added to workflows any longer.

Too bad there’s no way to do search/find across shortcuts, like you can with Swift code in Xcode.

Don’t make me start working on a 3rd party Shortcuts editor app, please But yes, I’m with you.

[leif]

Good morning,

Your plan to phase out the old features gradually sounds reasonable.

However, I wonder what I, as a user of applications like AFO who is more of an amateur when it comes to programming, should expect with such incompatible updates. What assumptions could be made for users like me?

1. I will never look into the shortcut workflow as long as it works. Any hints there about future changes will go unnoticed by me.
2. I have automatic app updates enabled, so I will only notice incompatible changes when the update is final and there was no prior warning.
3. Naturally, I do not read version notes or documentation unless there is an explicit need.
4. However, I would make necessary changes as soon as possible if there were explicit and noticeable warnings that my shortcuts would soon stop working, especially if there are references to documentation on what changes are needed, with helpful before-and-after examples.
5. I do not have a large number of shortcuts likely to be affected, so the point 4 will not hurt me.
6. Since I know that this app is developed by a dedicated individual developer, I don’t expect the same level of support as from a large commercial product. In my opinion, pragmatic solutions that require some effort from both sides are perfectly fine.

So what would help:

1. One or more versions where the new functionality is already implemented, but the old stuff works alongside it, without much transition logic.
2. Very clear warnings about the changes when the new version is installed or launched for the first time, perhaps repeated 2-3 times.
3. Of course, as soon as possible, note in the documentation that the functions will soon be deprecated, as in your example, but make it red!

These are my thoughts on the matter.

[czottmann]

Thanks @leif, appreciate the input.

So what would help:

1. One or more versions where the new functionality is already implemented, but the old stuff works alongside it, without much transition logic.
2. Very clear warnings about the changes when the new version is installed or launched for the first time, perhaps repeated 2-3 times.
3. Of course, as soon as possible, note in the documentation that the functions will soon be deprecated, as in your example, but make it red!

(1) is planned, (2) is a good idea and covered by the phase 2 notifications (I think). As for (3), you’re assuming people read the docs, aren’t you But I agree!