Jump to content

Workflows Best Practices


Recommended Posts

This thread will serve as reference for a list overall "best practices" when creating workflows for Alfred 2.

This will be an evolving document, so check back occasionally for updates.

Data Storage
In order to clean workflow directories clean and prevent syncing issues, we recommend using the following paths for storing volatile (non-persistent) and non-volatile (persistent) information.

Volatile:~/Library/Caches/com.runningwithcrayons.Alfred-2/Workflow Data/[bundle id]
Non-Volatile:~/Library/Application Support/Alfred 2/Workflow Data/[bundle id]

When writing data to these folders, remember to create a folder for your workflow. Name the folder to match the bundle id of your workflow. This helps keep things clean and organized and make sure that you don't accidentally delete or overwrite someone else's settings.

 

Synced Settings

While it is recommended that settings be written and stored within the two locations provided above, sometimes it is found to be more useful to sync settings along with installed workflows. If this option better fits the needs of your workflow, create a new folder inside of your workflow folder named config and write all settings that need to be synced there. We recommend keeping this folder minimal. Only store settings there that have been deemed necessary. Continue to store all other settings in the previously suggested paths.

 

When exporting workflows, remember to remove the config folder from the workflow path before exporting so that you do not distribute potentially confidential information to the masses. 


Requesting Remote Data
When creating workflows that request data from remote resources, be sure to set your "Please Wait" subtext to inform the end user that data is being requested from remote locations and therefore, may take a moment to populate the list of feedback results. See example image below.

bestpractices1.png

If possible, set timeouts for remote data requests appropriately and provide the the end user with an error (or other such) message to inform them that the request took longer than normal and that script execution has halted. This prevents the user from waiting an unnecessarily long amount of time thinking that feedback is coming.

post-10-0-86427900-1358813671_thumb.png

Link to comment

Okay, good to know. I've just been using the workflow folder itself for storage, so I'll update that for future releases.

 

Also, what's the deal with the BundleID? I would have thought that that was what Alfred used to recognize workflows as unique. However, currently, when you install a new version of a workflow that you already have, Alfred creates a 2nd duplicate version of it, even when the BundleID is identical. I take it that this will be sorted out in a future beta release?

Link to comment

Carlos - I haven't made Alfred use the bundle id yet, but when he does, he will use this to overwrite a currently existing workflow and migrate settings etc. If you use the bundle id in the folders David mentioned above, Alfred will also delete these folders too :)

Link to comment
Carlos - I haven't made Alfred use the bundle id yet, but when he does, he will use this to overwrite a currently existing workflow and migrate settings etc. If you use the bundle id in the folders David mentioned above, Alfred will also delete these folders too :)

Okay, so I can just get my workflow to create a subfolder in those working directories called "myworkflow.bundleID" and that's all Alfred needs to associate the workflow with the appropriate storage folder?

Link to comment
Okay, so I can just get my workflow to create a subfolder in those working directories called "myworkflow.bundleID" and that's all Alfred needs to associate the workflow with the appropriate storage folder?

 

Yep, just make sure the bundle id you set for your workflow exactly matches [case sensitive] the folder name you create.

Link to comment

2 Questions:

Is it possible for helper variables for [volatile] and [non-volatile] to be added to Alfred that get expanded to the path of the relevant directory including the bundleID before the scripts are run?

I've submitted a request for this: http://www.alfredforum.com/index.php?/topic/389-alfred-helper-variables-the-get-expanded-before-scripts-are-run/
 

I'd like to show subtitle only when I'm downloading or updating the api list (which happens monthly, and can't run search while this is happening), is there any way to do this?

Link to comment

Brian,

 

I've posted an initial PHP library on Github that provides a lot of helper functions to get you going when creating a PHP based workflow. When the class object is created, it automatically reads the bundle ID of the workflow, and then provides functions for easily grabbing: users home path, path to workflow, path to workflow data, path to workflow cache data and provides many other functions as well. It's just an initial push. I hope to get a lot more done and make this a REALLY helpful utility for all.

 

Find it here: https://github.com/jdfwarrior/Workflows

Link to comment
  • 3 weeks later...

[Edit added in December 2022: Note that we now recommend 256px for Alfred workflow icons.]

 

On 2/13/2013 at 8:15 PM, Tyler Eich said:

Is there a recommended size for workflow icons? I noticed Alfred's resources use 128x128 pngs

 

128px is a good size as it falls within the maximum 64px size Alfred shows, so will be sharp on a retina display. Also, it's worth optimising your pngs through http://tinypng.org to make them nice and small :)

 

Link to comment
  • 3 weeks later...

I've just tried out the syncing feature, and find it inconvenient that persistent workflow settings are not being synced as well.  E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.  Or for the WolframAlpha workflow it would be useful if the API key would sync.

 

I understand and agree that volatile/cached data should be kept on the local machine, but I wonder why it is recommended to keep user configuration out of the workflow directory?

 

I can see that it may be desirable to keep personal configuration data out of exported workflows. But that could be achieved by using a convention to put all such data into a Config subdirectory of the workflow folder, and the Export function could just ignore the content of that subdirectory.

Link to comment

I understand and agree that volatile/cached data should be kept on the local machine, but I wonder why it is recommended to keep user configuration out of the workflow directory?

 

This is very similar to how OS X works in that you have apps which don't change and a storage area for preferences and support files. When the app (or in Alfred's case, workflow) is upgraded or updated, the source app or workflow can cleanly be replaced without changing settings.

 

