Running scripts on Christmas day (and any other day)

My last blog post of this year will also be about a new (pre-release) feature of Configuration Manager, version 1710. This post will be all about the ability to create and run scripts from the Configuration Manager administration console. To be correct, the ability to create and run scripts was added in Configuration Manager, version 1706, and Configuration Manager, version 1710, added the ability to use parameters with those scripts. It completed the functionality.  My Christmas day present for the community is a walkthrough through this functionality and how it runs on the client device. After reading this post you should be able to understand how your script can create the output and how you can find the correct GUIDs to follow the activity on the client device.

Introduction

Starting with Configuration Manager, version 1706, it’s possible to run PowerShell scripts, via the Configuration Manager console, directly on client devices. Configuration Manager, version 1710, completed this functionality by adding the use of parameters. The ability to run PowerShell scripts on client devices is available in the Configuration Manager administration console, via the Run Scripts option. This makes it easier to automate tasks and, in general, the scripts are understood by a large population. It really simplifies building custom tools. Think about all the custom right-click actions that can now be integrated in this functionality. The biggest advantages of using the Run Script option, are the usage of the notification channel and getting good monitoring information. That means, quick results shown in the Configuration Manager administration console. In this post I’ll show the Run Script option by using a simple PowerShell script that will restart a service on the client device. That service is provided to the script via a script parameter.

Script

Now let’s have a look at the Run Script option in the Configuration Manager administration console. I’ll start by looking at a couple of important prerequisites, followed by how to create, approve and run scripts. I’ll end this section by following the script action to the client device.

Prerequisites

Before looking into the possibilities of the Run Script option, the following prerequisites should be in place to take full advantage of the available possibilities:

  • The client device must be running PowerShell version 3.0, or later;
  • The Configuration Manager clients must be running client version 1706, or later;

Create script

Let;s start by looking at the required steps to create a PowerShell script that can become available via the Run Script option. I’ll do that by using a simple script that can restart a service on a client device, based on the provided script parameter. Based on the result, of the script, a specific script output will be returned. The administrative user, creating the script, must have at least the Create permission for SMS Scripts object class.The following six steps walk through the creation of a PowerShell script (step 3 contains the used script):

1 Open the Configuration Manager administration console and navigate to Software Library > Overview > Scripts;
2 On the Home tab, in the Create group, click Create Script to open the Create Script wizard;
3

CS_ScriptOn the Script page, provide the following information and click Next;

  • Script name: Provide a name for the script;
  • Script language: Select PowerShell, as it’s currently the only option;
  • Script: Click Import to browse to a script file and to display it in the wizard. It’s also still possible to edit the imported script;

Note: Declaring variables, as shown with number 1 on the right, will enable an additional page in the wizard for configuring script parameters. The output shown with number 2, can be returned by the client device.

4a

CS_ScriptParametersOn the Script Parameters page, an overview is shown of the provided parameters with the script and it provides the option to set a Default Value. Select the variable and click Edit to adjust the parameter properties (see step 4b). After that, click Next.

Note: This page should provide an overview of the variables as declared in step 3.

4b

CS_ScriptParameterPropertiesOn the Script Parameter Properties dialog box, the information about the name, required status, hidden status and data type is prepopulated based on the declaration of the variable (see step 3). Use this dialog box to configure the following validation properties and click OK:

  • Minimum Length: Specify the minimum number of characters;
  • Maximum Length: Specify the maximum number of characters;
  • RegEx: Specify a regular expression validation;
  • Custom Error: Specify a custom error message.
5 On the Summary page, verify the configuration and click Next;
6 On the Completion page, verify the result and click Close.

Approve script

Before the just created PowerShell script becomes available via the Run Script option, it must be approved by another administrative user with at least the Approve permission for SMS Scripts object class. That will prevent unverified scripts from running on client devices, which should decrease the possibility of running faulty scripts on client devices. The following seven steps walk through the approval of a PowerShell script:

HierarchySettings_GeneralBy default it’s not possible for a script author to approve and/or deny their own scripts. To enable script authors to approve and/or deny their own scripts, open the Configuration Manager administration console and navigate to Administration > Overview > Site Configuration > Site. Now open the Hierarchy Settings and remove the checkbox with Do not allow script authors to approve their own scripts.

Important: It’s strongly advised to only do this in test and/or lab environments.

1 Open the Configuration Manager administration console and navigate to Software Library > Overview > Scripts;
2 Select the just created script and click Approve/Deny, in the Scripts group, on the Home tab, in the Create group, to open the Approve or deny script wizard;
3

