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()
Jobs APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
jobGetList() | None | a list of MJob objects | Retrieves the complete job list from the Dispatcher queue |
example | |||
jobGet(id) | The ID of the JOB to retrieve | an MJob object | Retrieves a job from the queue |
example | |||
jobReparent(id, newParentID) | The ID of the JOB to reparent and the new parent ID | None | Changes the parent folder of a job |
example | |||
jobSubmit(job, owner) | The MJob object to submit and the job owner name | None | Submits a new job into the queue |
example | |||
jobEdit(job) | The MJob object to edit | None | Edits an existing job of the queue |
example | |||
jobAddFolder(parent, owner, name) | The parent ID, the owner name and and the name of thew new folder | The new folder ID | Creates a new folder into the Dispatcher queue |
example | |||
jobReinit(id) | The job ID to reinint | None | Reinits an existing job |
example | |||
jobDelete(id) | The job ID to delete | None | Deletes a job from the queue |
example | |||
jobUpdateStatus(id) | The job ID to update | None | Recalculates the job status depending of its inner chunks status |
example | |||
jobUpdate(id) | The job ID to update | None | Flushes job changes to the database and updates the job on Consoles |
example |
Chunks APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
chunkGetList(id) | The id of the job to query | A list of MChunk objects | Retrieves the complete chunks list of a job |
example | |||
chunkGet(jobId, chunkId) | The id of the job and the chunk to retrieve | an MChunk object | Retrieves a specific chunk from a job |
example | |||
chunkSetStatus(jobId, chunkId, chunkStatus) | The id of the job and the chunk, and the new chunk status | None | Changes the status of a chunk |
example |
Nodes APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
nodeKillProcess(id) | The id of the node | None | Kills the current node process |
nodeKillProcessAndPause(id) | The id of the node | None | Kills the current node process and pause it |
nodeKillProcessAndRestart(id) | The id of the node | None | Kills the current node process and restart the same |
example | |||
nodeKillAndPauseNodesWorkingOnJob(id) | The id of the node | None | Kills the process on all the nodes working on a job and pause them |
nodeKillAndRedoNodesWorkingOnJob(id) | The id of the node | None | Kills the process on all the nodes working on a job and restarts them |
nodeKillAndGoOnNodesWorkingOnJob(id) | The id of the node | None | Kills the process on all the nodes working on a job |
example | |||
nodePause(id) | The id of the node | None | Pauses a node |
example | |||
nodeResume(id) | The id of the node | None | Resumes a node |
example | |||
nodeForceUpdate(id) | The id of the node | None | Forces the status update of a node |
example | |||
nodeSetProcessPriority(id,priority) | The id of the node and the new priority | None | Changes the process priority on a node |
example | |||
nodeSoftRestart(id) | The id of the node | None | Retrieves a list of MChunk objects of a job |
example | |||
nodePurgeTemplatesExclusion(id,templateId) | The id of the node and the template ID to remove | None | Retrieves a list of MChunk objects of a job |
example | |||
nodePurgeJobsExclusions(id,jobsId) | The id of the node and the job id to remove | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeSetRealtimeLog(id,status) | The id of the node and the real time log status | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeSendSystemEvent(id,event) | The id of the node and the system event to send | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeRunPythonCode(id,code) | The id of the node and the python code | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeSetNotes(id,notes) | The id of the node and the notes to set | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeRemoveRegistration(id) | The id of the node | None | Retrieves a list of MChunk objects of a job |
example | |||
nodeGetList() | None | A list of MNode objects | Retrieves the complete nodes list registered on the Dispatcher |
example | |||
nodeGet(id) | The id of the node to retrieve | an MNode object | Retrieves a node from its ID |
example | |||
nodeGetByName(name) | The name of the node to retrieve | an MNode object | Retrieves a node from its name |
example |
Database APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
dbGetStatisticsBounds() | None | starting time, ending time and number of samples | Gets the size and timing extension of the stored statistics samples |
example | |||
dbGetHistoryBounds() | None | starting time, ending time and number of samples | Gets the size and timing extension of the stored histories samples |
example | |||
dbClearStatisticsBounds(start,end) | Starting and ending time of the samples | None | Clears the statistics samples between the supplied range |
example | |||
dbClearHistoryBounds(start,end) | Starting and ending time of the samples | None | Clears the history samples between the supplied range |
example | |||
dbImportQueueSQL(sql) | The SQL of the queue to import | None | Clear the current queue and imports the supplied SQL code |
example | |||
dbExportQueueSQL() | an MStringRef object | None | Snapshots the current queue and reports its SQL code back |
example |
System APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
systemQueryEngineStatus() | None | The current engine status | Gets the running status of the Dispatcher engine |
systemSwapEngineStatus() | None | None | Swaps the current engine status |
example | |||
systemSoftRestart() | None | None | Soft restarts the Dispatcher |
example | |||
systemResetStatisticsCounters() | None | None | Resets the internal statistics counters |
example | |||
systemStartNodesNetworkScan() | None | None | Starts a network nodes scan |
example | |||
systemGetConfiguration() | None | an MDispatcherConfiguration object | Gets the Dispatcher configuration |
systemSetConfiguration(configuration,store) | the MDispatcherConfiguration object and a boolean to store the configuration permanently | None | Sets the Dispatcher configuration |
example | |||
systemGetLDAPConfiguration() | None | The current queue snapshot in SQL code | Gets the Dispatcher LDAP configuration |
systemSetLDAPConfiguration(configuration,store) | None | The current queue snapshot in SQL code | Sets the Dispatcher configuration |
example | |||
systemGetActivityLogsList() | None | A list of the activity logs filenames | Gets the list of the activity logs |
example | |||
systemGetActivityLog(name) | The filename of the log | The log content | Gets the content of an activity log file |
example | |||
systemRemoveActivityLog(name) | The filename of the log | None | Removes an activity log file |
example | |||
systemGetActionLogsList() | None | A list of the actions logs filename | Gets the list of the actions logs |
example | |||
systemGetActionLog(name) | The filename of the log | The log content | Gets the content of an action log file |
example | |||
systemRemoveActionLog(name) | The filename of the log | None | Removes an action log file |
example |
Logs APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
logClear() | None | None | Clears the current Dispatcher log |
example | |||
logAddInternalMessage() | Message | None | Adds the supplied message to the Dispatcher internal log |
example | |||
logAddMessage() | Message | None | Adds the supplied message to the Dispatcher log |
example |
Users and groups APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
userGetList() | None | a list of MUser objects | Gets the list of the users configured on the Dispatcher service including LDAP users prepended with @directory@ |
example | |||
userGet(name) | Name of the user | an MUser object | Gets the MUser object of the user specified |
userAdd(user) | MUser object | None | Adds a new user |
example | |||
userRemove(name) | Name of the user | None | Removes the user specified |
example | |||
userConfigure(user) | MUser object | None | Flushes the changes on the MUser object |
example | |||
groupGetList() | None | list of MGroup objects | Gets the list of the groups configured on the Dispatcher |
example | |||
groupGet(groupName) | Name of the group | MGroup object | Gets the group specified by the group name as an MGroup object |
groupAdd(group) | None | None | Adds a new group |
example | |||
groupRemove(groupName) | Name of the group | None | Removes the specified group |
example | |||
groupConfigure(group) | MGroup object | None | Flushes the changes on the MGroup object |
example |
Pools APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
poolGetList() | None | list of MPool objects | Gets the list of the pools |
example | |||
poolGet(name) | Name of the pool | MPool object | Gets the pool as an MPool object |
poolConfigure(pool) | MPool object | None | Flushes the changes of the specified pool |
example | |||
poolAdd(pool) | MPool object | None | Adds a new pool |
poolRemove(name) | Name of the pool | None | Removes the specified pool |
poolNotifyChanges() | None | None | Notifies that pools configuration have changed to all Console connected. Required if you want to live update the pools configuration |
example |
Repositories APIs
Function name | Expected parameters | Additional returned objects | Meaning |
---|---|---|---|
repositoriesGetList() | None | list of MRepository objects | Gets the list of the repositories configured on the Dispatcher |
example | |||
repositoriesGet(name) | Name of repository | MRepository object | Gets the repository object by name |
repositoriesConfigure(repository) | MRepository object | None | Flushes the changes to the repository |
example | |||
repositoriesAdd(repository) | MRepository object | None | Adds a new repository |
repositoriesNotifyChanges() | None | None | Notifies that repositories configuration have changed to all Console connected. Required if you want to live update the repositories configuration |
example | |||
repositoriesRemove(repository) | Name of repository | None | Removes the repository object by name |
example |