SugarCRM SupportDocumentationMobile SolutionsMobile Application Configuration ServiceMobile Application Configuration Service User Guide

Mobile Application Configuration Service User Guide

Overview

SugarCRM's Mobile Application Configuration Service (MACS) enables eligible users to create custom-branded versions of the SugarCRM Mobile app. OEM partners, implementation partners, and customers can customize the mobile app to promote their own brand and have more control over distribution. The customized app can be deployed via the Apple App Store and Google Play Store or via a private app store for increased security and ease of distribution.

MACS offers the following features and functionality:

  • Build a custom app that re-brands the SugarCRM Mobile application with your personalized logo and color theme.
  • Preset your Sugar instance configurations and settings in your new app.
  • Generate a binary that can then be deployed via different mobile device management tools (e.g MobileIron or AirWatch), a private app store, or a public app store (Google Play Store or Apple App Store).
  • Upon future releases of SugarCRM Mobile, download and redistribute updated versions of your customized app.

Prerequisites

To use MACS, you must belong to one of the following authorized user groups:

  • Customers running Enterprise or Ultimate editions of Sugar 7.7 or higher
  • SugarCRM's OEM partners for use and distribution with their authorized OEM solution

Note: SugarCRM partners who are creating a re-branded mobile app for a customer must log in and make the necessary changes directly in the customer's account. Partners are not authorized to create and store customer apps under their own Sugar account.

Eligible users must have the following requirements in order to use MACS:

  • Experience in distributing mobile applications
  • A development account with Apple and Google in order to allow app distribution
  • An active account on SugarCRM.com

We also recommend that you familiarize yourself with your Android and Apple developer accounts beforehand in order to generate a provisioning profile, certificate, and signing key.
Note: A partner or developer can generate a binary for you, however, you must use your provisioning profile and certificates for the production release.

Accessing the Configurator

Once the above items are confirmed, log into your SugarCRM.com account then either navigate to the Mobile Tools Portal page or to the Download Manager page and select "Mobile Tools" from the dropdown.
MACS MobileTools Download

Once you are in the Mobile Tools Portal page, ensure "Mobile Application Configuration Service" is selected in the top bar's dropdown menu.
MACS

The other dropdown option allows mobile developers to download Sugar's Mobile SDK, which is currently in Beta.
MobileSDK

Configurator List View

The Mobile Application Configuration Service list view shows all apps created by users in your account. From this page, you can create a new app as well as view details and take actions on existing apps.
MACS listView2

The list view offers the following information and actions for existing apps:

Column Description
User The user who created this app
Application Name The name of the app
Mobile SDK Version The SugarCRM Mobile version the app is based on
Status The status of the most recent build:
  • Blank : No builds have been created for this app.
  • Grey cross-out : The build was canceled.
  • Red exclamation mark : The build failed.
  • Green check mark : The build completed successfully.
Latest Build The app version most recently built
Note: Click the version to view build details to the right of the page. If the build was successful, it can be downloaded from below the list of details.
Builds The total count of builds that have been created for the app
Note: Click the number to see the app's list of builds where you can also check the status of a build and download completed builds.
Actions If one or more required fields are missing for the app, the following options will be available:
  • Continue : Resume creating the app.
  • Delete : Remove the app.
Once all required fields are completed for the app, the following options will be available:
  • Edit : Modify the app's configurations.
  • Create Build : Create a new version of the app.
  • Delete : Remove the app.

Creating and Editing an App

With "Mobile Application Configuration Service" selected in the top bar's dropdown menu, you can begin building your app by clicking the Create New App button above the list of apps.
MACS CreateNew

App Customization

