Muster Dispatcher Python API

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

import MDispatcherAPI

Be aware that , even you can import the MDispatcherAPI module inside any Python script, if will work only inside the Muster builtin Python interpreter and just on the scripts of template functions that are directly invoked by the Dispatcher service. You can still import it widely inside any template, but an attempt to call a function of the Dispatcher 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 MDispatcherAPI 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 MDispatcherAPI
err, jobs = MDispatcherAPI.jobGetList()
if (err.getErrorCode() != 0):
    print("Function failed: " + err.getDescription())
for job in jobs:
    print("Job status: " + str(job.getStatus()) + " name: " + job.getName()) 

Execution contexts

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

  • A Console script that targets the Dispatcher execution context
  • onDispatcherOverrideImpersonationUser()
  • onValidateJobSubmission();
  • onDeleteJob()
  • onSubmitJob()
  • onReinitJob()
  • onEditJob()
  • onJobPropertiesChanged()
  • onJobCompleted()
  • onValidateJobDependancies()
  • onValidateChunkDependancies()
  • onJobStart()
  • onJobEnd()
  • onDispatcherIdling()
Function nameExpected parametersAdditional returned objectsMeaning
jobGetList()Nonea list of MJob objectsRetrieves the complete job list from the Dispatcher queue
example
jobGet(id)The ID of the JOB to retrievean MJob objectRetrieves a job from the queue
example
jobReparent(id, newParentID)The ID of the JOB to reparent and the new parent IDNoneChanges the parent folder of a job
example
jobSubmit(job, owner)The MJob object to submit and the job owner nameNoneSubmits a new job into the queue
example
jobEdit(job)The MJob object to editNoneEdits an existing job of the queue
example
jobAddFolder(parent, owner, name)The parent ID, the owner name and and the name of thew new folderThe new folder IDCreates a new folder into the Dispatcher queue
example
jobReinit(id)The job ID to reinintNoneReinits an existing job
example
jobDelete(id)The job ID to deleteNoneDeletes a job from the queue
example
jobUpdateStatus(id)The job ID to updateNoneRecalculates the job status depending of its inner chunks status
example
jobUpdate(id)The job ID to updateNoneFlushes job changes to the database and updates the job on Consoles
example
Function nameExpected parametersAdditional returned objectsMeaning
chunkGetList(id)The id of the job to queryA list of MChunk objectsRetrieves the complete chunks list of a job
example
chunkGet(jobId, chunkId)The id of the job and the chunk to retrievean MChunk objectRetrieves a specific chunk from a job
example
chunkSetStatus(jobId, chunkId, chunkStatus)The id of the job and the chunk, and the new chunk statusNoneChanges the status of a chunk
example
Function nameExpected parametersAdditional returned objectsMeaning
nodeKillProcess(id)The id of the nodeNoneKills the current node process
nodeKillProcessAndPause(id)The id of the nodeNoneKills the current node process and pause it
nodeKillProcessAndRestart(id)The id of the nodeNoneKills the current node process and restart the same
example
nodeKillAndPauseNodesWorkingOnJob(id)The id of the nodeNoneKills the process on all the nodes working on a job and pause them
nodeKillAndRedoNodesWorkingOnJob(id)The id of the nodeNoneKills the process on all the nodes working on a job and restarts them
nodeKillAndGoOnNodesWorkingOnJob(id)The id of the nodeNoneKills the process on all the nodes working on a job
example
nodePause(id)The id of the nodeNonePauses a node
example
nodeResume(id)The id of the nodeNoneResumes a node
example
nodeForceUpdate(id)The id of the nodeNoneForces the status update of a node
example
nodeSetProcessPriority(id,priority)The id of the node and the new priorityNoneChanges the process priority on a node
example
nodeSoftRestart(id)The id of the nodeNoneRetrieves a list of MChunk objects of a job
example
nodePurgeTemplatesExclusion(id,templateId)The id of the node and the template ID to removeNoneRetrieves a list of MChunk objects of a job
example
nodePurgeJobsExclusions(id,jobsId)The id of the node and the job id to removeNoneRetrieves a list of MChunk objects of a job
example
nodeSetRealtimeLog(id,status)The id of the node and the real time log statusNoneRetrieves a list of MChunk objects of a job
example
nodeSendSystemEvent(id,event)The id of the node and the system event to sendNoneRetrieves a list of MChunk objects of a job
example
nodeRunPythonCode(id,code)The id of the node and the python codeNoneRetrieves a list of MChunk objects of a job
example
nodeSetNotes(id,notes)The id of the node and the notes to setNoneRetrieves a list of MChunk objects of a job
example
nodeRemoveRegistration(id)The id of the nodeNoneRetrieves a list of MChunk objects of a job
example
nodeGetList()NoneA list of MNode objectsRetrieves the complete nodes list registered on the Dispatcher
example
nodeGet(id)The id of the node to retrievean MNode objectRetrieves a node from its ID
example
nodeGetByName(name)The name of the node to retrievean MNode objectRetrieves a node from its name
example
Function nameExpected parametersAdditional returned objectsMeaning
dbGetStatisticsBounds()Nonestarting time, ending time and number of samplesGets the size and timing extension of the stored statistics samples
example
dbGetHistoryBounds()Nonestarting time, ending time and number of samplesGets the size and timing extension of the stored histories samples
example
dbClearStatisticsBounds(start,end)Starting and ending time of the samplesNoneClears the statistics samples between the supplied range
example
dbClearHistoryBounds(start,end)Starting and ending time of the samplesNoneClears the history samples between the supplied range
example
dbImportQueueSQL(sql)The SQL of the queue to importNoneClear the current queue and imports the supplied SQL code
example
dbExportQueueSQL()an MStringRef objectNoneSnapshots the current queue and reports its SQL code back
example
Function nameExpected parametersAdditional returned objectsMeaning
systemQueryEngineStatus()NoneThe current engine statusGets the running status of the Dispatcher engine
systemSwapEngineStatus()NoneNoneSwaps the current engine status
example
systemSoftRestart()NoneNoneSoft restarts the Dispatcher
example
systemResetStatisticsCounters()NoneNoneResets the internal statistics counters
example
systemStartNodesNetworkScan()NoneNoneStarts a network nodes scan
example
systemGetConfiguration()Nonean MDispatcherConfiguration objectGets the Dispatcher configuration
systemSetConfiguration(configuration,store)the MDispatcherConfiguration object and a boolean to store the configuration permanentlyNoneSets the Dispatcher configuration
example
systemGetLDAPConfiguration()NoneThe current queue snapshot in SQL codeGets the Dispatcher LDAP configuration
systemSetLDAPConfiguration(configuration,store)NoneThe current queue snapshot in SQL codeSets the Dispatcher configuration
example
systemGetActivityLogsList()NoneA list of the activity logs filenamesGets the list of the activity logs
example
systemGetActivityLog(name)The filename of the logThe log contentGets the content of an activity log file
example
systemRemoveActivityLog(name)The filename of the logNoneRemoves an activity log file
example
systemGetActionLogsList()NoneA list of the actions logs filenameGets the list of the actions logs
example
systemGetActionLog(name)The filename of the logThe log contentGets the content of an action log file
example
systemRemoveActionLog(name)The filename of the logNoneRemoves an action log file
example
Function nameExpected parametersAdditional returned objectsMeaning
logClear()NoneNoneClears the current Dispatcher log
example
logAddInternalMessage()MessageNoneAdds the supplied message to the Dispatcher internal log
example
logAddMessage()MessageNoneAdds the supplied message to the Dispatcher log
example
Function nameExpected parametersAdditional returned objectsMeaning
userGetList()Nonea list of MUser objectsGets the list of the users configured on the Dispatcher service including LDAP users prepended with @directory@
example
userGet(name)Name of the useran MUser objectGets the MUser object of the user specified
userAdd(user)MUser objectNoneAdds a new user
example
userRemove(name)Name of the userNoneRemoves the user specified
example
userConfigure(user)MUser objectNoneFlushes the changes on the MUser object
example
groupGetList()Nonelist of MGroup objectsGets the list of the groups configured on the Dispatcher
example
groupGet(groupName)Name of the groupMGroup objectGets the group specified by the group name as an MGroup object
groupAdd(group)NoneNoneAdds a new group
example
groupRemove(groupName)Name of the groupNoneRemoves the specified group
example
groupConfigure(group)MGroup objectNoneFlushes the changes on the MGroup object
example
Function nameExpected parametersAdditional returned objectsMeaning
poolGetList()Nonelist of MPool objectsGets the list of the pools
example
poolGet(name)Name of the poolMPool objectGets the pool as an MPool object
poolConfigure(pool)MPool objectNoneFlushes the changes of the specified pool
example
poolAdd(pool)MPool objectNoneAdds a new pool
poolRemove(name)Name of the poolNoneRemoves the specified pool
poolNotifyChanges()NoneNoneNotifies that pools configuration have changed to all Console connected. Required if you want to live update the pools configuration
example
Function nameExpected parametersAdditional returned objectsMeaning
repositoriesGetList()Nonelist of MRepository objectsGets the list of the repositories configured on the Dispatcher
example
repositoriesGet(name)Name of repositoryMRepository objectGets the repository object by name
repositoriesConfigure(repository)MRepository objectNoneFlushes the changes to the repository
example
repositoriesAdd(repository)MRepository objectNoneAdds a new repository
repositoriesNotifyChanges()NoneNoneNotifies that repositories configuration have changed to all Console connected. Required if you want to live update the repositories configuration
example
repositoriesRemove(repository)Name of repositoryNoneRemoves the repository object by name
example