App Personalization

Troubleshooting App Personalization service APIs

Use the sample error response, response codes, different cases associated with each code, and suggestions on APIs to resolve any issues that might occur while personalizing your Citrix client.

Sample error response

An unsuccessful App Personalization API request returns the following information in the response body:

The following is a sample API error response:

            {
                "type": "https://errors-api.cloud.com/branding/notFound",
                "detail": "resource not found",
                "parameters":
                {
                "name": "entityType",
                "value": "the request URL"
                }
            }
<!--NeedCopy-->

Suggestions on resolving issues with different App Personalization service APIs

Use the descriptions, response codes, and suggested action for different App Personalization service APIs, to resolve any issues that might occur while using specific APIs.

API 1: GET/ Personalizations

  • This API lets you fetch the result of app personalization requests. It displays the result based on the product and platform.
  • This API lets you know whether app personalizations were made. It returns successful responses but no rebranded outputs. For example, see Response code 200.
  • If the GET/ request displays the Case 2 result, perform a PUT operation to personalize the app again.

API 2: GET/ Personalizations/{id}

  • The GET operation for a particular personalizationId. This operation displays a single personalization result rather than a collection of personalization results.

API 3: POST/ Personalizations

  • The POST/ request can be made only once for a combination of product, platform, and customer ID.
  • If the request was already made, a Response Code 400 error appears. See Case 5 in the table.
  • The body parameters are the same for both PUT and POST.

API 4: PUT/ Personalizations/{id}

  • The id parameter is the personalization ID created during the post operation. You can also fetch it from the GET/ operation.

POST and PUT body parameters

  • appName
    • Length: 30 characters.
    • Alpha-numeric characters allowed.
  • platform
    • Enumeration values allowed. Supported values: “iOS,” “Android,” “Windows,” and “Mac.”
    • The values are case sensitive.
  • product
    • Enumeration values allowed. Supported values: “Secure Mail,” “Secure Web,” “Citrix Files,” and “Citrix Workspace app.”
    • The values are case sensitive.
  • abmDetails
    • This parameter is a property required by iOS.
    • Apple Business Manager Email ID & Organisation details.
  • storeURL
    • This is an optional parameter for “Citrix Workspace app”.
    • It is used to configure the Store URL and takes an alpha-numeric string input. Example value: https://testserver.net/Citrix/MyStore/discovery
  • appIconDataURI
    • This parameter is an image data URI.
    • Provide an image in .jpeg or .png format of size 512*512 pixels .

      appicon7030

    • Please note that android requires adaptive icon guidelines to be met for icons to display correctly. Please refer here before generating an icon: Android Adaptive icon tool

      Example of icon shapes on Android:

      appiconandroid1 appiconandroid2

  • secondaryDataURI
    • This parameter is a property required by Citrix Workspace app
    • This parameter is an image data URI
    • Provide an image in .jpeg or .png format of size 1024*500 pixels
    • Include 40px padding in the image
    • It will be primarily used as a launch screen image

      landingpage

Windows example

            {
                "appName": "Workspace",
                "platform": "Windows",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"(**optional),
                "helpURL": "www.helpurl.com"(**optional)
            }
<!--NeedCopy-->

Mac example

            {
                "appName": "Workspace",
                "platform": "Mac",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"(**optional),
                "macMenuBarIconOnlineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**optional),
                "macMenuBarIconOfflineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**optional),
                "viewerIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**optional)
            }
<!--NeedCopy-->

Android example

            {
                "appName": "Workspace",
                "platform": "Android",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"(**optional and applicable only for CWA)
            }
<!--NeedCopy-->

iOS example

            {
                "appName": "Workspace",
                "platform": "iOS",
                "product": "Citrix Workspace app",
                "abmDetails": "{"abmId": ["example@citrix.com"], "orgDetails": [{"orgId": "123456", "orgName": "example"}]}(**required only for iOS)",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"(**optional and applicable only for CWA)
            }
<!--NeedCopy-->

API 5: POST/ Personalizations/{id}/$promote

  • Use this API to move the preview build to production. It is helpful only when a preview build with the package ID is available in the app store.
  • This API is applicable only to iOS and Android.

API 6: POST/ Personalizations/{id}/builds?async=true

  • Make the POST/ request for Windows and macOS to fetch the personalized executable of the specified product.
  • You can make multiple requests if no active personalization (build status in progress) is present.
  • The successful response of the request is 202 Accepted.
  • In scenarios where the build is still in progress, 409 Conflict is returned.
  • The query parameter async=true is required because this is an asynchronous task that triggers another task to provide the results.