The first step in building your app is to customize its skin (e.g Name and Logos). The App Customization page allows you to configure the following items:

  • Application Platform : Select the platform(s) on which your app will be used (i.e. iOS or Android devices).
    Application Platform MACS
  • Name : Enter the name that will appear under the app icon on the device's home screen. The name can be up to 20 characters long, but 11 or fewer characters is recommended to ensure it is displayed in full. 
    MACs Name
  • Logos : Drag and drop your logo image file into the appropriate boxes for the iOS and Android app icons, as well as the image file for your company logo which will be used inside the app.
    MACS Logos
    Note: The image must be in a Scalable Vector Graphics (SVG) format with a minimum size of 256 x 256 pixels. For best image quality throughout the app, you must create the SVG image using Adobe Illustrator or another scalable vector graphics tool. 
  • Splash, Login, and Loading : Select the desired background colors for the login, splash, and loading screens.
    MACS SplashLoginLoading
  • Login Button : Select the desired background and font colors for the login button. 
    MACS LoginButton
  • Navigation : Select the desired background, font, icon (e.g. plus icon), and navigation link (e.g. Cancel and Save) colors for the headers inside the app.
    MACS Navigation AppCust
  • About : Enter the appropriate values for the fields below. Please note that this information will appear on the app login screen and the About page.
    • Sugar Instance URL : Enter your Sugar instance URL if you wish to pre-populate this field on your users' login screen.
      Note: "http://" can be included or left off without effect, but be careful to only include "www." if this is included when accessing your instance from a desktop browser.
    • Show Server URL : Check this box if you wish to display the Sugar instance URL field on your users' login screen.
    • Enable SSO : Check this box if your Sugar instance is configured to allow single sign-on authentication. 
    • Support URL : Enter the URL that will link users to your organization's support site via the login screen and About page.
    • Privacy Policy : Enter the URL that will link users to your organization's privacy policy via the login screen and About page.
    • Terms and Conditions : Enter the URL that will link users to your application's terms and conditions via the login screen and About page.
    MACs About
  • OEM-specific fields : If you are an OEM customer, the Privacy Policy and Terms and Conditions fields will not appear in the About section until you first complete the Unlock Key field.
    About UnlockKey MACS
    Simply click the "I have an unlock key" link then enter your company's unlock key code. If you do not know the unlock key code, please reach out to your SugarCRM contact for the OEM program. The Privacy Policy and Terms and Conditions fields will now appear in the About section for you to complete. In addition to these fields, the following fields will be available to configure:
    • Show "Powered by SugarCRM" : Check this box if you wish to display "Powered by SugarCRM" on the splash screen of your app.
    • Trademark Text : Enter the trademark text that you would like to display at the bottom of the About page.
      AdditionalAboutFields OEM

As you hover over or populate any fields on the App Customization page, the Help panel on the right will display a preview of the customized layout using the color, font, image, etc. you have defined. In addition, the Help panel provides information regarding the current field.
MACs AppTemplate

When you are satisfied with your changes, click "Update and Close" at the bottom of the page to preserve your changes and return to the list of apps. If you wish to continue to the next page, simply click "Next".

General Settings

The General Settings page connects MACS to your Apple and/or Google developer accounts so that you can successfully distribute the new mobile app via your chosen means. If you do not have an Apple or Google developer account or require assistance with the account, please contact your IT department or the team responsible for distributing the mobile app for your company. 

The following fields in the Package Names section must be populated before you can successfully create and distribute an app via MACS. For more information on acquiring the items discussed in this section, please refer to the App Signing for MACS article.
Note: If you selected "iOS App Only" or "Android App Only" as the Application Platform on the App Customization page, only some of the following fields will appear.

  • iOS bundle ID : Enter the iOS bundle ID, which must be registered with Apple. This ID identifies your application in the App Store and allows Apple to recognize any updates made to your app in the future.
    Note: This is a required field and cannot be altered after uploading the first build to the App Store.
  • iOS Distribution Certificate : Drag and drop your iOS distribution certificate file into this field. The file must be in .p12 extension format and is required for distributing the app. Please note that Apple has strict guidelines on distribution, therefore, it is recommended that you be familiar with iOS distribution guidelines prior to using MACS. For more information, please refer to Apple's App Distribution Guide
    Note: If you add an iOS Distribution Certificate, then you must also add an iOS Provisioning Profile. If you are only testing the app, it is recommended you do not add either of these items.
  • iOS Provisioning Profile : Drag and drop your iOS provisioning profile file into this field. This file is required for distributing your app. Please note that you are required to download a distribution profile for each new app via the Apple developer portal
    Note: If you add an iOS Provisioning Profile, then you must also add an iOS Distribution Certificate. If you are only testing the app, it is recommended you do not add either of these items.
  • Note: If this field is left empty, the binary will automatically be signed with a placeholder profile. However, you must re-sign the binary with your own profile prior to distributing the app.
  • Android Package Name : Enter your Android package name. This identifies your app in the Google Play Store.
    Note: This is a required field and cannot be altered once you have published the app in the Google Play Store.
  • Android Signing Key : Enter your Android signing key.
    Note: If this field is left empty, the binary will automatically be signed with a placeholder key. However, you must re-sign the binary with your own key prior to distributing the app.
    MACs PackageNames 

