CBStoreSubsystem

This APS type is abstract and must be implemented by globally accessible APS types of components that need to provide users with the ability to install, upgrade, or uninstall apps through the CloudBlue Store (https://docs.cloudblue.com/cbc/21.0/CloudBlue-Store/introduction.htm).

Apps in the CloudBlue Store are components, such as the Product Lifecycle Management (PLM) component; presets, such as PLM product presets; datasets, such as Reporting and Data Export (RDE) datasets; skins; APS applications; and any parts of components that can be shown to users as separate pieces of functionality.

Apps are grouped into subsystems, where each subsystem is represented by a separate APS type that implements the CBStoreSubsystem abstract APS type.

An app has an identifier in the CloudBlue Store that must be unique within the subsystem of that app.

A component can have one or more APS types that implement the CBStoreSubsystem abstract APS type (one per subsystem).

A component can use one of these installation and uninstallation methods for an app of a subsystem:

- View: The component must provide a shared component view for configurable installation and uninstallation. That shared component view is embedded in the CloudBlue Store UI. After the user provides the necessary information in the CloudBlue Store, the component must install the latest app version using the provided information. Uninstallation is also performed with the shared component view.

- API: The component must support the install and uninstall custom operations for non-configurable installation and uninstallation. The CloudBlue Store calls the respective custom operation after the user starts the installation or uninstallation of that app in the CloudBlue Store.

- View and API: The component must provide a shared component view and support the install and uninstall custom operations. That shared component view is embedded in the CloudBlue Store UI and is used to gather installation information. After the user provides the necessary information, the CloudBlue Store calls the install custom operation of the component and passes the gathered information to that custom operation. The CloudBlue Store calls the uninstall custom operation after the user starts the uninstallation of that app in the CloudBlue Store.

Note: In the current version of CloudBlue Store, an app can be uninstalled only with the uninstall custom operation.

Depending on app, the CloudBlue Store can retrieve an attachment from the JIRA issue of the latest app version and pass it to the install custom operation.

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "CBStoreSubsystem",
  "id": "http://com.ingrammicro/appstore/cbstore-subsystem/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "access": {
    "global": true
  },
  "operations": {
    "applications": {
      "path": "/applications",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "CBStoreApplication"
        }
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "application": {
      "path": "/applications/{appId}",
      "verb": "GET",
      "response": {
        "type": "CBStoreApplicationInformation"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "appId": {
          "kind": "path",
          "type": "string",
          "required": true
        }
      }
    },
    "install": {
      "path": "/applications/{appId}/install",
      "verb": "POST",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "appId": {
          "kind": "path",
          "type": "string",
          "required": true
        },
        "payload": {
          "kind": "body",
          "type": "object"
        }
      }
    },
    "uninstall": {
      "path": "/applications/{appId}/uninstall",
      "verb": "POST",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "appId": {
          "kind": "path",
          "type": "string",
          "required": true
        }
      }
    },
    "update": {
      "path": "/applications/{appId}/update",
      "verb": "POST",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "appId": {
          "kind": "path",
          "type": "string",
          "required": true
        },
        "payload": {
          "kind": "body",
          "type": "object"
        }
      }
    }
  },
  "structures": {
    "CBStoreApplication": {
      "type": "object",
      "properties": {
        "storeAppId": {
          "type": "string",
          "description": "App identifier (unique in subsystem)",
          "required": true
        },
        "status": {
          "type": "string",
          "description": "App status (installed_latest represents installed, regardless of version)",
          "required": true,
          "enum": [
            "not_installed",
            "provisioning",
            "installed_latest",
            "installation_not_available"
          ]
        },
        "version": {
          "type": "string",
          "description": "Installed version. Should be returned if app is installed and versionDisplayMode is not display_none"
        },
        "versionDisplayMode": {
          "type": "string",
          "description": "Allows to specify if versions are not supported (and should not be displayed). If not set, display_all is assumed",
          "enum": [
            "display_all",
            "display_none"
          ]
        },
        "applicationViewId": {
          "type": "string",
          "description": "UX1 view id of the installed app"
        },
        "applicationViewType": {
          "type": "string",
          "description": "Type of view that is opened during navigation to applicationViewId",
          "enum": [
            "open",
            "manage"
          ]
        }
      }
    },
    "AttachmentInfo": {
      "type": "object",
      "properties": {
        "mimeType": {
          "type": "string",
          "description": "Attachment mime type"
        },
        "fileName": {
          "type": "string",
          "description": "If specified, attachment with this exact filename is expected"
        }
      }
    },
    "CBStoreApplicationInformation": {
      "type": "object",
      "properties": {
        "storeAppId": {
          "type": "string",
          "description": "App identifier (unique in subsystem)",
          "required": true
        },
        "status": {
          "type": "string",
          "description": "App status (installed_latest represents installed, regardless of version)",
          "required": true,
          "enum": [
            "not_installed",
            "provisioning",
            "installed_latest",
            "installation_not_available"
          ]
        },
        "version": {
          "type": "string",
          "description": "Installed version. Should be returned if app is installed and versionDisplayMode is not display_none"
        },
        "versionDisplayMode": {
          "type": "string",
          "description": "Allows to specify if versions are not supported (and should not be displayed). If not set, display_all is assumed",
          "enum": [
            "display_all",
            "display_none"
          ]
        },
        "applicationViewId": {
          "type": "string",
          "description": "UX1 view id of the installed app"
        },
        "applicationViewType": {
          "type": "string",
          "description": "Type of view that is opened during navigation to applicationViewId",
          "enum": [
            "open",
            "manage"
          ]
        },
        "installationMethod": {
          "type": "string",
          "description": "App installation method",
          "required": true,
          "enum": [
            "api",
            "view",
            "view_and_api",
            "not_available"
          ]
        },
        "uninstallationMethod": {
          "type": "string",
          "description": "App uninstallation method",
          "required": true,
          "enum": [
            "api",
            "view",
            "view_and_api",
            "not_available"
          ]
        },
        "appId": {
          "type": "string",
          "description": "App id for installation shared component"
        },
        "installComponentName": {
          "type": "string",
          "description": "Component name for installation shared component"
        },
        "statusReasonMessage": {
          "type": "string",
          "description": "Status reason message"
        },
        "statusReasonMessageParameters": {
          "type": "object",
          "description": "Key-value dictionary with parameters for status reason message"
        },
        "uninstallStatusReasonMessage": {
          "type": "string",
          "description": "Uninstall status reason message"
        },
        "uninstallStatusReasonMessageParameters": {
          "type": "object",
          "description": "Key-value dictionary with parameters for uninstall status reason message"
        },
        "attachmentInfo": {
          "type": "AttachmentInfo",
          "description": "Information about attachment expected by install method"
        }
      }
    }
  }
}

