Show / Hide Table of Contents

Interface IQuoteConnector

This is the interface SuperOffice will call to integrate against an ERP system in the realm of quotes and orders. You don't have to implement all functions, use the capabilities to tell SuperOffice what the connector can and cannot do.

If an ERP system does not provide products, or if the ERP system is not available , the searches can be delegated to the built-in SuperOffice product registry by using the SuperOffice IProductRegisterCache object that is provided at startup.

Currencies are specified in ISO three letter codes: USD, NOK, SEK, EUR, GBP, etc. See http://www.currency-iso.org/dl_iso_table_a1.xls for details.

The user may click the TEST button in the configuration dialog, which calls the TestConnection method.
Namespace: SuperOffice.CRM
Assembly: SuperOffice.Plugins.dll
Syntax
public interface IQuoteConnector : IDisposable, IPlugin

Properties

CRMConnectionId

The id of this connection in the CRM system

Declaration
int CRMConnectionId { get; set; }
Property Value
Type Description
Int32

Methods

CanProvideCapability(String)

Check if one named capability can be provided (now) Using the PluginResponseInfo gives the connector the possibility to disable a capability, with a reason string that might be shown to the user.

Declaration
bool CanProvideCapability(string capabilityName)
Parameters
Type Name Description
String capabilityName

Name of the capability, see CRMQuoteConnectorCapabilities

Returns
Type Description
Boolean

True if connector has this capability

FindProduct(QuoteAlternativeContextInfo, String, String, String)

The connector should treat this as a freetext search, the user might want to enter several words and expect the system to search for through several fields like name, description, product code, extrafields, etc.

Since the return list is a potentially large return value, the connector or the ERP system should limit the number of matches returned to a few hundred.

The dropdown fast searcher calls this function to populate the dropdown list.
Declaration
ProductInfo[] FindProduct(QuoteAlternativeContextInfo context, string currencyCode, string userinput, string priceListKey)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
String currencyCode
String userinput
String priceListKey

If the pricelist is empty, the function will search in all active pricelists.

Returns
Type Description
ProductInfo[]

An array of products matching the search words

GetActivePriceLists(String)

Used by the admin client. Gets the available active PriceLists in a specific currency.

Declaration
PriceListInfo[] GetActivePriceLists(string isoCurrencyCode)
Parameters
Type Name Description
String isoCurrencyCode

Iso currency like: USD or NOK. Case insensitive.

Returns
Type Description
PriceListInfo[]

Return empty array if there is no PriceList available in the currency. Return all pricelists if isoCurrencyCode is empty.

GetAddresses(QuoteAlternativeContextInfo)

Gets two addresses:

  • the invoice address - [0].

  • the delivery address - [1].

