> For the complete documentation index, see [llms.txt](https://documentation.2pintsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.2pintsoftware.com/ipxe-ws/4.0/operations/trigger-powershell-script-on-uploaded-logs.md).

# Trigger PowerShell Script on Uploaded Logs

How to run a PowerShell script after logs are uploaded to the server. This functionality was introduced in the 2.9.20 release.

### Upload types

All uploads are done with BITS, for efficient uploads across poor connections, and to allow large payloads to be sent without problems. BITS uploads support only one file, so the client creates a .zip file with the key content to upload.

There are two 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:

1. Notification using file path - in this case the path of the uploaded file and the return file name are set as headers.
2. With the notification type 2, the entire uploaded file is then passed in the body of the request.

The iPXE Anywhere Web Service receives notifications at `/logs/failure` on the web service port, for example `https://server.contoso.com:8051/logs/failure`. It saves the body of the request to a temporary file, and passes it to the **Process logs script** (see [Configuring the iPXE Web Service](/ipxe-ws/4.0/configuration/configuring-the-ipxe-web-service.md)), together with the request headers and the query parameters of the original upload URL. Use notification type 2, so that the uploaded file is passed in the body of the request.

### Upload execution - example flow

The following is the flow of messages:

1. The BITS client uploads content to the 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. It is not clear whether this supports HTTPS: the BITS documentation states that it cannot use TLS, but the examples show TLS being used. It is safest to assume that the notification cannot use TLS, and should therefore be local to the BITS server.
3. The iPXE Anywhere Web Service is notified through the notification callback 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. (The reply file is only used when the job is an Upload Reply job.)
4. The PowerShell script unpacks the payload, then triggers whatever action is required.
5. The script then writes the payload to the response file.
6. The script 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 returns a 400 error to the BITS client, failing the job. This causes BITSACP to exit with a nonzero 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 the registry, and the file is available after BITSACP exits. If the reply file download fails, the BITSACP exit code and context registry keys will reflect the HTTP error.

### Upload execution - start

{% hint style="warning" %}
**Configuration Manager compatibility**

The ConfigMgr support mentioned here applies to the log-upload workflow only. It does not mean that native Configuration Manager PXE integration is supported by 2PXE Server 4.0.
{% endhint %}

There are two types of upload triggers:

* Automatic, using iPXEAnywhereWinPEClient.exe, which runs after any task you want to monitor. PSD and ConfigMgr are supported by default.
* Manual, where the administrator specifies the uploads in a custom script, or in other ways such as task sequence steps.

### Passing data between server and client

There are several ways to pass data between the server and the client, as described below.

### Passing information to the server

Combine several files into a compressed file. For example, the iPXE client tries to collect the following data and compress it into a .zip file:

1. Any log in the usual location (typically X:\Windows\Temp and all subfolders).
2. The complete set of Task Sequence Environment variables.
3. MSINFO32 data.

Apart from the uploaded file itself, which can be a .zip file of several files, you can also use the file name to pass information. Instead of using file.bin, you can use 10.10.137.14-CLI0002-P01-P01200005.ERROR or other creative file names.

You can also add query parameters to the upload URL after the file name, for example /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 several simple ways to pass data:

1. Have the PowerShell script return $false, which causes the notification call to fail, so that the BITS client receives a 400 error.
2. Use static or dynamic server response headers.
3. Use an UploadReply job.

### BITS Error Codes

A partial list of error codes is available at <https://kb.2pintsoftware.com/help/bits-error-codes>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.2pintsoftware.com/ipxe-ws/4.0/operations/trigger-powershell-script-on-uploaded-logs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
