MAPI service MorpheeProcessControl

To get MorpheeProcessControl service use:

with MAPIServices.instance.get_service("MorpheeProcessControl") as mpc:

Bases: MAPIServiceWithSignalR

MorpheeProcessControl MAPI service allows to control MORPHEE process: Test if MORPHEE is launched. Start MORPHEE. Manage MORPHEE report dialog. Call init_signalr if you intend to use the signalr hub events and with keyword on the MorpheeProcessControlServiceProxy object to be sure that the communication is closed at the end.

Source code in restmapi\restmapi\services.py

class MorpheeProcessControlServiceProxy(MAPIServiceWithSignalR):
	"""MorpheeProcessControl MAPI service allows to control MORPHEE process:
	Test if MORPHEE is launched.
	Start MORPHEE.
	Manage MORPHEE report dialog.
	Call init_signalr if you intend to use the signalr hub events and with keyword on the MorpheeProcessControlServiceProxy object to be sure that the communication is closed at the end.
	"""
	def __init__(self, url):
		"""DO NOT create MorpheeProcessControlServiceProxy by yourself. Always use MAPIServices.get_service("MorpheeProcessControl") method to create it.

		Parameters
		----------
		url : string
			Base URL to create of the REST service.
		"""
		super().__init__(url, "MorpheeProcessControl")

	def is_morphee_started(self):
		"""Check if morphee is started and MORPHEE MAPI REST services are available.
		Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services.
		You can is_morphee_process_started() to know that MORPHEE process is started.

		Returns
		-------
		bool
			Returns True if MORPHEE is started and available for REST requests.
		"""
		return self.invoke_web_get_request("IsMorpheeStarted")

	def is_morphee_process_started(self):
		"""Check if MORPHEE process is started. is_morphee_process_started() becomes true immediately after the process creation, but is_morphee_started() becomes true only when MORPHEE MAPI services are available.

		Returns
		-------
		bool
			Returns True if MORPHEE is started.
		"""
		return self.invoke_web_get_request("IsMorpheeProcessStarted")

	def get_number_of_instances(self):
		"""Get the number of MORPHEE instances including the master instance

		Returns
		-------
		int
			Number of MORPHEE instances
		"""
		return self.invoke_web_get_request("NumberOfInstances")

	def is_morphee_instance_started(self, instance):
		"""Check if morphee instance is started and MORPHEE MAPI REST services are available.
		Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services.
		You can is_morphee_instance_process_started() to know that MORPHEE process is started.

		Parameters
		----------
		instance : int
			Requested MORPHEE instance number

		Returns
		-------
		bool
			Returns True if MORPHEE is started and MORPHEE MAPI services are available
		"""
		return self.invoke_web_get_request(f"IsMorpheeInstanceStarted?instance={instance}")

	def is_morphee_instance_process_started(self, instance):
		"""Check if MORPHEE process is started. is_morphee_instance_process_started() becomes true immediately after the process creation, but is_morphee_instance_started() becomes true only when MORPHEE MAPI services are available.

		Parameters
		----------
		instance : int
			Requested MORPHEE instance number

		Returns
		-------
		bool
			Returns True if MORPHEE instance is started.
		"""
		return self.invoke_web_get_request(f"IsMorpheeInstanceProcessStarted?instance={instance}")

	def start(self, cmdLine = None, startAs = None, sessionId = None):
		"""Start MORPHEE.

		Parameters
		----------
		cmdLine : string, optional
			process command line arguments, by default None. For example, "-1" to start MORPHEE instance1.
		startAs : string, optional
			account used for starting the process, by default None.
			Values:
			- "lsa" Start the process as local system administrator account	
			- "morphee_interactive" Start the process as the current TM interactive user
			- "current" Start the process as the current windows login
			- "runas" Start the process using the administrator account (process will start by RunAs.exe application)
		sessionId : string, optional
			Current windows sessionId, by default None. When started in a RDP session, the current user session has to be set if you want to see the MORPHEE window into your RDP session.
			The method get_current_session_id should returns the current id.

		Returns
		-------
		Process
			Returns the MORPHEE process object.
		"""
		if cmdLine == None and startAs == None and sessionId == None:		
			pid = self.invoke_web_post_request("Start")
		else:
			query = ""
			if cmdLine != None:
				query = f"commandLine={cmdLine}&"
			if startAs != None:
				query += f"startAs={startAs}&"		
			if sessionId != None:
				query += f"sessionId={sessionId}&"
			query = query.rstrip("&")								
			pid = self.invoke_web_post_request(f"Start?{query}")								
		return psutil.Process(pid)

	def get_current_session_id(self):
		"""Get the current Windows session id (CAUTION that method fails for now).

		Returns
		-------
		int
			Current session id.
		"""
		return os.getsid(os.getpid())

	def is_report_pending(self, instance = 0):
		"""Check if a MORPHEE report is displayed. If yes, use get_report_messages to get the content.

		Parameters
		----------
		instance : int, optional
			MORPHEE instance number (0 master instance), by default 0.

		Returns
		-------
		bool
			Return if a MORPHEE report is displayed.
		"""
		return self.invoke_web_get_request(f"Report/{instance}/Pending")

	def get_report_messages(self, instance = 0):
		"""Get the content of a pending MORPHEE report window.

		Parameters
		----------
		instance : int, optional
			MORPHEE instance number (0 master instance), by default 0

		Returns
		-------
		ReportMessage array
			Returns an array of ReportMessage.
			The class RestReportMessage contains 3 parameters:
				- string severity ("Warning", "Error" or "FatalError")
				- string message
				- string source
		"""
		return self.invoke_web_get_request(f"Report/{instance}/Messages")

	def close_report(self, instance = 0, result = None):
		"""Close a pending MORPHEE report.
		Note that the report default button is OK if every messages are warning.
		If one message is an error or FatalError, the default button is Cancel.
		If one message is a FatalError, the OK button is disabled.

		Parameters
		----------
		instance : int, optional
			MORPHEE instance number (0 master instance), by default 0
		result : string, optional
			 A string convert from DialogResult enum ("OK" or "Cancel"). If the parameter is omitted, the report is closed using the default button.
		"""
		if result == None:		
			self.invoke_web_post_request(f"Report/{instance}/Close")
		else:
			self.invoke_web_post_request(f"Report/{instance}/Close?result={result}")

	def get_main_window_handles(self):
		"""Get MainWindow handles of morphee processes.

		Returns
		-------
		int array
			Returns MainWindow handles of morphee processes. You can use them to show/hide/activate MORPHEE main window.
		"""
		return self.invoke_web_get_request("MainWindowHandles")

	def register_started_callback(self, action):
		"""Register a signalR callback to be called when a MORPHEE instance is started.
		init_signalr() method has to be called before to initialize signalR communication.

		Parameters
		----------
		action : Function with an int parameter
			A callback function with  a parameter (instance number who send the event (0 for master instance)).
		"""
		self.hub.client.on('MorpheeStarted', action)

	def register_stopped_callback(self, action):
		"""Register a signalR callback to be called when a MORPHEE instance is stopped.
		init_signalr() method has to be called before to initialize signalR communication.

		Parameters
		----------
		action : Function with an int parameter
			A callback function with  a parameter (instance number who send the event (0 for master instance)).
		"""
		self.hub.client.on('MorpheeStopped', action)

	def register_report_updated_callback(self, action):
		"""Register a signalR callback to be called when a MORPHEE instance open or close a report dialog.
		init_signalr() method has to be called before to initialize signalR communication.

		Parameters
		----------
		action : Function with an int parameter
			A callback function with  a parameter (instance number who send the event (0 for master instance)).
		"""
		self.hub.client.on('MorpheeReportUpdated', action)						

