Manipulating Relationships

##Relationships

Sugarcrm connects entries together through predefined relationships between modules. The web services API provides functions to create and retrieve these links. The get_module_fields() function returns a list of fields in the module and a list of links to other modules. From these link_names we can retrieve all entries related somehow to the object in question.

##set_relationship()
In order to set a relationship between two Sugar Beans you must use the set function. This is a one to many type of relationship from one base bean to many others linked through one type of relationship, more on this later. The call can be found [here] (https://github.com/jmertic/KSU_Capstone_Spring_2011_Python/blob/master/sugarcrm/sugarcrm.py#L225-228) and looks like this.

[self.id, module_name, module_id, link_field_name, related_ids]

Self.id is the session id returned when you logged in, this is necessary as it is with all other API calls. Module_name is the name of the module that contains the bean that you are trying to set relationships for, or the base bean. Module_id is the id of that base bean. The link field name is the name of the link field that is being set.

Each module has a number of link fields that can be set to link beans or in other words establish relationships between beans. Most of these are common between all modules but some are unique to specific modules. For example all modules have a ‘created_by_link’ that is meant to connect a bean to the creator of that bean. By contrast the Documents module has a link fields named ‘revisions’ that is unique to documents. In this case, since we are only setting a single relationship for this bean, link_filed-name is a string corresponding to the link field you wish to set.

Since this is a one to many relationship you must provide an array of beans that will be set as linked to the base bean (on the many side). This array is related_ids.

##set_relationships()
Set_relationships() sets many, many to many relationships. The call can be found [here] (https://github.com/jmertic/KSU_Capstone_Spring_2011_Python/blob/master/sugarcrm/sugarcrm.py#L237-240) and looks like this.

[self.id, module_names, module_ids, link_field_names, related_ids]

Self.id is the session id returned at log in. Module_names is an array of modules that the base beans are part of. Module_ids is an array of id for the set of base beans. Link_field_names is an array of the link_field that will make up the links or relationships between the set of base beans and the set of linked beans. Related_id is an array of bean ids that the base beans will be related to.

##get_relationships()
Get_relationships() gets a list of the beans that have been linked to a bean by using set_relationship() and set_relationships(), in addition it can also return information about the the actual relationships if required. The call can be found [here] (https://github.com/jmertic/KSU_Capstone_Spring_2011_Python/blob/master/sugarcrm/sugarcrm.py#L252-256) and looks like this.

[self.id, module, module_id, link_field_name, related_module, related_module_query, related_fields, related_module_link, {True:1, False:0}[delete]]

Self.id is the session id returned at log in. Module is a string that is the name if the module that holds the base bean. Module_id is the id of the base bean. Link_name_field is the string that is the name of the link_field that will be used to retrieve the related beans. Related_module_query is a the part of a SQL WHERE clause (after the WHERE) that is used to retrieve beans. The related_fields parameter specifies the fields from the related beans that will be returned (e.g. name, work_phone, title). The related_module_link_name_to_fields_array is an array that specifies the fields to be returned from the link field provided (e.g. [name: ‘created_by_link’, value: {id, name, email_address}]) where created_by_link is the link name and id, name and email_address are the hypothetical fields to be returned from the related beans. Deleted is set to either 0 for false or 1 for true to return deleted entries or not (it should be noted that entries are not really removed but rather set to disabled and still in the database for safety purposes and thus can still be accessed is needed).