Skip to content

logging.md

Latest commit

 

History

History
150 lines (107 loc) · 3.76 KB

logging.md

File metadata and controls

150 lines (107 loc) · 3.76 KB

← Command Reference

Logging and Status Commands

Write diagnostic messages and update the task status shown to users.

Use these commands when you need more visibility during a run. Log adds operator-facing detail to the task log, while Status updates progress and localized status text in the UI. For status-message IDs and their wording, see Status Messages.

Log

Use Log to add a message to the task log from script logic.

Syntax

{
  "Log": {
    "Text": "Entered root shell"
  }
}

Parameters

Name Type Required? Description
Text Value or expression No Message text written to the operation log.

Examples

Log a state transition

From samples/ssh/vcenter-appliance/vCenterServerAppliance.json:

{ "Log": { "Text": "Entered root shell" } }

Log a task-specific warning

From samples/http/onelogin-jit/OneLogin_GRC_JIT_addon.json:

{
  "Log": {
    "Text": "ChangePassword does not do anything. A dummy password is set on the Account by OneLogin but in practice these Accounts will only have TOTP configured and used. Do not use the ChangePassword task."
  }
}

Trace (diagnostic pattern)

Current scripts and current engine source do not expose a separate Trace command. Use Log for explicit script-authored diagnostics, and enable extended logging when you need the engine's debug-level trace output around command execution.

Syntax

{ "Log": { "Text": "Entered root shell" } }

Parameters

Name Type Required? Description
Text Value or expression No Closest script-authored equivalent to a trace message in current scripts.

Example

From samples/ssh/vcenter-appliance/vCenterServerAppliance.json:

{ "Log": { "Text": "No users discovered" } }

SetStatusMessage (Status)

Use Status to publish progress and a localized message while the task is running. This is what end users see in the UI during longer checks, changes, or discovery operations.

Syntax

{
  "Status": {
    "Type": "Checking",
    "Percent": 60,
    "Message": {
      "Name": "AssetTestingConnectionWithAddress",
      "Parameters": [ "%AssetName%", "%Address%" ]
    }
  }
}

Parameters

Name Type Required? Description
Type Status enum Yes Status category such as Connecting, Checking, Changing, or Discovering.
Percent Integer Yes Completion percentage from 0 to 100.
Message.Name Message ID enum Yes Predefined status message identifier from the platform task engine.
Message.Parameters Array of values or expressions No Values inserted into the localized status message.

Examples

Report connection-test progress

From samples/ssh/generic-linux/GenericLinux.json:

{
  "Status": {
    "Type": "Checking",
    "Percent": 60,
    "Message": {
      "Name": "AssetTestingConnectionWithAddress",
      "Parameters": [ "%AssetName%", "%Address%" ]
    }
  }
}

Report discovery progress

From samples/ssh/generic-linux-with-discovery/GenericLinuxWithDiscovery.json:

{
  "Status": {
    "Type": "Discovering",
    "Percent": 75,
    "Message": {
      "Name": "DiscoveringAccounts",
      "Parameters": [ "%AssetName%" ]
    }
  }
}

Notes

Current script-authored logging exposes only Log.Text; severity is not configurable from the command itself in the current engine source.

There is no separate SetStatusMessage keyword in current scripts; status updates use Status.

Cross-References