Integrating and Routing Mobileforce Screens in Sugar

• Updated on Jul 11, 2024
• Published on Jul 10, 2024
• 6 minute(s) read

Introduction

MobileForce provides several modules (MobileForce_CPQ, MobileForce_FSM, and MobileForce_DSR), that allows one to embed MobileForce screens within SugarCRM. These screens are accessed by special URLs within the SugarCRM instance.

When one goes to one of these URLs within SugarCRM, the MobileForce module will open a SugarCRM screen that is nothing but an iframe displaying a MobileForce screen. The URL determines the MobileForce screen to display.

The URLs supported by the MobileForce modules are as follows:

• MobileForce_CPQ:
  • https://{sugar-instance-id}/#mfcpq_MobileForce_CPQ/{id}/{name}/{account_id}/{account_name}
  • https://{sugar-instance-id}/#mfcpq_MobileForce_CPQ_edit/{mobileforce_cpq_id_c}
  • https://{sugar-instance-id}/#mfcpq_MobileForce_CPQ_list/{id}
  • https://{sugar-instance-id}/#mfcpq_MobileForce/{query}
• MobileForce_FSM:
  • https://{sugar-instance-id}/#mffsm_MobileForce_FSM/{id}/{name}/{account_id}/{account_name}
  • https://{sugar-instance-id}/#mffsm_MobileForce/{query}
• MobileForce_DSR:
  • https://{sugar-instance-id}/#mfdsr_MobileForce_DSR/{id}/{name}/{account_id}/{account_name}
  • https://{sugar-instance-id}/#mfdsr_MobileForce/{query}

The URLs that are not of the form https://{sugar-instance-id}/#mfxxx_MobileForce/{query} are legacy URLs implemented before the SugarCRM router was implemented. Given that you can use the SugarCRM router is more powerful and can do anything that the legacy URLs could do, these legacy URLs are deprecated. This document will only cover the SugarCRM router URLs.

Router URL Syntax

All SugarCRM Router URLs are of the form https://{sugar-instance-id}/#mfxxx_MobileForce/{query} where mfxxx is either mfcpq, mffsm, or mfdsr, and {query} is a path that identifies what ADL screen to open as well as what parameters to pass to it.

The {query} part is a list of parameters used to determine which ADL screen to go to and which parameters should be passed to it. These parameters are encoded as path components. This was done to circumvent some limitations with SugarCRM URLs.

The {query} part can be one of the following formats:

• p/{screen-id}
• p/{screen-id}/a/{action}
• p/{screen-id}/a/{action}/sg/{sugar-obj-type}/{sugar-obj-id}
• p/{screen-id}/a/{action}/ec/{easyclm-obj-type}/{easyclm-obj-id}
• p/{screen-id}/a/{action}/id/{mf-datatable-or-cpq-id}

The query part is a composition of multiple subcomponents. The following subcomponents mean the following:

• p/{screen-id}: Go to the ADL screen with screen ID {screen-id}. If the screen ID does not have a portal (applet) ID, it will assume that the portal ID is Home.
• a/{action}: The action to perform on this screen. Common values are list, create, read or update. It is only supported for datatable, quote, or formconfig screens.
• sg/{sugar-obj-type}/{sugar-obj-id}: Read fields from the SugarCRM object whose table is named {sugar-obj-type} and whose object ID is {sugar-obj-id} and pass it to the datatable, quote, or formconfig screen. The fields that would be read are controlled by ADL properties, described later.
• ec/{easyclm-obj-type}/{easyclm-obj-id}: Read fields from the EasyCLM object whose table is named {easyclm-obj-type} and whose object ID is {easyclm-obj-id} and pass it to the datatable, quote, or formconfig screen. The fields that would be read are controlled by ADL properties, described later.
• id/{mf-datatable-or-cpq-id}: Pass the object ID mf-datatable-or-cpq-id to the ADL screen. This is only supported for read or update actions or for read or update ADL screens.

ADL Properties

The SugarCRM router supports several ADL properties. By convention, all SugarCRM router properties start with sugarroute-.

These ADL properties can be broken into categories; properties that configure what is passed to the ADL screen, and ADL properties that specify hooks that can be called to customize router behavior.

ADL Screen Properties