ADS_ScriptOn the Script page, verify the script and click Next;

4

ADS_ScriptParametersOn the Script Parameters page, verify the parameters and click Next;

Note: To verify the details of a parameter, select a parameter and click Details. That will show the script parameter properties, as configured during the creation of the script.

5

ADS_ApproveScriptOn the Approve or deny script page, select Approve, provide an Approver Comment (optional) and click Next;

Note: I know this is stating the obvious, but only approve scripts once you’re certain about their behavior. The ability to run scripts on client devices is just really strong and once the script is triggered it will run almost instantly.

6 On the Summary page, verify the configuration and click Next;
7 On the Completion page, verify the result and click Close.

Run script

After approving the just created PowerShell script, it becomes available via the Run Script option. The administrative user, that will run the script, must have at least the Run permission for SMS Scripts object class and the script will be executed in SYSTEM context on the client device. The following six steps walk through running a PowerShell script:

1 Open the Configuration Manager administration console and navigate to Assets and Compliance > Overview > Device Collections;
2

Open a device collection and right-click a client device and select Run Script to open the Run Script wizard;

Note: It’s also possible to start the Run Script wizard by right-clicking a device collection.

3

RS_ScriptOn the Script page, select the just created script and click Next;

Note: The script GUID is interesting for monitoring the script execution.

4

RS_ScriptParametersOn the Script Parameters page, provide a value for the available parameters and click Next.

5 On the Summary page, verify the details and click Next;
6

RS_MonitoringOn the Monitoring page, verify the script output and click Close.

The script output, on the Summary tab, shows the output as provided in the initial script. Within this summary it’s also possible to look at the exit codes and to look at different chart forms. The Script Details tab shows the general information about the script, like the name, version and parameters and the Run Details tab shows the details about the results, like the device name, execution status, exit code and script output.

Monitor script

Now let’s end this post by looking at the monitoring options for the initiated script. This can be done in real-time, as shown in the step 6, and this can be done by looking at the Script Status node in the Monitoring workspace. Below is on overview of the just triggered script and I’ve included the following highlighted numbers:

  • Number 1 highlights the Show Status button that can be used
    to get the script details, as shown in step 6 of the Run script
    section;
  • Number 2 highlights the Client Task ID that can be used to
    follow the script through the server log files (bgbserver.log) and the client
    log files (ccmnotification.log and script.log), as shown below;
  • Number 3 highlights the Script Guid, as also shown in step
    3 of the Run script section, that can be used to follow the script
    activity in the client log files (script.log), as shown below;
  • Number 4 highlights the Script Output that can be used to
    verify the results. It should refer to the scripted output, as shown in step 3
    of the Create script section.

ConfigMgrConsole_ScriptMonitoring

Let’s continue by following the initiated script through the log files. At least the three log files below are related to this action and together those log files provide a lot of information. As there is some overlap with the log files of last week, I won’t provide the generic information about the log files this time.

BgbServer.log: When initiating a script to run on a client device, this log file shows the information about pushing the script action to the client device, followed by information about the generation of the BGB task status report (.BTS) in the bgb.box inbox (see below). The processing of the BGB task status report can be followed through the bgbmgr.log.

Script_bgbserver

CcmNotificationAgent.log: When initiating a script to run on a client device, this log file shows the arrival of the script action on the client device (see below).

Script_ccmnotification

Script.log: When initiating a script to run on a client device, this log file will show the details about the script that will be executed. That includes the earlier mentioned IDs and the command line that will be used.

Script_script

Let’s end this section by looking at the executed command line in more detail. Below is the highlighted version of the executed command line. That command line clearly shows that the script on the client device is signed, that it uses parameters and that it’s stored locally. The script is stored in C:\Windows\CCM\ScriptStore, which is a hidden folder on the client device. By default only the SYSTEM account has permissions on the script files in that folder.

Executing command line: “C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe” -NoProfile -ExecutionPolicy RemoteSigned -File “C:\Windows\CCM\ScriptStore\D5FF9FBE-D25B-45DB-9771-946076A9FFAD_EB1AA60AF73737F0B342AEED2C5ECB15A9956654BDA4D30263178B3A79E79DD4.ps1” -ServiceName “Group Policy Client”

More information

For more information about the Run Script option, please refer to this article about creating and running PowerShell scripts from the Configuration Manager console.

2 thoughts on “Running scripts on Christmas day (and any other day)

Leave a Comment