__init__(url)

DO NOT create MorpheeProcessControlServiceProxy by yourself. Always use MAPIServices.get_service("MorpheeProcessControl") method to create it.

Parameters:

• url (string) –

  Base URL to create of the REST service.
  

Source code in restmapi\restmapi\services.py

def __init__(self, url):
	"""DO NOT create MorpheeProcessControlServiceProxy by yourself. Always use MAPIServices.get_service("MorpheeProcessControl") method to create it.

	Parameters
	----------
	url : string
		Base URL to create of the REST service.
	"""
	super().__init__(url, "MorpheeProcessControl")

close_report(instance=0, result=None)

Close a pending MORPHEE report. Note that the report default button is OK if every messages are warning. If one message is an error or FatalError, the default button is Cancel. If one message is a FatalError, the OK button is disabled.

Parameters:

• instance (int, default: 0 ) –

  MORPHEE instance number (0 master instance), by default 0
  

• result (string, default: None ) –

   A string convert from DialogResult enum ("OK" or "Cancel"). If the parameter is omitted, the report is closed using the default button.
  

Source code in restmapi\restmapi\services.py

def close_report(self, instance = 0, result = None):
	"""Close a pending MORPHEE report.
	Note that the report default button is OK if every messages are warning.
	If one message is an error or FatalError, the default button is Cancel.
	If one message is a FatalError, the OK button is disabled.

	Parameters
	----------
	instance : int, optional
		MORPHEE instance number (0 master instance), by default 0
	result : string, optional
		 A string convert from DialogResult enum ("OK" or "Cancel"). If the parameter is omitted, the report is closed using the default button.
	"""
	if result == None:		
		self.invoke_web_post_request(f"Report/{instance}/Close")
	else:
		self.invoke_web_post_request(f"Report/{instance}/Close?result={result}")

