# Archive Files to Microsoft SharePoint

Cloud Voice can offload your call recordings and configuration backups to a folder in Microsoft SharePoint, either on a recurring schedule or whenever you choose. Setting this up happens in two stages: first you prepare the Microsoft side (an app registration and a destination folder), then you register that SharePoint location on Cloud Voice and build the tasks that move your files.

## Requirements

| Item | Requirement |
| --- | --- |
| Firmware | Version 84.22.0.17 or later |
| Plan | Enterprise plan (self-managed system) or Ultimate plan (Cloud Voice-hosted system) |

## Limits

- Up to 10 archive servers.
- Up to 200 archive tasks.

## How archiving works

To send recordings or backups to a specific SharePoint folder, you complete the following:

1. **On Microsoft's side**, prepare the resources Cloud Voice needs to authenticate:
   - A Microsoft account with the **Global Administrator** role.
   - A set of API credentials created on the Azure portal, a **tenant ID**, a **client ID**, and a **client secret**.
   - A **folder** on your SharePoint site to hold the archived files.
2. **On Cloud Voice**, put those pieces to work:
   - Add SharePoint as an archive server.
   - Create one or more tasks that archive your files there.

When a task runs, Cloud Voice presents the API credentials to Microsoft SharePoint. Once the request is authenticated, the selected files are written to the folder you designated.

## Step 1: Register an application in Microsoft Entra

