CRUD SugarCRM

connectx.crud.sugarcrm

SugarCRM

Bases: Rest

Connector class for SugarCRM REST API.

Provides CRUD operations, ETL logging, batch processing, and integration utilities for SugarCRM modules. Supports concurrent reads/writes, record linking, and ETL job tracking with detailed logging.

__init__

Initialize a SugarCRM connector instance and authenticate.

Parameters:

Name	Type	Description	Default
url	str	Base URL of the SugarCRM instance	required
username	str	Username for authentication (required for password grant)	None
password	str	Password for authentication (required for password grant)	None
api_version	str	SugarCRM REST API version (default 'v11')	'v11'
platform	str	Platform type (default 'base')	'base'
client_id	str	Client ID for authentication (default 'sugar')	'sugar'
grant_type	str	OAuth2 grant type (default 'password')	'password'
client_secret	str	Optional client secret for OAuth2	None
n_rows_read	int	Default number of rows to read per API request	1000
n_rows_write	int	Default number of rows to write per API request	100
n_concurrent	int	Number of concurrent requests for batch operations	4
die_on_error	bool	If True, raise exceptions when operations fail	True
timeout		HTTP request timeout in seconds	120
verify		SSL verification setting for requests	None
cert		Optional client certificate	None

Returns:

Type	Description
	Instance of SugarCRM with an active connection

Raises:

Type	Description
Exception	If authentication fails

clean_sugarcrm_response

Clean a SugarCRM API response to prevent errors when converting to a Polars DataFrame.

Removes problematic fields such as '_acl' in user link objects which may be inconsistently present across records.

Parameters:

Name	Type	Description	Default
response		Dictionary returned by a SugarCRM read web service	required

Returns:

Type	Description
	Cleaned dictionary with '_acl' fields removed from user link subobjects

connect

Authenticate with SugarCRM using username/password or client credentials and obtain an access token.

Returns:

Type	Description
	Self instance with an active access token

Raises:

Type	Description
Exception	If authentication fails or the API response is invalid

count

Count the number of records in a SugarCRM module matching optional filters.

Parameters:

Name	Type	Description	Default
module	str	SugarCRM module name or API endpoint	required
filter	list	Optional list of filter conditions	None
deleted	bool	Show deleted records in the result set (default False)	False

Returns:

Type	Description
int | None	Number of records matching the filter, or None if request fails

create

Create a new record in the specified SugarCRM module.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module (sObject)	required
data	dict	Dictionary of field values for the new record	required

Returns:

Type	Description
dict | None	Created record as a dictionary, or None if the operation failed

delete

Delete a record from the specified module by ID.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
id	str	ID of the record to delete	required

Returns:

Type	Description
dict | None	Response dictionary with deletion status, or None if operation failed

download

Download a file from a specific record in a module.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
id	str	ID of the record to download the file from	required
field	str	Name of the file field to download (default "filename")	'filename'

Returns:

Type	Description
	File content returned by SugarCRM

headers

Return the HTTP headers required for SugarCRM API requests, including the Authorization token.

Returns:

Type	Description
dict	Dictionary containing Authorization header

integrate

Integrate a record in the specified module using a sync key. If the record exists, it is updated; otherwise, it is created.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
data	dict	Dictionary of field values to integrate	required
sync_key	str	Field used as unique identifier for integration (default "sync_key")	'sync_key'

Returns:

Type	Description
dict | None	The integrated record as a dictionary, or None if operation failed

job_end

Complete the current ETL job in SugarCRM.

Marks incomplete step logs as 'interrotta' (aborted) if necessary. If all steps are completed, updates the job's 'data_ultimo_aggiornamento_c' to the earliest start date among the steps. Resets internal job and log tracking attributes.

Returns:

Type	Description
	None

job_save

Save or update an ETL job in SugarCRM.

Creates a new job if id is None, otherwise updates the existing job. Handles setting the last completion date and other job metadata.

Parameters:

Name	Type	Description	Default
id	str	Optional ID of the job to update; creates a new job if None	None
name	str	Name of the ETL job (required if creating a new job)	None
last_start_date	str	Optional last completed date for the job	None

Returns:

Type	Description
	Dictionary representing the saved job with additional computed fields

job_start

Start an ETL job in SugarCRM.

Initializes the job, creates logs for each step, and ensures that incomplete logs from previous runs are marked as aborted.

Parameters:

Name	Type	Description	Default
name	str	Name of the ETL job	required
steps	list	List of module names representing steps of the ETL job	None
data	dict	Optional dictionary of additional job fields	None
enum	bool	Boolean flag to indicate whether to track enumerations	True

Returns:

Type	Description
	Dictionary representing the ETL job record

Raises:

Type	Description
JobNotEnabled	If the ETL job is disabled in SugarCRM

link

Create relationships between two SugarCRM objects in bulk.

Parameters:

Name	Type	Description	Default
from_object_type	str	Source module name	required
to_object_type	str	Target module name	required
data	DataFrame	Polars DataFrame containing associations to create	required
from_key	str	Column name in data representing the source record ID	'id'
to_key	str	Column name in data representing the target record ID	'id_right'
type	str	Relationship type (module-specific)	None
n_rows_write	int	Maximum number of rows per batch request	None
n_concurrent	int	Maximum number of concurrent batch requests	None
die_on_error	bool	Raise exception if any association fails	None
callback	callable	Optional callable for progress reporting	None

Returns:

