Geopointe

Actions

Actions are a powerful feature in Geopointe that allow you to extend and customize the app with your own business logic. Examples of Actions are linking to external sites, embedding Visualforce pages inside the map page, sending data from map searches to your own Apex code, and integrating with external services.

‚Äč

Types of Actions

Point Actions
Point Actions are those that can be applied to a single point on the map page. These points could be a salesforce record returned in a map search, the result of a Places search, anywhere on the map, or a Route Stop. When clicking one of these pins on the map page an info bubble will open. Inside this info bubble is where actions will be located and they can be displayed as buttons, links, or inline iframed web pages. Point Actions support URL and Apex action types.

Screen Shot 2013-07-28 at 11.30.41 AM

List Actions
List Actions can be applied to many records at once. This could be all the records returned in a map search, a subset of select record, or records contained within a shape. These Actions can be invoked with the Actions button located under the right side of the map or within a Shape info window popup. List Actions support Apex and POST (Visualforce) Action Types.

Screen Shot 2013-07-28 at 11.52.56 AM
>> back to top

Creating New Actions
To create a new Action go to the Geopointe Setup page and select the Actions tab. The select the New Action button.

Screen Shot 2013-07-28 at 11.27.27 AM

Below are the following settings for an Action.

Action Name
The Name of the action. Should be short but descriptive as it will be displayed as a button or link.

Available (Web)
If checked, this action will be available in web version of Geopointe.

Available (SF1)
If checked, this action will be available in the Salesforce1 Geopointe mobile app. Currently only Point Actions are supported in the Salesforce1 mobile app.

Enable for All Users
If checked, this will enable this Action for all users by adding the All Internal Users or Entire Organization group to this action's sharing model. This option is only available when creating a new Action. If you have defined the Action object org sharing settings as Public Read/Write this option will not be displayed as all users by default have access to all Actions.

Map Objects
This setting allows you to control what Salesforce objects an Action can be applied to. The default is all objects but choosing the ‘Selected Objects’ you will be provided a list of object you can select from to limit an Action to only the selected objects. This allows you to create an Action that can only be applied to Accounts instead of all objects.

Apply To
This field controls if the action will be applied to an individual record or to a list of records returned in a map page search. This is the key field that defines Point Actions vs List Actions.

Display Type (Point Actions only)
Controls how Actions are displayed to the user:

  • Button - Will be displayed as a button in a map record info window. Should be selected for the most commonly used Actions.
  • Link - Will be displayed as a link in the map record info window.
  • Inline - Will display an iframed website inside the info window that opens when a pin is selected on the map. This iframe can be a custom built Visualforce page or an external 3rd party web site/application.

Action Type
Defines the type of action:

  • URL – This will open the URL of a webpage. This could be an standard salesforce.com edit page, Visualforce page, or external website.
  • Apex – This will send the selected record(s) to custom Apex code.
  • POST (Visualforce) – This will POST an idArray parameter to the defined page with a comma separated set of Ids. See “Creating POST / Visualforce Actions” below for more detail.

Point Type
Controls where these point actions can be used.

  • Map - This actions can be applied to any point in the map. In the web version there are accessible with the right click menu. In Salesforce1 they can be accessed by holding the map where the action should take place.
  • Place - These actions can be applied to the result of a Places search. For example all the results when searching the map for 'coffee shops'.
  • Record - This actions are applied to the results of Data Set map searches.
  • Route Stop - These actions can be applied to a particular stop on a route.

URL  Settings

The follow settings are valid when the Action Type is ‘URL’ or ‘POST (Visualforce)’.

Link URL
The URL of the site that will be opened. For internal salesforce.com pages it is recommend to use relative URLs such as ‘/apex/c__myPage?id={!id}’. In the previous example you will see {!id}. This is a merge field and will combine data from the record into the URL. You will also notice ‘c__’ prepened to the Visualforce page name. This is required on relative URLs due to the way namespaces work in packages.

The following merge fields are supported: {!Id} {!Name} {!Company} {!Latitude} {!Longitude} {!Street} {!City} {!PostalCode} {!State} {!Country}. Company is only supported for Lead, Opportunity, and Account objects. You can also merge URL parameters as well. If the map page as a url like “/geopointe_map?id=00Q1400001KLyDN” you can pull the id value into the point action url with the {!URL.id} merge field.

Note: If this Link URL is part of a POST (Visualforce) Action and you have the My Domain functionality enabled you will need to enter the full url path. Salesforce.com prevents POSTing data to relative URLs when the My Domain feature is enabled.

Behavior
Defines how the url will be opened in the current users browser.

  • New Window – A new tab in the browser or window will be opened with the URL
  • Same Window – The current page will redirect to the new page. This will redirect the user from the map page and they will lose any open searches they have.
  • Modal Window – This will be a iFramed popup window within the map page. See example image below. For security reasons some websites do not enable iFrame access so if the URL is not loading try the ‘New Window’ option.

Modal Width & Height (Optional)

If Behavior is set to ‘Modal Window’ these two fields control the size of the popup. These fields are optional. If left empty the window will be as large as possible based on the user’s screen size. Valid values can define height and width in pixels (600px) or percent of windows width/height (60%).

Apex Settings

The follow settings are valid when the Action Type is ‘Apex’.

Apex Class
The name of the Apex Class that will process the records. See the section ‘Apex Actions’ below for more detail.

Status Message
The message displayed to the user while the Apex code is executing.

