Page tree
Skip to end of metadata
Go to start of metadata

 
This page provides information to help diagnose and fix issues that may arise for your end users working with the App Catalog, or you and other EASE administrators working in the EASE Portal.

Issues for App Catalog Users

Before you Begin

If you are troubleshooting an App Catalog issue with a user or contacting Apperian Customer Support for assistance, it is helpful to know the version number of the catalog currently installed on the device. A user can check this by tapping on the Profile button at the top of the catalog to display the side menu; the version number is listed next to the organization name.

Once you know the version of the user's catalog, you can compare it with the version number of the catalog currently uploaded to your EASE organization. Find the version number in EASE by hovering over the catalog icon on the Applications page. 

Installing Applications

IssueTroubleshooting

User sees an Unable to Download App message when trying to install an app or an app update from the App Catalog.

 

Check for these possible issues:

  • Entitlement Mismatch: There may be a mismatch between entitlements in the app and entitlements in the distribution provisioning profile with which the app was signed. It is important that you sign with a distribution provisioning profile that has entitlements that match the entitlements built into the app. If the app includes app extensions, each of those extensions must be signed with a different provisioning profile that has the correct entitlements. You can check for this by re-signing the app with the Signing Server using "New Credentials." When you sign with new credentials, EASE will compare the entitlements in the app and the provisioning profile(s) and highlight any issues. For instructions, see Sign with New Credentials.
     
  • Certificate/Provisioning Profile Mismatch: The app may be signed with a mismatched distribution certificate and distribution provisioning profile. When you upload signing credentials to EASE, you upload the .p12 file for your organization's enterprise distribution certificate and a distribution provisioning profile. When the provisioning profile was created in the Apple Developer Portal, it was associated with an distribution certificate. If you sign the app through EASE with a certificate that is not the one associated with the provisioning profile, then the user will not be able to install the app. Try re-signing the app with your enterprise distribution certificate and a matching distribution provisioning profile.

    As a best practice, you should have only one enterprise distribution certificate for your organization and all provisioning profiles should be associated with that certificate. This avoids the situation where an app is signed with a certificate and provisioning profile that do not match. If you do create more than one certificate in the Apple Developer Portal (for example, when you create a new certificate because the current one is due to expire), give the certificates unique names so they can be easily distinguished.

    _

  • Ad Hoc Provisioning Profile: The app may be signed with an Ad Hoc distribution provisioning profile and the user may be trying to install it on a device that is not provisioned via that Ad Hoc profile. When an app is distributed "Ad Hoc," the app is listed in the App Catalog for all users with group access to the app—regardless of whether the user's device is in the list of provisioned UDIDs. If the user's device is not provisioned, however, when the user clicks the Install button, the app will download and start to install, but the operating system will terminate the installation and display the message to the left. This scenario is less likely since Ad Hoc certificates are not used when distributing apps throughout an enterprise, but the app may have been signed when it was first distributed to a limited user group (such as during a test phase) and has not yet been re-signed.
     
  • App Store Provisioning Profile: The app may be signed with an App Store distribution provisioning profile. Applications built or signed with an App Store distribution provisioning profile will upload successfully to EASE, but will not install on a device until they are resigned with either an Ad Hoc or In House distribution provisioning profile. When the user taps the Install button, the app will download and start to install, but the operating system will terminate the installation and display the message to the left.
     
  • Wrong Form Factor or OS: In EASE, the app may be set to run on a certain form factor only, or the user is on a device running an operating system that does not meet minimum OS requirements for the app. These conditions will block an app from being displayed in the App Catalog, but if the user tries to install via a Direct Install link, the user will see the "Unable to Download App" message.

  • Different Distribution Provisioning Profile: The user is trying to install an update of an app that is signed with a different provisioning profile than the currently installed version. iOS will not overwrite an app with an app that has a different provisioning profile. This issue occurs when a provisioning profile has expired and an administrator in the Apple Developer Portal creates a new provisioning profile for the app rather than edits the expired profile to generate a new version. For instructions, see Editing a Distribution Provisioning Profile.
    _

Installing an update from the App Catalog installs a second app rather than updating the existing app.

