User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
en:devel:corebosws:getrelatedrecords [2015/10/24 18:49] 127.0.0.1 external edit |
en:devel:corebosws:getrelatedrecords [2021/03/03 13:49] (current) joebordes [Web service get Related Records method] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Web service get Related Records method ====== | ====== Web service get Related Records method ====== | ||
| - | |||
| - | Implemented in ~~issue:127~~ | ||
| {{youtube>5B0A6IPMnJM}} | {{youtube>5B0A6IPMnJM}} | ||
| \\ | \\ | ||
| - | The **getRelatedRecords()** webservice interface function permits us to retrieve the set of related records that belong to any given record. In other words, given an entity ID that represents one record in the application and the name of a module that is related to this entity, we will get the full set of records related to the ID. | + | The **getRelatedRecords()** web service interface function permits us to retrieve the set of related records that belong to any given record. In other words, given an entity ID that represents one record in the application and the name of a module that is related to this entity, we will get the full set of records related to the ID. |
| For example, suppose we have a contact record with id 22. We know that one contact can have many invoices. So if we want to see the invoices related to the contact with id 22 we would execute something like this: | For example, suppose we have a contact record with id 22. We know that one contact can have many invoices. So if we want to see the invoices related to the contact with id 22 we would execute something like this: | ||
| Line 17: | Line 15: | ||
| where | where | ||
| - | * **id** a webservice ID corresponding to the main record we want to relate | + | * **id** a web service ID corresponding to the main record we want to relate |
| * **module** the module name of the id, this must be of the same type as the ID, if not an error will be returned | * **module** the module name of the id, this must be of the same type as the ID, if not an error will be returned | ||
| * **relatedModule** the name of the module related to the main module, this represents the type of records to be returned | * **relatedModule** the name of the module related to the main module, this represents the type of records to be returned | ||
| Line 27: | Line 25: | ||
| * ProductLineSalesOrder{Only}: relation Account|Contact-Products, return products related through SalesOrder (only) | * ProductLineSalesOrder{Only}: relation Account|Contact-Products, return products related through SalesOrder (only) | ||
| * ProductLineQuote{Only}: relation Account|Contact-Products, return products related through Quote (only) | * ProductLineQuote{Only}: relation Account|Contact-Products, return products related through Quote (only) | ||
| - | * ProductLineAll: relation Account|Contact-Products, return products related through Quote, SalesOrder and Invoice | + | * ProductLineAll: relation Account|Contact-Products, return products related through Quote, SalesOrder, and Invoice |
| * ProductLineNone: relation Account|Contact-Products, return only products directly related, this is the default behavior | * ProductLineNone: relation Account|Contact-Products, return only products directly related, this is the default behavior | ||
| * **limit**: a string indicating the limit of records to be returned. this is needed for paging | * **limit**: a string indicating the limit of records to be returned. this is needed for paging | ||
| * **offset**: a string indicating the initial offset for returning values. this is needed for paging | * **offset**: a string indicating the initial offset for returning values. this is needed for paging | ||
| - | * **orderby**: a syntactically and semantically correct order by directive wihtout the "order by", only the fields and their order (no validation is done) | + | * **orderby**: a syntactically and semantically correct order by directive without the "order by", only the fields and their order (no validation is done) |
| - | * **columns**: a a comma separated string of column names that are to be returned. The special value "*" will return all fields. for example: 'assigned_user_id,id,createdtime,notes_title,filedownloadcount,filelocationtype,filesize' | + | * **columns**: a comma separated string of column names that are to be returned. The special value "*" will return all fields. for example: 'assigned_user_id,id,createdtime,notes_title,filedownloadcount,filelocationtype,filesize' |
| + | * **relationtouse**: label of the relation to select when more than one is found, if not given, or not found an exception will be thrown. when two modules are related by more than one function, the code does not know which one to use, in that case, it will throw an exception. Using this parameter you can tell the code which of the various relations you want to use. You must set the parameter to the internal (untranslated) label of the relation (vtiger_relatedlists.label) | ||
| + | * **returnattachments**: for Document module will return the file attached if present | ||
| - | * **returns** an array where each element represents a webservice record of the type of the related module. Only the columns and records the current user has access to will be returned. If the current user cannot access the main module or the related module, an error will be returned. | + | * **returns** an array where each element represents a web service record of the type of the related module. Only the columns and records the current user has access to will be returned. If the current user cannot access the main module or the related module, an error will be returned. |
| - | The method has been created with complete support in mind, but this is really hard to achieve due to the great variety of relations that exist and the different ways in which they are established. On top of that there is no one place to turn to to get the information on how two entities are related. | + | The method has been created with complete support in mind, but this is really hard to achieve due to the great variety of relations that exist and the different ways in which they are established. On top of that, there is no one place to turn to to get the information on how two entities are related. |
| Since we try to cover all the relations we have forced the method to return some non-standard relations that I will try to explain next. | Since we try to cover all the relations we have forced the method to return some non-standard relations that I will try to explain next. | ||
| Line 87: | Line 87: | ||
| * This exact same functionality is available for Services. The productDiscriminator parameter accepts the SAME values; ProductLine* not ServiceLine* | * This exact same functionality is available for Services. The productDiscriminator parameter accepts the SAME values; ProductLine* not ServiceLine* | ||
| * The user may have no permission to read Quotes, SO or Invoices and will still retrieve products related through these entities as long as the user has read permission on products. | * The user may have no permission to read Quotes, SO or Invoices and will still retrieve products related through these entities as long as the user has read permission on products. | ||
| + | ===== getRelatedRecordsThroughModule ===== | ||
| + | |||
| + | In some use cases, it is useful to be able to get a list of records related at a second level. For example, we want to get a list of project tasks related to an account going through the Projects related to the account. For this sort of question, we construct upon the getRelatedRecords method to create getRelatedRecordsThroughModule. | ||
| + | |||
| + | ^Purpose:|Returns a list of Object records related to the given record passing through another related module.| | ||
| + | ^Profile:|getRelatedRecordsThroughModule(id:string, module:string, relatedModule:string, bridgeModule:string, queryParameters:Map):Map| | ||
| + | ^Send as:|POST| | ||
| + | ^Parameters:| => id: web service ID of the main record \\ => module: module of the record in ID \\ => relatedModule:string: second level related module name we want to get the records from \\ => direct related module name that connects the ID with the related module \\ => queryParameters: additional parameters supported by the getRelatedRecords method| | ||
| + | ^Response:|list of related module records related to the ID record| | ||
| + | |||
| ===== Others ===== | ===== Others ===== | ||
| - | The rest of relations are based on a great idea of Prasad from vtiger where we retrieve the query that represents the relation from the relation function used in the related list //more information// tab. This way we use the same information that is already in the application to relate the two entities. | + | The rest of the relations are based on a great idea of Prasad from vtiger where we retrieve the query that represents the relation from the relation function used in the related list //more information// tab. This way we use the same information that is already in the application to relate the two entities. |
| The biggest limitation of this approach is that these functions are basically static in their column set as the columns present in the +info tab cannot be changed without coding so, in some cases, the query is limited to obtain only those columns, while we have made the getRelatedRecords function to return all the columns the current user has access to. So to get this working we have had to manipulate the SQL returned from the functions. | The biggest limitation of this approach is that these functions are basically static in their column set as the columns present in the +info tab cannot be changed without coding so, in some cases, the query is limited to obtain only those columns, while we have made the getRelatedRecords function to return all the columns the current user has access to. So to get this working we have had to manipulate the SQL returned from the functions. | ||
| - | In general this approaches permits the function to support any relation established using the related list vtlib, which makes it very powerful and flexible. | + | In general, this approaches permits the function to support any relationship established using the related list vtlib, which makes it very powerful and flexible. |
| + | |||
| + | |||
| + | ---- | ||
| + | <WRAP right> | ||
| + | [[:en:devel:corebosws:convertleadwebservice|Next: Convert Lead Webservice]] | [[en:devel:corebosws:tableofcontents|Table of Contents]] | ||
| + | </WRAP> | ||
| + | ---- | ||
