Muster Console Python API

The Muster Console Python API is available under the MConsoleAPI module. It can be imported into Python by simply typing:

import MConsoleAPI

Be aware that , even you can import the MConsoleAPI module inside any Python script, it will work only inside the Muster builtin Python interpreter and just on the scripts of template functions that are directly invoked by the Console. You can still import it widely inside any template, but an attempt to call a function of the Console from a wrong context, will return an error

A selective way to import modules only when launched from the correct context requires using the builtin muster.runningContext() function call like in the following example:

if (muster.runningContext() == "console"):
    import MConsoleAPI
elif (muster.runningContext() == "dispatcher"):
    import MDispatcherAPI
elif (muster.runningContext() == "renderclient"):
    import MInstanceAPI

Return types

Any function exported by the MConsoleAPI Python module returns always a MUSTERERR object as first. Each time you invoke a function, you must always check against the MUSTERERR object to check if the function has been invoked successfully.

In addition, the function may return a tuple instead of a single object with additional objects. Refer to each function specific documentation for a list of the returned objects:

import MConsoleAPI
err = MConsoleAPI.nodeKillProcess(1) # This returns just the error object
if (err.getErrorCode() != 0): sys.exit(err.getDescription())
 
err, node = MConsoleAPI.nodeGet(1) # This returns a tuple, error object and the node object
if (err.getErrorCode() != 0): print("Instance ID 1 does not exist or something really wrong is going on !")

Handling GUI scripting

Muster comes with a builtin installation of PySide inside its own Python interpreter. At the time of this writing, PySide is compiled against QT 4.8.6. Due to licensing limitation, we are not allowed to distribute PyQT too as an additional GUI scripting library, but nothing prevent you from compiling or obtaining PyQT for QT 4.8.6 on your own and install it into the Muster python library folder. Installing or using PyQT as well as PySide is out of the scope of this document. We suggest you to check the PySide and PyQT sites for further information on the capabilities of the libraries.

import shiboken
from PySide import QtGui, QtCore
import MConsoleAPI
import time
 
winPointer = int(MConsoleAPI.getMainWindow())
if winPointer != 0:
    mainWindow = shiboken.wrapInstance(winPointer,QtGui.QMainWindow)
 
#The following scripts creates a QT Dialog using Pyside and scans for jobs
#Pay attention to the QtGui.qApp.processEvents() call, it allows you to process GUI events and then update the interface while doing busy operations in Python
 
# Make the script available only if the running context is "console"
if (muster.runningContext() == "console"):
 
    from PySide import QtCore, QtGui
    import MConsoleAPI
 
    class JobScannerDialog(QtGui.QDialog):
 
        def __init__(self,parent):
            super(JobScannerDialog,self).__init__(parent)
            self.initUI()
 
        def initUI(self):
            self.layout = QtGui.QVBoxLayout()
 
            self.setWindowTitle("Job scanner")
 
            self.label = QtGui.QLabel("Job progress:")
            self.progress = QtGui.QProgressBar()
            self.progress.setProperty("textVisible",0)
            self.scanButton = QtGui.QPushButton("Scan")
 
            self.layout.addWidget(self.label)
            self.layout.addWidget(self.progress)
            self.layout.addStretch()
            self.layout.addWidget(self.scanButton)
 
            self.setLayout(self.layout)
            self.scanButton.clicked.connect(self.onScan)
 
        def onScan(self):
            err, jobs = MConsoleAPI.jobGetList()
            if (err.getErrorCode() != 0):
                sys.exit("Error getting the jobs list")
            self.progress.setProperty("minimum",1)
            self.progress.setProperty("maximum",len(jobs))
            for i in range(0, len(jobs)):
                self.progress.setValue(i)
                # Do something with jobs[i] MJob object
                time.sleep(0.1) # Give you some time to watch the progress bar moving if your queue is small :D
                QtGui.qApp.processEvents() # On busy blocking events, be sure to call the processEvents() function to let QT process GUI events and keep the interface interactive
 
    dlg = JobScannerDialog(mainWindow)
    result = dlg.show()

Execution contexts

The family of the MConsoleAPI functions can be invoked from within the following contexts:

  • A Console script that targets a Console execution context
  • A Console script that targets a context menu inside one of the Console builtin views (jobs, nodes, logs and chunks)
  • onFieldChanged()
  • onValidateJobSubmission()

Be sure to call MConsoleAPI functions only from the correct context. To avoid execution errors on templates functions that may be called from multiple contexts (like onValidateJobSubmission()) , you can execute the code selectively:

def onValidateJobSubmission(self,job):
    if (muster.runningContext() == "console"):
        # Prompt a dialog

Install your scripts programmatically

Muster Console supports a script editor window that let you create scripts on the fly and register them. The changes are saved into a scripts.xml file located in your Muster user preferences. Alternatively, you may want to install the script from your Python code , and maybe, globally in your studio. Console supports sourcing a console.py inside the Console root path. If the file is present, you can install your scripts in the following way:

# Content of console.py
 
# Location context may be one of the following: 
# kLocationContextJobViewContextMenu
# kLocationContextHostViewContextMenu
# kLocationContextLogViewContextMenu
# kLocationContextChunkViewContextMenu
# kLocationContextMenuBar
 
# Launching context may be one of the following:
 
# kLaunchContextDispatcher,
# kLaunchContextConsole,
# kLaunchContextOnlineInstances,
# kLaunchContextInstance,
# kLaunchContextInstancesPool
 
