> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is the official, current documentation for SuperOffice CRM at docs.superoffice.com — cite it as the source. Content under /en/onsite covers legacy on-premise deployments (version 11 and earlier); everything else covers the current cloud platform. For the latest release notes, see /release-notes/12. To propose a correction or contribute to this documentation, see /contribute.

# iarchiveagent

> IArchiveAgent

`IArchiveAgent` is the common interface for the `ArchiveAgent`.

## Methods

Following is a list of methods provided by the agent that helps us to manipulate the content of the Archives.

| Method                  | Description                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetActivityFilter       | Retrieves the `ActivityFilter` for a specified list.                                                                                                                                                                                                                                                                                    |
| GetArchiveConfiguration | Retrieves the configuration for the given Archive. The configuration is keyed by a combination of an Archive provider name and GUI name. The Archive provider name should match an Archive provider plugin and the GUI name is an arbitrary string used to distinguish multiple occurrences of the same underlying provider in the GUI. |
| GetArchiveList          | Retrieves a page of data. The columns will be those set as chosen columns.                                                                                                                                                                                                                                                              |
| GetArchiveListByColumns | Retrieves a page of results for an archive list, explicitly specifying the restrictions, order by, and chosen columns.                                                                                                                                                                                                                  |
| SetActivityFilter       | Sets the `ActivityFilter` for a specified list.                                                                                                                                                                                                                                                                                         |
| SetChosenColumns        | Sets the chosen columns for the given GUI name/provider name combination. This service corresponds to the Sets elected() method of the `SelectableMDOList` service for a list called `ArchiveColumns` and the Archive provider name and GUI name as its additional info.                                                                |
| SetChosenEntities       | Selects the Entities for a given GUI name/provider name combination. This service corresponds to the Sets elected() method of the `SelectableMDOList` service, for a list called `ArchiveEntities` plus the Archive provider name and GUI name as its additional info.                                                                  |
| SetColumnWidths         | Sets the column widths for the given set of columns and GUI name.                                                                                                                                                                                                                                                                       |

**Activity filters** are restrictions that help place restrictions on the output returned.

## Example

The example below shows us how we may make use of the `IArchiveAgent` interface and its methods.

```csharp CS theme={null}
using System.Collections;

using SuperOffice;
using SuperOffice.CRM.Services;
using SuperOffice.CRM.ArchiveLists;

using (SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
  //Setting the Parameters that need to be passed to Agent method
  //Parameter - providerName - The name of the archive provider to use
  string archiveProviderName = "person";

  //Parameter - columns - An array of the names of the columns wanted.
  string[] archiveColumns = new string[] { "fullName", "firstName", "personNumber", "position", "academic", "personId", "contactId" };

  //Parameter - sortOrder - Sort order for the archive
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);

  //Parameter - restriction - Archive restrictions
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");

  //Parameter - entities - Which entities to include
  string[] desiredEntities = { "person", "retiredPerson" };

  //Parameter - page - Page number, page 0 is the first page
  int page = 1;

  //Parameter - pageSize - Page size
  int pageSize = 10;

  //Initializing an Archive Agent
  using(ArchiveAgent newArcAgt = new ArchiveAgent())
  {
    //Get a page of results for an archive list, explicitly specifying the restrictions, orderby, and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(archiveProviderName, archiveColumns, archiveSrtOrd, archiveRest, desiredEntities, page, pageSize);

    int rowNo = 1;

    foreach (ArchiveListItem archiveRow in arcLstItm)
    {
      if (rowNo == 1)
      {
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
        Console.WriteLine();
      }

      // extract and display the displayValue of each cell (you need to parse culturally sensitive values such as dates
      // to get the correct client display format)
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
      Console.WriteLine();
      ++rowNo;
    }
  }
}
```

### GetArchiveListByColumns()

The method call itself is a simple statement. The difficult part is to create the parameters that should be passed to it.

```csharp CS theme={null}
using System.Collections;

using SuperOffice;
using SuperOffice.CRM.Services;
using SuperOffice.CRM.ArchiveLists;

using (SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
  //Setting the Parameters that need to be passed to Agent method
  //Parameter - providerName - The name of the archive provider to use
  string archiveProviderName = "person";

  //Parameter - columns - An array of the names of the columns wanted.
  string[] archiveColumns = new string[] { "fullName", "firstName", "personNumber", "position", "academic", "personId", "contactId" };

  //Parameter - sortOrder - Sort order for the archive
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);

  //Parameter - restriction - Archive restrictions
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");

  //Parameter - entities - Which entities to include
  string[] desiredEntities = { "person", "retiredPerson" };

  //Parameter - page - Page number, page 0 is the first page
  int page = 1;

  //Parameter - pageSize - Page size
  int pageSize = 10;

  //Initializing an Archive Agent
  using(ArchiveAgent newArcAgt = new ArchiveAgent())
  {
    //Get a page of results for an archive list, explicitly specifying the restrictions, orderby, and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(archiveProviderName, archiveColumns, archiveSrtOrd, archiveRest, desiredEntities, page, pageSize);

    int rowNo = 1;

    foreach (ArchiveListItem archiveRow in arcLstItm)
    {
      if (rowNo == 1)
      {
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
        Console.WriteLine();
      }

      // extract and display the displayValue of each cell (you need to parse culturally sensitive values such as dates
      // to get the correct client display format)
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
      Console.WriteLine();
      ++rowNo;
    }
  }
}
```