Check that the app was re-signed with the same signing credentials used to sign it previously. If you re-sign an app with different signing credentials, then the device will see it as a different app and install a new app rather than update the app that is already installed.

With iOS apps, note that if the App ID in the distribution provisioning profile you use for signing does not match the bundle ID of the app, EASE will automatically modify the bundle ID in the app to match the App ID in the provisioning profile. If you are not sure if you are signing with the correct provisioning profile, you can "Sign with New Credentials" so that EASE will highlight any App ID/bundle ID mismatches.

The following example shows a mismatch between the app's bundle ID and the provisioning profile App ID. If this app is signed with this provisioning profile, EASE will modify the app's bundle ID to match the App ID from the profile. While this is a convenient feature, it can cause a problem if the app had already been distributed to users with the original bundle ID. When a user installs the update that has a different bundle ID, iOS will install this update as a new app on the device.

Running Applications

IssueTroubleshooting

App crashes when the user tries to run it.

Expired Signing Credentials

The app may be expired. When an app "expires," it means that the credentials used to sign the app have expired. This could mean something different depending on the type of app.

  • With Android and Windows Phone apps, an "expired app" means that the certificate used to sign the app has expired. With Android apps, this is rare since the the certificate's private key typically has a validity period of 25 years or more to ensure that an app can be used and updated for the lifespan of the app. Therefore, you will not typically need to re-sign an Android app because it has expired. Windows Phone enterprise certificates typically expire after one year. When an app's certificate expires, the app will fail to run on the device. EASE does not currently notify an EASE Administrator when a Windows Phone app is due to expire, nor does it highlight expired apps on the Applications page.
     
  • With iOS apps, an "expired app" means that either the certificate or the distribution provisioning profile used to sign the app has expired. If the app includes extensions and is therefore signed with multiple provisioning profiles, EASE bases the expiration date on the date of the certificate or provisioning profile due to expire the soonest. Apple distribution certificates expire after one to two years, and distribution provisioning profiles expire after one year. When an iOS app is signed with an expired certificate or profile, users cannot install the app from an App Catalog or run the app if it was already installed. Apperian notifies EASE Administrators about iOS apps due to expire so that the apps can be re-signed with valid credentials before they expire. Notification emails are sent 60 days before an app expires, 45 days before, 30 days before, and then every day until the app either expires or is re-signed with current credentials.

When an app expires, you need to re-sign it and deploy the newly signed version of the app to your users. When you re-sign an iOS app through EASE, you can select the "Notify users about the update" option to send a Push Notification to the devices of all users who have already installed the app. (Push notifications are not yet supported with the Windows Phone App Catalog.)

For instructions on checking the expiration date of certificate used to sign an app, see Signing FAQ.
 

Problem with the Application

If the app's signing credentials have not expired, then there may be a problem with the application itself. When an application crashes, a crash report is stored on the device. This crash report is a useful tool for debugging issues with the application.

 

 (iOS) Click here for instructions on getting a crash log directly from a device without Xcode

To collect a crash report from a device, ask the App Catalog user to follow these instructions:

  1. Open Settings.
  2. Go to Privacy->Diagnostics & Usage.
  3. Tap Diagnostics & Usage Data.
  4. Locate the report for the crashed app. The reports will be named in this format: <AppName>_<DateTime>_<DeviceName>
  5. Tap the desired report to display it. 
     
  6. Using the text selection UI, select the entire text of the report. Once the text is selected, tap Copy.
  7. Paste the copied text into an email and send it to your EASE administrator.


If you wrap your apps with the Collect Crash Reports policy, you won't have to worry about collecting reports from your users: EASE will do it for you. When an app that is wrapped with the Collect Crash Reports policy crashes, EASE collects the crash report from the device. (With Android, this happens at the time of the crash; with iOS, it happens the next time the app is opened.) EASE lists all the reports it has collected for an app on the Crash Reports tab of the app’s details page. From that list, you can view reports and export reports to send to developers for further analysis. For instructions on applying the Collect Crash Reports policy to an app, see Apply Policies to an Application.

For help understanding and analyzing iOS application crash reports, see the iOS Developer Library.