get_current_session_id()

Get the current Windows session id (CAUTION that method fails for now).

Returns:

• int –

  Current session id.

Source code in restmapi\restmapi\services.py

def get_current_session_id(self):
	"""Get the current Windows session id (CAUTION that method fails for now).

	Returns
	-------
	int
		Current session id.
	"""
	return os.getsid(os.getpid())

get_main_window_handles()

Get MainWindow handles of morphee processes.

Returns:

• int array –

  Returns MainWindow handles of morphee processes. You can use them to show/hide/activate MORPHEE main window.

Source code in restmapi\restmapi\services.py

def get_main_window_handles(self):
	"""Get MainWindow handles of morphee processes.

	Returns
	-------
	int array
		Returns MainWindow handles of morphee processes. You can use them to show/hide/activate MORPHEE main window.
	"""
	return self.invoke_web_get_request("MainWindowHandles")

get_number_of_instances()

Get the number of MORPHEE instances including the master instance

Returns:

• int –

  Number of MORPHEE instances

Source code in restmapi\restmapi\services.py

def get_number_of_instances(self):
	"""Get the number of MORPHEE instances including the master instance

	Returns
	-------
	int
		Number of MORPHEE instances
	"""
	return self.invoke_web_get_request("NumberOfInstances")

get_report_messages(instance=0)

Get the content of a pending MORPHEE report window.

Parameters:

• instance (int, default: 0 ) –

  MORPHEE instance number (0 master instance), by default 0
  

Returns:

• ReportMessage array –

  Returns an array of ReportMessage. The class RestReportMessage contains 3 parameters: - string severity ("Warning", "Error" or "FatalError") - string message - string source

Source code in restmapi\restmapi\services.py

def get_report_messages(self, instance = 0):
	"""Get the content of a pending MORPHEE report window.

	Parameters
	----------
	instance : int, optional
		MORPHEE instance number (0 master instance), by default 0

	Returns
	-------
	ReportMessage array
		Returns an array of ReportMessage.
		The class RestReportMessage contains 3 parameters:
			- string severity ("Warning", "Error" or "FatalError")
			- string message
			- string source
	"""
	return self.invoke_web_get_request(f"Report/{instance}/Messages")

is_morphee_instance_process_started(instance)

Check if MORPHEE process is started. is_morphee_instance_process_started() becomes true immediately after the process creation, but is_morphee_instance_started() becomes true only when MORPHEE MAPI services are available.