Declaration
AddressInfo[] GetAddresses(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
Returns
Type Description
AddressInfo[]

Returns null if no address was found.

GetAllPriceLists(String)

Used by the admin client. Gets the all PriceLists in the given currency, including those inactive.

Declaration
PriceListInfo[] GetAllPriceLists(string isoCurrencyCode)
Parameters
Type Name Description
String isoCurrencyCode

Iso currency like: USD or NOK. Case insensitive.

Returns
Type Description
PriceListInfo[]

Return empty array if there is no PriceList available. Return all pricelists if isoCurrencyCode is empty.

GetCapabilities()

Return a set of capability name > status pairs that tell the system what capabilities this connector provides. Using the PluginResponseInfo gives the connector the possibility to disable a capability, with a reason string that might be shown to the user.

Declaration
Dictionary<string, bool> GetCapabilities()
Returns
Type Description
Dictionary<String, Boolean>

List of all capabilities

GetConfigurationFields()

This is a request for metadata needed to populate the Quote connection configuration admin dialog that takes in the information needed to create a connection to an ERP system. The values entered in the dialog are stored in the SuperOffice db and used when InitializeConnection(QuoteConnectionInfo, UserInfo, Boolean, Dictionary<String, String>, IProductRegisterCache) is called by the client.

Declaration
Dictionary<string, FieldMetadataInfo> GetConfigurationFields()
Returns
Type Description
Dictionary<String, FieldMetadataInfo>

A list of field descriptions for the GUI to use when populating the config dialog. Make sure that the Rank is set.

GetNumberOfActivePriceLists(String)

Is used to warn the user if there is no active pricelists in a given currency.

Declaration
int GetNumberOfActivePriceLists(string isoCurrencyCode)
Parameters
Type Name Description
String isoCurrencyCode

Iso currency code like: USD or NOK. Case insensitive.

Returns
Type Description
Int32

Return all pricelists if isoCurrencyCode is empty. Return an empty array if there is no PriceList with the stated currency available.

GetNumberOfProductImages(String)

Gets the number of images available for this product

Declaration
int GetNumberOfProductImages(string erpProductKey)
Parameters
Type Name Description
String erpProductKey
Returns
Type Description
Int32

Count of images

GetOrderState(QuoteAlternativeContextInfo)

After the order is created in the ERP system and the user wants to see what the current state of the order is this function gets called.

This new version will be displayed in the GUI.

Requires that the Order-State capability is true.
Declaration
OrderResponseInfo GetOrderState(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
Returns
Type Description
OrderResponseInfo

If nothing has changed it should return null. To create a new QuoteVersion, set OrderResponseInfo.CRMQuoteVersion.QuoteVersionId to 0, and return a new version with a new alternative and quotelines describing the current state.

GetProduct(QuoteAlternativeContextInfo, String)

Gets a product based on erpProductKey

Declaration
ProductInfo GetProduct(QuoteAlternativeContextInfo context, string erpProductKey)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
String erpProductKey
Returns
Type Description
ProductInfo

Returns the product with the specified key.

Exceptions
Type Condition
ArgumentException

If the argument is null or empty , the function will throw an ArgumentException.

Exception

If the product is not found , the function will throw an Exception.

GetProductImage(String, Int32)

Gets the full size picture of the given product.

Declaration
string GetProductImage(string erpProductKey, int rank)
Parameters
Type Name Description
String erpProductKey
Int32 rank

Which of the images to return, will in the first version only ask for the first.

Returns
Type Description
String

Returns the full size picture of the given product. Return NULL if no picture available.

Exceptions
Type Condition
ArgumentException

If the erpProductKey is null or empty , the function will throw an ArgumentException.

Exception

If the product is not found , the function will throw an Exception.

GetProducts(QuoteAlternativeContextInfo, String[])

See GetProduct for details

Declaration
ProductInfo[] GetProducts(QuoteAlternativeContextInfo context, string[] erpProductKeys)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
String[] erpProductKeys
Returns
Type Description
ProductInfo[]

Return products based on an array of unique ERP keys; handy when you’ve found products through archiveproviders or other mechanisms that leave you holding an ERPKey

GetQuoteLinesFromProduct(QuoteAlternativeContextInfo, String)

Given a product ERP Key, return one or more quote lines with the product data filled in, and some default values , typically quantity set to 1 (but not necessarily!) The quoteLineId will be provided by SuperOffice later.

Declaration
QuoteLineInfo[] GetQuoteLinesFromProduct(QuoteAlternativeContextInfo context, string erpProductKey)
Parameters
Type Name Description
QuoteAlternativeContextInfo context
String erpProductKey
Returns
Type Description
QuoteLineInfo[]

Return the QuoteLine(-s) with the product info filled in.

Exceptions
Type Condition
ArgumentException

If the erpProductKey is null or empty , the function will throw an ArgumentException.

Exception

If the product is not found , the function will throw an Exception.

GetQuoteList(String)

Gets a named list from the connector.

There are a few lists in the ERP system that we would like to show to the users: payment terms and types, delivery terms and types, and product classifications (product category, product family and product type). These lists can be supplied by the ERP connector using this interface. SuperOffice will take these values and convert the simple flat list of values into a SuperOffice list that appears in the GUI. If the ERP connector wants to supply a more complex nested list, then the ERP connector can implement a full MDO Provider.

There are some lists in the system we would like the ERP system to provide data for, if it can:

• ProductCategory

• ProductFamily

• ProductType

• PaymentTerms

• PaymentType

• DeliveryTerms

• DeliveryType

If a quote list is NULL, then the GUI will fall back to a text input field, where the user can enter text. This text is passed to the ERP plugin unchanged.

The Quote configuration API may also refer to custom list names which will be filled in by asking here. I.e. you will be asked for more lists than just the ones mentioned here, if you have added custom lists to the configuration dialog.
Declaration
ListItemInfo[] GetQuoteList(string quoteListType)
Parameters
Type Name Description
String quoteListType

The quoteListType parameter is case insensitive.

Returns
Type Description
ListItemInfo[]

Return array of QuoteListItems. Return NULL if the given list is not supported.

GetSearchableFields()

Get metadata about the fields that can be used as search criteria. Note that they do not have to be the same as the fields in the ProductInfo structure; but erpPriceListKey has to be supported.

Declaration
FieldMetadataInfo[] GetSearchableFields()
Returns
Type Description
FieldMetadataInfo[]

Metadata structures

Remarks

There are three levels of searching:
a) Quick search through IProductProvider.FindProduct - this is mandatory for all connectors that provide products
b) Advanced search through IProductSearchProvider - this is optional, and implements are more generic search, but still with a fixed result type (ProductInfo array)
c) Implement an Archive Provider called FindProduct<Your connector name> - this is a fully custom provider that can do whatever it wants, but it has to support a minimal result and restriction column set.

