SugarCRM Developers

SugarCRM Cookbook - The School of REST - Part 3

Blog Post created by SugarCRM Developers on Feb 28, 2014

Post originally written by sugarmajed.

 

This is the final section of the School of Rest. We'll be covering filtering on relationships as well as Global Search, Favorites, and Deleting records.

 

We've already created our Account "Burger Palace" in Part 1 and showed how to filter lists with various conditions.

 

And in Part 2 we created our Contact "Bob Burger" and related him to "Burger Palace". Now we'll show how these same concepts apply to relationships.

 

11. Filtering on Relationships

 

All the same stuff that we learned for filtering on lists can be applied to relationships as well. Let's retrieve all the Contacts that are related to "Burger Palace" whose first and last name starts with "B" and who we have marked as a favorite.

 

To filter on first and last name we know the filter looks like

filter[0][first_name][$starts]=B and filter[0][last_name][$starts]=B

 

But what about favorites? Favorites are a way for users to specify which records are important to them and they have a special filter condition that looks like

filter[0][$favorite]=_this

 

So we will do a GET request to /rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this&fields=name,first_name,last_name,email,description

 

CURL Filter Relationships.sh

curl -X GET -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:a86bc38a-8c3f-d364-fbfe-282e41b10645 http://server/pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this

GET Filter Relationships.http

GET /pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter%5B0%5D%5Blast_name%5D%5B%24starts%5D=b&filter%5B0%5D%5Bfirst_name%5D%5B%24starts%5D=b&filter%5B0%5D%5B%24favorite%5D=_this HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: fc8df8eb-c475-28bc-ca03-6b7ee511a069


Response.json

{
"next_offset": -1,
"records": []
}

 

 

Well that didn't work to well. First, we need to mark "Bob Burger" as a favorite.

 

12. Mark a Contact as a Favorite - Bob Burger

 

All we need to do is a PUT to  /rest/v10/Contacts/demo_bob_burger/favorite

 

This works on all modules that support favorites, and allows us to quickly filter our favorite records.

 

CURL PUT Favorite Contact.sh

curl -X PUT -H OAuth-Token:8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4 -H Cache-Control:no-cache -H Postman-Token:69fc3540-0acd-0186-c0c9-cb95ac352bd8 -H Content-Type:multipart/form-data; boundary=----WebKitFormBoundaryp7MA4YWxkTrZu0gW http://server/pro720/rest/v10/Contacts/demo_bob_burger/favorite

PUT Favorite Contact.http

PUT /pro720/rest/v10/Contacts/demo_bob_burger/favorite HTTP/1.1
Host: server
OAuth-Token: 8f027f7a-266a-dcd0-8dc4-530cfa3ce6d4
Cache-Control: no-cache
Postman-Token: cb2d99d7-241d-e4e2-71b3-f9a432d72a12
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryp7MA4YWxkTrZu0gW


Response.json