Having said that, I appreciate that syncing workflow settings is desirable and have added a note to have a good think about this after Alfred has been released :)

Link to comment

I've just tried out the syncing feature, and find it inconvenient that persistent workflow settings are not being synced as well.  E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

Link to comment

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

 

Well remember, you CAN still write data into the workflow folder. It's just not considered best practice. Also have to be careful when installing a new workflow to make sure that it doesn't get overwritten.

Link to comment

This is very similar to how OS X works in that you have apps which don't change and a storage area for preferences and support files. When the app (or in Alfred's case, workflow) is upgraded or updated, the source app or workflow can cleanly be replaced without changing settings.

 

Having said that, I appreciate that syncing workflow settings is desirable and have added a note to have a good think about this after Alfred has been released :)

 

Yes, that is a good point.

 

I think one possible solution would be for Alfred to provide 2 environment variables to all scripts it executes: $ALFRED_CACHE and $ALFRED_CONFIG. They would be set up to point to the volatile and non-volatile app data directories (including the bundle id). By default $ALFRED_CONFIG would point to the regular ~/Library/Application Support/... folder, but if the user sets a Sync Folder, then these config directories will be moved to a subdirectory of the sync folder.  The $ALFRED_CACHE setting however would continue to point to ~/Library/Caches/...

 

It should be the responsibility of the workflow to create the actual cache and/or config directories because not every workflow needs them; Alfred would just provide the paths, but the workflow has to execute `mkdir -p "$ALFRED_CONFIG"` before creating any files in them.

 

I don't have an opinion (yet) what should happen if the workflow doesn't have a bundle id. Maybe the $ALFRED_* variables should then not be set at all?

 

A side benefit of this scheme is that workflow code doesn't need to embed the bundle id to create these directory paths themselves; changing the bundle id via the Alfred GUI would be enough to change them.

Link to comment

Brian,

 

I've posted an initial PHP library on Github that provides a lot of helper functions to get you going when creating a PHP based workflow. When the class object is created, it automatically reads the bundle ID of the workflow, and then provides functions for easily grabbing: users home path, path to workflow, path to workflow data, path to workflow cache data and provides many other functions as well. It's just an initial push. I hope to get a lot more done and make this a REALLY helpful utility for all.

 

Find it here: https://github.com/jdfwarrior/Workflows

 

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

Link to comment

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

 

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

Link to comment

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

Hi Woofy,

I would really like to have an AppleScript "library". Please post here once you did it !

Link to comment

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

 

Awesome, thanks so much man!

 

P.S. the only problem I see so far with the library is that AS doesn't have json support, and using third-party libraries is out of the question for multiple reasons.. so I will probably improvise and see what other format I can use for reading/writing cache files and such things..

Link to comment

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

 

Hey David,

 

Just like I've promised, I already finished a fully working Applescript version of your Workflow class (slightly enhanced here and there). You can get it here: https://github.com/qlassiqa/qWorkflow (it contains heavily commented code, and I also made a very detailed documentation on all methods with examples).

 

As you will see I had to change the name of the methods to avoid language conflicts. Also, right now it has no JSON support since Applescript doesn't know what that is, but I'm already planning a JSON parser for Applescript ;)

 

P.S. I've also included an example AlfredWorkflow that uses my AS Workflow to show iTunes rating for the current song and also give options to rate it differently (make sure you look at the screenshot, it's funny :D)

Edited by ursanrazvan
Link to comment

Hey David,

 

Just like I've promised, I already finished a fully working Applescript version of your Workflow class (slightly enhanced here and there). You can get it here: https://github.com/qlassiqa/alfred-workflow (it contains heavily commented code, and I also made a very detailed documentation on all methods with examples).

 

As you will see I had to change the name of the methods to avoid language conflicts. Also, right now it has no JSON support since Applescript doesn't know what that is, but I'm already planning a JSON parser for Applescript ;)

 

P.S. I've also included an example AlfredWorkflow that uses my AS Workflow to show iTunes rating for the current song and also give options to rate it differently (make sure you look at the screenshot, it's funny :D)

 

Awesome, post it in the Share Your Workflows area with an appropriate heading so everyone else can find it. I'm sure people are going to love this. Great work.

Link to comment

E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.

 

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

Okay, I've done this now: http://www.alfredforum.com/topic/491-timezones-a-world-clock-script-filter-updated-to-v14/ :)

Link to comment

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...