SplendidCRM Full-Access API
SplendidCRM has had a SOAP API for many years. The original SOAP API was patterned after a similar SugarCRM API so that the SplendidCRM Plug-in for Outlook could work with both SplendidCRM and SugarCRM web applications.
As we developed the SplendidCRM Offline Client, we concluded that the original SOAP API was insufficient. It could not be easily extended to satisfy the synchronization needs of the Offline Client. Beyond basic access to module data, the Offline Client needed access to all tables, including those used for UI generation and system configuration. In short, the Offline Client needed direct access to the database tables while preserving the SplendidCRM security model.
The target audience for the Full-Access API is a Microsoft .NET developer. By specifically supporting .NET developers and by not attempting to support Java, PHP or any other development platform, we are able to dramatically simplify the API. Instead of attempting to create a platform-agnostic system, we are able to return popular and well-known .NET structures.
The design of the Offline Client is very similar to that of the Microsoft Sync Framework. SplendidCRM does not use the Microsoft Sync Framework because of the need for a more granular security model.
The SplendidCRM Full-Access API is a very thin layer on top of the database tables. At the heart of the API is the .NET DataTable structure. The advantage to using the DataTable directly is that it already is in the desired data-manipulation format. In addition to the data, the DataTable also contains schema information and can be fully serialized.
The Full-Access API consists of just eight methods. Three methods are informational, two are for authentication and the remaining three are for getting and updating data. Only three methods are used to manage data because SplendidCRM is data driven and the DataTable contains all the information necessary to manage the synchronization of a table.
The Full-Access API relies upon the existing session management of the SplendidCRM web application. It is for this reason that it is critical that you verify that the session is authenticated before performing the module data operations.
Returns the version of the SplendidCRM web application.
public string Version
(
)
None.
Type: System.String
The version, along with the edition, can be used to determine the features that are available. The string that is returned will match the SplendidCRM version number as displayed on the About page of the web application. The return value will look like 4.0.3632.12494.
Returns the edition of the SplendidCRM web application.
public string Edition
The version, along with the edition, can be used to determine the features that are available. The string that is returned will match the SplendidCRM edition as displayed on the About page of the web application. The return value will be one of the following: Enterprise, Professional or Community.
Returns the server time adjusted to UTC.
public DateTime UtcTime
Type: System.DateTime
The Offline Client is not expected to have a system clock that is perfectly synchronized with that of the web application server. The Offline Client will use the server UTC value to compute an offset that will be applied to all incoming and outgoing dates. While this technique is not perfect, it should allow the dates between client and server to be synchronized within a second or two.
Returns the current authentication state.
public bool IsAuthenticated
Type: System.Boolean
This method is typically called before any other operation that requires a valid and authenticated session. The Offline Client will use this information to determine if the user needs to be authenticated prior to performing a sync operation.
Performs user authentication and session initialization.
public Guid Login
( string UserName
, string Password
, string Version
UserName
Password
Type: System.String The password is in plain text, so it is advisable that a secure channel is used when connecting to the server.
Version
Type: System.String The Version is not used at this time, but is intended to be used to restrict functionality based on the version of the client.
Type: System.Guid
This function is very similar to the web application login in the way that it authenticates a user and initializes the session. If successful, this function will return the User ID.
This method will throw a SOAP exception if the login fails.
Gets system table data based on the last modification date.
public DataTable GetSystemTable
( string TableName
, DateTime DateModified
, string RequestedModules
TableName
DateModified
Type: System.DateTime The date field is used to reduce the amount of data returned, based on the oldest record available. When performing a full synchronization, this field should be set to DateTime.MinValue.
RequestedModules
Type: System.String The modules field is used to reduce the amount of data based on the modules that are available to the currently authenticated user due to the module sync flag or the access rights assigned to the current user. This list is a comma-separated list of module names.
Type: System.Data.DataTable
This method returns a DataTable with schema information, sorted by last modification date. The schema information is important because it is used by the Offline Client to determine if any custom fields were added to the table.
This method applies the expected access control filters for the currently authenticated user, but it does not use the base module view. When selecting data out of the database, this method will return all fields in the table, as well as all fields in the associated custom field table.
This method will not throw a SOAP exception if access is denied. Instead, it will simply return null.
Gets module table data based on the last modification date. The results can also be limited by count or by specific records.
public DataTable GetModuleTable
, int MaxRecords
, Guid[] Items
Type: System.DateTime The date field is used to reduce the amount of data returned, based on the oldest record available. When performing a full synchronization, this field should be set to DateTime.MinValue. The date field is typically not used when retrieving specific records.
MaxRecords
Type: System.Int32 The max records field is typically used when performing a full synchronization against a database with a large volume of data. This field is only used if greater than zero.
Items
Type: System.Guid[] The items field is used to retrieve specific records.
Updates module table data. This method can also be used to insert data.
public DataTable UpdateModuleTable
, DataTable Table
Table
Type: System.Data.DataTable The table should include all fields in the table, including all auditing fields such as DELETED, DATE_CREATED and CREATED_BY.
This method does not use the module-specific stored procedures to insert or update data. Access rights are still applied.
This method will throw a SOAP exception if the user does not have edit access to the implied module. Other errors are returned in the updated data table in the fields SPLENDID_SYNC_STATUS and SPLENDID_SYNC_MESSAGE.
The SplendidCRM Application Platform is constantly being improved. Please visit the SplendidCRM Software website to obtain the most recent version of the software:
http://www.splendidcrm.com
If you have any questions, please post them to the SplendidCRM Support forum:
http://www.splendidcrm.com/Forums/tabid/66/Default.aspx
If you discover any errors or omissions in this document, please email support@splendidcrm.com.