Problem

You want to modify related lists of Salesforce.com records in the mobile application, even when the records are not available locally on the mobile phone. Optionally, you'll use a Bluetooth peripheral device to update the data in the records.

Solution

For this recipe, let's assume that your organization sells servers. Your field service representatives want to update related list information on records from their mobile devices while at customer sites. For example, if they replace a broken component in a server, they want to be able to enter the new component's serial number and update the server record. The server is then associated with the new component instead of the replaced one.

To accomplish this, we'll create three custom objects and some custom fields. We'll use an Apex trigger to update the server record when the field service representatives replace a component.

• Mobile Licenses:All existing Developer Edition organizations have mobile licenses. Visit Developer Force and click Getting Started to sign up for a new Developer Edition organization.
• Mobile Devices: Verify that your mobile device will run Salesforce Mobile. See Supported Devices for Mobile in the Salesforce.com online help.

  If your mobile device is not supported, you can download and install the BlakBerry simulator package so you can run the mobile application on a simulator.

To use Apex to update data in Salesforce Mobile:

First, create a custom object named Server that has a lookup relationship to Account. This object allows your organization to keep track of the servers housed at each customer's site.

1. Click Setup | Create | Objects | New Custom Object.
2. Enter the following information:
   • Label: Server
   • Plural Label: Servers
3. Accept the remaining defaults and click Save.
4. In the Custom Fields & Relationships related list, click New and define a field with the following attributes:
   • Data Type: Lookup Relationship
   • Related To: Account
   • Field Label: Account
   • Field Name: Account
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
5. In the Custom Fields & Relationships related list, click New and define a second field with the following attributes:
   • Data Type: Text Area
   • Field Label: Description
   • Field Name: Description
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts

Next, create a custom object named Component that has a lookup relationship to Server. This object represents the various components that can be installed inside a server.

1. Click Setup | Create | Objects | New Custom Object.
2. Enter the following information:
   • Label: Component
   • Plural Label: Components
3. Accept the remaining defaults and click Save.
4. In the Custom Fields & Relationships related list, click New and define a field with the following attributes:
   • Data Type: Master-Detail Relationship
   • Related To: Server
   • Field Label: Server
   • Field Name: Server
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
5. In the Custom Fields & Relationships related list, click New and define a second field with the following attributes:
   • Data Type: Checkbox
   • Field Label: Operational
   • Field Name: Operational
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
6. In the Custom Fields & Relationships related list, click New and define a third field with the following attributes:
   • Data Type: Picklist
   • Field Label: Type
   • Values: Motherboard, RAM, CPU, Network Card, Power Supply
   • Field Name: Type
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
7. By default, one of the standard fields for the Component object is Component Name; however, the field service representatives reference the components by serial number. We'll change the standard field name to Component Serial Number. In the Standard Fields related list, click Edit next to Component Name.
8. In the Record Name field, type Component Serial Number.
9. Click Save.

1. Click Setup | Create | Objects | New Custom Object.
2. Enter the following information:
   • Label: Replacement
   • Plural Label: Replacements
3. Accept the remaining defaults and click Save.
4. In the Custom Fields & Relationships related list, click New and define a field with the following attributes:
   • Data Type: Date
   • Field Label: Date
   • Field Name: Date
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
5. In the Custom Fields & Relationships related list, click New and define a second field with the following attributes:
   • Data Type: Lookup Relationship
   • Related To: Component
   • Field Label: New Component
   • Field Name: New Component
   • Field-Level Security: Hidden from all profiles
   • Add Related List: Hidden from all page layouts
6. In the Custom Fields & Relationships related list, click New and define a third field with the following attributes:
   • Data Type: Lookup Relationship
   • Related To: Component
   • Field Label: Replaced Component
   • Field Name: Replaced Component
   • Field-Level Security: Hidden from all profiles
   • Add Related List: Hidden from all page layouts

     In the next two steps, we'll create text versions of the New Component and Replaced Component lookup fields. This is because Salesforce Mobile handles lookup fields differently than the Salesforce.com website. Users can type in lookup fields on the website, but not in the mobile application. We want the field representatives to be able to quickly enter the serial number of the new component, so we'll create text fields to replace the lookup fields.

     To further complicate matters, mobile configurations deliver only a subset of a user's data to the mobile application. There is a possibility that the record the user is trying to look up is not stored locally on the mobile device. By allowing a user to enter text, the mobile application can send the information to Salesforce.com when the record is saved, and then Salesforce.com validates the user's text entry against the component records with the Apex trigger.

     Additionally, if we want to pair the mobile device with a Bluetooth barcode scanner so that the field representatives can simply scan the serial numbers of the new and replaced components, it is imperative to set up the fields as text fields. For information about using a barcode reader, see the Discussion at the end of this recipe.