import MConsoleAPI
MConsoleAPI.registerScript("Mycommand","Tools",MConsoleAPI.kLocationContextMenuBar,"print('hello!')",MConsoleAPI.kLaunchContextConsole,"")
Function nameExpected parametersAdditional returned objectsMeaning
registerScript()actionName,groupName,locationContext, scriptContent,launchingContext,launchingContextFilterNoneRegister a new custom script into Console
example
getMainWindow()NonePointer to QT main windowReturns a string containing a memory pointer to the QT QMainWindow object that may be used to parent your Pyside widgets
example
getJobsModel()NonePointer to QT QAbstractItemModelReturns a string containing a memory pointer to the QT QAbstractItemModel associated to the jobs
getLogsModel()NonePointer to QT QAbstractItemModelReturns a string containing a memory pointer to the QT QAbstractItemModel associated to the logs
getNodesModel()NonePointer to QT QAbstractItemModelReturns a string containing a memory pointer to the QT QAbstractItemModel associated to the nodes
example
getJobViewSelection()NoneList of selection IDsReturns the IDs of the selected jobs into the current job view, valid only if called from a context menu
example
getInstancesViewSelection()NoneList of selection IDsReturns the IDs of the selected instance into the current instances/nodes view, valid only if called from a context menu
example
getLogsViewSelection()NoneList of selection IDsReturns the IDs of the selected logs into the current logs view, valid only if called from a context menu
example
getChunksViewSelection()NoneChunk view Job ID,List of selection IDsReturns the IDs of the selected chunks into the current chunks view, valid only if called from a context menu
example
nodeKillProcess(id)Node IDNoneKills the current process of the supplied instance ID
nodeKillProcessAndPause(id)Node IDNoneKills the current process and pause the supplied instance ID
nodeKillProcessAndRestart(id)Node IDNoneKills the current process and restarts it on the supplied instance ID
example
nodeKillAndPauseNodesWorkingOnJob(jobID)Node IDNoneKills the current instances processing the supplied job ID
nodeKillAndRedoNodesWorkingOnJob(jobID)Node IDNoneKills the current instances processing the supplied job ID and restarts the job
nodeKillAndGoOnNodesWorkingOnJob(jobID)Node IDNoneKill the current instances processing the supplied job ID
example
nodePause(id)Node IDNonePauses the supplied instance ID
example
nodeResume(id)Node IDNoneResumes the supplied instance ID
example
nodeSetProcessPriority(id,priority)Node IDNew process priorityChanges the process priority level of the supplied instance ID
example
nodeSoftRestart(id)Node IDNoneSoft restarts the supplied instance ID
example
nodePurgeTemplatesExclusion(id,templateId)Node ID, Template IDNoneRemoves the supplied template ID from the exclusion list of the supplied node ID
example
nodePurgeJobsExclusions(id,jobId)Node ID, Job IDNoneRemoves the supplied job ID from the exclusion list of the supplied node ID
example
nodeSetRealtimeLog(bool)Node ID, Real time log statusNoneChanges the real time log status of the supplied instance ID
example
nodeSendSystemEvent(id,event)Node ID, Real time log statusNoneSends the specified system event on the supplied instance ID
example
nodeRunPythonCode(id,code)Node ID, Real time log statusNoneRuns the supplied python code on the supplied instance ID
example
nodeSetNotes(id,notes)Node ID, Real time log statusNoneChanges the notes of the supplied instance ID
example
nodeRemoveRegistration(id)Node ID, Real time log statusNoneRemoves the registration of the specified offline instance ID
example
nodeGetList()NoneNoneGets the list of the registered nodes as MNode objects
example
nodeGet(id)Node IDMNode objectGets the specified instance ID as an MNode object
example
nodeGetByName(name)None nameMNode objectGets the specified instance as an MNode object
example
chunkEnsureAvailability(jobId)Job IDNoneDownloads, if missing, the chunks of the specified job ID and opens the chunks view
example
chunkGetList(jobId)Job IDList of MChunk objectsGets the list of the chunks of the specified job ID
example
chunkGet(jobId,chunkId)Job ID, Chunk IDMChunk objectGets the specified chunk as an MChunk object
example
chunkSetStatus(jobId,chunkId,status)Job ID, Chunk ID, StatusNoneChanges the status of the specified chunk
example
jobGetList()Nonelist of MJob objectsGets the job queue as a list of MJob objects
example
jobGet(id)Job IDMJob objectGets the job from its job ID as an MJob object
example
jobReparent(id, parentId)Job ID, parent Job IDNoneChanges the parent folder of the specified job ID
example
jobSubmit(job)MJob objectNoneSubmit a new job into the queue
example
jobEdit(job)MJob objectNoneEdits the job into the queue
example
jobChangeAttrib(id,name,value)job ID, name of attribute, value of attributeNoneChanges a single attribute of a job on the Dispatcher server and updates the job back on Consoles
example
jobAddFolder(parent,priority,name)parent job ID, folder priority, folder nameNoneSubmits a new folder into the queue
example
jobReinit(id)Job IDNoneReinit the supplied job ID
example
jobDelete(id)Job IDNoneRemoves the specified job ID from the queue
example
logClear()NoneNoneClears the internal log
example
logGetList()Nonelist of MLog objectsGets the logs queue as a list of MLog objects
example
logGet()Log IDMLog objectGets the log from its event ID as an MLog object
example
dispatcherRunPythonCode()Python codeNoneRuns the supplied python code on the Dispatcher
example