Parameters:

• instance (int) –

  Requested MORPHEE instance number
  

Returns:

• bool –

  Returns True if MORPHEE instance is started.

Source code in restmapi\restmapi\services.py

def is_morphee_instance_process_started(self, instance):
	"""Check if MORPHEE process is started. is_morphee_instance_process_started() becomes true immediately after the process creation, but is_morphee_instance_started() becomes true only when MORPHEE MAPI services are available.

	Parameters
	----------
	instance : int
		Requested MORPHEE instance number

	Returns
	-------
	bool
		Returns True if MORPHEE instance is started.
	"""
	return self.invoke_web_get_request(f"IsMorpheeInstanceProcessStarted?instance={instance}")

is_morphee_instance_started(instance)

Check if morphee instance is started and MORPHEE MAPI REST services are available. Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services. You can is_morphee_instance_process_started() to know that MORPHEE process is started.

Parameters:

• instance (int) –

  Requested MORPHEE instance number
  

Returns:

• bool –

  Returns True if MORPHEE is started and MORPHEE MAPI services are available

Source code in restmapi\restmapi\services.py

def is_morphee_instance_started(self, instance):
	"""Check if morphee instance is started and MORPHEE MAPI REST services are available.
	Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services.
	You can is_morphee_instance_process_started() to know that MORPHEE process is started.

	Parameters
	----------
	instance : int
		Requested MORPHEE instance number

	Returns
	-------
	bool
		Returns True if MORPHEE is started and MORPHEE MAPI services are available
	"""
	return self.invoke_web_get_request(f"IsMorpheeInstanceStarted?instance={instance}")

is_morphee_process_started()

Check if MORPHEE process is started. is_morphee_process_started() becomes true immediately after the process creation, but is_morphee_started() becomes true only when MORPHEE MAPI services are available.

Returns:

• bool –

  Returns True if MORPHEE is started.

Source code in restmapi\restmapi\services.py

def is_morphee_process_started(self):
	"""Check if MORPHEE process is started. is_morphee_process_started() becomes true immediately after the process creation, but is_morphee_started() becomes true only when MORPHEE MAPI services are available.

	Returns
	-------
	bool
		Returns True if MORPHEE is started.
	"""
	return self.invoke_web_get_request("IsMorpheeProcessStarted")

is_morphee_started()

Check if morphee is started and MORPHEE MAPI REST services are available. Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services. You can is_morphee_process_started() to know that MORPHEE process is started.

Returns:

• bool –

  Returns True if MORPHEE is started and available for REST requests.

Source code in restmapi\restmapi\services.py

def is_morphee_started(self):
	"""Check if morphee is started and MORPHEE MAPI REST services are available.
	Note that when MORPHEE starts, it can take some time before having MORPHEE MAPI REST services.
	You can is_morphee_process_started() to know that MORPHEE process is started.

	Returns
	-------
	bool
		Returns True if MORPHEE is started and available for REST requests.
	"""
	return self.invoke_web_get_request("IsMorpheeStarted")

is_report_pending(instance=0)

Check if a MORPHEE report is displayed. If yes, use get_report_messages to get the content.

Parameters:

• instance (int, default: 0 ) –

  MORPHEE instance number (0 master instance), by default 0.
  

Returns:

• bool –

  Return if a MORPHEE report is displayed.

Source code in restmapi\restmapi\services.py

def is_report_pending(self, instance = 0):
	"""Check if a MORPHEE report is displayed. If yes, use get_report_messages to get the content.

	Parameters
	----------
	instance : int, optional
		MORPHEE instance number (0 master instance), by default 0.

	Returns
	-------
	bool
		Return if a MORPHEE report is displayed.
	"""
	return self.invoke_web_get_request(f"Report/{instance}/Pending")

register_report_updated_callback(action)

Register a signalR callback to be called when a MORPHEE instance open or close a report dialog. init_signalr() method has to be called before to initialize signalR communication.

Parameters:

• action (Function with an int parameter) –

  A callback function with  a parameter (instance number who send the event (0 for master instance)).
  