POST body parameters

  • version
    • A string that specifies the version of the app to be personalized.
    • Fetch from Citrix Workspace app for Windows build version details.
    • Get the latest Citrix Workspace app versions available for Windows and Mac by using the GET/ Personalizations/{product}/{platform}/builds API

API 7: GET/ Personalizations/{id}/builds

API 8: GET/ Personalizations/{id}/builds/{id}

  • The first ID in the URL is the personalization ID and the second is the build ID that you get after performing a POST/ Personalizations/{id}/builds operation.
  • This API reveals information about the build. The resultLocation provides the download URL of the personalized app. For example, see Response code 200 - Case 4.
  • This API reveals information about MDX file for Secure mail, Secure web and Citrix files apps. The resultLocation provides the download URL of the MDX file.

API 9: GET/ Personalizations/{product}/{platform}/builds

  • This API reveals the versions available for rebranding.For example, see Response code 200 - Case 5.
  • The product parameter is the product name for which the available versions will be fetched for a particular platform denoted by the platform parameter.
  • The supported value for product is “Citrix Workspace app”. And the supported values for platform are “Windows” and “Mac” without quotes.

GET/ Personalizations/{id}/builds response

  • id
    • The ID of the build after the build is triggered. You can fetch this ID after performing the POST /personalizations/{id}/builds call.
  • type
    • The type is “builds.”
  • overallProgressPercent
    • The value range is 0 through100. 100 indicates that the build completed successfully.
  • status
    • Build status information:
      • notStarted: The build was triggered and is in queue.
      • inProgress: The build is in progress.
      • complete: The build completed successfully.
      • failed: The build failed.
  • createdAt
    • The creation date and timestamp of the build.
  • createdBy
    • The ID of the user who triggered the build.
  • startedAt
    • The start date and timestamp of the build.
  • endedAt
    • The end date and timestamp of the build.
  • version
    • A string that specifies the version of the personalized app.
  • resultLocation
    • The link to the download URL of the personalized app for Windows and macOS Worspace app.
    • The link to the download URL of the MDX file for Secure mail, Secure web and Citrix file iOS/Android app.
    • Information about the expiration date and timestamp of the link is also provided.
    • This parameter appears only in GET Personalizations/{id}/builds/{id} when the status of the build is “Complete.”

Response codes for App Personalization service APIs

The following section provides examples of response codes for App Personalization APIs.

200 OK

  • GET/ personalizations

Case 1: If you have not yet made any personalization requests

            {
                "status": "Success",
                "message": "Customer does not have branded apps."
            }
<!--NeedCopy-->
Case 2: If the request was made successfully
            {
                "items": [
                {
                    "appName": "Workspace",
                    "product": "Citrix Workspace app",
                    "platform": "Android",
                    "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                    "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                    "id": "b550cf4259c84b129df15cf11f7fbaee",
                    "bundleId": "com.citrix.browser.droid.usuqbxek0ae0"
                    }
                ]
            }