User sees an "Untrusted Enterprise Developer" message when they try to run an app installed from the App Catalog.

This is a standard iOS alert and does not indicate an issue. Before iOS runs any app that was not installed through the Apple App Store, it requires confirmation that a user trusts the source—the “Enterprise Developer”—of the app. The source of an app is determined by the enterprise distribution certificate used to sign the app. Once a user has trusted an Enterprise Developer, the user can then run any app that was signed with the same certificate—without having to trust the developer again. 

For instruction on the steps required to trust an enterprise developer, see Apple's support article: Install custom enterprise apps on iOS

Because the App Catalog is typically the first of your apps that your users will download to their devices, Apperian displays a note on the App Catalog download page. This note provides instructions for trusting the enterprise developer and displays an animated image that illustrates the steps. 

As a best practice you should sign the App Catalog and all of the apps distributed through it using the same enterprise distribution certificate. Things will still work when apps are signed with different certs, but it adds extra steps for end users since they will need to trust multiple Enterprise Developers.

The spinner does not display when the wrapped app is launched and I am not sure if policies are being evaluated.

 

By default, EASE evaluates most application's policies whenever the user opens the app, brings it to the foreground, or returns to it from a locked screen. (With some policies, EASE does not count multiple launches within a minute. These exceptions are described in the policy descriptions in Application Policies.) When evaluating policies, EASE blurs the app screen and displays a spinner. To the user, this looks like part of the process of starting the app, and it is typically quite fast—sometimes the user will not even notice the spinner. Evaluation speed, however, can be influenced by the device's network connection speed. 

If you are never seeing the spinner and are not sure if policies are being evaluated, you should check the Policy Evaluation Frequency for your organization. This setting can be customized from the EASE Portal Settings page under Policy Evaluation Frequency. If the policy evaluation frequency is changed to anything but Always and a user launches an app or brings it to the foreground before the set time has passed, then the app will not be evaluated and there will be no spinning wheel. Once the amount of time you set has passed, the app will again be evaluated when it is launched or brought to the foreground. To ensure an app is evaluated and a spinning wheel displays every time a wrapped app is launched or brought to the foreground, make sure that Always is selected.

For instructions on checking the Policy Evaluation Frequency, see Set the Policy Evaluation Frequency.

Listing Applications in the App Catalog

IssueTroubleshooting

User is not able to see an app listed in the App Catalog.

 

There are a few reasons why an app may not show up in the App Catalog:

  • App is disabled: If you add a new application to the EASE Portal from the Add New Application page and the Enabled checkbox is not checked, the newly added application will remain disabled until you enable it. This may also occur if you sign the app from the Signing tab on the EASE Portal without selecting the Enable app checkbox to automatically enable the app to users after it is signed. You can enable the app from the Edit Application page at any time. For instructions, see Disable or Enable an Application.

  • User does not have permission to access the app: The user may not belong to a group to which the app is assigned. To edit a group to modify its membership, see Edit a Group
     
  • User's device does not meet system requirements: If any of the following conditions are true, then the app will not display in the catalog:

    • The user is on a device of a different platform type than the app. For example, the user is on an iPhone and the app is an Android app. If possible, ensure that you have versions of a application for all device platforms you support within your organization. 
       
    • The user is on a device running an operating system that does not meet minimum OS requirements for the app. If possible, the user should upgrade to a more recent version of the OS. 
       
    • The app is an Android multidex app and the user is on a device running Android 4.x. EASE supports multidex apps on Android 5.x and higher only.
User sees the App Catalog listed as an app in the App Catalog.If there is more than one App Catalog of the same OS type uploaded to the same organization and both are enabled, then the App Catalog that was uploaded second will be seen as a normal application and will be displayed in the All tab of the App Catalog. To remove the second App Catalog you can either delete or disable the app. You can delete the app by clicking the Delete button under the specific app on the Applications page of the EASE Portal. You can disable the app by clicking the Edit button under the specific app on the Applications page of the EASE Portal, expanding the Application section, and unchecking the box labeled Enable.

Users see this message on the Popular page of the App Catalog:

 