Type	Description
DataFrame	Polars DataFrame with 'success' and 'message' columns for each row

Raises:

Type	Description
Exception	If any association fails and die_on_error is True

load

Perform bulk operations on a SugarCRM module.

Supports CREATE, UPDATE, DELETE, RETRIEVE, and INTEGRATE actions with optional batching, concurrency, and data transformation.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
data	DataFrame	Polars DataFrame containing records to process	required
action	int	Action to perform (CREATE, UPDATE, DELETE, RETRIEVE, INTEGRATE)	required
sync_key	str	Field used as unique identifier for INTEGRATE action (default "sync_key")	'sync_key'
transform		Optional callable to transform each row before processing	None
picklist	dict	Optional dictionary mapping picklist values	None
n_rows_write	int	Maximum number of rows per batch request	None
n_concurrent	int	Maximum number of concurrent batch requests	None
die_on_error	bool	Raise exception if any record fails	None
callback	callable	Optional callable for progress reporting	None

Returns:

Type	Description
DataFrame	Polars DataFrame with original data plus 'success', 'message', and record ID columns

Raises:

Type	Description
Exception	If records fail during processing and die_on_error is True

log_create

Create a new ETL step log in SugarCRM.

Parameters:

Name	Type	Description	Default
name	str	Name of the ETL step	required
data	dict	Optional dictionary of fields to include in the log	None

Returns:

Type	Description
	Dictionary representing the created log record

log_start

Start a specific ETL step log.

If the ETL job has not been started, it will start it automatically. Updates the step log's start timestamp and sets its status to 'in_corso' (in progress).

Parameters:

Name	Type	Description	Default
name	str	Name of the ETL step	required
data	dict	Optional dictionary of additional log fields	None

Returns:

Type	Description
	Dictionary representing the ETL job record

log_update

Update the current ETL step log in SugarCRM.

Updates fields of the step log, optionally marking it as completed or errored. Handles file attachments and row-level error records. Automatically ends the job if this step is the main job log and a success flag is provided.

Parameters:

Name	Type	Description	Default
data	dict	Optional dictionary of fields to update in the log	None
success	bool	Optional boolean to mark the log as completed (True) or errored (False)	None
files	list	Optional list of file paths or objects to attach to the log	None
rows	list	Optional list of polars DataFrames containing row-level errors	None

Returns:

Type	Description
	Updated log record dictionary

ping

Check if the SugarCRM instance is reachable and the access token is valid.

Returns:

Type	Description
bool	True if the instance responds correctly, False otherwise

query_condition

Save or update an ETL log entry in SugarCRM.

Handles creation or update of a log, including its status, processed record counts, attached files, and row-level error details.

Parameters:

Name	Type	Description	Default
id		Optional ID of the log to update; creates a new log if None	required
name		Name of the log entry	required
job_id		ID of the ETL job this log belongs to	required
log_id		Optional ID of a parent log for hierarchical logging	required
status		Status of the log ('queued', 'progress', 'success', 'error', 'abort')	required
num_records		Total number of records to process	required
processed_records		Number of records already processed	required
success_records		Number of successfully processed records	required
fail_records		Number of failed records	required
description		Optional textual description or note	required
start_date		Start datetime of the log	required
end_date		End datetime of the log	required
files		Optional list of file paths or objects to attach to the log	required
rows		Optional list of polars DataFrames representing row-level errors	required

Returns:

Type	Description
list	Dictionary representing the saved or updated log entry

read

Read records from a SugarCRM module with optional filtering, field selection, ordering, and batching.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
filter	list	Optional list of filter conditions	None
fields	list	Optional list of fields to return	None
order_by	str	Field to order results by (default "id")	'id'
limit	int	Maximum number of records to retrieve	None
deleted	bool	Show deleted records in the result set (default False)	False
n_rows_read	int	Number of rows to fetch per batch	None
n_concurrent	int	Number of concurrent requests	None
callback	callable	Optional callable for progress reporting	None

Returns:

Type	Description
DataFrame	Polars DataFrame containing the retrieved records

request

Send an HTTP request to the SugarCRM REST API and handle the response.

Parameters:

Name	Type	Description	Default
method	str	HTTP method (GET, POST, PUT, DELETE, etc.)	required
path	str	API endpoint path relative to the base URL	required
headers	dict	Optional dictionary of HTTP headers	None
kwargs		Additional arguments to pass to the request (e.g., params, json, data)	{}

Returns:

Type	Description
	Parsed JSON response as a dictionary, raw content if JSON parsing fails, or response object

Raises:

Type	Description
requests.HTTPError	If the HTTP response contains an error status code

retrieve

Retrieve a record from the specified module by its ID.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
id	str	ID of the record to retrieve	required

Returns:

Type	Description
dict | None	Record data as a dictionary, or None if not found

update

Update an existing record in the specified module.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
data	dict	Dictionary of field values to update	required
id	str	Optional record ID. If not provided, it is retrieved from data using the primary key	None

Returns:

Type	Description
dict | None	Updated record as a dictionary, or None if operation failed

upload

Upload files or data to a specific record in a module.

Parameters:

Name	Type	Description	Default
module	str	Name of the SugarCRM module	required
data	dict	Dictionary of fields and corresponding content. Values can be DataFrame, file path, bytes, or BufferedReader	required
id	str	ID of the record to attach files to	required

Returns:

Type	Description
dict | None	Response from SugarCRM API as a dictionary, or None if upload failed