<!--NeedCopy-->
Case 3: Fetch personalization builds
            {
                "items": [
                 {
                    "type": "builds",
                    "overallProgressPercent": 0,
                    "isCancellable": false,
                    "status": "notStarted",
                    "id": "542e9740198549af993d7e23d9801622",
                    "personalizationConfig": {
                        "appName": "Workspace"
                    },
                    "createdAt": "2020-06-23T08:59:46.945Z",
                    "createdBy": "dba9d636-082d-459a-b36d-3750c4d1e1bf",
                    "version": "27806901",
                ]
            }
<!--NeedCopy-->
Case 4: Fetch the personalization build that contains the build ID
           {
                "type": "builds",
                "isCancellable": false,
                "overallProgressPercent": 100,
                "status": "complete",
                "id": "12f19798ad054cf0bc995f23a931358f",
                "startedAt": "2020-07-10T07:43:03.529Z",
                "personalizationConfig": {
                    "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAA==",
                    "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAA==",
                    "appName": "Workspace"
                },
                "createdAt": "2020-07-10T07:41:04.862Z",
                "createdBy": "dba9d636-082d-459a-b36d-3750c4d1e1bf",
                "endedAt": "2020-07-10T07:50:24.518Z",
                "version": "27806901",
                "resultLocation": {
                    "downloadURL": "https://devbrandingbuildblob.blob.core.windows.net/buildassets/customer.a96.12f1.exe?st=2020-07-10T12%3A38%3A04Z&se=2020-08-30T00%3A38%3A04Z&sp=r&sv=2018-03-28&sr=b&sig=CXQDz%2F0UWkfF0Y0wl%2Fm6S2%3D",
                    "message": "downloadURL will expire on 2020-08-30T00:38:04.099Z"
            }
<!--NeedCopy-->
Case 5: Fetch the Citrix Workspace app versions available for rebranding on Windows and Mac
            {
                "items": [
                    "2010",
                    "2009",
                    "2008"
                ]
            }
<!--NeedCopy-->

201 Created

  • POST/ personalization

Case 1: If the request was made successfully

            {
                "type": "Success",
                "detail": "Customer request for branding app is completed successfully",
                "parameters": [
                    {
                        "name": "id",
                        "value": "1572cd92447742ef81638594a91f6b86"
                    }
                    ]
            }
<!--NeedCopy-->

202 Accepted

  • POST/ personalization/{id}/builds

Case 1: If the build request was made successfully

           {
                "type": "Success",
                "detail": "Customer request for building app is completed successfully",
                "parameters": [
                    {
                        "name": "id",
                        "value": "3c9008a2fe85443fa824c9205b4f3be"
                    }
                ]
            }
<!--NeedCopy-->

204 No Content

  • PUT/ personalizations/{id} No Response
  • Check the GET/ personalizations/{id} to see whether the request has been updated.

400 Validation Errors

  • POST/ personalizations
  • PUT/ personalizations/{id}
  • Validation errors inform you of specifying certain fields.

Case 1: If fields are empty, an error message flags the missing fields

            {
                "type": "https://errors-api.cloud.com/branding/validation",
                "detail": "Validation failed",
                "parameters": [
                    {
                    "name": "appName",
                    "value": "appName should not be empty"
                    },
                    {
                    "name": "platform",
                    "value": "platform should not be empty"
                    },
                    {
                    "name": "product",
                    "value": "product should not be empty"
                    },
                    {
                    "name": "appIconDataURI",
                    "value": "appIconDataURI should not be empty"
                    }
                ]
            }
<!--NeedCopy-->

Case 2: If the app name has more than 30 characters and is not alphanumeric

Error 1

            {
                "type": "https://errors-api.cloud.com/branding/validation",
                "detail": "Validation failed",
                "parameters": [
                    {
                        "name": "appName",
                        "value": "appName must be shorter than or equal to 30 characters"
                    }
                ]
            }
<!--NeedCopy-->

Error 2

            "parameters": [
                {
                    "name": "appName",
                    "value": "appName allows alphabets and numbers only"
                }
            ]
<!--NeedCopy-->

Case 3: If a platform or product is invalid

            "parameters": [
                {
                    "name": "platform",
                    "value": "platform is not supported"
                },
                {
                    "name": "product",
                    "value": "product is not supported"
                }
            ]
<!--NeedCopy-->

Case 4: If DataURI is invalid

            {
                "type": "https://errors-api.cloud.com/branding/invalid",
                "detail": "The DataURI provided is invalid"
            }
<!--NeedCopy-->

Case 5: If the personalization request was already made

            {
                "type": "https://errors-api.cloud.com/branding/invalid",
                "detail": "Branded app already exist"
            }
<!--NeedCopy-->
  • POST/ personalizations/{id}/build/{id}

Case 1: If the version is empty (not specified)

            {
                "type": "https://errors-api.cloud.com/branding/BadRequestException",
                "detail": "Validation failed",
                "parameters": [
                    {
                        "name": "version",
                        "value": "version should not be empty"
                    }
                ]
            }
<!--NeedCopy-->

Case 2: If the specified version is incorrect

            {
                "type": "https://errors-api.cloud.com/branding/BadRequestException",
                "detail": "The supplied version is either not eligible for personalization or incorrect"
            }

<!--NeedCopy-->

401 UnAuthorized

  • GET/ personalizations
  • GET/ personalizations/{id}
  • POST/ personalizations
  • PUT/ personalizations/{id}
  • GET/ Personalizations/{id}/builds
  • GET/ Personalizations/{id}/builds/{id}
  • POST/ personalizations/{id}/builds
  • POST/ personalizations/{id}/$promote
  • GET/ personalizations/{product}/{platform}/builds

Case 1: If the authorization header is empty or missing, the reason mentioned in the parameters value is missing

            {
                "type": "https://errors-api.cloud.com/branding/authentication",
                "detail": "Missing or invalid authentication details",
                "parameters": [
                    {
                        "name": "reason",
                        "value": "missing"
                    }
                ]
            }
<!--NeedCopy-->

Case 2: If the authorization header is invalid, the reason mentioned in the parameters value is invalid

            {
                "type": "https://errors-api.cloud.com/branding/authentication",
                "detail": "Missing or invalid authentication details",
                "parameters": [
                    {
                        "name": "reason",
                        "value": "invalid"
                    }
                ]
            }
<!--NeedCopy-->

403 Forbidden

If the authorization details provided in the header are incorrect, the following error appears:

  • GET/ personalizations
  • GET/ personalizations/{id}
  • POST/ personalizations
  • PUT/ personalizations/{id}
  • GET/ Personalizations/{id}/builds
  • GET/ Personalizations/{id}/builds/{id}
  • POST/ personalizations/{id}/builds
  • POST/ personalizations/{id}/$promote
  • GET/ personalizations/{product}/{platform}/builds

Case 1: Bearer token details are incorrect

            {
                "type": "https://errors-api.cloud.com/branding/authorization",
                "detail": "Access denied"
            }
<!--NeedCopy-->

404 Not Found

  • GET/ personalizations
  • GET/ personalizations/{id}
  • POST/ personalizations
  • GET/ Personalizations/{id}/builds
  • GET/ Personalizations/{id}/builds/{id}
  • POST/ personalizations/{id}/builds
  • POST/ personalizations/{id}/$promote
  • GET/ personalizations/{product}/{platform}/builds

Case 1: If the URL is not in line with the App Personalization Service REST API documentation

            {
                "type": "https://errors-api.cloud.com/branding/notFound",
                "detail": "resource not found",
                "parameters": [
                    {
                        "name": "entityType",
                        "value": "/personalizati"
                    }
                ]
            }
<!--NeedCopy-->

Case 2: If the ID parameter in the query or the ID parameter in GET/ personalizations /{id} or PUT/ personalizations/{id} is invalid

            {
                "type": "https://errors-api.cloud.com/branding/notFound",
                "detail": "Could not find branded application with personalization id a4bc9811534b404f964d12be20abb14 for CustomerId testcust",
                "parameters": [
                    {
                        "name": "entityType",
                        "value": "/personalizations/a4bc9811534b404f964d12be20abb14"
                    }
                ]
            }
<!--NeedCopy-->

406 Not Acceptable

  • GET/ personalizations/{product}/{platform}/builds

Case 1: Platform parameter value is incorrect

            {
                "type": "https://errors-api.cloud.com/branding/NotAcceptableException",
                "detail": "Platform should be either 'Windows' or 'Mac'"
            }
<!--NeedCopy-->

Case 2: Product parameter value is incorrect

            {
                "type": "https://errors-api.cloud.com/branding/NotAcceptableException",
                "detail": "Product name should be 'Citrix Workspace app'"
}
<!--NeedCopy-->

409 conflict

  • POST/ personalizations/{id}/builds
            {
                "type": "https://errors-api.cloud.com/branding/ConflictException",
                "detail": "Build is in progress for personalizationId a96b6d024900. Please check the status of the triggered build using GET /personalizations/a96b6d024900/builds API"
            }
<!--NeedCopy-->

500 Internal Server Error

To resolve the issues, report these errors directly to your Citrix representative. Be sure to include the customer ID and Transaction ID for Citrix to troubleshoot further.

  • GET/ personalizations
  • GET/ personalizations/{id}
  • POST/ personalizations
  • PUT/ personalizations/{id}
  • POST/ personalizations/{id}/builds
  • GET/ personalizations/{product}/{platform}/builds

Case 1: Server errors

            {
                "type": "https://errors-api.cloud.com/branding/internalerror",
                "detail": "There was a internal issue"
            }
<!--NeedCopy-->

501 Not Implemented

If the platform is not implemented, this error appears, informing you that the platform will be available in a future release.

  • POST/ personalizations
  • PUT/ personalizations/{id}

Case 1: The platform or product is not implemented

            {
                "type": "https://errors-api.cloud.com/branding/notImplemented",
                "detail": "Platform is not yet implemented"
            }
<!--NeedCopy-->
Resources
App Personalization OpenAPI Specification
Copy Download
Troubleshooting App Personalization service APIs