Note: The first time you compile your app on MACS, it is recommended to only provide the iOS bundle ID and Android package name in the Package Names section. While you will not be able to distribute your app without providing the certificate and profile information, leaving these off will allow you to confirm that you are able to successfully compile your app.

When you hover on or populate any fields on the General Settings page, the Help panel on the right will display additional information regarding the field and what it represents, along with any important notes.
MACs GenSet Help

Once you have populated all of the required fields, click "Update and Close" at the bottom of the page to preserve your changes and return to the list of apps. If you wish to continue to the next page, simply click "Next".

Build Creation 

Now that MACS is connected to your Apple and/or Google developer accounts, you can update the version details for your app and finalize the build.

The following fields must be populated before you can successfully create the build:

  • Mobile SDK Version : Select the version of SugarCRM Mobile from which you want to build your app. It is recommended to always use the latest release to take advantage of recent enhancements and fixes.
  • Subscription : Enter the Enterprise or Ultimate subscription key for your Sugar instance. If you have a developer or partner account and are creating the app for your customer, you will need to enter the customer's subscription key in order to prevent the app from timing out after 30 days.
  • Version : Enter the version number for your app (e.g. 1.0.3).
  • iOS Distribution Certificate Password : Enter the password for your iOS distribution certificate.
    Note: This field will only appear if an iOS distribution certificate is attached via the General Settings page.
  • Android Signing Key Password : Enter the password for your Android signing key.
    Note: This field will only appear if an Android signing key is attached via the General Settings page.
    MACS BuildCreation Fields2

When you hover over or populate any fields on the Build Creation page, the help panel on the right will display additional information regarding the field and what it represents.
MACS BuildCreation CreateAppButton

To finalize and build the new app, simply click the Create App and Build button at the bottom of the page. Please note that depending on the size of your binary, this process may take a few minutes to complete. You can view the build's progress via the progress wheel displayed in the Status column on the list of builds. 
MACs BuildStatus

Distributing the App

With the new app successfully created, it is now time to distribute the app to your users. We strongly recommend that your company designates an individual or team to manage the app distribution as the app will need to be updated on a regular basis, whenever new versions of SugarCRM Mobile are released, as described in the Maintaining the App section below.

Downloading the App

Before the app can be successfully distributed to your users, you must first download the app from MACS using the following steps:

  1. Navigate to your list of apps.
  2. Locate the desired app and click the build count (e.g. 4) to view the list of available builds for the app. 
    MACS clickBuildCount
  3. Click the appropriate link(s) (e.g. android or ios) on the far right of each build's row to begin downloading the build to your local machine. 
    MACS DownloadApp

Once the download completes, you can distribute the app to your users.

Distribution Methods

Once the app is successfully downloaded to your computer, you can begin distributing it to your users. There are three methods you can use to distribute your app:

  • Via your preferred mobile device management solution
  • Publicly via the App Store or Google Play Store
  • Privately via your internal Enterprise store
    Note: If you wish to distribute via your internal Enterprise store, please reach out to your company's IT group. 

Distributing to iOS

This section will cover the different ways you can distribute your iOS app. It is important to note that the iOS distribution method depends on your Apple developer account type. Before distributing your app to iOS it must be digitally signed as described in the App Signing for MACS article.

Distribution Type Distribution Methods
Development 
  • Install the app via iTunes or Xcode
Beta Testing 
  • Distribute via Apple TestFlight
  • Distribute via HockeyApp for iOS
  • Distribute via other services similar to HockeyApp 
Production
  • Distribute via MDM vendors (e.g. MobileIron and AirWatch) 
    Note: This distribution method requires an Enterprise Apple dev account.
  • Distribute privately via internal Enterprise stores
    Note: This distribution method requires an Enterprise Apple dev account. If you wish to distribute via your internal Enterprise store, please reach out to your company's IT group.
  • Distribute publicly via the Apple AppStore
    Note: This distribution method requires either an Enterprise or Individual Apple dev account.

The iOS distribution certificate and provisioning profile must be entered via the General Settings page and the certificate password must be entered via the Build Creation page prior to downloading the app.

Before you can distribute via the App Store, you must have a production certificate, a registered App ID, and a distribution provisioning profile. For more information on completing these steps, please refer to the App Signing for MACS article. The app must also be approved by Apple before it becomes available in the store. Because of the pre-approval process, customers building iOS apps for their own, internal use may not wish to rely on the App Store for distribution. Once approved, the app will then be available to download from the Apple App Store. An alternative is to use the Apple iOS Developer Enterprise Program, however, this does require an annual subscription. 

