CRM On Demand Technical Tips and Tricks: Javascript API - CRUD. Create, Read, Update and Delete records

techtips.jpg

This post is part of a series of technical articles we are writing on the Javascript API. In this series, we will cover:

  1. Custom buttons.
  2. Storing your code.
  3. Classes, context, the screen, chaining plus the titlebar.
  4. CRUD. Create, Read, Update and Delete records.

In our first three blog articles in this series you learned the canonical “hello world” program, options for storing your code, and reviewed the API classes including Context, Screen, TitleBar and the concept of chaining.

In this blog article we’ll discuss CRUD; creating, reading, updating and deleting records. Our last article included a review of making changes to on-screen values, meaning there is programmatic access to object fields values that are being shown on the CRM On Demand UI (User Interface). However, what about when a field is not being displayed on the UI? For instance, if on Account objects the District Office is not displayed on the UI, and you want to work with the data in that field, this is where CRUD operations come in handy.

Create

Lets jump right in with a full example showing how to create a new record when a button is clicked.

oraclecrmod.onReady(function() { if(oraclecrmod.ctx.isObject("Account") && oraclecrmod.ctx.isDetailPage()) {

// This function called after the createRecord API call returns var on_create_callback=function(request,response) { var data = "Response Data: "; var status = ""; if (response.status == "OK") { status = "Create succeeded: " + response.status; } else { status = " Create failed: " + response.errors; } var dataObj = response.data; if (dataObj != null) { data += "Id = " + response.getRowId(); } else { data += "Data is Null"; } alert(status + "\n" + data); };

// This function called when "Test Create" button clicked var on_create=function() { var create_data = {* Name : "TEST123", Location : "Location Test", Type : "Customer", Description : "Description Test" } oraclecrmod.dataSvc.createRecord( "Account", create_data, null, on_create_callback); };

// Create the "Test Create" button on the main Account TitleBar var tb = oraclecrmod.getTitleBar("AccountFormTB"); var bt = oraclecrmod.createButton({ id:"TestBtn", text:"Test Create", parent:tb }); bt.on("click",on_create); } });

Notice the very bottom of this code. When the user clicks the “Test Create” button, then the on_create function is called. The on_create function is defined above and simply passes in the appropriate parameters to the oraclecrmod.dataSvc.createRecord function call.

  • The first parameter is the type of object to create. In this case it creates an Account.
  • The second parameter contains the values to store in the new Account. Notice that in our case we only specify four field values: Name, Location, Type and Description.
  • The third parameter should always be null. In R25 this is not yet used.
  • The final parameter is the callback function to call after the createRecord call returns.

Much of the above code consists of the callback function. When you run this in your system and click the custom “Create Record” button, the first time it will succeed. The second time it will not. This is because for the second time you are attempting to create a duplicate record in CRM On Demand, and it won’t let you do that. Duplicate Accounts are those that have the same Name and Location values. You’ll see this when your browser shows the Alert dialog that is part of the callback function above.

In the callback we have the response object which has the status and errors attributes. The code checks those and creates the message for the alert dialog box accordingly. If response.status has a value of “OK”, then the record was created successfully. Otherwise, response.errors will provide error information. See page 33 of the R25 JS API doc for details on errors.

The response.data and response.getRowId() are then used to provide more information about the transaction. As it’s name implies, getRowId() returns the row ID of the created record. response.data contains the name value pairs of the data that was used to create the record.

Read

Reading records is very easy, but somewhat limited due to limits on the searchType parameter, as you’ll see below.

oraclecrmod.onReady(function() { if(oraclecrmod.ctx.isObject("Account") && oraclecrmod.ctx.isDetailPage()) {

// This function called after the readRecord API call returns var on_read_callback=function(request,response) { var data = "Response Data: "; var status = ""; if (response.status == "OK") { status = "Read succeeded: " + response.status; } else { status = " Read failed: " + response.errors; } var dataObj = response.data; if (dataObj != null) { data += "Id = " + response.getRowId(); } else { data += "Data is Null"; } alert(status + "\n" + data); };

// This function called when "Test Read" button clicked var on_read=function() { oraclecrmod.dataSvc.readRecord( "Account", ['Name','Location'], { searchType: 'rowId', 'rowId':'AAPA-UWWA5K' }, on_read_callback); };

// Read the "Test Read" button on the main Account TitleBar var tb = oraclecrmod.getTitleBar("AccountFormTB"); var bt = oraclecrmod.createButton({ id:"TestBtn", text:"Test Read", parent:tb }); bt.on("click",on_read); } });

The structure of the code is the same as the Create example before, except of course the calls are now read instead of create. Again, notice at the bottom of the code that when you click the “Test Read” button, the on_read function is called. This function calls the oraclecrmod.dataSvc.readRecord JavaScript API function, passing in four parameters.

  • The first parameter is the type of object to create. In this case it creates an Account.
  • The second parameter is a list, or a comma separated string of the fields to read.
  • The third parameter is the search type which is specified to be of type rowId. For example in this case, when running the create record code, the rowId was displayed in the alert window as 'AAPA-UWWA5K'.This value was then specified as the rowId for the read call. You’ll need to do this yourself, to get the specific rowId of the record to query. Note that currently this is the only way to search, using the rowId. We anticipate Oracle will add future search types to make this more valuable.
  • The final parameter is the callback function to call after the readRecord call returns.

In the above code, the readRecord callback is basically identical to the createRecord callback.

Update

The update call is very similar to the create and read, so only the call itself will be shown here.

// This function called when "Test Update" button clicked var on_update=function() { oraclecrmod.dataSvc.updateRecord( "Account", {'Name':'TEST456'}, { searchType: 'rowId', 'rowId':'AAPA-UWWA5K' }, on_update_callback); };

As you can see, again we are updating the Account object, changing the Name field to have a value of TEST456, for the record with row Id of AAPA-UWWA5K, and calling the on_update_callback function when this returns from the server.

Delete

Finally, the delete call.

// This function called when "Test Update" button clicked var on_delete=function() { oraclecrmod.dataSvc.deleteRecord( "Account", 'AAPA-UWWA5K', on_delete_callback); };

Here we are deleting the Account record that has a row Id of AAPA-UWWA5K and then calling the on_delete_callback once the function call finishes. It doesn’t get much easier than this!

And with that, we hope you enjoyed these four blog articles on the CRM On Demand Javascript API. We look forward to publishing more articles about new CRM On Demand technology as it becomes available. Happy hacking to you!

Also, don’t forget to subscribe to our quarterly update and get valuable information on CRM Best Practices, User Adoption, CRM On Demand Tips & Techniques, and our upcoming R26 series.