{
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_entered": "2014-02-25T12:16:41-08:00",
"date_modified": "2014-02-25T12:21:22-08:00",
"modified_user_id": "1",
"modified_by_name": "Administrator",
"created_by": "1",
"created_by_name": "Administrator",
"doc_owner": "",
"user_favorites": [
"1"
    ],
"description": "Bob Burger was updated",
"deleted": false,
"assigned_user_id": "",
"assigned_user_name": "",
"team_count": "",
"team_name": [
        {
"id": 1,
"name": "Global",
"name_2": "",
"primary": true
        }
    ],
"email": [
        {
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
        }
    ],
"email1": "bob.burger@example.com",
"email2": "",
"invalid_email": false,
"email_opt_out": false,
"salutation": "",
"first_name": "Bob",
"last_name": "Burger",
"full_name": "Bob Burger",
"title": "",
"facebook": "",
"twitter": "",
"googleplus": "",
"department": "",
"do_not_call": false,
"phone_home": "",
"phone_mobile": "",
"phone_work": "",
"phone_other": "",
"phone_fax": "",
"primary_address_street": "",
"primary_address_street_2": "",
"primary_address_street_3": "",
"primary_address_city": "",
"primary_address_state": "",
"primary_address_postalcode": "",
"primary_address_country": "",
"alt_address_street": "",
"alt_address_street_2": "",
"alt_address_street_3": "",
"alt_address_city": "",
"alt_address_state": "",
"alt_address_postalcode": "",
"alt_address_country": "",
"assistant": "",
"assistant_phone": "",
"picture": "",
"email_and_name1": "",
"lead_source": "",
"account_name": "Burger Palace",
"account_id": "demo_burger_palace",
"dnb_principal_id": "",
"opportunity_role_fields": "",
"opportunity_role_id": "",
"opportunity_role": "",
"reports_to_id": "",
"report_to_name": "",
"birthdate": "",
"campaign_id": "",
"campaign_name": "",
"c_accept_status_fields": "",
"m_accept_status_fields": "",
"accept_status_id": "",
"accept_status_name": "",
"accept_status_calls": "",
"accept_status_meetings": "",
"sync_contact": false,
"mkto_sync": false,
"mkto_id": null,
"mkto_lead_score": null,
"my_favorite": true,
"_acl": {
"fields": {}
    },
"following": true,
"_module": "Contacts"
}

 

You'll notice in the response the record now says "my_favorite" is true.

 

If we wanted to unmark a record as a favorite we would just do a DELETE  to /rest/v10/Contacts/demo_bob_burger/favorite

 

13. Try Step 11 Again!

 

Let's re-run the relationship filter from Step 10! Let's do a GET request to /rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this&fields=name,first_name,last_name,email,description

 

CURL filter relationships again.sh

curl -X GET -H OAuth-Token:d1645103-c562-e439-c0d0-530d2f4e3801 -H Cache-Control:no-cache -H Postman-Token:4ab308ee-7902-6a3f-dc9c-f8bb595dec97 http://server/pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter[0][last_name][$starts]=b&filter[0][first_name][$starts]=b&filter[0][$favorite]=_this&fields=name,first_name,last_name,email,description

GET Filter Relationships Again.http

GET /pro720/rest/v10/Accounts/demo_burger_palace/link/contacts?filter%5B0%5D%5Blast_name%5D%5B%24starts%5D=b&filter%5B0%5D%5Bfirst_name%5D%5B%24starts%5D=b&filter%5B0%5D%5B%24favorite%5D=_this&fields=name%2Cfirst_name%2Clast_name%2Cemail%2Cdescription HTTP/1.1
Host: server
OAuth-Token: d1645103-c562-e439-c0d0-530d2f4e3801
Cache-Control: no-cache
Postman-Token: 8ee8836c-e7c4-51e8-a187-bbfd92e6a790


Response.json

{
"next_offset": -1,
"records": [
        {
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_modified": "2014-02-25T15:03:01-08:00",
"description": "Bob Burger was updated",
"email": [
                {
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
                }
            ],
"first_name": "Bob",
"last_name": "Burger",
"_acl": {
"fields": {}
            },
"_module": "Contacts"
        }
    ]
}

 

 

Excellent! Now that's what we expected!

 

14. Filter by a Related record

 

Now, let's filter our Accounts list for only records that have a contact with the last name "burger". Our filter condition will look like filter[0][contacts.last_name]=burger and remember that "contacts" in this case is the Link or Relationship Name not the module name.

 

So let's do a GET to rest/v10/Accounts?filter[0][contacts.last_name]=burger

