App Personalization

Troubleshooting App Personalization service APIs

August 29, 2024

Contributed by:

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:

Type: A link to the standard HTTP response code. For example, https://errors-api.cloud.com/branding/notFound.
Details: A brief description of the error.
Parameters: An optional JSON object to provide extra error information.

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 .
- 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:
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

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

This API reveals the builds placed and the status of each build. For example, see Response code 200 - Case 3.

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
201 Created
202 Accepted
204 No Content
400 Validation Errors
401 UnAuthorized
403 Forbidden
404 Not Found
406 Not Acceptable
409 Conflict
500 Internal Server Error
501 Not Implemented

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-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

App Personalization OpenAPI Specification

Copy Download

Troubleshooting App Personalization service APIs

August 29, 2024

Contributed by:

August 29, 2024

Contributed by:

Troubleshooting App Personalization service APIs

Sample error response

Suggestions on resolving issues with different App Personalization service APIs

API 1: GET/ Personalizations

API 2: GET/ Personalizations/{id}

API 3: POST/ Personalizations

API 4: PUT/ Personalizations/{id}

POST and PUT body parameters

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

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

POST body parameters

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

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

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

GET/ Personalizations/{id}/builds response

Response codes for App Personalization service APIs

200 OK

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

Case 2: If the request was made successfully

Case 3: Fetch personalization builds

Case 4: Fetch the personalization build that contains the build ID

Case 5: Fetch the Citrix Workspace app versions available for rebranding on Windows and Mac

201 Created

Case 1: If the request was made successfully

202 Accepted

Case 1: If the build request was made successfully

204 No Content

400 Validation Errors

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

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

Case 3: If a platform or product is invalid

Case 4: If DataURI is invalid

Case 5: If the personalization request was already made

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

Case 2: If the specified version is incorrect

401 UnAuthorized

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

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

403 Forbidden

Case 1: Bearer token details are incorrect

404 Not Found

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

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

406 Not Acceptable

Case 1: Platform parameter value is incorrect

Case 2: Product parameter value is incorrect

409 conflict

500 Internal Server Error

Case 1: Server errors

501 Not Implemented

Case 1: The platform or product is not implemented

Resources

App Personalization OpenAPI Specification

In this article

Resources

App Personalization OpenAPI Specification