Interface IFindAgent

Interface for the Find Agent Find functions

Namespace: SuperOffice.CRM.Services

Assembly: SuperOffice.Services.dll

Syntax

[Agent("Find Agent", "Interface for the Find Agent. Find functions")]
public interface IFindAgent : IAgent

Examples

using SuperOffice;
using SuperOffice.CRM.Services;

using (SoSession mySession = SoSession.Authenticate("user", "pass"))
{
   using (FindAgent agent = new FindAgent())
   {
      // call methods on agent here...
   }
}

Methods

CreateRestrictionGroupAsync(string, string, string, string, CancellationToken)

Create a restriction group, initialized with next rank etc.

Declaration

Task<ArchiveRestrictionGroup> CreateRestrictionGroupAsync(string storageType, string providerName, string storageKey, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionGroup>	The new restriction group.

DeleteRestrictionGroupAsync(string, string, string, int, string, CancellationToken)

Create a restriction group, initialized with next rank etc.

Declaration

Task DeleteRestrictionGroupAsync(string storageType, string providerName, string storageKey, int rank, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
int	rank	Rank of the group to be deleted.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions.

FindAsync(string, string, string, int, int, CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are fetched from the restriction storage provider according to the given parameters. The columns of the result are calculated based on the restriction. The orderby columns are also calculated by the system.<para/>The other variants of the Find method allow you greater control over the individual aspects of the process.

Declaration

Task<FindResults> FindAsync(string storageType, string providerName, string storageKey, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

FindFromRestrictions2Async(string, string, int, int, CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are passed in directly, not fetched by a restriction storage provider. The columns of the result are calculated based on the restriction.

Declaration

Task<FindResults> FindFromRestrictions2Async(string restrictions, string providerName, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	restrictions	String of restrictions specifying the search. e.g. "name='SuperOffice'" Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

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'"

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") );

FindFromRestrictionsAsync(ArchiveRestrictionInfo[], string, int, int, CancellationToken)

Declaration

Task<FindResults> FindFromRestrictionsAsync(ArchiveRestrictionInfo[] restrictions, string providerName, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ArchiveRestrictionInfo[]	restrictions	Array of restrictions specifying the search. Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

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]");

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);

FindFromRestrictionsColumns2Async(string, string, string, int, int, CancellationToken)

Execute a Find operation and return a page of results. <para/>The criteria for the Find are passed in directly, not fetched by a restriction storage provider. <para/>The desired columns of the result set are also passed in directly.<para/>The orderby information is calculated by the system.<para/>Use the GetCriteriaInformation and GetDefaultDesiredColumns service methods to let the system calculate these values, if you want to use or modify them.

Declaration

Task<FindResults> FindFromRestrictionsColumns2Async(string restrictions, string providerName, string desiredColumns, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	restrictions	String of restrictions specifying the search. e.g.:"name begins 'Super'". Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	desiredColumns	Array of column names desired for the result. Each name must match a column offered by the given archive provider.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

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'"

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") );

FindFromRestrictionsColumnsAsync(ArchiveRestrictionInfo[], string, string[], int, int, CancellationToken)

Declaration

Task<FindResults> FindFromRestrictionsColumnsAsync(ArchiveRestrictionInfo[] restrictions, string providerName, string[] desiredColumns, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ArchiveRestrictionInfo[]	restrictions	Array of restrictions specifying the search. Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string[]	desiredColumns	Array of column names desired for the result. Each name must match a column offered by the given archive provider.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

Remarks

Archive Restriction Info objects represent search terms.

Column names and operator strings are defined elsewhere.

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

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);

FindFromRestrictionsColumnsOrderBy2Async(string, string, string, string, int, int, CancellationToken)

Execute a Find operation and return a page of results. <para/>The criteria for the Find are passed in directly, not fetched by a restriction storage provider. <para/>The desired columns of the result set are also passed in directly.<para/>The orderby information is also passed in directly.<para/>Use the GetCriteriaInformation, GetDefaultDesiredColumns and GetDefaultOrderBy service methods to let the system calculate these values, if you want to use or modify them.

Declaration

Task<FindResults> FindFromRestrictionsColumnsOrderBy2Async(string restrictions, string providerName, string desiredColumns, string orderBy, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	restrictions	String of restrictions specifying the search. Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	desiredColumns	Comma separated list of column names desired for the result. Each name must match a column offered by the given archive provider.
string	orderBy	String of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

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'"

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") );

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

Execute a Find operation and return a page of results. <para/>The criteria for the Find are passed in directly, not fetched by a restriction storage provider. <para/>The desired columns of the result set are also passed in directly.<para/>The orderby information is also passed in directly.<para/>Use the GetCriteriaInformation, GetDefaultDesiredColumns and GetDefaultOrderBy service methods to let the system calculate these values, if you want to use or modify them.

Declaration

Task<FindResults> FindFromRestrictionsColumnsOrderByAsync(ArchiveRestrictionInfo[] restrictions, string providerName, string[] desiredColumns, ArchiveOrderByInfo[] orderBy, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ArchiveRestrictionInfo[]	restrictions	Array of restrictions specifying the search. Each restriction must match a column of the given archive provider, and that column must have its CanRestrictBy property set to true.
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string[]	desiredColumns	Array of column names desired for the result. Each name must match a column offered by the given archive provider.
ArchiveOrderByInfo[]	orderBy	Array of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

FindOrderBy2Async(string, string, string, int, int, string, CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are fetched from the restriction storage provider according to the given parameters. The columns of the result are calculated based on the restriction. The orderby parameter is used for sorting the results.<para/>The other variants of the Find method allow you greater control over the individual aspects of the process.

Declaration

Task<FindResults> FindOrderBy2Async(string storageType, string providerName, string storageKey, int pageSize, int pageNumber, string orderBy, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
string	orderBy	Comma separated list of order by specifications. "name asc, dept desc" If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

FindOrderByAsync(string, string, string, int, int, ArchiveOrderByInfo[], CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are fetched from the restriction storage provider according to the given parameters. The columns of the result are calculated based on the restriction. The orderby parameter is used for sorting the results.<para/>The other variants of the Find method allow you greater control over the individual aspects of the process.

Declaration

Task<FindResults> FindOrderByAsync(string storageType, string providerName, string storageKey, int pageSize, int pageNumber, ArchiveOrderByInfo[] orderBy, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
ArchiveOrderByInfo[]	orderBy	Array of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

FindWithColumnsAsync(string, string, string, string[], int, int, ArchiveOrderByInfo[], CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are fetched from the restriction storage provider according to the given parameters.

Declaration

Task<FindResults> FindWithColumnsAsync(string storageType, string providerName, string storageKey, string[] desiredColumns, int pageSize, int pageNumber, ArchiveOrderByInfo[] orderBy, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string[]	desiredColumns	Array of column names desired for the result. Each name must match a column offered by the given archive provider.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
ArchiveOrderByInfo[]	orderBy	Array of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

FindWithExtraRestrictions2Async(string, string, string, string, string, string, int, int, CancellationToken)

Execute a Find operation and return a page of results. The criteria for the Find are fetched from the restriction storage provider according to the given parameters. In addition an extra set of restrictions can be added to the search. These restrictions will not be saved, they are only valid for the current search. Extra restrictions will override restrictions with the same key already stored on the storagekey.

Declaration

Task<FindResults> FindWithExtraRestrictions2Async(string storageType, string providerName, string storageKey, string extraRestrictions, string orderBy, string desiredColumns, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string	extraRestrictions	Extra restrictions to append to the the search. These will override saved restrictions with the same key.
string	orderBy	Comma separated list of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
string	desiredColumns	Comma separated list of column names desired for the result. Each name must match a column offered by the given archive provider.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

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'"

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") );

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

Declaration

Task<FindResults> FindWithExtraRestrictionsAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionInfo[] extraRestrictions, ArchiveOrderByInfo[] orderBy, string[] desiredColumns, int pageSize, int pageNumber, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
ArchiveRestrictionInfo[]	extraRestrictions	Extra restrictions to append to the the search. These will override saved restrictions with the same key.
ArchiveOrderByInfo[]	orderBy	Array of order by specifications. If it is null or empty, the row order is unspecified, database dependent, and might not be the same from call to call, depending on query execution plans. The unspecified order willgenerally not vary within pages of the same query.
string[]	desiredColumns	Array of column names desired for the result. Each name must match a column offered by the given archive provider.
int	pageSize	Size of result set pages
int	pageNumber	Result set page to return, 0 is the first page. When a call returns no rows, no further pages are available. Negative page numbers are interpreted as number of rows to skip.
CancellationToken	cancellationToken

Returns

Type	Description
Task<FindResults>	Results from search, containing column information and result rows.

GetAvailableRestrictionColumnsAsync(string, string, CancellationToken)

Get a list of the column names corresponding to available restrictions for a certain archive provider and restriction storage provider. Such columns have CanRestrict set to true, and are supported by the given restriction storage provider.

Declaration

Task<string[]> GetAvailableRestrictionColumnsAsync(string storageType, string providerName, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is to execute the search and return the result columns/rows
CancellationToken	cancellationToken

Returns

Type	Description
Task<string[]>	Array of column names, corresponding to support restrictions for the given archive and restriction storage providers.

GetCriteriaInformationAsync(string, string, string, string[], CancellationToken)

Get criteria information from a set of saved criteria. The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control

Declaration

Task<CriteriaInformation> GetCriteriaInformationAsync(string storageType, string providerName, string storageKey, string[] staticColumns, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string[]	staticColumns	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control

GetCriteriaInformationWithContextAsync(string, string, string, string[], string, CancellationToken)

Declaration

Task<CriteriaInformation> GetCriteriaInformationWithContextAsync(string storageType, string providerName, string storageKey, string[] staticColumns, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string[]	staticColumns	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control

GetDefaultDesiredColumnsAsync(string, string, string, CancellationToken)

Calculate the default desired columns, i.e., the result columns for a given search. The search is defined by a storage type, provider name and storage key, which are used to fetch the corresponding restrictions from the database (in the same way as Find does). If you want to specify the restriction directly, use the GetDefaultDesiredColumnsFromRestrictions method instead. This is the algorithm that is used by the Find service method.

Declaration

Task<ArchiveColumnInfo[]> GetDefaultDesiredColumnsAsync(string storageType, string providerName, string storageKey, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of the provider to calculate default desired columns for
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveColumnInfo[]>	Column information for the default desired columns, fully populated. Percentage-specified column widths sum to exactly 100.

GetDefaultDesiredColumnsFromRestrictions2Async(string, string, CancellationToken)

Calculate the default desired columns, i.e., the result columns for a given search. The search is defined by a provider name and a set of restrictions. This is the algorithm that is used by the Find service method.

Declaration

Task<ArchiveColumnInfo[]> GetDefaultDesiredColumnsFromRestrictions2Async(string providerName, string restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	providerName	Name of the provider to calculate default desired columns for
string	restrictions	Restriction to use in the calculation of default desired columns
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveColumnInfo[]>	Column information for the default desired columns, fully populated. Percentage-specified column widths sum to exactly 100.

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'"

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") );

GetDefaultDesiredColumnsFromRestrictionsAsync(string, ArchiveRestrictionInfo[], CancellationToken)

Declaration

Task<ArchiveColumnInfo[]> GetDefaultDesiredColumnsFromRestrictionsAsync(string providerName, ArchiveRestrictionInfo[] restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	providerName	Name of the provider to calculate default desired columns for
ArchiveRestrictionInfo[]	restrictions	Restriction to use in the calculation of default desired columns
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveColumnInfo[]>	Column information for the default desired columns, fully populated. Percentage-specified column widths sum to exactly 100.

GetDefaultOrderByAsync(string, string, string, CancellationToken)

Calculate the default orderby columns for a given provider and a search. The search is specified by a storage type, provider name and storage key, and is fetched from the database. Default desired columns are then calculated for the search, and those columns are then used as the basis for calculating an order by. If you want to specify the desired columns directly, use the GetDefaultOrderByFromDesiredColumns method instead. This is the same algorithm that is used by the Find service method.

Declaration

Task<ArchiveOrderByInfo[]> GetDefaultOrderByAsync(string storageType, string providerName, string storageKey, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Provider name to calculate default orderby for
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveOrderByInfo[]>	Orderby information

GetDefaultOrderByFromDesiredColumnsAsync(string, string[], CancellationToken)

Calculate the default orderby columns for a given provider and a set of desired columns. This is the same algorithm that is used by the Find service method.

Declaration

Task<ArchiveOrderByInfo[]> GetDefaultOrderByFromDesiredColumnsAsync(string providerName, string[] desiredColumns, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	providerName	Provider name to calculate default orderby for
string[]	desiredColumns	Desired columns (return fields), used in the orderby calculation. You can generally only order by columns that have been set as 'desired'.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveOrderByInfo[]>	Orderby information

GetRestrictionGroupAsync(string, string, string, int, string, CancellationToken)

Return the restriction group with given rank or a blank carrier.

Declaration

Task<ArchiveRestrictionGroup> GetRestrictionGroupAsync(string storageType, string providerName, string storageKey, int rank, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
int	rank	Rank of the group to be deleted.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionGroup>	The new restriction group.

GetRestrictionGroupsAsync(string, string, string, string, CancellationToken)

Return all the restriction groups.

Declaration

Task<ArchiveRestrictionGroup[]> GetRestrictionGroupsAsync(string storageType, string providerName, string storageKey, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionGroup[]>	The restriction groups.

GetSpecifiedCriteriaInformationWithDefaultsAsync(string, string, string, string[], string[], CancellationToken)

Get criteria information from a set of saved criteria, for a specific set of columns. The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control. ALL columns specified in the call will be present in the results; those that do not have corresponding criteria set will have empty values and the default (first) operator, with the IsActive flag set to false.

Declaration

Task<CriteriaInformation> GetSpecifiedCriteriaInformationWithDefaultsAsync(string storageType, string providerName, string storageKey, string[] desiredColumnNames, string[] staticColumns, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string[]	desiredColumnNames	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
string[]	staticColumns	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control. ALL columns specified in the call will be present in the results; those that do not have corresponding criteria set will have empty values and the default (first) operator, with the IsActive flag set to false.

GetSpecifiedCriteriaInformationWithDefaultsWithContextAsync(string, string, string, string[], string[], string, CancellationToken)

Declaration

Task<CriteriaInformation> GetSpecifiedCriteriaInformationWithDefaultsWithContextAsync(string storageType, string providerName, string storageKey, string[] desiredColumnNames, string[] staticColumns, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it fetches criteria for the search
string[]	desiredColumnNames	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
string[]	staticColumns	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control. ALL columns specified in the call will be present in the results; those that do not have corresponding criteria set will have empty values and the default (first) operator, with the IsActive flag set to false.

PopulateRestrictionValuesAsync(ArchiveRestrictionInfo[], CancellationToken)

Take an incoming set of Restrictions (name + operator + any user-entered values), and populate/expand all values as specified by the operator's ValueHints, taking into account any values already there. Used for dynamic date periods; perhaps others in the future

Declaration

Task<ArchiveRestrictionInfo[]> PopulateRestrictionValuesAsync(ArchiveRestrictionInfo[] restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ArchiveRestrictionInfo[]	restrictions	Restrictions to populate. The Name and Operator fields have to have valid content, and Values should be set as appropriate. Other fields can be left blank or null and will not be changed.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionInfo[]>	Restrictions in the same order as the incoming restrictions, with all values expanded.

PopulateRestrictionsAsync(string, ArchiveRestrictionInfo[], CancellationToken)

Take an incoming set of minimally populated restrictions (name + operator is required), and populate all the other parts of the ArchiveRestrictionInfo structure. This includes column information, display values (including list value lookup), and calculated/default values where the value hints specify read-only (R).

Declaration

Task<ArchiveRestrictionInfo[]> PopulateRestrictionsAsync(string providerName, ArchiveRestrictionInfo[] restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	providerName	Provider name to use for populating column information
ArchiveRestrictionInfo[]	restrictions	Restrictions to populate. The Name and Operator fields have to have valid content, and Values should be set as appropriate. Other fields can be left blank or null. If a ColumnInfo is already set, it will not be overwritten.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionInfo[]>	Fully populated restrictions in the same order as the incoming restrictions.

SaveRestrictionGroupAsync(string, string, string, ArchiveRestrictionGroup, string, CancellationToken)

Save an array of restrictions as a restriction group for later use as search criteria (including as dynamic selection and Find).

Declaration

Task SaveRestrictionGroupAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionGroup restrictionGroup, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
ArchiveRestrictionGroup	restrictionGroup	Information about a group of restrictions
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions.

SaveRestrictionGroupsAsync(string, string, string, ArchiveRestrictionGroup[], string, CancellationToken)

Save and rerank an array of restriction groups, returning the possibly modified array.

Declaration

Task<ArchiveRestrictionGroup[]> SaveRestrictionGroupsAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionGroup[] restrictionGroups, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
ArchiveRestrictionGroup[]	restrictionGroups	Information about a group of restrictions
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task<ArchiveRestrictionGroup[]>	The new restriction group.

SaveRestrictions2Async(string, string, string, string, CancellationToken)

Save an array of restrictions for later use as search criteria (including as dynamic selection and Find).

Declaration

Task SaveRestrictions2Async(string storageType, string providerName, string storageKey, string restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
string	restrictions	String of restrictions. "name = 'SuperOffice'" The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions. See SaveRestrictionsAndGetCriteriaInformation if you would like the restrictions returned as criteria immediately, in one roundtrip

SaveRestrictionsAndGetCriteriaInformation2Async(string, string, string, string, string, CancellationToken)

Save an array of restrictions for later use as search criteria (including as dynamic selection and Find). Then, return the same result as a call to GetCriteriaInformation would have done. The purpose is to encapsulate saving and updating of a GUI in one round trip.

Declaration

Task<CriteriaInformation> SaveRestrictionsAndGetCriteriaInformation2Async(string storageType, string providerName, string storageKey, string restrictions, string staticColumns, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
string	restrictions	String of restrictions. The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
string	staticColumns	Optional string of comma-separated columns that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control

SaveRestrictionsAndGetCriteriaInformationAsync(string, string, string, ArchiveRestrictionInfo[], string[], CancellationToken)

Declaration

Task<CriteriaInformation> SaveRestrictionsAndGetCriteriaInformationAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionInfo[] restrictions, string[] staticColumns, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
ArchiveRestrictionInfo[]	restrictions	Array of restrictions. The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
string[]	staticColumns	Optional array of restrictions that are to be EXCLUDED from the CriteriaArchiveRows part of the result. In the Find dialogs, that corresponds to the 'static' fields, to avoid duplicating them in the 'Match also' criteria list. This array can be null, indicating that all restrictions should be included in the criteria list.
CancellationToken	cancellationToken

Returns

Type	Description
Task<CriteriaInformation>	The result contains the restrictions in two forms: fully populated ArchiveRestrictionInfo objects, used to display details and for saving changes; and as a list suitable for an Archive control

SaveRestrictionsAsync(string, string, string, ArchiveRestrictionInfo[], CancellationToken)

Save an array of restrictions for later use as search criteria (including as dynamic selection and Find).

Declaration

Task SaveRestrictionsAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionInfo[] restrictions, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
ArchiveRestrictionInfo[]	restrictions	Array of restrictions. The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions. See SaveRestrictionsAndGetCriteriaInformation if you would like the restrictions returned as criteria immediately, in one roundtrip

SaveRestrictionsWithContext2Async(string, string, string, string, string, CancellationToken)

Save an array of restrictions for later use as search criteria (including as dynamic selection and Find).

Declaration

Task SaveRestrictionsWithContext2Async(string storageType, string providerName, string storageKey, string restrictions, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
string	restrictions	String of restrictions. The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions. See SaveRestrictionsAndGetCriteriaInformation if you would like the restrictions returned as criteria immediately, in one roundtrip

SaveRestrictionsWithContextAsync(string, string, string, ArchiveRestrictionInfo[], string, CancellationToken)

Save an array of restrictions for later use as search criteria (including as dynamic selection and Find).

Declaration

Task SaveRestrictionsWithContextAsync(string storageType, string providerName, string storageKey, ArchiveRestrictionInfo[] restrictions, string context, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	storageType	Restriction storage type specification, either 'Criteria' or 'Reporter' (or possible extensions)
string	providerName	Name of archive provider that is the intended consumer of the restrictions
string	storageKey	Storage key to be interpreted by the restriction storage provider, when it saves the restrictions as criteria
ArchiveRestrictionInfo[]	restrictions	Array of restrictions. The ColumnInfo member and the DisplayValues members need NOT be populated; it is enough to provide a name, operator and any values the operator may need. The IsActive is also saved. Values should be encoded using the CultureDataFormatter to ensure compatibility across cultures.
string	context	Optional context that can be used by FindProvider
CancellationToken	cancellationToken

Returns

Type	Description
Task	This service call just saves the restrictions. See SaveRestrictionsAndGetCriteriaInformation if you would like the restrictions returned as criteria immediately, in one roundtrip