Interface IContactAgent

Interface for the Contact Agent Contact (company) data services.

Namespace: SuperOffice.CRM.Services

Assembly: SuperOffice.Services.dll

Syntax

[Agent("Contact Agent", "Interface for the Contact Agent. Contact (company) data services.")]
public interface IContactAgent : IAgent

Examples

using SuperOffice;
using SuperOffice.CRM.Services;

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

Methods

AddPersonAsync(int, PersonEntity, CancellationToken)

Add a person to the given contact

Declaration

Task<PersonEntity> AddPersonAsync(int contactId, PersonEntity newPersonEntity, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	Contact to add person to
PersonEntity	newPersonEntity	Person object to add
CancellationToken	cancellationToken

Returns

Type	Description
Task<PersonEntity>	Updated person object

ChangeCountryAsync(ContactEntity, int, CancellationToken)

Change country regenerates the default values and localized information such as phone number and address format

Declaration

Task<ContactEntity> ChangeCountryAsync(ContactEntity contactEntity, int toCountryId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContactEntity	contactEntity
int	toCountryId	The country to switch to
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>

CopyAsync(int, string, string, bool, CancellationToken)

Copy a contact. Activities and related data will be ignored

Declaration

Task<int> CopyAsync(int sourceContactId, string destinationContactName, string destinationContactDepartment, bool copyPersons, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	sourceContactId	The id of the contact to copy
string	destinationContactName	The name of the destination contact
string	destinationContactDepartment	The department of the destination contact
bool	copyPersons	If true, persons will be copied from source contact
CancellationToken	cancellationToken

Returns

Type	Description
Task<int>	Id of copied contact

CreateDefaultContactEntityAsync(CancellationToken)

Loading default values into a new ContactEntity.

Declaration

Task<ContactEntity> CreateDefaultContactEntityAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	New ContactEntity with default values

CreateDefaultPreviewContactAsync(CancellationToken)

Loading default values into a new PreviewContact.

Declaration

Task<PreviewContact> CreateDefaultPreviewContactAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<PreviewContact>	New PreviewContact with default values

CreateNewEntryAsync(DuplicateEntry, CancellationToken)

Creates a new contact based on external duplicate

Declaration

Task<int> CreateNewEntryAsync(DuplicateEntry duplicate, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
DuplicateEntry	duplicate	The duplicate to create a new entry based upon
CancellationToken	cancellationToken

Returns

Type	Description
Task<int>	The database identity of the newly created entry

DeleteContactEntityAsync(int, CancellationToken)

Deletes the ContactEntity. This table supports Soft Delete; records will be marked as deleted and disappear from the GUI and API results, but will not be physically deleted by this (and any other) method.

Declaration

Task DeleteContactEntityAsync(int contactEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactEntityId	The identity of the ContactEntity
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

DeleteExpiredAsync(CancellationToken)

Trigger deletion of contacts (companies) that has been (soft) deleted and have timed out the expiry period (the SoftDeleteRetention preference).

Declaration

Task DeleteExpiredAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

EnrichContactEntityAsync(ContactEntity, string, CancellationToken)

Enrich a contact with data from the AI Enrichment service. This will update the contact with address, phone number, and email.

Declaration

Task<ContactEntity> EnrichContactEntityAsync(ContactEntity contactEntity, string enrichId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContactEntity	contactEntity	The contact entity to enrich.
string	enrichId	Id from the EnrichContact provider
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	Enriched contact entity with address, phone number, and email updated.

GetAddressAsync(int, CancellationToken)

Gets the contact's localized address.

Declaration

Task<Address> GetAddressAsync(int contactId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	The contact id
CancellationToken	cancellationToken

Returns

Type	Description
Task<Address>	The address as LocalizedField[][].

GetAddressByCountryAsync(int, int, CancellationToken)

Gets the contact's localized address.

Declaration

Task<Address> GetAddressByCountryAsync(int contactId, int countryId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	The contact id
int	countryId
CancellationToken	cancellationToken

Returns

Type	Description
Task<Address>	The address as LocalizedField[][].

GetContactAsync(int, CancellationToken)

Gets a Contact object.

Declaration

Task<Contact> GetContactAsync(int contactId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	The identifier of the Contact object
CancellationToken	cancellationToken

Returns

Type	Description
Task<Contact>	A single Contact

GetContactEntityAsync(int, CancellationToken)

Gets a ContactEntity object.

Declaration

Task<ContactEntity> GetContactEntityAsync(int contactEntityId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactEntityId	The identifier of the ContactEntity object
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	A single ContactEntity

GetContactListAsync(int[], CancellationToken)

Gets an array of Contact objects.

Declaration

Task<Contact[]> GetContactListAsync(int[] contactIds, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int[]	contactIds	The identifiers of the Contact object
CancellationToken	cancellationToken

Returns

Type	Description
Task<Contact[]>	Array of Contact

GetContactSummaryAsync(int, int, CancellationToken)

Get summary of contact and its recent activity.

Declaration

Task<ContactSummary> GetContactSummaryAsync(int contactId, int limit, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	The contact id to summarize.
int	limit	Max number of items to include in summary lists.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactSummary>	Summary of contact, with recent requests, sales, follow-ups, chats.

GetContactWithPersonsAsync(int, CancellationToken)

Returns the contact with all the contact persons belonging to the contact

Declaration

Task<ContactEntity> GetContactWithPersonsAsync(int contactId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	The id of the contact.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	ContactEntity with all data and persons.

GetDomainDuplicatesAsync(string, CancellationToken)

Get duplicates based on the domain

Declaration

Task<DuplicateEntry[]> GetDomainDuplicatesAsync(string domain, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	domain	Domain used for lookup
CancellationToken	cancellationToken

Returns

Type	Description
Task<DuplicateEntry[]>	Any records matching the specified domain

GetDuplicateRulesAsync(CancellationToken)

Retrieve all available duplicate rules for contact

Declaration

Task<DuplicateRule[]> GetDuplicateRulesAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<DuplicateRule[]>	All available duplicate rules

GetDuplicatesAsync(string, CancellationToken)

Get duplicates (exact or similar in the database) based on the name

Declaration

Task<DuplicateEntry[]> GetDuplicatesAsync(string name, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	Name used for lookup
CancellationToken	cancellationToken

Returns

Type	Description
Task<DuplicateEntry[]>	Any records matching the specified name

GetMyActiveContactsAsync(DateTime, int[], ContactAction, CancellationToken)

Returns the contacts where there has been activity since activityStartTime. If activityStartTime is larger than the current date, all contacts with activity since last log-out are returned. The result set can be filtered by category and action type.

Declaration

Task<ContactActivity[]> GetMyActiveContactsAsync(DateTime activityStartTime, int[] contactCategories, ContactAction actionType, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
DateTime	activityStartTime	The start time of the activities. If the start time is set to a future date; activites since the user last logged out are returned.
int[]	contactCategories	Integer array of categories to filter on. If the array is empty contacts from all categories will be selected.
ContactAction	actionType	The type of action that has occured. E.g. updates, deletes, new appointments, etc.
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactActivity[]>	Array of contacts where there have been activity in the period.

GetMyBizCardAsync(CancellationToken)

Returns all data needed to display the logged on person's business card. That is company, person, and company interest data.

Declaration

Task<ContactEntity> GetMyBizCardAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	The contact object with persons and interests

GetMyContactAsync(CancellationToken)

Gets the contact belonging to the currently logged on user.

Declaration

Task<ContactEntity> GetMyContactAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	The Contact

GetMyContactsAsync(CancellationToken)

Getting the contacts where the user currently logged in is set as contact owner.

Declaration

Task<Contact[]> GetMyContactsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task<Contact[]>	Array of contacts

GetMyRecentContactsAsync(ContactSourceType, CancellationToken)

Method that returns a set of initial contacts. This could be the contacts in a favorites selection, the history list, the diary, or from all sources. If retrieved from the diary it will get appointments for the current and the next day.

Declaration

Task<Contact[]> GetMyRecentContactsAsync(ContactSourceType sourceType, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContactSourceType	sourceType	The source where the contacts are retrieved from (Favorites, History, Diary)
CancellationToken	cancellationToken

Returns

Type	Description
Task<Contact[]>	Arrayof contacts

GetNameDepartmentDuplicatesAsync(string, string, CancellationToken)

Get duplicates based on the contact name and department

Declaration

Task<DuplicateEntry[]> GetNameDepartmentDuplicatesAsync(string name, string department, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	name	Name used for lookup
string	department	Department used for lookup (if any)
CancellationToken	cancellationToken

Returns

Type	Description
Task<DuplicateEntry[]>	Any records matching the specified name and department

GetPersonsAsync(int, CancellationToken)

Returns an array of all the contact persons for the company card.

Declaration

Task<Person[]> GetPersonsAsync(int contactId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId
CancellationToken	cancellationToken

Returns

Type	Description
Task<Person[]>	Array of Persons

GetPreviewContactAsync(int, CancellationToken)

Get a contact from its ID

Declaration

Task<PreviewContact> GetPreviewContactAsync(int contactId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	Contact ID
CancellationToken	cancellationToken

Returns

Type	Description
Task<PreviewContact>	Minimal contact suitable for preview

GetPreviewEnrichContactAsync(string, CancellationToken)

Get a contact from its ID

Declaration

Task<PreviewContact> GetPreviewEnrichContactAsync(string enrichId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	enrichId	Enrich Contact ID from the EnrichContact MDO list provider
CancellationToken	cancellationToken

Returns

Type	Description
Task<PreviewContact>	Minimal contact suitable for preview

GetQuoteVersionAddressesAsync(int, CancellationToken)

Get the associated billing and invoice quote version addresses. These addresses might be address on the contact, or a custom address.

Declaration

Task<Address[]> GetQuoteVersionAddressesAsync(int quoteVersionId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	quoteVersionId	The version to get the addresses for.
CancellationToken	cancellationToken

Returns

Type	Description
Task<Address[]>	The quote version addresses. Invoice and billing address, in that order.

IsNumberValidAsync(int, string, CancellationToken)

Checks if the number is unique or required. The setting is configured from admin under system options.

Declaration

Task<bool> IsNumberValidAsync(int contactId, string number, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	contactId	Primary key
string	number	Number field value to check.
CancellationToken	cancellationToken

Returns

Type	Description
Task<bool>	True if the number satisifies the configured rules for uniqueness.

MergeAsync(int, int, bool, bool, CancellationToken)

Merge two contacts. The destination contact will remain.

Declaration

Task MergeAsync(int sourceContactId, int destinationContactId, bool mergeIdenticalPersons, bool replaceEmptyFieldsOnDestination, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	sourceContactId	Source contact to merge from. This contact will disappear after the merge.
int	destinationContactId	Destination contact to merge into
bool	mergeIdenticalPersons	Persons with identical names will be merged
bool	replaceEmptyFieldsOnDestination	If true, empty fields on destination will be replaced by values from source.
CancellationToken	cancellationToken

Returns

Type	Description
Task

SaveContactEntityAsync(ContactEntity, CancellationToken)

Updates the existing ContactEntity or creates a new ContactEntity if the id parameter is 0.

Declaration

Task<ContactEntity> SaveContactEntityAsync(ContactEntity contactEntity, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContactEntity	contactEntity	The ContactEntity that is saved
CancellationToken	cancellationToken

Returns

Type	Description
Task<ContactEntity>	New or updated ContactEntity

SaveQuoteVersionAddressAsync(int, Address, AddressType, int, CancellationToken)

Save a custom quote version address.

Declaration

Task<Address> SaveQuoteVersionAddressAsync(int quoteVersionId, Address address, AddressType addressType, int countryId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	quoteVersionId	The version to save the address on.
Address	address	The address to save on the quote version.
AddressType	addressType	Should be either QuoteBillingAddress or QuoteShippingAddress
int	countryId	The country for the custom address
CancellationToken	cancellationToken

Returns

Type	Description
Task<Address>	The saved addresses.

SetDuplicateRulesStatusAsync(DuplicateRule[], CancellationToken)

Set which duplicate rules should be active or not

Declaration

Task SetDuplicateRulesStatusAsync(DuplicateRule[] rules, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
DuplicateRule[]	rules	Duplicate rules to update active status for
CancellationToken	cancellationToken

Returns

Type	Description
Task

UndeleteAsync(int, CancellationToken)

This entity supports Soft Delete. Call this method to Undelete a previously soft-deleted record

Declaration

Task UndeleteAsync(int id, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
int	id	The primary key of the entity to undelete
CancellationToken	cancellationToken

Returns

Type	Description
Task	This method has no return value

ValidateContactEntityAsync(ContactEntity, CancellationToken)

Check that entity is ready for saving, return error messages by field.

Declaration

Task<StringDictionary> ValidateContactEntityAsync(ContactEntity contactEntity, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
ContactEntity	contactEntity	Entity to be checked for errors.
CancellationToken	cancellationToken

Returns

Type	Description
Task<StringDictionary>	Error messages tagged by field.