Custom Operations

OPERATION	VERB	PATH	RETURNS	Description
applications	GET	/applications	An array of CBStoreApplication structures.	Return a list of apps that are known to a subsystem.
application	GET	/applications/{appId}	A CBStoreApplicationInformation structure.	Return detailed information on an app of a subsystem. If the app specified in the appID parameter is unknown but that app can be installed, the status property must be set to not_installed in the CBStoreApplicationInformation structure. For example, the UI and Branding component can install new skins as they are released. If the app specified in the appID parameter cannot be installed, in addition to setting the status property to installation_not_available in the CBStoreApplicationInformation structure, the statusReasonMessage property must contain an explanatory message that will be displayed in the CloudBlue Store for that app.
install	POST	/applications/{appId}/install	An HTTP status code.	Install an app of a subsystem. This custom operation must be implemented if the component of the subsystem supports the API or View and API installation method for the app.
uninstall	POST	/applications/{appId}/uninstall	An HTTP status code.	Uninstall an app of a subsystem. This custom operation must be implemented if the component of the subsystem supports the API or View and API uninstallation method for the app.
update	POST	/applications/{appId}/update		This custom operation is reserved for future use.

applications

HTTP Request

GET /aps/2/resources/{aps-id}/applications

Description

Return a list of apps that are known to a subsystem.

Returns

An array of CBStoreApplication structures.

application

HTTP Request

GET /aps/2/resources/{aps-id}/applications/{appId}

Description

Return detailed information on an app of a subsystem.

If the app specified in the appID parameter is unknown but that app can be installed, the status property must be set to not_installed in the CBStoreApplicationInformation structure. For example, the UI and Branding component can install new skins as they are released.

