This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for details.

The main interface is split into three key sections:

• Primary Output. Items to be published are organized by their output type with the primary output given prominence at the top of the UI. There must be exactly one item to publish for the primary output which would typically be the scene file itself.

• Secondary Outputs. Secondary outputs are optional and there can be as many as required. Items from the scene (e.g. a mesh in Maya) can also be associated with multiple secondary outputs (e.g. OBJ export together with an Alembic Cache export) if needed.

• Publish Details. In addition to selecting the items to publish, the interface also allows the artist to choose the Shotgun task (if they haven't already specified this in the current Work Area), capture a thumbnail and add a comment.

When using the app, the artist workflow would typically be:

1. Launch the app, select the items to be published, choose the Shotgun task, set the thumbnail, enter a comment and then click 'Publish'.
2. The app will perform a pre-publish validation pass on the selected items.
3. If there are any problems it will ask if it should continue. If it shouldn't then it will stop and display the problems, allowing them to be fixed before continuing.
4. If there were no problems or it was told to ignore any problems, it will then publish all selected items, starting with the primary.
5. As long as the primary item is successfully published, the app will finish by running a post-publish step. Typically this is used to version-up the current scene and do any cleanup.
6. Finally the result: Success or Failure, is displayed together with any problems reported by the publish step.

Multi Publish has been designed to be extremely configurable with all the key steps being implemented as a series of hooks. As well as separating out all engine specific calls from the app, making it easy to configure for new engines, these hooks also provide complete control over the publish process.

These are the main hooks that together comprise the publish workflow:

• hook_scan_scene is responsible for scanning the current scene for items to be published. It should return a primary item together with any number of secondary items.
• hook_primary_pre_publish is typically where you would validate that the primary item can be published. This can return a list of non-fatal problems that won't stop the publish.
• hook_secondary_pre_publish is where the validation of all secondary items happens. Again this can return a list of problems that the user will have the opportunity to fix before continuing.
• hook_primary_publish will publish the primary item for the primary output. Typically this is responsible for copying the current scene file to the publish area and registering it with Shotgun. It should return the full path to the published file which is then passed as a dependency to the secondary publish hook. Raising an exception within this hook will stop the publish and notify the user.
• hook_secondary_publish publishes the secondary items for the secondary outputs. Again this typically exports or copies the published files and then registers them with Shotgun.
• hook_post_publish is the final hook in the publish workflow allowing any clean up to be done at the end of a publish. In the default hooks, this is where the scene is versioned up. This hook will only by run if the primary publish succeeded without raising an exception.

These additional hooks can be used to customize the behaviour of the app.

• hook_thumbnail can be used to provide a thumbnail for the publish in cases where performing a screen capture doesn't make any sense. If this returns a file path to a thumbnail then the screen capture functionality is disabled.
• hook_copy_file is used to do any disk based file copying of files by the app. The default hooks use a utility method on the app which in turn calls this hook. To do this, call self.parent.copy_file(...) from within the hook.

It's important to understand the relationship between the outputs defined in the configuration and the items returned by the scan-scene hook.

Each output has a scene_item_type property which is an arbitrary string defined by the configuration.

The primary_scene_item_type must be unique. Multiple secondary outputs can share the same scene_item_type. For example, if the two secondary outputs: 'OBJ' and 'Alembic Cache' are given the same scene_item_type geometry, this indicates the intention that all geometry items from the scene should have both an OBJ and Alembic Cache file published for them.

Each item returned by the scan-scene hook has a type which must match a scene_item_type for one of the outputs defined in the configuration.

The app will combine the list of items with the list of outputs using the mapping between the output's scene_item_type and the item's type and present the final list to the user to allow them to select the items for each output to be published.