At the top of the Popular apps page in the App Catalog, users can browse a collection of featured applications selected by you or another EASE Administrator. If you don't select any applications to feature in the App Catalog, users will see the "No Features Apps" message shown to the left.

For instructions on featuring apps in the App Catalog, see Select Featured Apps for the App Catalog.

Receiving Push Notifications

IssueTroubleshooting

iOS device user is not receiving push notifications

 

Check for the following:

  • Is Push Notification enabled for the App Catalog and is a valid Production Push SSL Certificate uploaded to EASE? For more information, see Enable Push Notification for an iOS App Catalog.
     
  • Has the App Catalog user already logged in to the App Catalog and installed the app that was updated? Users receive push notifications only for updates of apps that they already installed.
     
  • Did the user choose to allow the App Catalog to send notifications? When a user first launches the App Catalog, he/she is prompted to allow the app to send notifications. Unless the user taps Allow, the user will not receive any push notifications from the App Catalog.
     

  • (With application update notifications) Did the EASE administrator specify that users should be notified about the update? This can be done when uploading a new version on the Edit Application page or when signing a new version on the Signing tab. If a new version of an application needs to be signed before it is distributed and it is being signed through EASE, then typically an administrator will not choose to notify users when editing the app but will choose to notify users when signing the app.
     

     Click here to see the options to notify users when editing or signing an app...

Android device user is not receiving push notifications

Check for the following:

  • Is Push Notification enabled for the App Catalog? For more information, see Enable/Disable Push Notification for an Android App Catalog.
     
  • Has the App Catalog user already logged in to the App Catalog and installed the app? Users receive push notifications only for updates of apps that they already installed.
  • Did the user choose to allow the App Catalog to send notifications? Unlike on iOS where the user has to choose to allow the App Catalog to send notifications, on Android this happens by default. The user can, however, choose to hide notifications on the device or block them for a specific app. If a user is not seeing push notifications on an Android device, ask the user to check the notification settings.

  • (With application update notifications) Did the EASE administrator specify that users should be notified about the update? This can be done when uploading a new version on the Edit Application page or when signing a new version on the Signing tab. If a new version of an application needs to be signed before it is distributed and it is being signed through EASE, then typically the administrator will not choose to notify users when editing the app but will choose to notify users when signing the app.
     

     Click here to see the options to notify users when editing or signing an app...

Issues for EASE Administrators

Uploading Apps to the EASE Portal

 

IssueTroubleshooting

Administrator sees this message when trying to upload an app to the EASE Portal:

AppID: The team identifier doesn't match the value in the embedded.mobileprovision. This app may not install.

The team Identifier in the application you are attempting to upload does not match the team identifier defined in the embedded.mobileprovision file bundled with the app. EASE will still sign the application, but it is unlikely that users will be able to install the application on their devices from the App Catalog.

To solve this issue, you should use EASE to re-sign the application. When you re-sign the application, EASE will automatically modify both the team ID and bundle ID of the app to match the App ID associated with the distribution provisioning profile used to sign the app.

Note that re-signing the app will fix a mismatch between the team ID/bundle ID and the provisioning profile, but if there are entitlements in the app that do not match the entitlements in the provisioning profile, the app will not install on a user's device. You can check for this by re-signing the app with the Signing Server using "New Credentials." When you sign with new credentials, EASE will compare the entitlements in the app and the provisioning profile(s) and highlight any issues. For instructions, see Sign with New Credentials. For more information on entitlements, see App Extensions and Entitlements.

Administrator sees this message when trying to upload an app to the EASE Portal:

Distribution: development profile found

The application you are attempting to upload to the EASE Portal is signed with a development provisioning profile instead of a distribution provisioning profile. An app signed with a development provisioning profile can still be uploaded to EASE without issue, but should be signed with a distribution certificate and distribution provisioning profile before it is distributed to your users.

For information on the difference between development and distribution provisioning profiles, see Signing FAQ.

Administrator sees this message when trying to upload an app to the EASE Portal:

"App type" File: this application is expired

The certificate used to sign the application you are attempting to upload is expired. An expired application can still be uploaded to EASE with no issue, but before it can be distributed to your users, the app must be re-signed with a valid distribution certificate and distribution provisioning profile.