1. Sign in to the [Microsoft Azure portal](https://portal.azure.com/) with your Global Administrator account.
2. Search for and open the **Microsoft Entra ID** service to reach your organization's directory.

   ![Searching for the Microsoft Entra ID service in the Azure portal search bar](/images/pbx/ms-entra-id.png)

3. Register the application:

   a. In the directory's left navigation, go to **Manage > App registrations** and click **New registration**.

   ![The App registrations page with the New registration button](/images/pbx/aad-new-registration.png)

   b. Give the application a name that will help you recognize it later, then click **Register**.

   
   ![Cloud Voice, Register an application page with a name entered](/images/pbx/aad-archive-app-name.png)

   c. Record the **Application (client) ID** and the **Directory (tenant) ID** shown on the overview page.

   ![The application overview page listing the client ID and tenant ID](/images/pbx/aad-client-archive-credential.png)

4. Generate a client secret:

   a. In the application's left navigation, go to **Manage > Certificates & secrets > Client secrets** and click **New client secret**.

   ![The Client secrets tab with the New client secret button](/images/pbx/aad-add-archive-secret.png)

   b. Configure the secret (description and expiry), then click **Add**.

   ![The Add a client secret panel with description and expiry fields](/images/pbx/aad-configure-archive-secret.png)

   c. Copy the secret's **Value**.

   :::caution
   Copy the secret value before you navigate away from this page. Microsoft displays it only once, if you lose it, you will have to create a new secret.
   :::

   ![The client secret Value shown once for copying](/images/pbx/aad-copy-archive-secret.png)

You now have three credentials, the client ID, the tenant ID, and the client secret value, which you will enter into Cloud Voice in Step 4.

## Step 2: Grant the application API permissions

1. In the application's left navigation, open **API permissions** and click **Add a permission**.

   
   ![Cloud Voice, API permissions page with the Add a permission button](/images/pbx/aad-archive-api-permission.png)

2. On the **Select an API** page, choose **Microsoft APIs > Microsoft Graph**.

   ![Selecting Microsoft Graph under Microsoft APIs](/images/pbx/archive-ms-graph.png)

3. Grant the application read and write access to all site collections:

   a. Click **Application permissions**, search for and select **Sites.ReadWrite.All**, then click **Add permissions**.

   ![Selecting the Sites.ReadWrite.All application permission](/images/pbx/ms-archive-api-permission.png)

   b. Click **Grant admin consent for...** to apply the permission.

   
   ![Cloud Voice, Grant admin consent button on the API permissions page](/images/pbx/ms-archive-grant-permission.png)

   c. In the confirmation dialog, select **Yes**.

   
   ![Cloud Voice, Confirmation dialog for granting admin consent](/images/pbx/ms-archive-admin-consent.png)

   When the permission's **Status** shows a green check mark, admin consent has been granted successfully.

## Step 3: Create a folder in SharePoint

:::note
Archived files must live in a folder inside a SharePoint container. The steps below create a folder in a document library, but if you already have a suitable folder or prefer a different container, use that instead.
:::

1. Open the SharePoint site where you want the folder, then open its document library.
2. At the top right, click **Create or Upload** and choose **Folder** from the menu.

   ![The Create or Upload menu with the Folder option in a SharePoint document library](/images/pbx/sharepoint-create-folder.png)

3. Enter a recognizable name in the **Name** field and click **Create**.

   ![Naming the new folder in the Create a folder panel](/images/pbx/sharepoint-edit-folder.png)

   The new folder appears in the document library list.

   ![The new folder shown in the SharePoint document library list](/images/pbx/sharepoint-folder-created.png)

## Step 4: Add SharePoint as an archive server

1. Sign in to the Cloud Voice management portal and go to **System > Archive**.
2. On the **Archive Task** tab, click **Archive Server**.

   ![The Archive Task tab with the Archive Server button](/images/pbx/click-archive-server.png)

3. Add the server:

   a. Click **Add**.

   b. Complete the settings in the pop-up window.

   ![The archive server configuration window with SharePoint credential fields](/images/pbx/sharepoint-archive-server-setting.png)

   | Setting | What to enter |
   | --- | --- |
   | Name | A label that identifies this server. |
   | Server Type | Select **SharePoint**. |
   | Application (Client) ID | The client ID you recorded in Step 1. |
   | Tenant ID | The directory (tenant) ID you recorded in Step 1. |
   | Client Secret | The client secret value you copied in Step 1. |

   c. Click **Save**. SharePoint now appears in the archive server list.

4. Close the window.

## Step 5: Create an archive task

1. On the **Archive Task** tab, click **Add**.
2. In the **Task Configuration** section, fill in the basic settings.

   ![The Task Configuration section of a new archive task](/images/pbx/s3-archive-task.png)

   | Setting | Description |
   | --- | --- |
   | Name | A label that identifies the task. |
   | File Type | Choose **Recording Files** or **Backup Files**. |
   | Data Range | The time range of files to archive. See the note below. |
   | Recording File Format | The download format for recordings. Available only when the file type is recordings; all recordings in the system are archived in this format. |

   :::note
   A single task can cover a data range of up to 31 days.
   :::

   Under **Sync Frequency**, choose how often the task runs:

   - **Once**: archives immediately after you save the task.
   - **Daily**: pick a time of day; the task runs at that time every day.
   - **Weekly**: pick a day of the week and a time; the task runs then each week.
   - **Monthly**: pick a day of the month and a time; the task runs then each month.

   :::tip
   Archiving large amounts of data consumes CPU on the system, so schedule recurring tasks for off-peak hours.
   :::

3. In the **Storage Configuration** section, choose where the files go.

   | Setting | Description |
   | --- | --- |
   | Archive Server | Select the SharePoint server you added in Step 4. |
   | Select Folder/Path | Choose the SharePoint folder that will hold the archived files. |

   For **Storage Method**, pick how files are laid out on the server. The options depend on whether the task runs once or on a schedule.

   For a one-time task:

   - **Create Task Folder**: creates a folder named `FileType-TaskName` under the selected path and stores the files there.
   - **Save Directly to Selected Path**: writes files straight to the selected path with no new folder.

   For a recurring task:

   - **Create Folder per Execution**: each run creates a folder named `FileType-TaskName-ExecutionDate` under the selected path and stores that run's files inside it.
   - **Create Task Folder Once and Reuse It**: the first run creates `FileType-TaskName` under the selected path, and every later run adds its files to that same folder.
   - **Save Directly to Selected Path**: every run writes files straight to the selected path with no new folder.

   The remaining options are optional and apply only to recording-file tasks:

   | Setting | Description |
   | --- | --- |
   | Skip archived files | When enabled, files already archived are not archived again. When disabled, they are archived again; the file's stored location is updated, but the earlier copy is left in place on the server. |
   | Delete local files after archiving | When enabled, local recordings are removed after archiving. They can still be played and downloaded from the Cloud Voice management portal and the Cloud Voice App, but not from the archive server. When disabled, local files are kept. |

   :::caution
   Enabling **Delete local files after archiving** deletes the original recordings from the system once they are copied. Make sure the task is succeeding (check **Archival Logs** after it runs) before you rely on this, because the archive server then becomes the only place those recordings exist.
   :::

   **Organize Files by Date** applies to any task type. When enabled, the system creates date subfolders (named `YYYYMMDD`, for example `20260301`) under the storage path. When disabled, files are saved directly to the path without date grouping.

   :::note
   If the selected time range contains only one record, no date subfolder is created and the file is stored directly in the path.
   :::

4. (Optional) Set a retention policy for the archived files.

   :::note
   Retention is available only for recurring tasks, and the Microsoft account must have permission to **delete** resources on the archive server.
   :::

   ![The retention policy settings for an archive task](/images/pbx/archive-retention-settings.png)

   | Setting | Description |
   | --- | --- |
   | Retention Type | **Retention by Quantity** keeps a maximum number of files/folders and deletes the oldest once that number is exceeded. **Retention by Days** keeps files/folders for a maximum period and deletes anything older. |
   | Retention Limit | The maximum number of files/folders, or the maximum number of days, depending on the retention type. |
   | Retention Unit | **Folder** counts the task folders created on the server (available only when the storage method is **Create Folder per Execution**, and it does not count date subfolders from **Organize Files by Date**). **File** counts individual archived files. |

   :::note
   For **Retention by Days**, the clock starts at the time a file is archived on the server, not when it was created on the system, and a "day" is an exact 24-hour interval rather than a calendar day.
   :::

5. Click **Save**.

## Result

Your selected files are archived to the designated SharePoint folder, immediately for a one-time task, or at the scheduled time for a recurring one.

:::note
To protect performance, the system runs one archive task at a time. When several tasks are due, they queue and run one after another.
:::

You can confirm the outcome in two places:

**On Cloud Voice**: go to **System > Archive > Archival Logs**. A **Result** of **Succeeded** means the files reached SharePoint.

![The Archival Logs list showing task results](/images/pbx/sharepoint-archival-logs.png)

:::note
A failed task raises a **Failed to Archive File(s)** event. Use the retry action on the log entry to run the task again.
:::

![Retrying a failed archive task from the Archival Logs](/images/pbx/sharepoint-retry-archive-task.png)

**On Microsoft SharePoint**: open the folder you created. If the expected files are listed, the archive succeeded.

![Archived files listed in the destination SharePoint folder](/images/pbx/backup-file-on-sharepoint.png)