Skip to main content

Force a reset or reinstallation of a Medulla agent

Applies to: Medulla Server
Version: 5.6.4 and later
Environment: On-Premise
Category: Agent / Diagnostics / Maintenance

Starting with version Medulla 5.6.4, it is possible to instruct the Medulla server to force a reset of an agent.

This operation can be used, for example, when an agent encounters a persistent malfunction, such as when it no longer updates correctly.

The reset is initiated by adding the computer’s JID to the table:

xmppmaster.reset_machine

Important:
The operations described in this documentation directly affect the Medulla database. They must be performed with caution and only by a platform administrator.


1. Identify the computer’s JID

To request a computer reset, you must have its Medulla JID.

The JID can be looked up directly in the xmppmaster.machines table.

For example, to search for a computer using part of its name:

SELECT jid
FROM xmppmaster.machines
WHERE jid LIKE '%MACHINE_NAME%';

Example JID:

spo-w11-1.o68@spo-ars01/bc241109f61e

Note:
Always use the full JID returned by Medulla to precisely target the computer in question.


2. Force a reset of an agent

To request a reset for a specific agent, add its JID to the xmppmaster.reset_machine table.

Example:

INSERT INTO xmppmaster.reset_machine (jid, reason)
VALUES ('spo-w11-1.o68@spo-ars01/bc241109f61e', 'Unstable agent');

The reason field allows you to specify the reason for requesting the reset.

It is recommended to use a description that clearly identifies the reason for the operation.

For example:

INSERT INTO xmppmaster.reset_machine (jid, reason)
VALUES ('MACHINE_JID', 'Agent update issue');

3. Verify the reset request

After inserting the record, you can verify that the request is present in the table:

SELECT *
FROM xmppmaster.reset_machine
WHERE jid = 'spo-w11-1.o68@spo-ars01/bc241109f61e';

This check confirms that the reset request has been successfully recorded.


4. Force a reset of all agents

It is also possible to request a reset of all machine-type agents registered in Medulla.

Before performing this operation, it is strongly recommended that you verify the list of affected computers:

SELECT jid
FROM xmppmaster.machines
WHERE agenttype = 'machine';

To then request a reset of all these agents:

INSERT INTO xmppmaster.reset_machine (jid, reason)
SELECT jid, 'Reset all agents'
FROM xmppmaster.machines
WHERE agenttype = 'machine';

Caution:
This command applies to all machine-type agents registered in Medulla. It should not be used to resolve an isolated incident on a single workstation.


5. Check the number of computers before a global reset

Before performing a global reset, you can verify the number of affected agents using:

SELECT COUNT(*)
FROM xmppmaster.machines
WHERE agenttype = 'machine';

You can also view the exact data that will be used to populate the reset table:

SELECT jid, 'Reset all agents' AS reason
FROM xmppmaster.machines
WHERE agenttype = 'machine';

Recommendation:
Always run this verification query before the INSERT ... SELECT command to verify the scope of the operation.


6. Use cases

Resetting an agent can be used in the following situations, among others:

  • an agent is no longer updating correctly;
  • an agent remains in an inconsistent state despite standard diagnostic procedures;
  • Medulla Support explicitly requests that the agent be forcibly reset;
  • a maintenance operation requires resetting a set of agents.

Important:
Resetting an agent should not be the first diagnostic step. If an agent malfunctions, it is recommended to first identify the source of the problem and, if necessary, use the Medulla diagnostic tool.


7. Agent reset or global reset?

Requirement Recommended method
Problem on a single computer Add only the computer’s JID to xmppmaster.reset_machine
Agent no longer updating Perform an individual reset after diagnosis
Multiple computers identified Enter only the JIDs of the affected computers
Reset the entire fleet Use INSERT ... SELECT after verifying the scope

8. Best practices

  • reset only a single computer when the incident is isolated;
  • verify the JID before submitting the reset request;
  • provide an explicit reason in the reason field;
  • verify the number of computers before performing any global operation;
  • do not use a global reset to resolve an issue affecting only a few computers;
  • perform a diagnostic check on the agent before requesting a reset when the cause of the problem is unknown.

Recommendation:
If a problem occurs with a Medulla agent, always prioritize a targeted reset using the JID of the affected computer. A global reset of all agents should remain an exceptional and carefully controlled operation.