Show / Hide Table of Contents

Interface IPreferenceAgent

Interface for the Preference Agent Preferences, user interface tab configuration

Namespace: SuperOffice.CRM.Services
Assembly: SuperOffice.Services.dll
Syntax
[Agent("Preference Agent", "Interface for the Preference Agent. Preferences, user interface tab configuration")]
public interface IPreferenceAgent : IAgent
Examples
using SuperOffice;
using SuperOffice.CRM.Services;

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

Methods

CreateDefaultPreferenceAsync(CancellationToken)

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

Declaration
Task<Preference> CreateDefaultPreferenceAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<Preference>

New Preference with default values

CreateDefaultPreferenceDescriptionAsync(CancellationToken)

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

Declaration
Task<PreferenceDescription> CreateDefaultPreferenceDescriptionAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription>

New PreferenceDescription with default values

CreateDefaultPreferenceDescriptionLineAsync(CancellationToken)

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

Declaration
Task<PreferenceDescriptionLine> CreateDefaultPreferenceDescriptionLineAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine>

New PreferenceDescriptionLine with default values

DeleteFromSectionAndKeyAsync(string, string, CancellationToken)

Gets a PreferenceDescription based on the section and key

Declaration
Task DeleteFromSectionAndKeyAsync(string section, string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string section

The PreferenceDescription-section

string key

The PreferenceDescription-key

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

DeletePrefDescLinesByPrefDescIdAsync(int, CancellationToken)

Delete the PrefDescLines associated with Preference Description Id in the SuperOffice database

Declaration
Task DeletePrefDescLinesByPrefDescIdAsync(int prefDescId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int prefDescId

Primary key of the Preference Description that contains PrefDescLines to delete

CancellationToken cancellationToken
Returns
Type Description
Task

Nothing

DeletePrefDescLinesByPrefDescIdsAsync(int[], CancellationToken)

Delete the PrefDescLines associated with Preference Description Ids in the SuperOffice database

Declaration
Task DeletePrefDescLinesByPrefDescIdsAsync(int[] prefDescIds, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int[] prefDescIds

Primary keys of the Preference Descriptions that contains PrefDescLines to delete

CancellationToken cancellationToken
Returns
Type Description
Task

Nothing

DeletePreferenceAsync(int, CancellationToken)

Delete a preference by id

Declaration
Task DeletePreferenceAsync(int id, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int id

The id of the preference to delete

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

DeletePreferenceDescriptionAsync(int, CancellationToken)

Deletes the PreferenceDescription

Declaration
Task DeletePreferenceDescriptionAsync(int preferenceDescriptionId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int preferenceDescriptionId

The identity of the PreferenceDescription

CancellationToken cancellationToken
Returns
Type Description
Task

DeletePreferenceDescriptionLineAsync(int, CancellationToken)

Deletes the PreferenceDescriptionLine

Declaration
Task DeletePreferenceDescriptionLineAsync(int preferenceDescriptionLineId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int preferenceDescriptionLineId

The identity of the PreferenceDescriptionLine

CancellationToken cancellationToken
Returns
Type Description
Task

DeletePreferenceDescriptionLinesAsync(int[], CancellationToken)

Delete the PrefDescLines in the SuperOffice database

Declaration
Task DeletePreferenceDescriptionLinesAsync(int[] prefDescLineIds, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int[] prefDescLineIds

Primary keys of the PrefDescLines to delete

CancellationToken cancellationToken
Returns
Type Description
Task

Nothing

DeletePreferencesAsync(int[], CancellationToken)

Delete some preferences by id

Declaration
Task DeletePreferencesAsync(int[] ids, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int[] ids

The ids of the preference to delete

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

GetAllAsync(CancellationToken)

Gets a list of all PreferenceDescriptions in the system.

Declaration
Task<PreferenceDescription[]> GetAllAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription[]>

All PreferenceDescriptions in the system

GetAllFromSectionAsync(string, CancellationToken)

Gets all PreferenceDescription-items in the specified section

Declaration
Task<PreferenceDescription[]> GetAllFromSectionAsync(string section, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string section

The PreferenceDescription-section

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription[]>

All PreferenceDescriptions found.

GetFromSectionAndKeyAsync(string, string, CancellationToken)

Gets a PreferenceDescription based on the section and key

Declaration
Task<PreferenceDescription> GetFromSectionAndKeyAsync(string section, string key, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string section

The PreferenceDescription-section

string key

The PreferenceDescription-key

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription>

A PreferenceDescription or null

GetNetServicesStatusUrlAsync(CancellationToken)

Returns URL to status service. e.g. 'https://help.superoffice.com/sodispatcher/v1/status' Returns NULL if status does not need to be checked yet.

Declaration
Task<string> GetNetServicesStatusUrlAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<string>

NULL or URL of the status service that returns an XML or JSON block.

GetPreferenceAsync(int, CancellationToken)

Get a preference by id

Declaration
Task<Preference> GetPreferenceAsync(int id, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int id

The id of the preference to load

CancellationToken cancellationToken
Returns
Type Description
Task<Preference>

The preference loaded

GetPreferenceByNameAndIdAsync(string, string, PreferenceLevel, int, CancellationToken)

Get a preference by name and owner id.

Declaration
Task<Preference> GetPreferenceByNameAndIdAsync(string prefSection, string prefKey, PreferenceLevel prefLevel, int ownerId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string prefSection

The preference section name. e.g. 'Functions'. See SuperOffice.CRM.UserPreferenceStrings for constants.

string prefKey

The preference key name. e.g. 'ShowTipsAtStart'. See SuperOffice.CRM.UserPreferenceStrings for constants.

PreferenceLevel prefLevel

The preference level to read. Undefined (0) means to return the preference defined closest to the user.

int ownerId

The preference owner id, individual or group.

CancellationToken cancellationToken
Returns
Type Description
Task<Preference>

The preference. Note that id = 0 and value = null if preference not found in the database at the requested pref-level.

GetPreferenceByNameAsync(string, string, PreferenceLevel, CancellationToken)

Get a preference by name

Declaration
Task<Preference> GetPreferenceByNameAsync(string prefSection, string prefKey, PreferenceLevel prefLevel, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string prefSection

The preference section name. e.g. 'Functions'. See SuperOffice.CRM.UserPreferenceStrings for constants.

string prefKey

The preference key name. e.g. 'ShowTipsAtStart'. See SuperOffice.CRM.UserPreferenceStrings for constants.

PreferenceLevel prefLevel

The preference level to read. Undefined (0) means to return the preference defined closest to the user.

CancellationToken cancellationToken
Returns
Type Description
Task<Preference>

The preference. Note that id = 0 and value = null if preference not found in the database at the requested pref-level.

GetPreferenceDescriptionAsync(int, CancellationToken)

Gets a PreferenceDescription object.

Declaration
Task<PreferenceDescription> GetPreferenceDescriptionAsync(int preferenceDescriptionId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int preferenceDescriptionId

The identifier of the PreferenceDescription object

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription>

PreferenceDescription

GetPreferenceDescriptionLineAsync(int, CancellationToken)

Gets a PreferenceDescriptionLine object.

Declaration
Task<PreferenceDescriptionLine> GetPreferenceDescriptionLineAsync(int preferenceDescriptionLineId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int preferenceDescriptionLineId

The identifier of the PreferenceDescriptionLine object

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine>

PreferenceDescriptionLine

GetPreferenceDescriptionLineFromIdAndValueAsync(int, string, CancellationToken)

Get a preference description line from a prefDesc_id and a prefValue

Declaration
Task<PreferenceDescriptionLine> GetPreferenceDescriptionLineFromIdAndValueAsync(int prefDescId, string prefValue, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int prefDescId

The id of the preference description this line is connected to

string prefValue

The value of the description line to return

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine>

The preference description line matching the id and the value

GetPreferenceDescriptionLinesByPrefDescIdAsync(int, CancellationToken)

Get all preference description lines from a prefDesc_id

Declaration
Task<PreferenceDescriptionLine[]> GetPreferenceDescriptionLinesByPrefDescIdAsync(int prefDescId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
int prefDescId

The id of the preference description this line is connected to

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine[]>

The preference description lines matching the id

GetPreferencesAsync(PreferenceSpec[], CancellationToken)

Get one or more preferences based on a set of specifications.<br/>The prefDisplayvalue and prefDisplaytooltip are blank (faster processing relative to GetPreferencesWithDisplayValues)

Declaration
Task<Preference[]> GetPreferencesAsync(PreferenceSpec[] specifications, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PreferenceSpec[] specifications

Array of preference specifications. The key value may be * (asterisk), which means 'all keys within section'. Note that the semantics of this are more strictly 'all keys actually set at any accessible level for this associate'; you will NOT get entries for preferences that might exist, but have no set value anywhere. You can also have askerisk as the section name. In that case the specification array must contain exactly one entry and the key must also be asterisk. This will return all known preferences in all sections for your associate. It might be a lot, tests have shown that a heavily used database can accumulate up to 500 preferences on a single associate. If the Sentry table/field right preferences have been used, the number could be a lot greater!

CancellationToken cancellationToken
Returns
Type Description
Task<Preference[]>

Array of preference values for your given specification(s). More strictly: 'all keys actually set at any accessible level for this associate'; you will NOT get entries for preferences that might exist, but have no set value anywhere.

GetPreferencesWithDisplayValuesAsync(PreferenceSpec[], CancellationToken)

Get one or more preferences based on a set of specifications<br/>The PrefDisplayValue and PrefDisplaytooltip are populated, at some additional processing cost.

Declaration
Task<Preference[]> GetPreferencesWithDisplayValuesAsync(PreferenceSpec[] specifications, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PreferenceSpec[] specifications

Array of preference specifications. The key value may be * (asterisk), which means 'all keys within section'. Note that the semantics of this are more strictly 'all keys actually set at any accessible level for this associate'; you will NOT get entries for preferences that might exist, but have no set value anywhere. You can also have askerisk as the section name. In that case the specification array must contain exactly one entry and the key must also be asterisk. This will return all known preferences in all sections for your associate. It might be a lot, tests have shown that a heavily used database can accumulate up to 500 preferences on a single associate. If the Sentry table/field right preferences have been used, the number could be a lot greater!

CancellationToken cancellationToken
Returns
Type Description
Task<Preference[]>

Array of preference values for your given specification(s). More strictly: 'all keys actually set at any accessible level for this associate'; you will NOT get entries for preferences that might exist, but have no set value anywhere.<br/>The PrefDisplayValue and PrefDisplaytooltip are populated, at some additional processing cost.

GetTabOrderAsync(string, CancellationToken)

Gets the tab order.

Declaration
Task<TabOrder> GetTabOrderAsync(string tabName, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string tabName

Name of the tab control

CancellationToken cancellationToken
Returns
Type Description
Task<TabOrder>

Tab order. Array of strings. Each string represent a named tab.

GetTabOrdersAsync(CancellationToken)

Interface for the Preference Agent Preferences, user interface tab configuration

Declaration
Task<TabOrder[]> GetTabOrdersAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<TabOrder[]>

GetXsrfPathsAsync(string, CancellationToken)

Returns paths that XSRF cookies should be set on

Declaration
Task<string[]> GetXsrfPathsAsync(string hostname, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string hostname

The hostname that we are storing paths for.

CancellationToken cancellationToken
Returns
Type Description
Task<string[]>

Paths that XSRF cookies should be set for: ['/cs', '/crm']

SaveFromSectionAndKeyAsync(string, string, PreferenceDescription, CancellationToken)

Update a PreferenceDescription based on the section and key

Declaration
Task<PreferenceDescription> SaveFromSectionAndKeyAsync(string section, string key, PreferenceDescription preferenceDescription, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string section

The PreferenceDescription-section

string key

The PreferenceDescription-key

PreferenceDescription preferenceDescription

The PreferenceDescription to save.

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription>

Saved PreferenceDescription

SavePreferenceAsync(Preference, CancellationToken)

Save this preference

Declaration
Task SavePreferenceAsync(Preference preference, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Preference preference

Preference to be saved. All fields must be filled in, and the preference will be saved on the Associate level only. Setting for other levels is an administrative task and not available through this service.

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

SavePreferenceDescriptionAsync(PreferenceDescription, CancellationToken)

Updates the existing PreferenceDescription or creates a new PreferenceDescription if the id parameter is empty

Declaration
Task<PreferenceDescription> SavePreferenceDescriptionAsync(PreferenceDescription preferenceDescription, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PreferenceDescription preferenceDescription

The PreferenceDescription that is saved.

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescription>

New or updated PreferenceDescription

SavePreferenceDescriptionLineAsync(PreferenceDescriptionLine, CancellationToken)

Updates the existing PreferenceDescriptionLine or creates a new PreferenceDescriptionLine if the id parameter is empty

Declaration
Task<PreferenceDescriptionLine> SavePreferenceDescriptionLineAsync(PreferenceDescriptionLine preferenceDescriptionLine, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PreferenceDescriptionLine preferenceDescriptionLine

The PreferenceDescriptionLine that is saved.

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine>

New or updated PreferenceDescriptionLine

SavePreferenceDescriptionLinesAsync(PreferenceDescriptionLine[], CancellationToken)

Saves the PreferenceDescriptionLine array in the SuperOffice database

Declaration
Task<PreferenceDescriptionLine[]> SavePreferenceDescriptionLinesAsync(PreferenceDescriptionLine[] preferenceDescriptionLines, CancellationToken cancellationToken = default)
Parameters
Type Name Description
PreferenceDescriptionLine[] preferenceDescriptionLines

The PreferenceDescriptionLine array to save.

CancellationToken cancellationToken
Returns
Type Description
Task<PreferenceDescriptionLine[]>

The updated PrefDesc lines (If the PreferenceDescriptionLine array was new, it returns with id's set.

SavePreferenceEntitiesAsync(Preference[], bool, CancellationToken)

Save this set of preferences.

Declaration
Task SavePreferenceEntitiesAsync(Preference[] preferences, bool removeLowerLevels, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Preference[] preferences

Preferences to be saved. Note that all fields must be filled in.

bool removeLowerLevels

If this is true, all user preferences on lower levels will be deleted

CancellationToken cancellationToken
Returns
Type Description
Task

SavePreferenceEntityAsync(Preference, bool, CancellationToken)

Saves a complete preference object, on any level and any target. Preference administrator rights are required to use this

Declaration
Task<Preference> SavePreferenceEntityAsync(Preference preference, bool removeLowerLevels, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Preference preference

The preference object to be saved

bool removeLowerLevels

If this is true, all user preferences on lower levels will be deleted

CancellationToken cancellationToken
Returns
Type Description
Task<Preference>

Returns the saved preference

SavePreferencesAsync(Preference[], CancellationToken)

Save this set of preferences. Note this method DOES NOT look at level/targetId - it only saves on behalf of the CURRENT USER.

Declaration
Task SavePreferencesAsync(Preference[] preferences, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Preference[] preferences

Preferences to be saved. Note that all fields must be filled in, and the preference will be saved on the Associate level only! Setting for other levels is an administrative task and not available through this service.

CancellationToken cancellationToken
Returns
Type Description
Task

SaveTabOrderAsync(TabOrder, CancellationToken)

Saves the tab order. The order is saved pr. user.

Declaration
Task SaveTabOrderAsync(TabOrder tabOrder, CancellationToken cancellationToken = default)
Parameters
Type Name Description
TabOrder tabOrder

Name of the tab control

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

SaveTabOrdersAsync(TabOrder[], CancellationToken)

Interface for the Preference Agent Preferences, user interface tab configuration

Declaration
Task SaveTabOrdersAsync(TabOrder[] tabOrders, CancellationToken cancellationToken = default)
Parameters
Type Name Description
TabOrder[] tabOrders
CancellationToken cancellationToken
Returns
Type Description
Task

SetXsrfPathsAsync(string, string[], CancellationToken)

Update the paths that need XSRF cookies

Declaration
Task SetXsrfPathsAsync(string hostname, string[] paths, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string hostname

The hostname that we are storing paths for.

string[] paths

Paths that XSRF cookies should be set for: ['/cs', '/crm']

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

UpdateNetServicesStatusAsync(string, CancellationToken)

Update the NetServices preferences with values contained in the content from the Status URL

Declaration
Task UpdateNetServicesStatusAsync(string xml_or_json, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string xml_or_json

The text that was returned by getting the Status URL

CancellationToken cancellationToken
Returns
Type Description
Task

This method has no return value

© SuperOffice. All rights reserved.
SuperOffice |  Community |  Release Notes |  Privacy |  Site feedback |  Search Docs |  About Docs |  Contribute |  Back to top