# Copia Scripting

## Overview

The Copia Script type allows you to automate your own custom scripts to back up a device. This is handy when the device has a command-line interface, backup script, or simple API for producing a backup. Using PowerShell, Batch, VB, C#, or any Windows-executable scripting language, the Copia Agent can automate your creation to backup and compare your Devices.

## Agent Requirements

Below are the Agent system requirements to configure a Copia Agent for the backups using scripts:

* The Agent should be tested to confirm that it can backup the desired files utilizing the script on the Agent.

## Scripts

Prior to configuring a Project in Copia, it is important to have created a script that is proven and tested to create a backup of the desired Project data. A script can be written in any Windows-executable format (batch, Powershell, C#, etc.).

There are a few requirements for the script:

* **Results should be placed in the %temp%\backup\_results\ folder**\
  Copia will pre-create this folder prior to running the script, and it should contain the results of the script execution (i.e. the backup data)
  * NOTE: prior to sending the data to Copia, the results will be compressed into a zip file with the Job ID as the name.  If after testing this zip is found to be empty, it is likely your script did not complete as expected.
* **CopiaError.log**\
  Copia will prepopulate the %temp%\backup\_results\ folder with a CopiaError.log file. *You should always delete this file as part of your script!* If the file is deleted, Copia will accept the results. If the file is not deleted, Copia will assume the script has crashed or failed to execute. You can also write log messages to the file, to improve troubleshooting in these failure cases.
* **Existing project data will be made available for the script in %temp%\backup\_data**\
  Copia will bring the existing project data down to the Agent and place it in this folder. This will allow you to use this data (such as copying it to the results, and updating it) in any manner you may see fit.
* **The script must exist on the Agent**\
  The script must exist on the agent before the backup starts.
* **Test the script on the Agent prior to configuration using the command-line**\
  The Agent will execute the script in a similar manner to using the command-line to execute a process. (for example, if it is a PowerShell script, then the Windows association for ps1 files should be PowerShell)  The script should be able to be manually executed in this manner, and it should be able to backup and place the resulting data in the %temp%\backup\_results folder.

### Script Path Allowlist

The Script Path Allowlist is a security control that restricts which scripts the Copia Agent is permitted to execute. Before running any script backup, the Agent checks the script's absolute path against a local allowlist file on the machine. If the path does not match an entry in the allowlist, the backup is blocked and the job run fails.

This ensures that only users with administrative access to the Agent machine can authorize which scripts run on it. The allowlist cannot be modified from the Copia web application.

#### Allowlist File Location

The allowed scripts file is located at:

```
%ProgramData%\Copia Automation\Copia Agent\AllowedScripts.txt
```

This typically resolves to `C:\Program Data\Copia Automation\Copia Agent\AllowedScripts.txt`. The `%ProgramData%` directory requires administrator privileges to modify on Windows, preventing standard users from tampering with the allowlist.

If the file does not exist or is empty, all script backups on that Agent are blocked.

#### Pattern Syntax

Each line in `AllowedScripts.txt` is a pattern matched against the full absolute path of the script. The file supports glob-style patterns with two special characters:

| Pattern | Meaning                                                                                 |
| ------- | --------------------------------------------------------------------------------------- |
| `*`     | Matches any characters **except** path separators. Does not cross directory boundaries. |
| `**`    | Matches zero or more path segments. Crosses directory boundaries.                       |

All other characters are treated as **literals** — no regex syntax is needed. Matching is case-insensitive and treats backslashes (`\`) and forward slashes (`/`) interchangeably.

Lines starting with `#` are comments. Empty lines are ignored.

#### Examples

```bash
# Exact path — only this specific script is allowed
C:\Scripts\backup.bat

# Any .bat file directly in C:\Scripts (not in subdirectories)
C:\Scripts\*.bat

# Any .bat file in C:\Scripts or any subdirectory beneath it
C:\Scripts\**\*.bat

# Any file anywhere under C:\Scripts (all subdirectories, all extensions)
C:\Scripts\**

# Any file named "backup" regardless of extension
C:\Scripts\backup.*

# Multiple paths — one pattern per line
C:\Backups\nightly.ps1
D:\Automation\Scripts\**\*.bat
```

#### Editing the Allowlist

To add, remove, or modify allowed script paths:

1. Open `AllowedScripts.txt` in a text editor with administrator privileges (e.g. right-click Notepad → "Run as administrator")
2. Add one pattern per line, or remove lines to revoke access
3. Save the file

Changes take effect immediately — no Agent restart is required.

## Project Configuration

Script projects require a File List to determine what files in the %temp%\backup\_results folder to include and exclude, as well as the contents to exclude from the compare. While you can simply grab all files in the directory, if you need additional filtering or need to ignore certain files during the compare operation, you can do this via the file list creation.

Copia recommends that you create a File List prior to creating a Project. More information can be found in [File List](/docs/devicelink/sitesandagents/sites/file-lists.md) section.

{% hint style="info" %}
If you will have multiple projects of the same type, like a Network Switch Configuration, then a File List called "NetworkSwitch\_Type1" may be a good name, and can be used for multiple Script projects to backup multiple network switches.
{% endhint %}

To configure a Project as a Script, you need a repository with a Project folder to store the data. The name of the folder is usually similar to that of the robot or controller. Your Project will need to point to that folder.

{% hint style="success" %}
The folder can be created during the project creation process.
{% endhint %}

Click either of the *Add a Project* buttons in the Projects tab.

<figure><img src="/files/1BcYxuoZamhKngczwmLF" alt=""><figcaption></figcaption></figure>

The *Add a new project* configuration dialog will appear which allows you to fully configure the project, devices and job for the project.

{% hint style="info" %}
Any items highlighted with an asterisk are required.
{% endhint %}

<figure><img src="/files/Smr8WpGuz6V42oPkccb0" alt=""><figcaption></figcaption></figure>

This is a multi-step process with each section explained in detail.  At any time, you can edit the prior section of this workflow.   &#x20;

{% hint style="info" %}
The project can be edited after creation.  Devices and Jobs can also be edited or created directly, using the Devices or Jobs tab.  The steps for creation are similar to the steps provided below for those sections.
{% endhint %}

### Define the Project

To get started, we will first select the *Project Type* from the list provided, and then select an *Agent*.  If you have not already created an Agent, you can create and assign an Agent at a later time.  See more about this in the [Agents ](/docs/devicelink/sitesandagents/agents.md)section of the documentation.

When complete, press *Save and Continue*.

<figure><img src="/files/v4CSgw2jgFLxU0zXenpC" alt=""><figcaption></figcaption></figure>

You will now select the Project Path, which is the location (Repo/Branch) that the project is, or will be stored.

{% hint style="info" %}
You can edit the previous steps at any time.
{% endhint %}

<figure><img src="/files/xDIpeicRgzh18GO8fd8D" alt=""><figcaption></figcaption></figure>

For Scripting, you can either select an existing folder, or create a new empty folder (so that you can upload a copy of your project data from the device) for an initial revision.  You can make this choice after you have selected the repository and branch for the project folder.&#x20;

In this example, we will create a new empty project folder.  Once complete, press *Save and Continue* to proceed.

Once selected, press *Save and Continue* to proceed.

<figure><img src="/files/NHtW8oG4L4aWRT7PXw5j" alt=""><figcaption></figcaption></figure>

The project details allows you to update the Project name, and description if desired. &#x20;

The name of the Project will pre-populate with the folder name that you selected. Add a description and select the Script type. You will need to provide two pieces of information:

* **Script Path**\
  The script path is the location of the script (on the Agent) to be run. This must be an absolute, local path. Relative paths and UNCs paths are not supported.
* **Script Arguments**\
  This section enumerates the arguments to be passed to the script file. For security reasons, only alphanumeric characters and the characters `.-_` (dot, dash, and underscore) are allowed. If multiple arguments are added, they are delimited by a space. In the example below, the script would be executed as the command `c:\temp\Copia\backup.bat -file backupresult.zip` .
* **File List**\
  A File List is a list of files to be included/excluded in the backup, and also what may be excluded from Compare. In this field you will select the File List for this Device type. This is optional and can be set later on the Project. See the [File List](/docs/devicelink/sitesandagents/sites/file-lists.md) section for more details.

<figure><img src="/files/nQRhOB7oxe0WN9dwEvaZ" alt=""><figcaption></figcaption></figure>

### Define the Device(s)

Since the Script exists on the Agent, there is no need to define a Device for Projects that use a Script during setup.  You can skip to the Job section. &#x20;

### Define the Job(s)

Creating Jobs is similar for all vendor types, and is described in the [Creating Jobs](/docs/devicelink/jobs/creating-jobs.md) section.  It is recommended to review that section while completing a job configuration, and press Save to save the job.  You can create more than one job for a device if desired. &#x20;

### Submit the Configuration

Once complete, press *Submit Project Setup* to create the Project, Device(s) and Job(s).

<figure><img src="/files/xjyvRMWXfmr7xGqPpHUs" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Don't forget to enable/disable the [Watch ](/docs/devicelink/projects-and-devices.md#watching-a-project)button, based on your preferences for project [Notifications](/docs/devicelink/administration/notifications.md).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.copia.io/docs/devicelink/basic/copia-scripting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.