Join our Telegram Channel
Hello Trailblazers,
Welcome to the 5th tutorial in the Salesforce Integration Tutorial Series. In the previous tutorial, we learned about DELETE method in detail. You can view that tutorial by clicking here. In this tutorial, we'll have a look at the PUT method. We'll create a custom REST API which will deal with the contact object that is available in salesforce.
The PUT method gives us the flexibility by updating a record if it's already present in Salesforce. In case, the record is not present, it'll create a new record. We know that when we have to create/update a record in Salesforce we use the upsert call. In that case, if a record id is specified in the object instance we're trying to upsert, it'll update that record. However, in case a record id is not present in that instance, it'll create a new record. Therefore, we'll be using upsert in our PUT method.
The PUT method will have an annotation of @HTTPPut. It supports a request body so there are different ways you can pass data to this method. One way can be to pass all the data in the request body which is automatically mapped to the parameters of the method. Another way can be to deserialize the JSON in the request body in the method itself and cast it to the object you want to upsert, in our example it'll be contact. We've seen both the approaches in our previous tutorial in which we've explored the POST method in detail. So, here we'll be going with something different.
We'll pass the record id at the end of the URL and all the other parameters in the request body which will be mapped to the method parameters (to keep it simple). If a record id is present at the end of the URL, our upsert call will update that particular record, otherwise it'll create a new record. We'll be using the same ContactResource class and updating that. Let's have a look at the updated code below:-
As you can see above, in our ContactResource class which has a URL Mapping of /ContactAPI/*, we have a method named as upsertContact which is having 4 parameters namely:- firstName, lastName, birthDate and leadSource as we had in out POST method tutorial. Inside this method, we're getting the actual request using the request context variable from the RestContext class and assigning it to an instance of RestRequest class named contactRequest. Then, we're getting the requestURI from contactRequest and finding the contact id from that request URI by getting the substring after the last slash (/) from the request URI. We then assign the contact id to a String named contactId. Now, we have all the values, so it's time to create a new contact and upsert it.
Next, we created a new instance of contact and checked if the contactId string is not empty, we assigned contactId as the id of the contact we're going to upsert. I noticed one thing here that it's not necessary to use Id.valueOf() like we've done previously as Salesforce automatically typecast it to the Id type. Then we'll assign the first name, last name, birth date and lead source for a contact. We're parsing the birthdate using Date.parse() and converting the string input into date format. If you don't want to parse the date, you can directly have a parameter of type Date in the method itself as:- Date birthDate but you need to take care of the format in that case in which you're sending date. The acceptable format for that is:- YYYY-MM-DD. Finally, we're upserting the contact and returning the contact in the response.
I tested this API from workbench and got the following results:-
Inserting a New Contact
Updating the same contact by specifying an id in the URL
You can see in the response, we got the same id back that we mentioned in the URL and the contact's lead source is updated in Salesforce from Web to Phone Inquiry as shown below:-
[UPDATE]:- The below case is valid only because I am taking the input in the form of method parameters and I am overriding the contact values with the values passed in method parameters. Therefore, the values are updated to null if it's not present in the input. In case, you're parsing the whole JSON request body by using requestBody variable of RestRequest class, the system will consider only the values present in the input and will update/insert only those. Rest of the data remains unaffected if upsert is updating the record which is already present.
If you notice, you'll see that even if I have to update one single field, I am passing all the other values in the input too. That's because, upsert method expects the field values to be present while upserting a record. To confirm that, let's try to update the lead source to web again, but this time we'll pass only the changed value in input. You'll see the below response:-
It is giving us the error that the required fields are missing even if I am specifying the record id in the URL and as we know, this record also have a value in the last name. Let's just fill up the last name and see what happens.
As you can see above, I have updated the last name to Hendricks and also the leadSource back to Web and I got the response in which the first name and birth date is specified as null. Let's have a look at the record in Salesforce.
You can see above that the last name is updated to Hendricks and the lead source is updated to Web. However, the birth date and first name are shown as empty as they're automatically updated to null as shown in the response. So, while using PUT method, we need to take care that we pass the whole record as it'll be an upsert call.
Tired of reading or just scrolled down, don't worry, you can watch the video too.
That's all for this tutorial, in the next tutorial we'll have a look at the PATCH method in detail which is specifically used to update the record fields. You can find all the code related to this tutorial in the put branch of my github repository here. If you liked this tutorial, make sure to share it in your network and provide your feedback in the comments below.
Happy Trailblazing..!!
Welcome to the 5th tutorial in the Salesforce Integration Tutorial Series. In the previous tutorial, we learned about DELETE method in detail. You can view that tutorial by clicking here. In this tutorial, we'll have a look at the PUT method. We'll create a custom REST API which will deal with the contact object that is available in salesforce.
The PUT method gives us the flexibility by updating a record if it's already present in Salesforce. In case, the record is not present, it'll create a new record. We know that when we have to create/update a record in Salesforce we use the upsert call. In that case, if a record id is specified in the object instance we're trying to upsert, it'll update that record. However, in case a record id is not present in that instance, it'll create a new record. Therefore, we'll be using upsert in our PUT method.
The PUT method will have an annotation of @HTTPPut. It supports a request body so there are different ways you can pass data to this method. One way can be to pass all the data in the request body which is automatically mapped to the parameters of the method. Another way can be to deserialize the JSON in the request body in the method itself and cast it to the object you want to upsert, in our example it'll be contact. We've seen both the approaches in our previous tutorial in which we've explored the POST method in detail. So, here we'll be going with something different.
We'll pass the record id at the end of the URL and all the other parameters in the request body which will be mapped to the method parameters (to keep it simple). If a record id is present at the end of the URL, our upsert call will update that particular record, otherwise it'll create a new record. We'll be using the same ContactResource class and updating that. Let's have a look at the updated code below:-
As you can see above, in our ContactResource class which has a URL Mapping of /ContactAPI/*, we have a method named as upsertContact which is having 4 parameters namely:- firstName, lastName, birthDate and leadSource as we had in out POST method tutorial. Inside this method, we're getting the actual request using the request context variable from the RestContext class and assigning it to an instance of RestRequest class named contactRequest. Then, we're getting the requestURI from contactRequest and finding the contact id from that request URI by getting the substring after the last slash (/) from the request URI. We then assign the contact id to a String named contactId. Now, we have all the values, so it's time to create a new contact and upsert it.
Next, we created a new instance of contact and checked if the contactId string is not empty, we assigned contactId as the id of the contact we're going to upsert. I noticed one thing here that it's not necessary to use Id.valueOf() like we've done previously as Salesforce automatically typecast it to the Id type. Then we'll assign the first name, last name, birth date and lead source for a contact. We're parsing the birthdate using Date.parse() and converting the string input into date format. If you don't want to parse the date, you can directly have a parameter of type Date in the method itself as:- Date birthDate but you need to take care of the format in that case in which you're sending date. The acceptable format for that is:- YYYY-MM-DD. Finally, we're upserting the contact and returning the contact in the response.
I tested this API from workbench and got the following results:-
Inserting a New Contact
You can see that PUT is selected from the radio buttons above and a new contact is created in Salesforce with the data given:-
Updating the same contact by specifying an id in the URL
[UPDATE]:- The below case is valid only because I am taking the input in the form of method parameters and I am overriding the contact values with the values passed in method parameters. Therefore, the values are updated to null if it's not present in the input. In case, you're parsing the whole JSON request body by using requestBody variable of RestRequest class, the system will consider only the values present in the input and will update/insert only those. Rest of the data remains unaffected if upsert is updating the record which is already present.
If you notice, you'll see that even if I have to update one single field, I am passing all the other values in the input too. That's because, upsert method expects the field values to be present while upserting a record. To confirm that, let's try to update the lead source to web again, but this time we'll pass only the changed value in input. You'll see the below response:-
As you can see above, I have updated the last name to Hendricks and also the leadSource back to Web and I got the response in which the first name and birth date is specified as null. Let's have a look at the record in Salesforce.
You can see above that the last name is updated to Hendricks and the lead source is updated to Web. However, the birth date and first name are shown as empty as they're automatically updated to null as shown in the response. So, while using PUT method, we need to take care that we pass the whole record as it'll be an upsert call.
Tired of reading or just scrolled down, don't worry, you can watch the video too.
That's all for this tutorial, in the next tutorial we'll have a look at the PATCH method in detail which is specifically used to update the record fields. You can find all the code related to this tutorial in the put branch of my github repository here. If you liked this tutorial, make sure to share it in your network and provide your feedback in the comments below.
Happy Trailblazing..!!
Posts
No comments:
Post a Comment