Full-Access API

SplendidCRM Full-Access API

Introduction

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.

API Design

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.


API Reference

Version

Returns the version of the SplendidCRM web application.

Syntax

public string Version

(

)

Parameters

None.

Return Value

Type: System.String

Remarks

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.


Edition

Returns the edition of the SplendidCRM web application.

Syntax

public string Edition

(

)

Parameters

None.

Return Value

Type: System.String

Remarks

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.


UtcTime

Returns the server time adjusted to UTC.

Syntax

public DateTime UtcTime

(

)

Parameters

None.

Return Value

Type: System.DateTime

Remarks

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.


IsAuthenticated

Returns the current authentication state.

Syntax

public bool IsAuthenticated

(

)

Parameters

Return Value

Type: System.Boolean

Remarks

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.


Login

Performs user authentication and session initialization.

Syntax

public Guid Login

( string UserName

, string Password

, string Version

)

Parameters

UserName

Type: System.String

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.

Return Value

Type: System.Guid

Remarks

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.


GetSystemTable

Gets system table data based on the last modification date.

Syntax

public DataTable GetSystemTable

( string   TableName

, DateTime DateModified

, string   RequestedModules

)

Parameters

TableName

Type: System.String

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.

Return Value

Type: System.Data.DataTable

Remarks

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.


GetModuleTable

Gets module table data based on the last modification date.  The results can also be limited by count or by specific records.

Syntax

public DataTable GetModuleTable

( string   TableName

, DateTime DateModified

, int      MaxRecords

, Guid[]   Items

)

Parameters

TableName

Type: System.String

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.  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. 

Return Value

Type: System.Data.DataTable

Remarks

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.


UpdateModuleTable

Updates module table data.  This method can also be used to insert data.

Syntax

public DataTable UpdateModuleTable

( string    TableName

, DataTable Table

)

Parameters

TableName

Type: System.String

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.

Return Value

Type: System.Data.DataTable

Remarks

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.


Additional Information

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

 

Errors and Omissions

If you discover any errors or omissions in this document, please email support@splendidcrm.com.