curl -X GET \  'http://server/pro720/rest/v10/Accounts?filter%5B0%5D%5Bcontacts.last_name%5D=burger&fields=name%2Cfirst_name%2Clast_name%2Cemail%2Cdescription' \  -H 'cache-control: no-cache' \  -H 'oauth-token: 39ba05eb-2289-4770-ac39-9fe03f99c77a' \  -H 'postman-token: 65094f2f-ae73-851b-11b1-995e66eb1779'
GET /pro720/rest/v10/Accounts?filter[0][contacts.last_name]=burger&fields=name,first_name,last_name,email,description HTTP/1.1
Host: server
OAuth-Token: 39ba05eb-2289-4770-ac39-9fe03f99c77a
Cache-Control: no-cache
Postman-Token: 598e3c09-43cd-2e7c-704e-0ffbd0378a1e
{
     "next_offset": -1,
     "records": [
         {
             "id": "demo_burger_palace",
             "name": "Burger Palace",
             "date_modified": "2017-07-28T10:14:29-04:00",
             "description": "My Example Account",
             "locked_fields": [],
             "email": [
                 {
                     "email_address": "burgers@example.com",
                     "primary_address": true,
                     "reply_to_address": false,
                     "invalid_email": false,
                     "opt_out": false
                 }
             ],
             "_acl": {
                 "fields": {}
             },
             "_module": "Accounts"
         }
    ]
}

Great! We got "Burger Palace" which is what we wanted.

 

15. Global Search/Full Text Search 

 

Now let's just search everywhere for the word "burger" and see what we get! All we have to do is a GET request to /rest/v10/search?q=burger  and that will search against SugarCRM's Full Text Search.

 

CURL Full Text Search.sh

curl -X GET -H OAuth-Token:4ef8594d-5b45-20f4-0a01-530d20d69d1f -H Cache-Control:no-cache -H Postman-Token:e76d2d29-bc10-bea7-c2b6-761e49a8a197 http://server/ent720/rest/v10/search?q=burger&fields=name,email,description

GET Full Text Search.http

GET /ent720/rest/v10/search?q=burger&fields=name%2Cemail%2Cdescription HTTP/1.1
Host: server
OAuth-Token: 4ef8594d-5b45-20f4-0a01-530d20d69d1f
Cache-Control: no-cache
Postman-Token: 7aeedc64-602a-535d-7c0d-b32bf2e1a035

Response.json

{
"next_offset": -1,
"records": [
        {
"id": "demo_bob_burger",
"name": "Bob Burger",
"date_modified": "2014-02-25T23:03:01+00:00",
"description": "Bob Burger was updated",
"email": [
                {
"email_address": "bob.burger@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
                }
            ],
"_acl": {
"fields": {}
            },
"_module": "Contacts",
"_search": {
"score": 1,
"highlighted": {
"last_name": {
"text": "<strong>Burger</strong>",
"module": "Contacts",
"label": "LBL_LAST_NAME"
                    }
                }
            },
"following": true
        },
        {
"id": "demo_burger_palace",
"name": "Burger Palace",
"date_modified": "2014-02-25T23:01:42+00:00",
"description": "My Example Account",
"email": [
                {
"email_address": "burgers@example.com",
"invalid_email": false,
"opt_out": false,
"primary_address": false,
"reply_to_address": false
                }
            ],
"_acl": {
"fields": {}
            },
"_module": "Accounts",
"_search": {
"score": 1,
"highlighted": {
"name": {
"text": "<strong>Burger</strong> Palace",
"module": "Accounts",
"label": "LBL_NAME"
                    },
"email1": {
"text": "<strong>burgers</strong>@example.com",
"module": "Accounts",
"label": "LBL_EMAIL_ADDRESS"
                    }
                }
            },
"following": true
        }
    ]
}

 

We got two records back - "Burger Palace" and "Bob Burger". So using Global Search/Full Text Search we can search against all of our objects at once!

 

16.  Let's Clean Up

 

All we need to do is a DELETE request to /rest/v10/Accounts/demo_burger_palace

 

and another DELETE request to /rest/v10/Contacts/demo_bob_burger

 

And remember there is more documentation at /rest/v10/help!

Outcomes