Migration guide

Muster 9 has a new databases schema either for the regular queue and history queue. It also includes a new database for the backups facilities, so be sure to create a new database for the backup if you are working on MySQL or SQL Server, no action is necessary if you're using the builtin Sqlite engine. Muster 9 also lets you use different database engines independently for the three end points. Have a look at the new Dispatcher configuration dialog for possible configurations.

Also be aware that, Muster checks on startup the databases schema, so if you absolutely need to migrate the old queue data, be sure to make a snapshot of your previous databases and manually migrate to the new schema otherwise your data will be erased on the first startup. Instructions for schemas migration are DB dependant and are not automated at the moment.

Starting from Muster 9.0.2, databases from version 8.5+ can be automatically upgraded by Muster 9. Be sure to make a backup of the muster.db and muster_history.db files if you're running sqlite. If you're running Mysql or SQL Server, backup tables are created automatically.

If you are querying the databases outside of Muster, also have a look at the new databases schemas to verify if you need to modify your queries.

Muster 9 uses different network ports to allow running version 8 and 9 simultaneously while you slowly migrate your pipeline to the newer version.

The new network ports are:

• Dispatcher
  • 9880 : Renderclients connections
  • 9881 : Console / mrtool connections
  • 9883 : Notificator connections (TCP only, UDP broadcast has been removed)
  • 9890 : Web server HTTP connections
  • 9891 : Web server HTTPS connections
• Renderclient
  • 9885 : Remote management and log querying connections

While the Windows installer attempts to add expection rules for both the Dispatcher and the Renderclient for inbound network traffic, it may be possible you may need to configure your firewall. Also if you're running on a Windows Domain, you may need to configure the Domain's policies to allow inbound traffic for both the Renderclient and the Dispatcher.

Linux and Mac OS X installers do not provide any kind of automatic configuration for any installed Firewall, you may need to configure inbound rules manually.

Actions paths and environment fields now supports Python inline execution to build complex command lines from the jobs or the chunks contents. While you can use them in the old way without invoking Python, strings are now escaped. That means that a regular path like C:\Windows\System32\cmd.exe must be escaped to C:\\Windows\\System32\\cmd.exe. Refer to the actions and environment section to check what characters needs to be escaped.

The old attributes syntax like %attr(job_id) is no longer supported, so you need to use the Python inline expression builder to obtain the same result.

Muster 9 includes the MJob and MChunk objects over more functions to allow a better control over the entire template logic.
To modify your existing templates, be sure to change the definitions of the following functions according:

• onGetApplicationPath(self, job,chunk, clientTemplatePreferences,pathOut)
• onGetApplicationStartingFolder(self, job, chunk, clientTemplatePreferences,pathOut)
• onCheckForSubframeAdvancingString(self, job, chunk, line)
• onCheckForSubframeProgress(self, job, chunk, line, progressOut)
• onCheckForFramesMask(self,job,chunk,line,prefixOut) (DEPRECATED , look for onCheckForFramesMaskForLayer())
• onCheckLogLine(self,job,chunk,clientTemplatePreferences,line,lineNum,warnings,errors,silencedWarnings,silencedErrors)
• onCheckLog(self,job,chunk,clientTemplatePreferences,log,warnings,errors,silencedWarnings,silencedErrors)

New templates functions and modified behaviours :

• onCheckForFramesMaskForLayer(self,job,chunk,line, prefixOut,layerOut) : returns the file path mask for a specific render layer. Should be used instead of the old onCheckForFramesMask that's still supported for backward compatibility

• onGetFlagForRenderLayers(self, job, layers) : Returns the flag to pass to the batch render to select a specific render layer, used by automatic frames requeue for a specific render layer

• onCheckLog(self,job,chunk,clientTemplatePreferences,line,lineNum,warnings,errors,silencedWarnings,silencedErrors): Implements the new lists to hold warnings, errors, silenced warnings and silenced errors as MTextFileMarker objects. The objects are preserved into the chunks details and allow fine control over each error line number. Take a look at the new chunks details window for further information. Also check the template engine reference to understand how to migrate your templates to this new logic

• onCheckLogLine(self,job,chunk,clientTemplatePreferences,log,warnings,errors,silencedWarnings,silencedErrors): Require changes like onCheckLog() even the purpose of onCheckLogLine is parsing the logs while they are produced. So a simple line error check like the ones implemented in the old version may still be fine. The entire errors and warnings collection will effectively happen inside onCheckLog(), by the way, if you would like to collect the errors and the warnings even a render is aborted, you can fill the lists even from this member function.

Muster 9 supports frames ranges instead of the fixed start, end, by frame values. While the old syntax into the templates is still valid, you can easily migrate your existing custom templates with two steps:

• Remove the start, end, and by frame fields from your engine declaration, and add a unique MTemplateItemFramesRange object
• Instead of declare 3 mappings to the start_frame, end_frame, and by_frame internals, declare a single map to the frames_range internal

This is a sample code snippet for the new declaration:

mayaFrames = MTemplateAPI.MTemplateItemFramesRange("MAYAFRAMES","Frames","Specifies the frames ranges for the rendering job in the 1-10x1s1n1,... form","1-10",0,1,1)
self.addSubmissionItem(mayaFrames)
...
self.addMapping("MAYAFRAMES","frames_range")	

The new template system supports versioning. This does not require any code change, you just need to define multiple versions for a render engine through the templates configuration dialog. Once your configuration is complete, you can just Configure a renderclient, and you'll get multiple clients configurations blocks for each version. At runtime, you'll get a different clientTemplatePreferences object, depending on the version you're running. Also additional member function of the MTemplate class are available to access global system wide defined macros as well as versions specific.

The mailing templates no longer exist. Due to a complete revamp of the notifications system, mails are now built and handled through the global template (0). If you need to customise the output of mailing notifications, you'll need to modify the global python template and build your emails according. Building the mails through the template gives you access to the inner objects like MJob and MChunk with more capabilities available for your reports. The default global template (0) already contains a full implementation of the mailing notifications and it's a good starting point for your customizations.

We changed the way the getChunksViewSelection() function works when invoked from a custom script inside the chunks details. Instead of returning a single list of the selected chunks, it now returns two lists, depending if you have selected regular chunks, or history chunks, and let you interact with the history chunks too.

Please be sure to take a look at the new Mrtool flags and API functions. We included a bunch of new properties on the jobs like the sequence, shot, and so on. All those new attributes have a corresponding member function or mrtool flag.

The previous plugins are not compatible with Muster 9. Be sure to update them, they also include a new field for the engine version selection.