Trigger PowerShell script on uploaded logs

This page contains documentation on how to manage script execution after logs are uploaded to server. This functionality came in the 2.9.20 release.

Upload types

All uploads are done via BITS for efficient uploads across poor connections, allow for large payloads to be sent up without problems. BITS uploads support only one file, hence why we create a .zip file with key content to upload.

There are 2 types of uploads;

• Uploads

• Uploads with reply data

The script execution depends on the notification setting on the BITS upload directory. If you just want to have the logs, there is no need to have the script execution run. The script is triggered by the notification URL property defined on the BITS server. There are two types of notification:

There are two types of notification types;

1. Notification using file path - in this case the path of the uploaded file and the return file name is set as headers.

2. With the notification type 2, the entire uploaded file is then passed in the body of the request.

The iPXEAnywhere Web Service support both types of notification types via the following URLs:

Upload execution - example flow

The following is the flow of messages:

1. BITS Client uploads content to server

2. When the upload completes, the server side executes an HTTP call against the "notify" server URL specified in the BITS server components. This can be a local URL on the same server or a remote server. Whether this supports HTTPS or not, is unknow, documentation states that it cannot use TLS, but the examples shows use of TLS. Safe to assume the notification cannot use TLS and should therefore be local to the BITS server.

3. The iPXE Anywhere Web Service gets notified, via the notification call-back from the BITS server. This triggers the execution of a PowerShell script, which then gets the headers containing the full path to the uploaded file, and a path to a reply file. (Only used when the job is a Upload Reply job)

4. PowerShell script unpacks the payload, then triggers whatever action required.

5. PowerShell then writes the payload to the response file.

6. PowerShell exits and the Web Service returns either True or False. If False is returned, the iPXE Anywhere Web Service fails the incoming request and throws an exception, which in turn throws a 400 error to the BITS Client, failing the job. This leads to the BITSACP exit with a non zero exit code, returning the actual error code from BITS. Further information on the error message and context is written to the registry.

7. If True is returned, and the response file is created, the BITS server will instruct the BITS client to download the file specified.

8. The BITS client starts the download of the reply file.

9. The reply file name is written to registry, the file is available after the BITSACP exits. If the reply file download fails, the BITSACP exit code and context registry keys will reflect the HTTP error.

Upload execution - start

There are two types of uploads triggers;

• Automatic, via the iPXEAnywhereWinPEClient.exe that runs after any task you want to monitor, we support PSD and ConfigMgr by default.

• Manual, where the administrator specifies the uploads in a custom script or other types of execution via Task Sequence steps etc.

Passing data between server and client

There are many ways to skin a client... some mentioned below.

Passing information to the server

Use several files into a compressed format. As an example the iPXE Client tries to collect the following data and compress into a .zu

1. Any log in the usual spot (Typically X:\Windows\Temp and all subfolders)

2. The complete set of Task Sequence Environment variables.

3. MSINFO32 data

Apart from the obvious file itself to upload, which we now know can be a .zip file of several files, you can also use the Filename itself. Instead of using file.bin you can use 10.10.137.14-CLI0002-P01-P01200005.ERROR or other really creative file names.

You can also set query parameters on the uploading URL after the file name itself. Like /file.zip?ComputerName=CLI0002&Network=10.10.11.30.

Both headers and query parameters are available when the PowerShell script executes on the server side.

Passing data from server to client

There are some trivial ways to pass data;

1. Let the PowerShell script return $false, which will cause the notification call to error, and the BITS client retrieves a 400 error.

2. Use static/dynamic server response headers

3. Us an UploadReply job

BITS Error Codes

An incomplete list of error codes can be found here: https://kb.2pintsoftware.com/help/bits-error-codes