Selected entities in Toolkit App?

Does the Toolkit App payload have knowledge of the selected entities in the Shotgun web interface? Is it possible to query the user selected entities from within an App?


Hi @pipeTD,

Welcome to the forums! Yes, the toolkit actions in the webUI are aware of the user selection, for example I’ve selected 2 assets and run the Create Folders action and it runs it for all selected entities;

As for how to set this up in a custom app I’m not sure, but it is possible, I’ll see if someone more knowledgeable is able to chime in. Just for clarity, what action are you trying to perform specifically?



Actually you can use the folders app @DavidMason mentioned to show you how:
When you register the command with the engine you need to set the supports_multiple_selection parameter:

And then the callback method will get passed the entity_type and entity_ids:


That is perfect, exactly what I was looking for. Thanks @DavidMason and @philip.scadding!

This brings me to my next questions. If I can get to what the user has selected in the web interface within a Toolkit App, would there really be a need for using AMIs anymore? Couldn’t the same thing be done via a Toolkit App, which is also something that can be bundled to distribute remotely? An AMI needs to have either a web server (Flask, cherrypy, etc.) to host, or a custom protocol handler installed on the local machine. Both of which may not be possible when users are working remotely on their own personal machines. Is there a benefit to using AMIs over developing Toolkit Apps that could do the same functionality?


Hello – There is a lot of overlap of functionality between AMIs and Toolkit apps, but there are some differences, too. One that comes up occasionally is the contents of the payload: for example, an AMI payload includes details of the webapp environment from which it’s being run: URL, page ID and title, etc. So, if the logic you’re trying to run requires that info, you’d want to opt for an AMI.

You can read about all the AMI payload contents here:


Hi @tannaz, thanks. That is one of the links I was looking at. One of the options for hosting an AMI is a Custom Protocol Handler. Is it possible to make a Toolkit App be a custom protocol handler?

What I am looking for is a solution where remote artists can run a tool based on their selection in the web interface. Say a selection of Versions to create a client Playlist or bundle data to ship to a vendor. But, because they are working remotely they do not have access to a locally hosted http that is behind a network. I also do not have control over installing programs on their system to act as a custom protocol handler.

However, with Toolkit being distributed to their machines locally via SG Desktop, that may work. So, would it be possible to setup something where a Toolkit App could act as the custom protocol handler in the AMI URL field? If so, this may also get past the differences in the OS and building/installing PyQt locally, as that also is bundled nicely with SG Desktop.

1 Like

Also, in this link it talks about registering a custom protocol on Windows, OSX, and Linux. Is that something that can be done via the Toolkit distribution? Something along the lines of what @philip.scadding has outlined here?

1 Like

Hi @philip.scadding, can you verify that the tk-shotgun-folders App is working for you out of the box? I was getting an error when trying to use entity_type and entity_ids in my Toolkit App. So, I tried copying the tk-shotgun-folders code to my site to see if I got the same error. When trying to call create_folders or preview_folders I am getting the same error to my tk-desktop.log:

2020-05-26 13:37:51,713 [69062 ERROR sgtk.ext.tkimp6349a9a780da40429d4339d558a7f281.tk_desktop.site_communication] [PROXY] Error calling __commands::create_folders((), {}):
Traceback (most recent call last):
  File "~/Library/Caches/Shotgun/bundle_cache/app_store/tk-desktop/v2.5.3/python/tk_desktop/", line 186, in _trigger_callback
    callback(*args, **kwargs)
  File "~/Library/Caches/Shotgun/.../p92c216.basic.desktop/cfg/install/core/python/tank/platform/", line 1082, in callback_wrapper
    return callback(*args, **kwargs)
TypeError: create_folders() takes exactly 3 arguments (1 given)

Here is an example of how I have the engine register command setup:

1 Like

It looks to me as though you are maybe running it from an engine other than tk-shotgun?

You will only get passed the entity_type and entity_ids if running as an action in the Shotgun website. Can you confirm if that is what you are doing?

If you want to test/develop the app outside of the tk-shotgun engine (for example in the tk-shell engine), I would probably just hard code those values to some entity type and ids and test with that.


When you say that I need to run from the tk-shotgun engine, do you mean I have to run it by right clicking on an entity type in the Shotgun web interface and select it from this context menu?

If so, I need to figure out how to add the App to this menu under the Toolkit section. I am currently running my App by clicking on a button that I added to the SG Desktop interface.

1 Like

Hi @pipeTD! I think I can offer some clarification on some of the issues you’re hitting up against:

  • First off, I should mention that with Toolkit actions you don’t need to worry about custom protocol handlers. As long as the user is running Shotgun Desktop, its built-in websocket server will handle the requests and run the expected python code from the user’s cached Toolkit pipeline configuration.
  • I’m not sure what your workflow was around running your app via Desktop, but I can talk you through adding it to the right-click menu on entities in Shotgun in the browser, as you showed with the screenshot in your last reply:
    • While most engines correspond with DCC integrations (eg, tk-maya, tk-nuke), we have a few “special” engines: tk-shell corresponds with the command line tank command, tk-desktop is the engine for the Desktop app, tk-desktop2 for Shotgun Create, and finally tk-shotgun is for the Shotgun web app.
    • So, if you want to add an app to those right-click menus in Shotgun, you’d add them to the tk-shotgun engine, in the same way you add an app to any other engine: choose the environment for which you want to configure the app (in this case, the entity type on whose right-click menu you want the app to show up), follow the includes in your pipeline configuration to get to the proper file, and add the app to it. You can see detailed instructions on adding an app to your config here.

Hope that helps! Let us know if you have any other questions.


Stumbled upon this old thread and noticed that the link to AMI docs is broken. Here’s a better one:

1 Like

Nice to see you again @tannaz ! :slight_smile:

1 Like