For instructions on generating distribution certificates and provisioning profiles, see iOS Certificates, Identifiers, and Profiles. For instructions on signing an app through EASE, see Sign an Application.

When uploading a native application to the EASE Portal, the app is not associated with an app icon.

Typically, a native application will have an icon image file bundled with the application binary. When you upload a native app to EASE, that image file will be added to EASE as the Icon Image for that app, and it will display in both the EASE Portal Applications list and app lists in the App Catalog.


If you upload a native app and nothing is uploaded for the Icon Image, then it means the app was built without an icon or there is something wrong with the icon it was built with (for example, the size or format may be incompatible). If this is the case, you need to ask the app developer for a new version of the app that includes a valid icon. Once you get this version, attempt to add the app to EASE again.

Even when an icon is extracted from the app, you can upload a different icon to EASE. The icon you upload will be displayed in the EASE Portal and the App Catalog, but the icon bundled with the application file will still be used to display the app on the Home screen of the user's mobile device once the app is installed.

Any icon you upload manually must be in PNG format and should be at least 114 x 114 pixels. Be sure the image was saved in PNG format and not saved in another format and then simply renamed with a .png extension.

If you want to change the icon of a previously added application, click the Edit button under the app and expand the Icon Image section of the page.

Administrator sees this message when trying to upload an app to the EASE Portal:

Distribution: not enterprise and no provisioned devices

The application you are attempting to upload to the EASE Portal is signed with an App Store distribution provisioning profile instead of an Ad Hoc or In House distribution provisioning profile. An app signed with an App Store distribution provisioning profile can still be uploaded to EASE without issue, but should be signed with a distribution certificate and distribution provisioning profile before it is distributed to your users. Any app signed with an App Store distribution provisioning profile will not install on a device until it is resigned with a correct distribution provisioning profile.

For more information on creating the correct distribution provisioning profile for an iOS application, see Distribution Provisioning Profiles.

 

Signing Apps with the Signing Server

IssueTroubleshooting

Administrator receives an App Expiration Notice email indicating that an app(s) signing certificate is due to expire in X days.

EASE sends an email to the EASE Administrators in your organization to warn that an iOS app's Apple signing certificate (distribution certificate) is due to expire. Notification emails are sent 60 days before an app expires, 45 days before, 30 days before, and then every day until the app either expires or is re-signed with current signing credentials.

When an application's signing certificate expires, the app is disabled. Users cannot install disabled apps from an App Catalog, and cannot run a disabled app that was already installed. To avoid any loss of service for an app's users, you should be sure to re-sign the app and redistribute it to users BEFORE the certificate expires. Follow these steps:

  1. In the Apple Developer Portal, log in with your Enterprise account and create a new distribution certificate. You cannot renew or extend the life of an existing certificate that is due to expire. For instructions on creating a certificate, see Distribution Certificates.

  2. In the Apple Developer Portal, edit any distribution provisioning profiles that are associated with the certificate that is due to expire, and then generate and download the updated .mobileprovision files. For instructions, see Edit a Distribution Certificate.

  3. In EASE, upload the new certificate and new provisioning profiles and then re-sign apps that are currently signed with those credentials. When you re-sign an app, it will create a new version of that app that will need to be distributed to your users.
     

Android applications will not typically expire because they are signed with certificates with long life spans (25+ years).


My certificate is expired and I cannot sign applications with it.

 

iOS distribution certificates expire after one or two years. When a certificate has expired, you can no longer sign any apps with it.

For instructions on creating a new certificate, see Distribution Certificates. You should aim to re-sign and redistribute an app before its associated certificate expires. See the procedure in the first row of this table.

When trying to sign an application, the entitlements of the app do not match the entitlements of the distribution provisioning profile.

When you sign an app, you need to sign it with a distribution provisioning profile that has entitlements (app services) that match the entitlements (capabilities) built into the app. If the entitlements don't match, users will not be able to install the app on their devices. If the app includes app extensions, each extension must be signed with a different provisioning profile that has the correct entitlements.