Source code in restmapi\restmapi\services.py

def register_report_updated_callback(self, action):
	"""Register a signalR callback to be called when a MORPHEE instance open or close a report dialog.
	init_signalr() method has to be called before to initialize signalR communication.

	Parameters
	----------
	action : Function with an int parameter
		A callback function with  a parameter (instance number who send the event (0 for master instance)).
	"""
	self.hub.client.on('MorpheeReportUpdated', action)						

register_started_callback(action)

Register a signalR callback to be called when a MORPHEE instance is started. init_signalr() method has to be called before to initialize signalR communication.

Parameters:

• action (Function with an int parameter) –

  A callback function with  a parameter (instance number who send the event (0 for master instance)).
  

Source code in restmapi\restmapi\services.py

def register_started_callback(self, action):
	"""Register a signalR callback to be called when a MORPHEE instance is started.
	init_signalr() method has to be called before to initialize signalR communication.

	Parameters
	----------
	action : Function with an int parameter
		A callback function with  a parameter (instance number who send the event (0 for master instance)).
	"""
	self.hub.client.on('MorpheeStarted', action)

register_stopped_callback(action)

Register a signalR callback to be called when a MORPHEE instance is stopped. init_signalr() method has to be called before to initialize signalR communication.

Parameters:

• action (Function with an int parameter) –

  A callback function with  a parameter (instance number who send the event (0 for master instance)).
  

Source code in restmapi\restmapi\services.py

def register_stopped_callback(self, action):
	"""Register a signalR callback to be called when a MORPHEE instance is stopped.
	init_signalr() method has to be called before to initialize signalR communication.

	Parameters
	----------
	action : Function with an int parameter
		A callback function with  a parameter (instance number who send the event (0 for master instance)).
	"""
	self.hub.client.on('MorpheeStopped', action)

start(cmdLine=None, startAs=None, sessionId=None)

Start MORPHEE.

Parameters:

• cmdLine (string, default: None ) –

  process command line arguments, by default None. For example, "-1" to start MORPHEE instance1.
  

• startAs (string, default: None ) –

  account used for starting the process, by default None.
  Values:
  - "lsa" Start the process as local system administrator account 
  - "morphee_interactive" Start the process as the current TM interactive user
  - "current" Start the process as the current windows login
  - "runas" Start the process using the administrator account (process will start by RunAs.exe application)
  

• sessionId (string, default: None ) –

  Current windows sessionId, by default None. When started in a RDP session, the current user session has to be set if you want to see the MORPHEE window into your RDP session.
  The method get_current_session_id should returns the current id.
  

Returns:

• Process –

  Returns the MORPHEE process object.

Source code in restmapi\restmapi\services.py

def start(self, cmdLine = None, startAs = None, sessionId = None):
	"""Start MORPHEE.

	Parameters
	----------
	cmdLine : string, optional
		process command line arguments, by default None. For example, "-1" to start MORPHEE instance1.
	startAs : string, optional
		account used for starting the process, by default None.
		Values:
		- "lsa" Start the process as local system administrator account	
		- "morphee_interactive" Start the process as the current TM interactive user
		- "current" Start the process as the current windows login
		- "runas" Start the process using the administrator account (process will start by RunAs.exe application)
	sessionId : string, optional
		Current windows sessionId, by default None. When started in a RDP session, the current user session has to be set if you want to see the MORPHEE window into your RDP session.
		The method get_current_session_id should returns the current id.

	Returns
	-------
	Process
		Returns the MORPHEE process object.
	"""
	if cmdLine == None and startAs == None and sessionId == None:		
		pid = self.invoke_web_post_request("Start")
	else:
		query = ""
		if cmdLine != None:
			query = f"commandLine={cmdLine}&"
		if startAs != None:
			query += f"startAs={startAs}&"		
		if sessionId != None:
			query += f"sessionId={sessionId}&"
		query = query.rstrip("&")								
		pid = self.invoke_web_post_request(f"Start?{query}")								
	return psutil.Process(pid)