List Windows Services

Reads the full service inventory of one or more Windows servers and records each service name with its current state. Nothing is started or stopped. Use it to find out what is installed on a box, or to capture the service states on either side of a deployment and compare the two.

When you already know the service name and want to act on it, use Windows service instead. That op takes one name and can start, stop or restart it.

Both fields expand ${var} placeholders against the stash before the op runs.

Fields

Server

The Windows servers to query. The picker lists the resources that can take an agent connection, plus the variables that resolve to one.

More than one server can be selected, and they are queried one after another rather than in parallel. A variable holding a comma-separated list is split on the commas and treated the same way.

The field is required. A value that does not resolve to a real resource ends the step with a resource error, as does a server that cannot be reached. The server has to be reachable through a Clarive agent or a worker; a resource configured for plain SSH only does not return the structured command result this op reads, and the step ends with an error.

A server marked inactive is not contacted. A warning goes into the job log, its entry in the result carries _error set to INACTIVE instead of a service map, and the run moves on.

A server that connects but answers the query with nothing at all ends the step with an error, and the servers queued behind it are never queried.

Output that comes back but cannot be read as a service list fails much more quietly. The return code of the query is never looked at, so an access-denied message, or anything else the box prints in place of an inventory, leaves that server with an empty map and the run carries on to the next one. An empty map for a server you know is running services means the query was refused or answered with something unexpected.

The connection uses whatever the server resource is configured with, including its user and its agent timeout. This op has no user field of its own.

Filter (optional)

A case-insensitive regular expression matched against the service names. Leave it blank and every service comes back.

The match is unanchored, so sql keeps anything containing sql anywhere in the name. Anchor it yourself when you need to: ^foo for names that start with foo, svc$ for names that end with svc, ^foosvc$ for an exact name.

The pattern is matched against the short service name only, never the display name. A filter written against what the Services console shows you comes back empty.

An expression the server cannot parse, foo( for instance, ends the step with an error. Test the pattern before you commit it to a production rule.

Status values

Each service is recorded with one of these, in English, whatever display language the Windows box runs.

Status	Meaning
RUNNING	the service is running
STOPPED	the service is stopped
START_PENDING	the service is starting
STOP_PENDING	the service is stopping
PAUSE_PENDING	the service is pausing
CONTINUE_PENDING	the service is resuming
PAUSED	the service is paused
UNKNOWN	the state came back as a value this op does not recognise

A service whose state line cannot be read at all is dropped from the result rather than reported as UNKNOWN. An absent entry means either the filter excluded it or the state was unreadable, and the two cases look the same from the outside.

What lands in the stash

The op writes windows_services_list, a map of server name to a map of service name to status:

windows_services_list:
  bar_host:
    fooagent:  RUNNING
    bazsvc:    STOPPED
  baz_host:
    fooagent:  STOPPED

The key is fixed, and a second List Windows Services op later in the rule overwrites it. Fill in Return Key on the op to store the same structure under a name of your own when the rule queries more than once.

The inner map is keyed by service name, so it has no order. A typical Windows server returns a few hundred entries per server when no filter is set, and there is no cap on the size, so filter when you only need a handful.

The number of services found per server is reported at debug level only. At the default log level a successful run writes nothing to the job log.

This op reads and never writes, so it takes no part in rollback and registers no undo.

Combining with other ops

Run this first, then branch with IF var condition THEN on a path such as windows_services_list.bar_host.fooagent before handing the name to Windows service.

This is also the only way to tell an uninstalled service from a stopped one. The status action on Windows service answers STOPPED for a name that is not present on the box, so it cannot distinguish the two. Run this op with the filter blank and check whether the key exists under the server name.

Snapshot the list into your own variable with Return Key before a deployment and again after it, then compare the two with Code to spot services that changed state while the job ran.

Write the result somewhere readable with LOG Message when the point of the step is an audit trail rather than a decision.

Examples

Inventory every service on a group of servers.

Server             ${target_servers}
Filter (optional)  (blank)

Narrow to the services of one product before acting on them.

Server             bar_host, baz_host
Filter (optional)  ^foo

Confirm a single service name, exactly, on one host.

Server             bar_host
Filter (optional)  ^fooagent$