Class ArchiveAgent

Proxy class for the Archive Agent Used when communicating remote using WebServices. Avoid using directly. Use the AgentFactory to create the proxy instead.

Inheritance
object
ArchiveAgent
Implements
Inherited Members
Namespace: SuperOffice.CRM.Services
Assembly: SuperOffice.Services.Implementation.dll
Syntax
public class ArchiveAgent : IArchiveAgent, IAgent

Constructors

ArchiveAgent(IActivityFilterImplementation, IArchiveConfigurationImplementation, IArchiveListImplementation, IArchiveListResultImplementation, IRelatedDataImplementation, ISoRequestItemsAccessor)

Proxy class for the Archive Agent Used when communicating remote using WebServices. Avoid using directly. Use the AgentFactory to create the proxy instead.

Declaration
public ArchiveAgent(IActivityFilterImplementation activityFilterImplementation, IArchiveConfigurationImplementation archiveConfigurationImplementation, IArchiveListImplementation archiveListImplementation, IArchiveListResultImplementation archiveListResultImplementation, IRelatedDataImplementation relatedDataImplementation, ISoRequestItemsAccessor accessor)
Parameters
Type Name Description
IActivityFilterImplementation activityFilterImplementation
IArchiveConfigurationImplementation archiveConfigurationImplementation
IArchiveListImplementation archiveListImplementation
IArchiveListResultImplementation archiveListResultImplementation
IRelatedDataImplementation relatedDataImplementation
ISoRequestItemsAccessor accessor

ArchiveAgent(IActivityFilterImplementation, IArchiveConfigurationImplementation, IArchiveListImplementation, IArchiveListResultImplementation, IRelatedDataImplementation, ISoRequestItemsAccessor, IDebugUser, IServiceCallsRepository)

Proxy class for the Archive Agent Used when communicating remote using WebServices. Avoid using directly. Use the AgentFactory to create the proxy instead.

Declaration
public ArchiveAgent(IActivityFilterImplementation activityFilterImplementation, IArchiveConfigurationImplementation archiveConfigurationImplementation, IArchiveListImplementation archiveListImplementation, IArchiveListResultImplementation archiveListResultImplementation, IRelatedDataImplementation relatedDataImplementation, ISoRequestItemsAccessor accessor, IDebugUser debugUser, IServiceCallsRepository serviceCallsRepository)
Parameters
Type Name Description
IActivityFilterImplementation activityFilterImplementation
IArchiveConfigurationImplementation archiveConfigurationImplementation
IArchiveListImplementation archiveListImplementation
IArchiveListResultImplementation archiveListResultImplementation
IRelatedDataImplementation relatedDataImplementation
ISoRequestItemsAccessor accessor
IDebugUser debugUser
IServiceCallsRepository serviceCallsRepository

Methods

CreateDefaultArchiveListResultAsync(CancellationToken)

Loading default values into a new ArchiveListResult. NetServer calculates default values (e.g. Country) on the entity, which is required when creating/storing a new instance

Declaration
public Task<ArchiveListResult> CreateDefaultArchiveListResultAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<ArchiveListResult>

New ArchiveListResult with default values

ExportArchiveAsync(string, string, string[], string[], ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string, string[], int, CancellationToken)

Exports the target archive to a downloadable format.