Note: In order to deploy your app into the public App Store, you must abide by the SugarCRM Terms of Service and Privacy legal agreements. Please contact the Sugar legal team in order to have the app content reviewed before production deployment.

Distributing to Android 

This section will cover the different ways you can distribute your Android app. Before distributing your app to iOS it must be digitally signed as described in the App Signing for MACS article.

Distribution Type Distribution Methods
Development 
  • Send the app via email
  • Upload the app to a cloud service (e.g. Dropbox) and access it via Android device 
  • Install the app via Android SDK command-line tools
    Install the app via an Android SDK emulator (e.g. Genymotion)
  • Distribute via email, website download, or a cloud service
    Note: Please refer to Android's Alternative Distribution Options article for more information on distributing via their open platform.  
Beta Testing 
  • Distribute via HockeyApp for Android
  • Distribute via other services similar to HockeyApp
  • Distribute via email, website download, or a cloud service
    Note: Please refer to Android's Alternative Distribution Options article for more information on distributing via their open platform.  
Production
  • Distribute via MDM vendors (e.g. MobileIron and AirWatch)
  • Distribute via email, website download, or a cloud service
    Note: Please refer to Android's Alternative Distribution Options article for more information on distributing via their open platform.  
  • Distribute privately via internal Enterprise stores
    Note: If you wish to distribute via your internal Enterprise store, please reach out to your company's IT group
  • Distribute publically via the Google Play Store

The signing key must be entered via the General Settings page and the signing key password must be entered via the Build Creation page prior to downloading the app. For more information on generating a private key, please refer to Oracle's Key and Certificate Management Tool article.

Note: In order to distribute your app via the Google Play Store, you must abide by the SugarCRM Terms of Service and Privacy legal agreements. Please contact the Sugar legal team in order to have the app content reviewed before production deployment.

Distributing via Mobile Device Management

Mobile device management is implemented via a third party product (e.g. MobileIron or AirWatch) that provides management features for mobile devices. It enables you to remotely push apps to devices for instant installation, remotely push updates, and remotely remove apps. 

Please note that MACS currently only supports app wrapping as a mobile device management solution. App wrapping allows you to embed security (e.g. encryption code) and control capabilities into your app without accessing the app's source code.

Every vendor may have different requirements for app wrapping, however, most require the following items:

  • An iOS mobile app .ipa file or Android .apk file
  • iOS and/or Android Distribution Provisioning Profiles
  • iOS Distribution Certificate or Android Signing Key

Maintaining the App

Once a new app is created, it will need to be maintained on a regular basis. To do this, you will need to create a new build for your existing app which will then be distributed to your users as an update. There are two main situations where you would need to create a new build:

  • A new version of SugarCRM Mobile has been released.
  • You have made changes to the custom app via MACS.

Use the following steps to create a new build in MACS:

  1. Navigate to the list of apps and click "Create Build" to the far right of the desired app's (e.g. Ace of Spade) row.
    MACS CreateBuildLV
    Alternatively, you can also click the app's build count (e.g. 3) then click "Create Build" above the list of builds. 
    MACs CreateBuild MainApp
  2. Enter the appropriate values in the fields on the Create Build form.
    • Mobile SDK Version : Select the latest production version of the SugarCRM Mobile app.
    • Subscription : Enter the Enterprise or Ultimate subscription key for your Sugar instance. If you have a developer or partner account and are creating the app for your customer, you will need to enter the customer's subscription key in order to prevent the app from timing out after 30 days.
    • Version : Enter the new version of your app (e.g. 1.0.3). 
    • iOS Distribution Certificate Password : Enter the password for your iOS distribution certificate.
      Note: This field will only appear if an iOS distribution certificate is attached via the General Settings page.
    • Android Signing Key Password : Enter the password for your Android signing key.
      Note: This field will only appear if an Android signing key is attached via the General Settings page.
  3. Click "Start Build" to begin the process. Please note that the build may take a few minutes to complete.
    MACS NewBuild wSubKey

You can easily monitor the process by navigating to the app's list of builds and viewing the progress wheel in the Status column. When the build is successfully completed, a green checkmark icon will display in the build's Status column. At this point, you will need to download and distribute the updated version of your app.
MACs BuildStatus 

Last modified: 03/10/2017 03:00pm

Back to top Contents