It is best practice to obtain the list of an app's entitlements from the app developer before attempting to sign the application so that you can ensure that you have a suitable distribution provisioning profile(s), but if you don't have this information, EASE can help. When you upload a provisioning profile in the Sign with New Credentials section of the Signing tab, EASE compares the entitlements in the profile with the app/extension. If the entitlements don't match, EASE warns you and clearly identifies what doesn't match. Once you have this level of information, you can follow up on your own or with the appropriate member of your team to generate the necessary provisioning profile(s) from the Apple Dev Portal. 

For more information on entitlements, see Entitlements. For instructions on signing with new credentials, see Sign with New Credentials.

Administrator sees this message when attempting to sign an application:

The app does not have a ProvisionedDevices (ad hoc) or ProvisionsAllDevices (enterprise) key

You attempted to sign an application with an App Store distribution provisioning profile. Applications in EASE must be signed with either an Ad Hoc or In House distribution provisioning profile. Signing with an App Store distribution provisioning profile will fail and EASE will display the message to the left.

For more information on signing requirements, see Signing Requirements. For more information on creating the correct distribution provisioning profile for an iOS application, see Distribution Provisioning Profiles.

Signing Apps with the Signing Package

For instructions on downloading a signing package to sign an app outside of EASE, see Use the Signing Package.

Signing iOS Apps with the signApp Script

IssueTroubleshooting

The signApp script returns an error when signing an iOS app.

 

Check for the following issues:

  • The distribution certificate and private key are not installed properly in your Login Keychain. Use Keychain Access to verify that both the certificate and private key are listed in your Login Keychain.
     
  • The app contains extensions and you are signing the app with multiple distribution provisioning profiles, but you edited the signables_manifest.txt file incorrectly or did not edit it at all. See step 3 in the procedure above.

  • You have more than one distribution certificate with the same name in your Keychain. The certificate name that you specify when you execute the script must be unique across all Keychains. For example, you cannot have a certificate with the same name in both the Login and System Keychains. If you have the certificate in more than one Keychain, you should delete it from all Keychains other than the Login Keychain, but first you should make sure that there are no other apps using the certificate in the other Keychain.

Signing Windows Phone Apps with the sign.bat Script

Issue
Troubleshooting

Any messaging indicating that a file/script/utility/command/application could not be found. For example:

certutil.exe application could not be found in "%SystemRoot%\system32\certutil.exe

BuildMDILXap.ps1 script could not be found in "%ProgramFiles(x86)%\Microsoft SDKs\Windows Phone\v8.0\Tools\MDILXAPCompile\BuildMDILXap.ps1

Ensure that you meet all the requirements listed in Signing Requirements.
<path to file> file could not be found. Check the path and retry.The XAP or APPX file you are trying to sign is not located in the same directory as the sign.bat script. Ensure that both files are in the same directory and repeat step 9 above.
The Symantec Root/CA certificate could not be foundEnsure that both the Symantec Root and Symantext CA certificates are installed in the correct locations, as described in Signing Requirements.
Certificate not found in <path>The pfx certificate file you passed as an argument in the command line is not located in the same directory as the sign.bat script. See step 7 above.
Too many parameters were passedWhen executing the script, you passed more than two parameters (for example:sign.bat certificate.pfx password extra_parameter). Rerun the script, without the extra parameter. See step 9 above.
Signing with a certificate without password is not allowed.When executing the script, you did not specify the certificate password (for example: sign.bat certificate.pfx). See step 9 above.
The password for the certificate is not correct.Repeat step 9 above with the correct password.
There was a problem while signing the <XAP/APPX>. Check that the certificate <pfx certificate name> is valid to sign the appThe pfx certificate that you used is not valid for signing. For more information, see Windows Phone Application Signing Requirements.

The application is already signed. Trying to resign <XAP/APPX> file...

Disregard this message. It indicates that the app is already signed, and will be resigned with the certificate included in the working directory

Signing Apps through the API

For a list of  errors that may be returned if the signing process cannot start when you send a request to the PUT /applications/<app_psk>/credentials/<credentials_id> API resource, see Error Messages.

For a list of messages that may be returned in the signing_status_details field of a GET /applications/<app_psk> API response, see Signing Status Messages.


  • No labels