7. In the Custom Fields & Relationships related list, click New and define a fourth field with the following attributes:
   • Data Type: Text
   • Field Label: New Component Serial Number
   • Field Name: New Component Serial Number
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts
8. In the Custom Fields & Relationships related list, click New and define a fifth field with the following attributes:
   • Data Type: Text
   • Field Label: Replaced Component Serial Number
   • Field Name: Replaced Component Serial Number
   • Field-Level Security: Visible for all profiles
   • Add Related List: On all page layouts

Next, create an Apex trigger on the Replacement object so that a server's components are automatically updated when a field representative creates a replacement record.

1. Click Setup | Create | Objects | Replacement.
2. In the Triggers related list, click New.
3. In the Body text box, enter the following Apex trigger code:

   trigger replacementPart on Replacement__c (before insert) {
      for(Replacement__c r : Trigger.new) {
          //first, find the old component  
       
          //(the one we are replacing)  
       
         Component__c oldCompInfo = [select id, type__c, Server__c
             from component__c where Name=
             :r.Replaced_Component_Serial_Number__c];
         //find the new component by name  
       
         Component__c newCompInfo = [select id, type__c from 
            component__c where
              Name=:r.New_Component_Serial_Number__c];
         if(oldCompInfo == null)
            r.Replaced_Component_Serial_Number__c.addError(
               'The serial number you entered does not match '+
               'any existing components.');
         if(newCompInfo == null)
             r.New_Component_Serial_Number__c.addError(
                'The serial number you entered does not match '+
                'any existing components.');
         //set the Replacement part's fields  
       
         r.Replaced_Component__c = oldCompInfo.Id;
         r.New_Component__c = newCompInfo.Id;
         if(newCompInfo.type__c != oldCompInfo.type__c)
            r.New_Component__c.addError(
            'The new component type must be ' + 
            'the same as the replaced component type.');
         //update the old component's Server__c to null  
       
         Component__c oldComp = new Component__c(
            Id= oldCompInfo.Id, Server__c=null);
         //update the new component's Server__c  
       
         //to the old component's Server__c  
       
         component__c newComp = new Component__c(
            Id=r.New_Component__c, Server__c=
              oldCompInfo.Server__c);
         //update both components  
       
         List<Component__c> comps = new List<Component__c>();
         comps.add(oldComp);
         comps.add(newComp);
         update(comps);
         r.Date__c = System.Today();
      }
   }
4. Click Save.

Next, create a mobile configuration and mobilize the new objects.

1. Click Setup | Mobile Configurations | New Mobile Configuration.
2. In the Name field, type Field Service.
3. Select the Active checkbox.
4. Select the Mobilize Recent Items checkbox.
5. Select your name in the Available Members list box and click Add.
6. Click Save.
7. In the Data Sets related list, click Edit.
8. Click Add....
9. Select Server and click OK.
10. Click the Data Sets node in the tree, click Add.... Select Component, and click OK.
11. Click the Data Sets node in the tree, and click Add.... Select Replacement, and click OK.

    If this was a real mobile configuration for field representatives, you would probably also mobilize other objects, like Account and Case. For the recipe, we just need to mobilize the custom objects we created.

12. Click Done.

Finally, test the Apex trigger in the mobile application:

1. On the Salesforce.com website, create a server record and three related component records so you have some data to work with in the mobile application.
   • Server: IBM BladeCenter S
   • Component Serial Number: 100000; Type: CPU
   • Component Serial Number: 100001; Type: Motherboard
   • Component Serial Number: 100002; Type: Power Supply
2. Create one more component record that is not associated with any server record. Enter 100003 as the Component Serial Number, and set the Type to CPU.
3. Install the mobile application on your device. For installation instructions, see “Installing the Mobile Application” in the Salesforce.com online help. If you're using a BlackBerry simulator, the mobile application is already installed on the simulator device; you just need to activate your Salesforce.com Developer Edition account after launching Salesforce Mobile for the first time.
4. In the mobile application, select the Replacement tab.
5. Open the menu and select New.
6. In the Replaced Component Serial Number field, type 100000.
7. In the New Component Serial Number field, type 100003.
   Pairing the mobile device with a Bluetooth barcode scanner allows the field service representative to enter the serial numbers in the replacement record fields by scanning the barcodes.
8. Open the menu and select Save.

   The mobile application sends the record to Salesforce.com and the new component is associated with the server record.

Discussion

To make this solution even more effective, implement the Apex trigger and give the field representatives barcode scanners so that they can quickly scan the serial numbers when replacing components. Many barcode scanners can operate wirelessly using a Bluetooth connection. Just pair the barcode scanner with a Bluetooth-enabled mobile device, and you'll be able to use the scanner for entering data in the mobile application.