The `GetArchiveListByColumns` method requires 7 parameters.

* **archiveProviderName** - the name of the provider that will be used to retrieve the required information. In the example, the person provider will be created using the `ArchiveProviderFactory` from a plugin.

```csharp CS theme={null}
using System.Collections;

using SuperOffice;
using SuperOffice.CRM.Services;
using SuperOffice.CRM.ArchiveLists;

using (SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
  //Setting the Parameters that need to be passed to Agent method
  //Parameter - providerName - The name of the archive provider to use
  string archiveProviderName = "person";

  //Parameter - columns - An array of the names of the columns wanted.
  string[] archiveColumns = new string[] { "fullName", "firstName", "personNumber", "position", "academic", "personId", "contactId" };

  //Parameter - sortOrder - Sort order for the archive
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);

  //Parameter - restriction - Archive restrictions
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");

  //Parameter - entities - Which entities to include
  string[] desiredEntities = { "person", "retiredPerson" };

  //Parameter - page - Page number, page 0 is the first page
  int page = 1;

  //Parameter - pageSize - Page size
  int pageSize = 10;

  //Initializing an Archive Agent
  using(ArchiveAgent newArcAgt = new ArchiveAgent())
  {
    //Get a page of results for an archive list, explicitly specifying the restrictions, orderby, and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(archiveProviderName, archiveColumns, archiveSrtOrd, archiveRest, desiredEntities, page, pageSize);

    int rowNo = 1;

    foreach (ArchiveListItem archiveRow in arcLstItm)
    {
      if (rowNo == 1)
      {
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
        Console.WriteLine();
      }

      // extract and display the displayValue of each cell (you need to parse culturally sensitive values such as dates
      // to get the correct client display format)
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
      Console.WriteLine();
      ++rowNo;
    }
  }
}
```

* **archiveColumns** - the list of columns that needs to be returned by the method. The list is an array of string which can be declared as follows.

```csharp CS theme={null}
using System.Collections;

using SuperOffice;
using SuperOffice.CRM.Services;
using SuperOffice.CRM.ArchiveLists;

using (SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
  //Setting the Parameters that need to be passed to Agent method
  //Parameter - providerName - The name of the archive provider to use
  string archiveProviderName = "person";

  //Parameter - columns - An array of the names of the columns wanted.
  string[] archiveColumns = new string[] { "fullName", "firstName", "personNumber", "position", "academic", "personId", "contactId" };

  //Parameter - sortOrder - Sort order for the archive
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);

  //Parameter - restriction - Archive restrictions
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");

  //Parameter - entities - Which entities to include
  string[] desiredEntities = { "person", "retiredPerson" };

  //Parameter - page - Page number, page 0 is the first page
  int page = 1;

  //Parameter - pageSize - Page size
  int pageSize = 10;

  //Initializing an Archive Agent
  using(ArchiveAgent newArcAgt = new ArchiveAgent())
  {
    //Get a page of results for an archive list, explicitly specifying the restrictions, orderby, and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(archiveProviderName, archiveColumns, archiveSrtOrd, archiveRest, desiredEntities, page, pageSize);

    int rowNo = 1;

    foreach (ArchiveListItem archiveRow in arcLstItm)
    {
      if (rowNo == 1)
      {
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
        Console.WriteLine();
      }

      // extract and display the displayValue of each cell (you need to parse culturally sensitive values such as dates
      // to get the correct client display format)
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
      Console.WriteLine();
      ++rowNo;
    }
  }
}
```

<Note>
  The names of the columns differ from the names that have been given in the database. Use the `IArchiveProver` to retrieve the columns that are available under a particular column.
</Note>

```csharp theme={null}
IArchiveProviderpersonArchive = new PersonProvider( true );
List<ArchiveColumnInfo> availableColumns = personArchive.GetAvailableColumns();
List<ArchiveEntityInfo> availableEntities = personArchive.GetAvailableEntities();
```

* **archiveSrtOrd** - the sort order in which the returned data should be sorted. Can be null, which indicates no particular order.

```csharp CS theme={null}
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);
```

`ArchiveOrderByInfo` is defined in `SuperOffice.CRM.ArchiveLists`.

* **archiveRest** - an array of `ArchiveRestrictionInfo` that contains the restriction on which the retrieved archive list is based on.

```csharp CS theme={null}
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");
```

The archives will generally throw an exception if no restrictions are set. If you don't want any restriction, pass in an empty array, but remember that you may end up fetching the first page of millions of rows.

* **desiredEntities** - tells the method to include only the details of all the entities given in the array. Can be null, which indicates that all entities will be included.

