Skip to main content

PayComplete™™ Help Center

Zero Touch Services troubleshooting

Zero Touch Services is a set of features that make it possible to perform a number of operations without going on-site. The information available here applies to Remote software upgrade and Remote configuration update.

Important

Machines must be online for the ZTS features to work.

Zero Touch Services status overview

These are the statuses a remote software upgrade or remote configuration update can have:

PENDING

The Zero Touch Services action was initiated from the Connect UI. Connect will request the installation of the new package using the RM Protocol Reply Message, which is sent as a response to the next SystemStatus message received from the machine.

SENT

The RM Protocol Reply Message contains the package installation request with details.

When the RM Protocol Reply Message is sent to the machine as a response to the next SystemStatus message, Connect changes the status of the Zero Touch Services action to SENT. This means that Connect assumes that the machine is notified about the requested Zero Touch Services action.

Note

  • If all of these three criteria are met, Connect retries the request to install the package in the next RM Protocol Reply Message:

    • Zero Touch Services has the Zero Touch Services action in SENT status

    • The next SystemStatus message doesn’t contain the expected SetSoftwareUpgrade.WAITING section

    • The values in the SetSoftwareUpgrade.CURRENT section don’t match the target values

  • Target values are the values indicating that the requested installation was successful.

WAITING

Connect receives a SystemStatus message from the machine with the following section:

"SetSoftwareUpgrade": {
  "WAITING": {...

The section has details about the requested package installation. If these details match the package installation details previously requested by Connect, and if the Zero Touch Services action is currently in SENT status, the status is changed to WAITING.

DONE

Connect receives a SystemStatus message from the machine. The SystemStatus message has the following section:

"SetSoftwareUpgrade": {
  "CURRENT": {...

The section has details about the currently installed package. If these details match the package installation details previously requested by Connect, and if the Zero Touch Services action is currently in WAITING status, the status is changed to DONE.

The version field of the SystemStatus message now matches the requested package version.

CANCELLING

The Zero Touch Services action that was in progress - that is, in PENDING, SENT, or WAITING status - was canceled from the Connect UI, but the machine has not yet been notified about the cancellation.

The notification to the machine is sent when the RM Protocol Reply Message for the next System Status message is received from the machine.

CANCELED

The Zero Touch Services action was canceled before the new version was installed.

Troubleshooting Zero Touch Services

When troubleshooting Zero Touch Services,it is important to remember that the whole process relies on SystemStatus messages and their replies. If a machine, for some reason, doesn’t send messages, Connect can’t trigger Zero Touch Services actions or track the progress of requested Zero Touch Services actions. Currently, System Status retention in Connect is one month, and it is not possible to troubleshoot any problems that happened more than one month ago.

Check firewall settings

If all Zero Touch Services actions fail or get stuck in SENT status, the issues might be related to your firewall settings. If your machines are behind a firewall, you need to make sure they have access to https://storage.<domain_name>:9000.

For more information, see Firewall whitelist requirements

Possible causes of stuck statuses

You can draw conclusions regarding the potential reason for Zero Touch Services getting stuck in a certain status based on the status overview: Zero Touch Services status overview

Stuck in PENDING status

  1. The machine can be catching up, offline, or not connected to your Connect Cloud instance at all. Try these steps to find the cause and its resolution:

    1. Verify against the Machine online status report if the machine is online.

    2. If the machine is missing from the Machine online status report, it means that the machine has never communicated with your instance of Connect.

    3. If the machine is offline/has never communicated with your instance of Connect, stuck in PENDING status is valid. To resolve the issue, you need to make the machine communicate with Connect.

Stuck in SENT status

  1. The machine has not properly processed the RM Reply Message requesting the package installation. Try these steps to find the cause and its resolution:

    1. Verify Connect on-Device logs and check to see if you can find the reason why the machine has failed to process the instruction.

    2. If reviewing the logs doesn’t bring any clarity, try canceling the Zero Touch Services action and triggering it once again.

  2. The machine is in catching-up/offline mode and Connect has not yet received the SystemStatus message, allowing it to set the action status to WAITING.

Stuck in WAITING status

  1. The machine has a poor Internet connection, and it is taking a long time to download the requested file. This is a valid suspicion, especially if the software upgrade file is large.

  2. The machine fails to download the file. Try this resolution:

    1. In the Connect UI, check if you can download the requested file from a web browser.

  3. The software installation is scheduled for a future date.

  4. The machine is in catching-up/offline mode and Connect has not yet received the SystemStatus message, allowing it to set the action status to DONE.

See also

Articles