If the app specified in the appID parameter cannot be installed, in addition to setting the status property to installation_not_available in the CBStoreApplicationInformation structure, the statusReasonMessage property must contain an explanatory message that will be displayed in the CloudBlue Store for that app.

Parameters

PARAMETER	TYPE	DESCRIPTION
appId	String	The CloudBlue Store identifier of the app.

Returns

A CBStoreApplicationInformation structure.

install

HTTP Request

POST /aps/2/resources/{aps-id}/applications/{appId}/install

Description

Install an app of a subsystem. This custom operation must be implemented if the component of the subsystem supports the API or View and API installation method for the app.

Parameters

PARAMETER	TYPE	DESCRIPTION
appId	String	The CloudBlue Store identifier of the app.
payload	Object	The payload of the custom operation. For details, see The Format of Payload for the install Custom Operation in the Examples section. The CloudBlue Store prepares that payload for the app and passes it to the custom operation.

Returns

An HTTP status code.

uninstall

HTTP Request

POST /aps/2/resources/{aps-id}/applications/{appId}/uninstall

Description

Uninstall an app of a subsystem. This custom operation must be implemented if the component of the subsystem supports the API or View and API uninstallation method for the app.

Parameters

PARAMETER	TYPE	DESCRIPTION
appId	String	The CloudBlue Store identifier of the app.

Returns

An HTTP status code.

update

HTTP Request

POST /aps/2/resources/{aps-id}/applications/{appId}/update

Description

This custom operation is reserved for future use.

Parameters

PARAMETER	TYPE	DESCRIPTION
appId	String	Reserved for future use.
payload	Object	Reserved for future use.

Returns

Structures

CBStoreApplication

A structure of this kind represents an app of a subsystem and contains basic information on that app.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
storeAppId	String	Required		The CloudBlue Store identifier of the app.
status	Enum	Required		The status of the app. The following values are supported: not_installed - The app is not installed. provisioning - The app is being installed or uninstalled. installed_latest - The app is installed. This status must be used for an installed app regardless of whether the latest app version is installed or not. installation_not_available - The app cannot be installed. For example, if there are two mutually exclusive apps in a subsystem and one of them is already installed, the other app cannot be installed.
version	String	Not Required		The current version of the installed app. This property must be returned if status is installed_latest and versionDisplayMode is display_all.
versionDisplayMode	Enum	Not Required		The version display mode of the app. The following values are supported: display_all - The app supports versioning. The CloudBlue Store displays versions of the app. display_none - The app does not support versioning. The CloudBlue Store does not display versions of the app.
applicationViewId	String	Not Required		The identifier of the view that must be opened in the CloudBlue Store when the Open or Manage button is clicked for the app. If not specified, no button is displayed in the CloudBlue Store for the app.
applicationViewType	Enum	Not Required		Defines which button must be displayed in the CloudBlue Store for the app. This property must be specified if applicationViewId is specified. The following values are supported: open - The Open button must be displayed. manage - The Manage button must be displayed.

AttachmentInfo

A structure of this kind represents an attachment of an app. That attachment is retrieved by the CloudBlue Store from the JIRA issue that belongs to the latest app version and is passed to the install custom operation during app installation.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
mimeType	String	Not Required		The MIME type of the attachment.
fileName	String	Not Required		The file name of the attachment.

CBStoreApplicationInformation