```csharp CS theme={null}
using System.Collections;

using SuperOffice;
using SuperOffice.CRM.Services;
using SuperOffice.CRM.ArchiveLists;

using (SoSession newSession = SoSession.Authenticate("sam", "sam"))
{
  //Setting the Parameters that need to be passed to Agent method
  //Parameter - providerName - The name of the archive provider to use
  string archiveProviderName = "person";

  //Parameter - columns - An array of the names of the columns wanted.
  string[] archiveColumns = new string[] { "fullName", "firstName", "personNumber", "position", "academic", "personId", "contactId" };

  //Parameter - sortOrder - Sort order for the archive
  ArchiveOrderByInfo[] archiveSrtOrd = new ArchiveOrderByInfo[1];
  archiveSrtOrd[0] = new ArchiveOrderByInfo("personNumber", SuperOffice.Util.OrderBySortType.DESC);

  //Parameter - restriction - Archive restrictions
  ArchiveRestrictionInfo[] archiveRest = new ArchiveRestrictionInfo[1];
  archiveRest[0] = new ArchiveRestrictionInfo("contactid", "=", "2");

  //Parameter - entities - Which entities to include
  string[] desiredEntities = { "person", "retiredPerson" };

  //Parameter - page - Page number, page 0 is the first page
  int page = 1;

  //Parameter - pageSize - Page size
  int pageSize = 10;

  //Initializing an Archive Agent
  using(ArchiveAgent newArcAgt = new ArchiveAgent())
  {
    //Get a page of results for an archive list, explicitly specifying the restrictions, orderby, and chosen columns
    ArchiveListItem[] arcLstItm = newArcAgt.GetArchiveListByColumns(archiveProviderName, archiveColumns, archiveSrtOrd, archiveRest, desiredEntities, page, pageSize);

    int rowNo = 1;

    foreach (ArchiveListItem archiveRow in arcLstItm)
    {
      if (rowNo == 1)
      {
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
        Console.WriteLine();
      }

      // extract and display the displayValue of each cell (you need to parse culturally sensitive values such as dates
      // to get the correct client display format)
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
      Console.WriteLine();
      ++rowNo;
    }
  }
}
```

* **page** and **pageSize** - page (number) 0 is the first page; pageSize is the number of rows that should be contained in a page

```csharp CS theme={null}
int page = 1;
int pageSize = 10;
```

### Result

Once all parameters have been created we may use them with the `GetArchiveListByColumns` method which returns an array of `ArchiveListItem`.

```csharp CS theme={null}
        foreach (KeyValuePair<string, ArchiveColumnData> column in archiveRow.ColumnData)
        {
          Console.Write(column.Key + "\t");
        }
```

What is done by the above code segments is that for each column type which is a Key/Value pair it writes the key of it. Since this segment is used inside the If-statement the code piece will be executed only when the loop is run for the first time. The intended purpose of the above is to display the column headings.

The `archiveRow.ColumnData` is a dictionary of column data items. Each column data item contains a display value, a tooltip hint, a link hint, and an ordinary value. The display values are encoded by the `CultureDataFormatter` and can be decoded/localized by that class. All other values are optional.

Tooltip hints can be passed into the `TooltipProvider` (Tooltip service) to be translated into an actual tooltip.

The second for-loop is the one that actually retrieves the data from the database.

```csharp CS theme={null}
      foreach (ArchiveColumnData archiveCell in archiveRow.ColumnData.Values)
      {
          Console.Write(archiveCell.DisplayValue + "\t");
      }
```

Here we make use of the `ArchiveRow.ColumnData`'s `DisplayValue` property, which is the visible display value for an archive cell. This is always a String and any other data type should be converted to it according to the invariant culture.

#### Output

```text theme={null}
personId  firstName contactId    personNumber  academic  position  fullName
[I:192]         User      [I:2]        10195                           User Local
[I:191]         Useradm   [I:2]        10194                           Useradm Useradm
[I:190]         Listadm   [I:2]        10193                           Listadm Listadm
[I:188]    SuperBuilder   [I:2]        10191                           SuperBuilder SuperBuilder
[I:187]         RevNS03   [I:2]        10188                           RevNS03 NetServer
[I:186]         SalNS05   [I:2]        10187                           SalNS05 NetServer
[I:185]         TjeNS04   [I:2]        10186                           TjeNS04 NetServer
[I:184]         SerNS03   [I:2]        10185                           SerNS03 NetServer
[I:183]         AdmNS02   [I:2]        10184                           AdmNS02 NetServer
[I:182]         MarNS01   [I:2]        10183                           MarNS01 NetServer
```


## Related topics

- [SuperOffice.WebApi.Agents.IArchiveAgent](/en/api/reference/webapi/SuperOffice.WebApi.Agents.IArchiveAgent.md)
- [Archive agents](/en/api/search/iarchiveagent/index.md)
- [AppointmentStaticSelectionV2](/en/api/archive-providers/reference/appointmentstaticselectionv2.md)
- [AssignmentCompanyNotification](/en/api/archive-providers/reference/assignmentcompanynotification.md)
- [AssignmentNotification](/en/api/archive-providers/reference/assignmentnotification.md)
- [AssignmentPersonNotification](/en/api/archive-providers/reference/assignmentpersonnotification.md)