This interface defines alternative b) of the above list.

GetSearchResults(SearchRestrictionInfo[])

Perform the advanced search and return results

Declaration
ProductInfo[] GetSearchResults(SearchRestrictionInfo[] restrictions)
Parameters
Type Name Description
SearchRestrictionInfo[] restrictions

Array of restrictions chosen by the user; see SearchRestrictionInfo for details

Returns
Type Description
ProductInfo[]

Array (possibly empty) of hits, populated as fully as reasonably possible (should follow same policy as

InitializeConnection(QuoteConnectionInfo, UserInfo, Boolean, Dictionary<String, String>, IProductRegisterCache)

Set up the connection to the ERP system. Will be called as part of SuperOffice client startup for each installed connection. Configuration data comes from the configuration dialog shown in the Admin client (GetConfigurationFields())

Declaration
PluginResponseInfo InitializeConnection(QuoteConnectionInfo connectionData, UserInfo user, bool isOnTravel, Dictionary<string, string> connectionConfigFields, IProductRegisterCache productRegister)
Parameters
Type Name Description
QuoteConnectionInfo connectionData

Contains the configuration values defined in the Admin client.

UserInfo user

Information about the logged in user

Boolean isOnTravel

Is the user on Travel?

Dictionary<String, String> connectionConfigFields

{"name" = "value"}. The names are defined by the FieldMetadata. The values are what the user typed into the fields in the configure connection dialog.

IProductRegisterCache productRegister

Product caching object that allows connectors to stash product information in the SuperOffice database for off-line use.

Returns
Type Description
PluginResponseInfo

IsOk set to false if connector can’t provide service (no network); The connector is then ignored until the application restarts.

OnAfterSaveQuote(QuoteAlternativeContextInfo)

Called after a sale containing a quote is saved or created. (Notice that new items have now gotten their ids in the CRM system.)

Declaration
void OnAfterSaveQuote(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The quote and its parts. Contact, Person, Project are read-only. Quote, QuoteRevision, QuoteAlternative parts can be changed before the save.

OnAfterSentQuoteVersion(QuoteVersionContextInfo)

Called after a quote version is sent to the user's customer.

You may do extra work and return the modified the Quote Version info, but you cannot abort the sending process. Any mail or document generation in SuperOffice is independent of the connector.
Declaration
QuoteSentResponseInfo OnAfterSentQuoteVersion(QuoteVersionContextInfo quoteContext)
Parameters
Type Name Description
QuoteVersionContextInfo quoteContext

The Quote Version that was sent to the customer

Returns
Type Description
QuoteSentResponseInfo

URL and/or modified quote version info.

OnBeforeCreateQuote(QuoteAlternativeContextInfo)

Called when a user is creating a quote. The Quote does not exist in database at this time; any changes in the returned QuoteResponseInfo will be saved and the GUI updated.

Declaration
QuoteResponseInfo OnBeforeCreateQuote(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The quote and its parts.

Returns
Type Description
QuoteResponseInfo

An updated quote. If returns IsOk = false, then quote creation is aborted.

OnBeforeCreateQuoteAlternative(QuoteAlternativeContextInfo)

Called when a user is creating a quote alternative. The quote alternative does not exist in database at this time; any changes in the returned Quote alternative will be saved and the GUI updated.

Declaration
QuoteAlternativeResponseInfo OnBeforeCreateQuoteAlternative(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The quote and its parts.

Returns
Type Description
QuoteAlternativeResponseInfo

An updated quote alternative. If returns IsOk = false, then quote alternative creation is aborted.

OnBeforeCreateQuoteVersion(QuoteVersionContextInfo)

Called when a user is creating a new quoteversion. The version does not exist in database at this time; any changes in the returned QuoteVersionResponseInfo will be saved and the GUI updated.

Declaration
QuoteVersionResponseInfo OnBeforeCreateQuoteVersion(QuoteVersionContextInfo context)
Parameters
Type Name Description
QuoteVersionContextInfo context

The quote and its parts.

Returns
Type Description
QuoteVersionResponseInfo

An updated quote version. If returns IsOk = false, then quoteversion creation is aborted.

OnBeforeDeleteQuote(QuoteInfo, ISaleInfo, IContactInfo)

Called before a sale containing a quote is deleted. Clean up in the ERP system, if needed.

The connector cannot stop the quote being deleted in the CRM system.
Declaration
void OnBeforeDeleteQuote(QuoteInfo quote, ISaleInfo sale, IContactInfo contact)
Parameters
Type Name Description
QuoteInfo quote

The Quote being deleted

ISaleInfo sale

The sale the quote belongs to

IContactInfo contact

The main contact on the sale

OnQuoteLineChanged(QuoteAlternativeContextInfo, QuoteLineInfo, String[])

Called when the user has changed a field in the Quote Line. The QuoteContext is readonly; QuoteLine may be changed in the return value. Response time must be fast since this method is called often (every time a field is changed).

Declaration
QuoteLineInfo OnQuoteLineChanged(QuoteAlternativeContextInfo context, QuoteLineInfo ql, string[] changedFields)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The alternative this quoteline belongs to

QuoteLineInfo ql

The changed quoteline

String[] changedFields

List of fields that were changed, in the format: "TableName.FieldName"

Returns
Type Description
QuoteLineInfo

The updated quote line

Remarks

The connect can signal errors or warnings by setting the Status and Reason fields. This information will be displayed in the Quote Line dialog and in the quote-line archive.

PlaceOrder(QuoteAlternativeContextInfo)

Some ERP systems will be able to turn quotes into orders. The user selects a quote alternative to send to the ERP system and clicks OK in the CREATE ORDER dialog. After the Quote has been accepted/sold, then the user can check the delivery status with the ERP system.

Place the order in the ERP system. If the operation retuns successfully, the Quote will be locked (completed) in the CRM system and all updates will come from the ERP system thru the GetOrderState function.

Requires that the Create-Order capability is true. If the Create-Order capability is false, then this function is not called.
Declaration
PlaceOrderResponseInfo PlaceOrder(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The selected Quote Alternative, along with the version and lines

Returns
Type Description
PlaceOrderResponseInfo

The context, with any updates. The ERPOrderKey should be filled in with the id of the generated order. If the returned state in not OK, then the PlaceOrder call is aborted and the error message displayed.

RecalculateQuoteAlternative(QuoteAlternativeContextInfo)

The user is finished with entering the quotelines, and wants to calculate the order discount (alternative discount) on this alternative. This method is called whenever the quote lines are changed in the alternative, or when the user clicks the RECALCULATE button.

Declaration
QuoteAlternativeWithLinesInfo RecalculateQuoteAlternative(QuoteAlternativeContextInfo context)
Parameters
Type Name Description
QuoteAlternativeContextInfo context

The context as it appears to the user

Returns
Type Description
QuoteAlternativeWithLinesInfo

The updated alternative

Remarks

The connector may signal problems with the quote by setting the Status to Error, Warning or OkWithInfo, and fill in the alternative's Reason field with an explanation.

Use CalculateQuoteAlternativeWithLines(QuoteAlternativeWithLinesInfo) to help you calculate amounts.

TestConnection(Dictionary<String, String>)

Check that the ERP connection is good. Return some status info that the Admin client can show to the user.

Testing if the connection data is sufficient to get a connection with the ERP system. The Connector should try to do some operations to check if the connection has sufficient rights to run. The connection has not been created yet.
Declaration
PluginResponseInfo TestConnection(Dictionary<string, string> connectionData)
Parameters
Type Name Description
Dictionary<String, String> connectionData

{"name" = "value"}. The names are defined by the FieldMetadata. The values are what the user typed into the fields in the configure connection dialog.

Returns
Type Description
PluginResponseInfo

Ok or not + a status or error message. This message is shown in a result dialog.

UpdateQuoteVersionPrices(QuoteVersionContextInfo, HashSet<String>)

Fetch new prices from the pricelist for all the alternatives in the quote. This method is explicitly triggered by the user clicking the UPDATE PRICES button in the quote dialog.

The connector should update all the quotelines on all the alternatives with new list prices, minimum prices, cost prices, etc from the pricelist, and update the ERP discount suggestions.
Declaration
QuoteVersionResponseInfo UpdateQuoteVersionPrices(QuoteVersionContextInfo context, HashSet<string> writeableFields)
Parameters
Type Name Description
QuoteVersionContextInfo context

The quote version, with alternatives and quote lines

HashSet<String> writeableFields

Collection of quoteline fieldnames that are writeable according to the QuotelineConfiguration table. Fieldnames are all lowercase.

Returns
Type Description
QuoteVersionResponseInfo

Updated quote version, with alternatives and quote lines.

Remarks

The system will call ValidateQuoteVersion(QuoteVersionContextInfo, QuoteAction) after calling this method to determine the new version state.

ValidateQuoteVersion(QuoteVersionContextInfo, QuoteAction)

Validates the version, looks for problems. Will typically change the Status and Reason fields, possibly change the State to NeedsApproval. Should validate all the alternatives and their quote-lines. The user is finished with entering the quote-lines, and wants to prepare the sending of the quote. This method gives the ERP system a chance to enforce its business rules.

This method is called whenever the user clicks the SEND button, the PLACE ORDER or closes the quote dialog. Quote Lines, Alternatives, Version and Quote fields can be changed in the return value. Use CalculateVersionWithAlternatives(QuoteVersionContextInfo) to help you calculate amounts.
Declaration
QuoteResponseInfo ValidateQuoteVersion(QuoteVersionContextInfo context, QuoteAction action)
Parameters
Type Name Description
QuoteVersionContextInfo context

The context as it appears to the user

QuoteAction action

The action that started this call; the context it is called in, like place order or send quote

Returns
Type Description
QuoteResponseInfo

The updated Context, with changes to State and UserExplanation if needed.

Remarks

Validation should not change the prices on quotelines - it should ensure conformance to business rules.

A draft quote version will have state = QuoteVersionStateInfo.DraftNotCalculated when called. The connector should set the version state to if the calculations were successful. Leave the state as DraftNotCalculated if the ERP system was not available or some other factor that made the calculation unsuccessful.

The connector can trigger the approval workflow by setting the state to QuoteVersionStateInfo.DraftNeedsApproval. When a user with the approval permission has approved or rejected the quote, the quote version state will be QuoteVersionStateInfo.DraftApproved or QuoteVersionStateInfo.DraftNotApproved.

Note that recalculate may also be called when the quote is Approved, or Archived. In these cases, please leave the quote version state alone.

The connector may signal problems with the quote by setting the Status to Error, Warning or OkWithInfo, and fill in the version's Reason field with an explanation.

The QuoteConnectorBase implementation of this method defines methods for validating ValidateQuoteLine(QuoteAlternativeContextInfo, QuoteLineInfo, Boolean)

Extension Methods

EnumUtil.MapEnums<From, To>(From)
Converters.MapEnums<From, To>(From)
© SuperOffice. All rights reserved.
SuperOffice |  Community |  Release Notes |  Privacy |  Site feedback |  Search Docs |  About Docs |  Contribute |  Back to top