A structure of this kind represents an app of a subsystem and contains detailed information on that app.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
storeAppId	String	Required		The CloudBlue Store identifier of the app.
status	Enum	Required		The status of the app. The following values are supported: not_installed - The app is not installed. provisioning - The app is being installed or uninstalled. installed_latest - The app is installed. This status must be used for an installed app regardless of whether the latest app version is installed or not. installation_not_available - The app cannot be installed. For example, if there are two mutually exclusive apps in a subsystem and one of them is already installed, the other app cannot be installed.
version	String	Not Required		The current version of the installed app. This property must be returned if status is installed_latest and versionDisplayMode is display_all.
versionDisplayMode	Enum	Not Required		The version display mode of the app. The following values are supported: display_all - The app supports versioning. The CloudBlue Store displays versions of the app. display_none - The app does not support versioning. The CloudBlue Store does not display versions of the app.
applicationViewId	String	Not Required		The identifier of the view that must be opened in the CloudBlue Store when the Open or Manage button is clicked for the app. If not specified, no button is displayed in the CloudBlue Store for the app.
applicationViewType	Enum	Not Required		Defines which button must be displayed in the CloudBlue Store for the app. This property must be returned if applicationViewId is specified. The following values are supported: open - The Open button must be displayed. manage - The Manage button must be displayed.
installationMethod	Enum	Required		| The installation method supported by the component that the subsystem of the app belongs to. Note: In the current version of CloudBlue Store, an app can be uninstalled only with the uninstall custom operation. The following values are supported: view - The component provides a shared component view for configurable installation and uninstallation. That shared component view is embedded in the CloudBlue Store UI. After the user provides the necessary information in the CloudBlue Store, the component must install the app using the provided information. Uninstallation is also performed with the shared component. For this installation method, the appId and installComponentName properties must be specified. api - The component provides the install and uninstall custom operations for non-configurable installation and uninstallation. The CloudBlue Store calls the respective custom operation after the user starts the installation or uninstallation of the app in the CloudBlue Store. view_and_api - The component provides a shared component view that is embedded in the CloudBlue Store UI and is used to gather installation information. After the user provides the necessary information, the CloudBlue Store calls the install custom operation of the component and passes the gathered information to that custom operation. Uninstallation is performed with the uninstall custom operation. For this installation method, the appId and installComponentName properties must be specified. not_available - The component does not provide any method to install the app through the CloudBlue Store. Optionally, details can be specified in the statusReasonMessage property.
uninstallationMethod	Enum	Required		| The uninstallation method supported by the component that the subsystem of the app belongs to. Note: In the current version of CloudBlue Store, an app can be uninstalled only with the uninstall custom operation. The following values are supported: view - The component provides a shared component view for configurable installation and uninstallation. That shared component view is embedded in the CloudBlue Store UI. After the user provides the necessary information in the CloudBlue Store, the component must install the app using the provided information. Uninstallation is also performed with the shared component. For this installation method, the appId and installComponentName properties must be specified. api - The component provides the install and uninstall custom operations for non-configurable installation and uninstallation. The CloudBlue Store calls the respective custom operation after the user starts the installation or uninstallation of the app in the CloudBlue Store. view_and_api - The component provides a shared component view that is embedded in the CloudBlue Store UI and is used to gather installation information. After the user provides the necessary information, the CloudBlue Store calls the install custom operation of the component and passes the gathered information to that custom operation. Uninstallation is performed with the uninstall custom operation. For this installation method, the appId and installComponentName properties must be specified. not_available - The component does not provide any method to install the app through the CloudBlue Store. Optionally, details can be specified in the statusReasonMessage property.
appId	String	Not Required		The Application ID of the APS application of the component that the subsystem of the app belongs to. That Application ID can be obtained in APP-META.xml. This property must be specified for the view and view_and_api installation or uninstallation methods.
installComponentName	String	Not Required		The name of the UI component that represents the shared component view of the app. This property must be specified for the view and view_and_api installation or uninstallation methods.
statusReasonMessage	String	Not Required		A message that explains the reason why the app cannot be installed. It is shown in the CloudBlue Store. That message can contain placeholders that are filled based on the values specified in the statusReasonMessageParameters property.
statusReasonMessageParameters	Object	Not Required		The values for the placeholders that are used in the message specified in the statusReasonMessage property. It must be a JSON object that consists of key-value pairs, where each pair is a placeholder name and a placeholder value.
uninstallStatusReasonMessage	String	Not Required		A message that explains the reason why the app cannot be uninstalled. That message can contain placeholders that are filled based on the values specified in the uninstallStatusReasonMessageParameters property.
uninstallStatusReasonMessageParameters	Object	Not Required		The values for the placeholders that are used in the message specified in the uninstallStatusReasonMessage property.
attachmentInfo	AttachmentInfo	Not Required		If specified, defines which attachment the CloudBlue Store must retrieve from the JIRA issue that belongs to the latest app version. The CloudBlue Store passes that attachment to the install custom operation during app installation.

Examples

Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.

← CBStoreAppTenant

ExternalApplication →