Executing Actions on Clients

In this article:

Overview - Basic overview of client action execution

Workflow Activity Usage - How to use the ExecuteActionOnClient workflow activity

Action Expressions - How to build action expressions

Executing the Workflow - How to execute the workflow and ExecuteActionOnClient activity

Troubleshooting - Troubleshooting tips if the activity does not return data

Further Information - Where to go for further information

Overview

Executing actions on clients is performed by the ExecuteActionOnClient workflow activity.

This activity can be combined with REST API calls to invoke actions on client in response to a REST API request. For information on the REST API foundry please see this article.

Actions can be accessed from the left-hand menu in the web UI, under the Endpoint Inventory product, or from the Endpoint VM product. For more information on actions and action factories please see this article.

Workflow Activity Usage

The ExecuteActionOnClient workflow activity requires a Server workflow. Start by authoring a new Server workflow. For assistance authoring workflows, please see this guide.

Find and add the ExecuteActionOnClient activity:

With the ExecuteActionOnClient1 activity selected, fill in the desired properties:

• Name: An appropriate name for the activity
• Description: (Optional) A description for this activity
• LogData: (Optional) Text to get written to the workflow log file when this activity executes
• ClientID: The numerical Client ID for the endpoint that should run the action
• Expression: The action expression to run on the endpoint (see Action Expressions section)
• Timeout: The number of seconds to wait before aborting the action execution attempt
• PrimaryActionSensor: (Optional) Sensor ID. Leave blank.
• MaxRows: (Optional) Maximum number of rows to return. Leave blank

When executed, this activity will return the following output properties:

• Value: JSON containing the output of the action result
• StatusCode: Numeric status code indicating the success or failure of the action execution
• ReasonCode: The reason code for any failure that occurred during execution
• ReasonText: Textual reason for the failure that occurred during execution
• ExceptionMessage: Textual message describing the error if an exception occurred during execution

The three key fields from the above input and output properties are:

• [Input] ClientID
• [Input] Expression (see Action Expressions section)
• [Output] Value

These should be the only ones that are needed.

Action Expressions

The action expression language supports a comprehensive array of different expressions, each with their own syntax and attributes.

For the purposes of the ExecuteActionOnClient workflow activity however, a simple action expression can be used in the vast majority of cases.

The syntax for an appropriate action expression is:

Action(<ActionID>,"<PropertyName>"="<StringValue>","<PropertyName>"=<IntegerValue>,<etc>)

If the action in question does not have any properties, the property section can be omitted.

Here are some example expressions:

Create a file called MyFile.txt in C:\Windows\Temp using the built-in CreateFile action with ID 200005004:

Action(200005004,"CaseSensitivePath"="C:\Windows\Temp\MyFile.txt")

Create a registry key HKLM\SOFTWARE\MySoftware using the built-in CreateKey action with ID 200005017:

Action(200005017,"Hive"=2,"CaseSensitiveSubKeyPath"="SOFTWARE\MySoftware","Wow32_64"=0,"CaseSensitiveDefaultValueData"="")

Start a service called wuauserv using the built-in StartService action with ID 200005024:

Action(200005024,"Name"="wuauserv")

Execute a custom PowerShell action with ID 250000002 with no input parameters:

Action(250000002)

Executing the Workflow

The workflow can be launched through many different ways. The most common is through a REST API call. See this article for assistance creating a REST API workflow.

When the workflow gets launched and the ExecuteActionOnClient activity runs, it will send a message to the specified client instructing it to execute the specified action. The client will download and cache the action, execute it and then send back the result. The Value property can then be used to display the result of the action.

Troubleshooting

In the event that the ExecuteActionOnClient workflow activity is not returning any data, check the following things:

• First, ensure that the server workflow is running by checking the Adaptiva Server logs\workflowlogs folder and locating the workflow log that shares the same name as the workflow that contains the ExecuteActionOnClient activity. Ensure that this workflow is running and that there are no obvious errors during execution.
• Ensure that the client ID specified is a valid active, online client.
• Ensure that the client is able to communicate with the Adaptiva Server (ensure it can ping the server and that it is registered and receiving policies and workflows. Check the last check-in time on the server).
• Ensure the action expression specified is valid.
• Ensure that the action specified in the expression is deployed (navigate to the action in the web UI and check at the top and make sure that the Deployment Status shows "Deployed".
• Check the following logs on the client:
  • componentlogs\ActionExec.log

Further Information

For further information, please see the other resources in the Technical Reference Library or speak to a member of Adaptiva Support.

If you experience any issues or suspect there is a bug in any part of the client action execution system, please log a support ticket and a member of the Adaptiva support team will be touch as soon as possible.