• sugarroute-{action}-{obj-type}-field-{mf-field-name}: The name of the SugarCRM or EasyCLM field to set the given MobileForce field to. If the value is two field names separated by a comma, then it is assumed that the first field is for reading the key value and the second is for reading the value value of a key/value pair.
• sugarroute-{action}-{obj-type}-action: If set, this ADL property changes the action passed on to the ADL screen. This is useful if you wish to create a dummy action that uses different ADL properties than the default.
• sugarroute-{action}-{obj-type}-id: Name of SugarCRM or EasyCLM field to read the row ID from.
• sugarroute-{action}-{obj-type}-filter: Name of forconfig/cpq summary table filter to use.

ADL screen parameters

The SugarCRM router passes parameters to ADL screens via the params parameter. The params parameter is a standard parameter supported by ADL webui screen. The value of the screens parameter is a JSON object. The fields supported in the JSON object vary based on the ADL screen type.

Here are the fields of the params parameter that are set by the SugarCRM router:

• action: Action to perform in the screen.
• id or rowId: ID of object to perform a read or update action on.
• filter: Name of the quote or form-config filter to use in the list screen.
• form: An associative array of fields to set and their values.

Examples

Here are some examples of ADL screen properties:

<prop key="sugarroute-create-Opportunities-field-account">account_name</prop>
<prop key="sugarroute-create-Opportunities-field-opportunity">id,name</prop>
<prop key="sugarroute-list-Opportunities-field-opportunity_id">id</prop>

Hook Properties

The following ADL properties are supported for SugarCRM routes:

• sugarroute-route-hook: Hook called whenever the SugarCRM router is called. This can be used to build a custom screen for a particular route URL.
• sugarroute-{action}-{obj-type}-params-hook: Hook called to generate parameters to pass to an ADL screen for the given action and object type. This overrides the default code for generating ADL screen parameters.
• sugarroute-{action}-params-hook: Hook called to generate parameters to pass to an ADL screen for the given action type and any object type. This overrides the default code for generating ADL screen parameters.
• sugarroute-params-hook: Hook called to generate parameters to pass to an ADL screen for any action and object type. This overrides the default code for generating ADL screen parameters.

Hook URL Endpoints

One can customize the behavior of a SugarCRM route via hooks. A hook is a HTTP URL.

Hook request parameters

Hooks are invoked using a HTTP POST. The parameters passed to the hook are;

• account: MobileForce account name
• app: MobileForce app name.
• i: SugarCRM instance.
• q: The {query} part of the SugarCRM URL used to call the router.
• sg-username: SugarCRM user-name
• sg-display_name: SugarCRM user full name
• sg-email: SugarCRM user email-address
• sg-accessToken: SugarCRM OAuth access token
• sg-refreshToken: SugarCRM OAuth refresh token
• sg-downloadToken: SugarCRM download token

Hook response

Hooks must return a JSON object. This JSON object can have the following parameters:

• type: (required) Error status of the hook. Should be ok on success.
• message: If the hook failed, this is the error message that should be displayed to the user.
• url: For the sugarroute-route-hook, this contains the URL of the screen to display in SugarCRM.
• screenParams: The ADL screen parameters to pass to the ADL screen. This is only used for the -params-hook hooks.

Mapping of SugarCRM instances to MobileForce accounts.

The SugarCRM router determines the MobileForce account to app to use for a SugarCRM instance from the AccountAppLookup table in the mobileforce.fmaccounts database. Unlike the legacy SugarCRM instance.php script, it does not use the customers/sugarcrm/instance.ini file.

The AccountAppLookup table also has a host column. If this column is not null, the SugarCRM router will redirect to the corresponding SugarCRM router on the server with the given hostname. You can use this hostname field to redirect SugarCRM calls to a different MobileForce deployment, such as our European (apps-eu) or sandbox (apps-sandbox) deployments.

Implementation notes

This section describes the reasons why the SugarCRM router is implemented the way it is.

Why doesn't the SugarCRM route URL accept form fields or object names in its URL?

SugarCRM has several flaws with its module URL syntax. First, SugarCRM does not URL-escape any expanded macro variables in its URLs. Because of this, our module URL will break if you macro expand a variable that has a space or a URL unsafe character such as ampersand (&).

Second, SugarCRM does not properly handle URLs that are longer than 255 characters after macro expansion. Third, SugarCRM uses hash fragments, (e.g., #mfcpq_MobileFore...) for determining the module to call. You cannot include HTTP query parameters after the hash fragment.

Because of these issues, we were forced to implement an indirect means for passing SugarCRM object fields to MobileForce. Rather than passing them directly from SugarCRM via the URL, we instead just pass the object ID in the URL, then read the fields for that object from our router. The fields that need to be read and passed are determined from sugaroute- ADL properties.