Declaration
public Task<ExportArchiveResult> ExportArchiveAsync(string providerName, string context, string[] desiredEntities, string[] columns, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restrictions, string exportType, string[] selectedRowIds, int estimatedRowCount, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
string[] desiredEntities

Comma separated list of the names of the desired entities.
string[] columns

Comma separated list of the names of the columns wanted; supports display names
ArchiveOrderByInfo[] sortOrder
ArchiveRestrictionInfo[] restrictions
string exportType

To what format the archive should be exported; Excel, etc.
string[] selectedRowIds
int estimatedRowCount

The estimated amount of rows to be exported. Used to determine if the operation should be run as a batch task or immediately.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ExportArchiveResult>

GetActivityFilterAsync(CancellationToken)

Get activity filter for the specified list.

Declaration
public Task<ActivityFilter> GetActivityFilterAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ActivityFilter>

The activity filter for the specified list

GetArchiveConfigurationAsync(string, string, CancellationToken)

Get the configuration for one archive. The configuration is keyed by a combination of archive provider name and gui name. The archive provider name must match an archive provider plugin; the gui name is an arbitrary string used to distinguish multiple occurrences of the same underlying provider in a gui.

Declaration
public Task<ArchiveConfiguration> GetArchiveConfigurationAsync(string guiName, string providerName, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ArchiveConfiguration>

Archive configuration consisting of column information, orderby information and entities

GetArchiveConfigurationV2Async(string, string, string, string, CancellationToken)

Get the configuration for one archive. The configuration is keyed by a combination of archive provider name (plus optional context), gui name, and optional table binding. The archive provider name must match an archive provider plugin; the gui name is an arbitrary string used to distinguish multiple occurrences of the same underlying provider in a gui.

Declaration
public Task<ArchiveConfiguration> GetArchiveConfigurationV2Async(string guiName, string providerName, string context, string ownerKeys, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor. Optional, but required for archives that depend on a context - for instance Quote archives that need to know their QuoteConnectionId to be meaningful
string ownerKeys

Name/value string containing ownership binding information. The first should resolve to a table/primarykey, such as selection=123. Future functionality may allow multiple/extended keys
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ArchiveConfiguration>

Archive configuration consisting of column information, orderby information and entities

GetArchiveConfigurationWithContextAsync(string, string, string, CancellationToken)

Get the configuration for one archive, with context parameter. The configuration is keyed by a combination of archive provider name and gui name. The archive provider name must match an archive provider plugin; the gui name is an arbitrary string used to distinguish multiple occurrences of the same underlying provider in a gui.

Declaration
public Task<ArchiveConfiguration> GetArchiveConfigurationWithContextAsync(string guiName, string providerName, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ArchiveConfiguration>

Archive configuration consisting of column information, orderby information and entities

GetArchiveList2Async(string, string, string, string, string, int, int, CancellationToken)

Get a page of data for an archive using a restriction string. The columns returned will be those set as chosen columns, using either the SetChosenColumns service or the corresponding SelectableMDOList.SetSelected.

Declaration
public Task<ArchiveListItem[]> GetArchiveList2Async(string guiName, string providerName, string sortOrder, string restriction, string entities, int page, int pageSize, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

The GUI name of the archive list, used to retrieve the currently configured set of columns (otherwise manipulated using the ArchiveConfiguration service)
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
string restriction

Archive restrictions as string. e.g. "name = 'baz' or category oneOf (1,2,3)". Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListAsync(string, string, ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, CancellationToken)

Get a page of data for an archive. The columns returned will be those set as chosen columns, using either the SetChosenColumns service or the corresponding SelectableMDOList.SetSelected.

Declaration
public Task<ArchiveListItem[]> GetArchiveListAsync(string guiName, string providerName, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

The GUI name of the archive list, used to retrieve the currently configured set of columns (otherwise manipulated using the ArchiveConfiguration service)
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetArchiveListByColumns2Async(string, string, string, string, string, int, int, CancellationToken)

Get a page of results for an archive list, explicitly specifying the restrictions as a string, orderby and chosen columns.

Declaration
public Task<ArchiveListItem[]> GetArchiveListByColumns2Async(string providerName, string columns, string sortOrder, string restrictions, string entities, int page, int pageSize, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string columns

An array of the names of the columns wanted.
string sortOrder

Sort order for the archive as string ('name asc, dept desc'). Can be null, which indicates 'no particular order'
string restrictions

Archive restrictions as string ('category = 1 and business oneOf (1,2,3)'). Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListByColumnsAsync(string, string[], ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, CancellationToken)

Get a page of results for an archive list, explicitly specifying the restrictions, orderby and chosen columns.

Declaration
public Task<ArchiveListItem[]> GetArchiveListByColumnsAsync(string providerName, string[] columns, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string[] columns

An array of the names of the columns wanted.
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetArchiveListByColumnsWithContext2Async(string, string, string, string, string, int, int, string, CancellationToken)

Get a page of results for an archive list with context parameter, explicitly specifying the restrictions as a string, orderby and chosen columns.

Declaration
public Task<ArchiveListItem[]> GetArchiveListByColumnsWithContext2Async(string providerName, string columns, string sortOrder, string restriction, string entities, int page, int pageSize, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string columns

Comma separated names of the columns wanted.
string sortOrder

Comma separated list of columns to sort order for the archive. e.g.: "name asc, dept desc, registeredBy" Can be null, which indicates 'no particular order'
string restriction

Archive restrictions as string. e.g. "name startsWith 'foo' and (dept = 'bar' or dept = 'baz')" Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListByColumnsWithContextAsync(string, string[], ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, string, CancellationToken)

Get a page of results for an archive list with context parameter, explicitly specifying the restrictions, orderby and chosen columns.

Declaration
public Task<ArchiveListItem[]> GetArchiveListByColumnsWithContextAsync(string providerName, string[] columns, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string[] columns

An array of the names of the columns wanted.
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetArchiveListByColumnsWithHeader2Async(string, string, string, string, string, int, int, string, CancellationToken)

Get a page of results for an archive list, explicitly specifying the restrictions as strings, orderby and chosen columns; as well as a name/value string formatted set of options. The return value includes a header that has various extra information, in addition to the actual rows.

Declaration
public Task<ArchiveListResult> GetArchiveListByColumnsWithHeader2Async(string providerName, string columns, string sortOrder, string restriction, string entities, int page, int pageSize, string options, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string columns

Comma separated string of the names of the columns wanted.
string sortOrder

Comma separated string of sort order for the archive. e.g. "name asc, dept desc" Can be null, which indicates 'no particular order'
string restriction

Archive restrictions. e.g. "category = 2 or business oneOf (2,3,4)" Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string options

name=value&amp;... formatted set of options. "rowcount=true" will cause the rowcount to be calculated and populated.
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListResult>

Header with optional row count, plus array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListByColumnsWithHeaderAsync(string, string[], ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, string, CancellationToken)

Get a page of results for an archive list, explicitly specifying the restrictions, orderby and chosen columns; as well as a name/value string formatted set of options. The return value includes a header that has various extra information, in addition to the actual rows.

Declaration
public Task<ArchiveListResult> GetArchiveListByColumnsWithHeaderAsync(string providerName, string[] columns, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, string options, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string[] columns

An array of the names of the columns wanted.
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string options

name=value&amp;... formatted set of options. "rowcount=true" will cause the rowcount to be calculated and populated.
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListResult>

Header with optional row count, plus array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetArchiveListByColumnsWithHeaderWithContext2Async(string, string, string, string, string, int, int, string, string, CancellationToken)

Get a page of results for an archive list, with context parameter, explicitly specifying the restrictions as strings, orderby and chosen columns; as well as a name/value string formatted set of options. The return value includes a header that has various extra information, in addition to the actual rows.

Declaration
public Task<ArchiveListResult> GetArchiveListByColumnsWithHeaderWithContext2Async(string providerName, string columns, string sortOrder, string restriction, string entities, int page, int pageSize, string options, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string columns

Comma separated list of the names of the columns wanted.
string sortOrder

Sort order for the archive. "name asc, dept desc" Can be null, which indicates 'no particular order'
string restriction

Archive restrictions as string. "updated > '2009.1.1' and registeredBy = 2" Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string options

name=value&amp;... formatted set of options. "rowcount=true" will cause the rowcount to be calculated and populated.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListResult>

Header with optional row count, plus array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListByColumnsWithHeaderWithContextAsync(string, string[], ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, string, string, CancellationToken)

Get a page of results for an archive list, with context parameter, explicitly specifying the restrictions, orderby and chosen columns; as well as a name/value string formatted set of options. The return value includes a header that has various extra information, in addition to the actual rows.

Declaration
public Task<ArchiveListResult> GetArchiveListByColumnsWithHeaderWithContextAsync(string providerName, string[] columns, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, string options, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string[] columns

An array of the names of the columns wanted.
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string options

name=value&amp;... formatted set of options. "rowcount=true" will cause the rowcount to be calculated and populated.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListResult>

Header with optional row count, plus array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetArchiveListWithContext2Async(string, string, string, string, string, int, int, string, CancellationToken)

Get a page of data for an archive using restrictions as strings, with context parameter. The columns returned will be those set as chosen columns, using either the SetChosenColumns service or the corresponding SelectableMDOList.SetSelected.

Declaration
public Task<ArchiveListItem[]> GetArchiveListWithContext2Async(string guiName, string providerName, string sortOrder, string restriction, string entities, int page, int pageSize, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

The GUI name of the archive list, used to retrieve the currently configured set of columns (otherwise manipulated using the ArchiveConfiguration service)
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string sortOrder

Sort order for the archive. e.g. "name asc, dept desc" Can be null, which indicates 'no particular order'
string restriction

Archive restrictions as string. e.g. "name gt 'B' or dept = 'baz'" Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string entities

Comma separated list of entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetArchiveListWithContextAsync(string, string, ArchiveOrderByInfo[], ArchiveRestrictionInfo[], string[], int, int, string, CancellationToken)

Get a page of data for an archive, with context parameter. The columns returned will be those set as chosen columns, using either the SetChosenColumns service or the corresponding SelectableMDOList.SetSelected.

Declaration
public Task<ArchiveListItem[]> GetArchiveListWithContextAsync(string guiName, string providerName, ArchiveOrderByInfo[] sortOrder, ArchiveRestrictionInfo[] restriction, string[] entities, int page, int pageSize, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

The GUI name of the archive list, used to retrieve the currently configured set of columns (otherwise manipulated using the ArchiveConfiguration service)
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
ArchiveOrderByInfo[] sortOrder

Sort order for the archive. Can be null, which indicates 'no particular order'
ArchiveRestrictionInfo[] restriction

Archive restrictions. Archives will generally throw an exception if no restrictions are set. Pass in an empty array if you really do not want restrictions, but remember that you may end up fetching the first page of millions of rows.
string[] entities

Which entities to include. Can be null, which indicates 'include all entities'
int page

Page number, page 0 is the first page. Negative page numbers are interpreted as number of rows to skip.
int pageSize

Page size, which should be kept reasonable (say, no more than 1000 rows at a time)
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation can be cancelled
Returns
Type Description
Task<ArchiveListItem[]>

Array of archive list items, where each item represents one row of data (row level data + the requested columns)
Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

Values should be encoded using the CultureDataFormatter, so 10 is "[I:10]". Default string encodings should be handled ok, but beware of non-invariant cultures leading to incorrect date and float parsing. 

var restriction1 = new ArchiveRestrictionInfo("category", "equals", "[I:10]");


Cancellation: This operation can be cancelled.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var restrictions = new ArchiveRestrictionInfo[1];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var restrictions = new ArchiveRestrictionInfo[2];
restrictions[0] = new ArchiveRestrictionInfo("updatedBy", "equals", "2");
restrictions[1] = new ArchiveRestrictionInfo("updatedDate", "after", "2000.1.2");
var res = _agent.FindFromRestrictions(restrictions, "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

GetAvailableColumnsAsync(string, string, CancellationToken)

Return list of all columns supported by an archive provider. See also GetArchiveConfiguration.

Declaration
public Task<ArchiveColumnInfo[]> GetAvailableColumnsAsync(string providerName, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string context

Optional context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<ArchiveColumnInfo[]>

Array of all columns supported by the archive provider.

GetAvailableEntitiesAsync(string, string, CancellationToken)

Return list of all entities supported by an archive provider. See also GetArchiveConfiguration.

Declaration
public Task<MDOListItem[]> GetAvailableEntitiesAsync(string providerName, string context, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string providerName

The name of the archive provider to use; it will be created via the ArchiveProviderFactory from a plugin
string context

Optional context parameter, url-encoded string context parameter for ArchiveProvider constructor
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<MDOListItem[]>

Array of all entity types supported by the archive provider. MDOListItem.Name = DisplayName, Tooltip = DisplayTooltip, Type = code name, StyleHint = optional/mandatory, IconHint=DefaultShow
Remarks

Archive Restriction strings are OData or SQL-ish. They are parsed and converted into ArchiveRestrictions.

For example: 
"name begins 'Super'"
"category = 3"
"category in (2,3,4)"
"xstop set"
"registered after '2014.3.4'"
"registered dateBetween ('2014.11.29', '2014.12.25')"
Unary operators: 
"updatedDate lastWeek", "assocId currentAssociate"

Brackets and or

AND and OR can be used to combine terms. AND has a higher priority than OR

"business = 2  AND name contains 'super'"

Brackets can be used for grouping.

"(business = 2 or category = 3) and name contains 'super'"

Aggregation operators

The column names can encode grouping and summarizing. You add functions and modifiers to the column name to trigger aggregation.

Example: group last names together, and inject a header row for each group. 
GroupBy(lastName):Header
Example: count instances of middle names, and hide the individual rows, report just the totals for each group using a footer. Note how the modifiers stack. 
Count(middleName):HideDetail:Footer
Example: the aggregator functions can nest, so you can say 
GroupBy(DatePart(personUpdatedDate):YearMonth):Header

Strings

Use the begins or contains operators to do string searches. You can also use the normal = operator to do string exact match checks.

Use backslash to escape single quotes in strings (note that backslash needs to be doubled because c# also uses backslash escapes): 

"department contains 'Bob\\'s'"


Cancellation: This operation cannot be cancelled; the cancellationToken parameter and/or cancellation by Controllers is ignored.
Examples
"name = 'SuperOffice AS'"
"name startsWith 'SuperOffice'"
"startsWith(name, 'SuperOffice')"
"updatedDate after '2000.12.30'"
"category = 10"
"category in (10, 12, 53)"
"category in (2,3,4) and name startswith 'super'"
"category in (2,3,4) or name startswith 'super'"
"(category = 2 or business = 3) and name contains 'super'"

var agent = new FindAgent();

var res1 = agent.FindFromRestrictions2("updatedBy = 2", "FindContact", 100, 0);
foreach (var row in res1.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue == 2

var res2 = agent.FindFromRestrictions2("updatedBy unequals 6 and updatedDate after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res2.ArchiveRows)
    (int)row.ColumnData["updatedBy"].RawValue != 6 && 
    row.ColumnData["updatedDate"].GetDateTimeValue() > new DateTime(2000, 1, 2);

var res3 = agent.FindFromRestrictions2("category in (2,3)", "FindContact", 100, 0);
foreach (var row in res3.ArchiveRows)
    (int)row.ColumnData["category"].RawValue == 2 || (int)row.ColumnData["category"].RawValue == 3;

var res4 = agent.FindFromRestrictions2("sale/date after '2000.1.2'", "FindContact", 100, 0);
foreach (var row in res4.ArchiveRows)
    (row.ColumnData["sale/date"].GetDateTimeValue().Year >= 2000 

var res5 = _agent.FindFromRestrictionsColumns2("(category =2 or business = 3) and name contains 'e'", 
         _provider, "category,business,name", 100, 0);
foreach (var row in res5.ArchiveRows)
    ((int)x.ColumnData["category"].RawValue == 2 || 
     (int)x.ColumnData["business"].RawValue == 3) && 
     (x.ColumnData["name"].RawValue as string).Contains("e") );

GetGroupAssociateIdsAsync(int[], CancellationToken)

Returns the associate ids that belongs to the given groups

Declaration
public Task<int[]> GetGroupAssociateIdsAsync(int[] groupIds, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int[] groupIds

Array of group ids
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<int[]>

Array of associate ids

GetProviderNamesAsync(CancellationToken)

Return list of all archive provider names

Declaration
public Task<string[]> GetProviderNamesAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<string[]>

Array of all archive provider names.

GetRelatedData2Async(string, int, string, CancellationToken)

Get data for fields related to a table record. While this method /can/ be used to fetch plain fields, that is not the intended usage and it does not replace the Entity.Get methods available for that purpose. Nor does it replace the generic DotSyntax/Dynamic archive provider.

Declaration
public Task<RelatedData[]> GetRelatedData2Async(string table, int recordId, string fields, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string table

The root table to get related data for, such as 'ticket' or 'y_car'
int recordId

The primary key of the root table to get related data for
string fields

Names of fields as a comma-separated list - these need to be valid in the DotSyntax for this table, and can be arbitrarily deep. Example: 'title,created_by.associate_id.person.fullName, x_comment'. Do not start with the root table name.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<RelatedData[]>

Array of field => ArchiveColumnData objects

GetRelatedDataAsync(string, int, string[], CancellationToken)

Get data for fields related to a table record. While this method /can/ be used to fetch plain fields, that is not the intended usage and it does not replace the Entity.Get methods available for that purpose. Nor does it replace the generic DotSyntax/Dynamic archive provider.

Declaration
public Task<RelatedData[]> GetRelatedDataAsync(string table, int recordId, string[] fields, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string table

The root table to get related data for, such as 'ticket' or 'y_car'
int recordId

The primary key of the root table to get related data for
string[] fields

Names of fields - these need to be valid in the DotSyntax for this table, and can be arbitrarily deep. Examples: 'title', 'created_by.associate_id.person.fullName', 'x_comment'. Do not start with the root table name.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task<RelatedData[]>

Array of field => ArchiveColumnData objects

SetActivityFilterAsync(ActivityFilter, CancellationToken)

Set activity filter for the specified list.

Declaration
public Task SetActivityFilterAsync(ActivityFilter activityFilter, CancellationToken cancellationToken = default)
Parameters
Type Name Description
ActivityFilter activityFilter

New activity filter
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetChosenColumnsAsync(string, string, string[], CancellationToken)

Set the currently chosen columns for the given gui name/provider name combination. This service corresponds to the SetSelected method of the SelectableMDOList service, for a list called archiveColumns: plus the archive provider name and gui name as its additionalInfo.

Declaration
public Task SetChosenColumnsAsync(string guiName, string providerName, string[] chosenColumns, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string[] chosenColumns

Array of column names, where array order indicates left to right order in the archive.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetChosenColumnsV2Async(string, string, string, string, string[], CancellationToken)

Set the currently chosen columns for the given gui name/provider name combination. This service corresponds to the SetSelected method of the SelectableMDOList service, for a list called archiveColumns: plus the archive provider name and gui name as its additionalInfo.

Declaration
public Task SetChosenColumnsV2Async(string guiName, string providerName, string context, string ownerKeys, string[] chosenColumns, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor. Optional, but required for archives that depend on a context - for instance Quote archives that need to know their QuoteConnectionId to be meaningful
string ownerKeys

Name/value string containing ownership binding information. The first should resolve to a table/primarykey, such as selection=123. Future functionality may allow multiple/extended keys
string[] chosenColumns

Array of column names, where array order indicates left to right order in the archive.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetChosenEntitiesAsync(string, string, string[], CancellationToken)

Set the currently chosen entities for the given gui name/provider name combination. This service corresponds to the SetSelected method of the SelectableMDOList service, for a list called archiveEntities: plus the archive provider name and gui name as its additionalInfo.

Declaration
public Task SetChosenEntitiesAsync(string guiName, string providerName, string[] entities, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string[] entities

Array of entity names
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetChosenEntitiesV2Async(string, string, string, string, string[], CancellationToken)

Set the currently chosen entities for the given gui name/provider name combination. This service corresponds to the SetSelected method of the SelectableMDOList service, for a list called archiveEntities: plus the archive provider name and gui name as its additionalInfo.

Declaration
public Task SetChosenEntitiesV2Async(string guiName, string providerName, string context, string ownerKeys, string[] entities, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor. Optional, but required for archives that depend on a context - for instance Quote archives that need to know their QuoteConnectionId to be meaningful
string ownerKeys

Name/value string containing ownership binding information. The first should resolve to a table/primarykey, such as selection=123. Future functionality may allow multiple/extended keys
string[] entities

Array of entity names
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetColumnWidthsAsync(string, string[], CancellationToken)

Set the column widths for the given set of columns and GUI name.

Declaration
public Task SetColumnWidthsAsync(string guiName, string[] columnWidths, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string[] columnWidths

Array of column widths. A column width is specified either as a fixed number of character (10c) or as a percentage (10%). Percentages will be recalculated so that they add up to exactly 100 when the configuration is fetched again.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

SetColumnWidthsV2Async(string, string, string, string, string[], CancellationToken)

Set the column widths for the given set of columns and GUI name.

Declaration
public Task SetColumnWidthsV2Async(string guiName, string providerName, string context, string ownerKeys, string[] columnWidths, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string guiName

String that identifies the archive in the GUI, must be the same when fetching and storing configurations, but does not otherwise have to match anything.
string providerName

Name of archive provider, must match one of the plugins known to the ArchiveProviderFactory.
string context

Context parameter, url-encoded string context parameter for ArchiveProvider constructor. Optional, but required for archives that depend on a context - for instance Quote archives that need to know their QuoteConnectionId to be meaningful
string ownerKeys

Name/value string containing ownership binding information. The first should resolve to a table/primarykey, such as selection=123. Future functionality may allow multiple/extended keys
string[] columnWidths

Array of column widths. A column width is specified either as a fixed number of character (10c) or as a percentage (10%). Percentages will be recalculated so that they add up to exactly 100 when the configuration is fetched again.
CancellationToken cancellationToken

This operation cannot be cancelled; the cancellationToken parameter is ignored
Returns
Type Description
Task

Implements