Batch Size (List Actions only, Optional)
The number of records sent to the Apex class at one time. If there is a map search that returns 1000s of records you may want to process these records in smaller groups instead of all at once. Setting a batch size will control this size. This field is optional and if left blank the batch size will be 1.

Modal Width & Height (Optional)
When the Apex code is done executing it will send instructions back to the page on how to respond. One of these options is to open a new modal window. These fields control the size of the popup modal window.  If left empty the window will be as large as possible based on the user’s screen size. Valid values can define height and width in pixels (600px) or percent of windows width/height (60%).

Create Record Settings
The following settings are valid when the Action Type is 'Create Record'.

Object - Select the type of salesforce record, standard or custom, that should be created with this action.

Field Set Mapping - For each record type of the object that will be created you can define a different Field Set that will be used to capture inputs upon record creation

Default Values - Here you can set default values on records created from Geopointe. For example, if you wanted the Lead Source to be 'Geopointe' for all records created with this action it could be set here.

>> back to top

User Access
Actions use the standard Salesforce.com sharing model and administrators can control what users have access to what Actions using Groups, Roles, and Sharing Rules. Administrators can select the User Access link to control what users have access to a specific Action.

Screen Shot 2013-07-28 at 12.08.14 PM

>> back to top

Apex Actions
Apex actions are a very powerful tool that let you build custom business logic and integrate it with the Geopointe application. The first step is to create an Apex class that implements the geopointe.ActionHander class. Inside this class there will be one method named execute. It will receive a geopointe.ActionRequest object as the argument and it should return a geopointe.ActionResponse object. Below is an example of what this class may look like.

NOTE: These classes must be declared as global so Geopointe can access them.

global class GP_SendToERP implements geopointe.ActionHandler{
 
    public geopointe.ActionResponse execute(geopointe.ActionRequest req){
 
        //Custom Apex logic
 
        //Construct and return an actionResponse object for the map page
        geopointe.ActionResponse res = new geopointe.ActionResponse();
        res.responseAction = geopointe.ActionResponse.ResponseAction.MESSAGE;
        res.message = 'Record successfully processed.';
 
        return res;
    }
}

In the scenario above this could be invoked by clicking an Action button for a record. This would send a geopointe.ActionRequest object to this class, custom logic could be executed, and then this class will tell the Map page how to respond after the operation is completed by returning a geopointe.ActionResponse object. Below are details about the geopointe.ActionRequest and geopointe.ActionResponse objects.

geopointe.ActionRequest
This is the object the Geopointe application sends to your Apex code. It includes information such as record Ids, object names, and more.

Property Name
Type
Description
batchNumber Integer Number indicating which batch is being processed.
batchSize Integer The number of records that will be processed with each execute() invocation.
jobId String Unique Id to represent the execution of an Action. If there are multiple batches this Id will remain constant across all executions.
numberOfBatches Integer The total number of batches. This will default to 1 unless changed in the Geopointe Actions setup page.
objectNameRecordIdsMap Map<String,Set<Id>> A map with the key as the object API name and a related Set of record Ids. This is most useful when there are many different types of objects on the map that need to be processed.
recordIds Set<Id> A set of record Ids that the action should be performed on.
urlParameters Map<String,String> A map of URL parameters from the map page when the Action is invoked.

geopointe.ActionResponse
This is the object you create with Apex and return to the Geopointe application. It controls how the page responds once the operation is complete. For example, show a message or redirect the user to a new page.

Property Name
Type
Description
message String If response action is MESSAGE this is the message that will be displayed to the user.
url String If responseAction is URL or MODAL_IFRAME this is the URL the map page will open.
responseAction geopointe.ActionReponse.ResponseAction enum Controls how the map page behavior when the action is completed. See section below for more detail.

geopointe.ActionResponse.responseAction
Below are the valid enum values when setting the responseAction property in the geopointe.ActionResponse object.

Value
Description
MESSAGE This will display a message to the end user.
MODAL_IFRAME This will open a modal iFrame with the supplied url value.
REDIRECT This will redirect the user away from the map page to a new page with the supplied url value.
REDIRECT_NEWWINDOW This will redirect the user to a URL and this URL will be opened in a new browser window/tab.

>> back to top

POST / Visualforce Actions

POST / Visualforce Actions allow you you to embed custom Visualforce pages inside the Geopointe Map page and interact with the mapped data. This allows you to truly extend and customize Geopointe to meet the unique business use cases of your company. The first step is to create a List Action on the Geopointe Setup page. It will look similar to this:

Make sure the Action Type field is set to “POST (Visualforce)” and the Link URL is the relative URL of the Visualforce page the search data should be POSTed to. The URL could also be an external page. When a user selects this Action the Geopointe application will construct a comma separated list of record Id values from the mapped data and it will POST it to the URL defined with a parameter key of “idArray”.

Important: Make sure to use the full URL path, not a relative URL. The different domains in which salesforce serves pages from can cause issues.

Below is an example controller for a Visualforce page that will receive the POST.

public class VisualforceActionController {
 
    Set idArray = new Set(); //Contains all of the record Ids sent from Geopointe
 
    //Constructor
    public VisualforceActionController(){
 
        //Retrieve the idArray parameter from Geopointe, split the Ids, and add them to a Set of Ids
        if(ApexPages.currentPage().getParameters().get('idArray') != null){
            for(String s : ApexPages.currentPage().getParameters().get('idArray').split(',')){
                idArray.add(s);
            }
        }
    }
 
   //Custom methods for Visualforce page below. Query records, update records, etc...
}

This Visualforce page can now use the idArray to query the record data and perform any type of advanced functionality supported by Visualforce pages.

>> back to top