diff --git a/how-to/workspace-platform-starter/CHANGELOG.md b/how-to/workspace-platform-starter/CHANGELOG.md index d86ca8bc3f..812784e704 100644 --- a/how-to/workspace-platform-starter/CHANGELOG.md +++ b/how-to/workspace-platform-starter/CHANGELOG.md @@ -2,6 +2,7 @@ ## v16 +- Improved launchPreference so that now args for a native app (app asset or external) can be specified via launchPreference. Launch preference can also be configured to allow args to be specified dynamically when the launch request is made. - Improved launchPreference so additional options such as url, interop, customData can be specified. Modules can now pass a launchPreference when launching an app by appId. They can see if the app supports being updated by getting the app by id and checking for the updatable setting under launchPreference.options. Only inline-view/view and inline-window/window support updatable launch preferences. Please see [how to define app launch preference](./docs/how-to-define-app-launch-preference.md). - Added support for Snap, enable by setting `customSettings.snapProvider.enabled` to true. Configure the `customSettings.snapProvider.serverAssetInfo` to point to the `SNAP_ASSET_URL`. Enable the Snap debugging window by setting `customSettings.snapProvider.showDebugWindow` to true. - Added new module type `content-creation`, these modules can be used to define content creation rules and handle the associated events. Modules are added in `customSettings.contentCreationProvider` section in manifest. diff --git a/how-to/workspace-platform-starter/client/src/framework/launch.ts b/how-to/workspace-platform-starter/client/src/framework/launch.ts index aaec090b85..51054bcb78 100644 --- a/how-to/workspace-platform-starter/client/src/framework/launch.ts +++ b/how-to/workspace-platform-starter/client/src/framework/launch.ts @@ -54,7 +54,7 @@ export async function launch( switch (app.manifestType) { case MANIFEST_TYPES.External.id: case MANIFEST_TYPES.InlineExternal.id: { - const platformIdentity = await launchExternal(app, launchPreference); + const platformIdentity = await launchExternal(app, undefined, launchPreference); if (platformIdentity) { platformAppIdentities.push(platformIdentity); } @@ -62,7 +62,7 @@ export async function launch( } case MANIFEST_TYPES.Appasset.id: case MANIFEST_TYPES.InlineAppAsset.id: { - const platformIdentity = await launchAppAsset(app); + const platformIdentity = await launchAppAsset(app, undefined, launchPreference); if (platformIdentity) { platformAppIdentities.push(platformIdentity); } @@ -846,11 +846,13 @@ async function launchSnapshot(snapshotApp: PlatformApp): Promise { const options: OpenFin.ExternalProcessRequestType = {}; logger.info(`Request to launch app asset app of type ${appAssetApp.manifestType}`); @@ -881,7 +883,7 @@ export async function launchAppAsset( } try { logger.info(`Launching app asset with appId: ${appAssetApp.appId} with the following options:`, options); - const identity = await launchExternalProcess(appAssetApp, options, instanceId); + const identity = await launchExternalProcess(appAssetApp, options, instanceId, launchPreference); logger.info( `External app with appId: ${appAssetApp.appId} launched with the following identity`, identity @@ -919,26 +921,12 @@ export async function launchExternal( options.uuid = externalApp.appId; } - if(externalApp.launchPreference?.options?.type === "native") { - if(launchPreference?.options?.type === "native" && - Array.isArray(launchPreference.options.updatable) && - launchPreference.options.updatable.length > 0) { - for (const option of launchPreference.options.updatable) { - if (option.name === "arguments" && isStringValue(launchPreference.options.native?.arguments)) { - options.arguments = launchPreference.options.native?.arguments; - } - } - } else if(isStringValue(externalApp.launchPreference?.options?.native?.arguments)) { - options.arguments = externalApp.launchPreference?.options?.native?.arguments; - } - } - try { logger.info( `Launching external app asset with appId: ${externalApp.appId} with the following options:`, options ); - const identity = await launchExternalProcess(externalApp, options, instanceId); + const identity = await launchExternalProcess(externalApp, options, instanceId, launchPreference); logger.info( `External app with appId: ${externalApp.appId} launched with the following identity`, identity @@ -954,18 +942,47 @@ export async function launchExternal( * @param app The app being launched. * @param options The launch options. * @param instanceId Provide an instance id for the app being launched. + * @param launchPreference Optional custom launch preferences * @returns The identity of the process. */ async function launchExternalProcess( app: PlatformApp, options: OpenFin.ExternalProcessRequestType, - instanceId?: string + instanceId?: string, + launchPreference?: UpdatableLaunchPreference ): Promise { const nativeOptions = app.launchPreference?.options as NativeLaunchOptions; const hasPath = isStringValue(options.path); let identity: PlatformAppIdentifier | undefined; + + let args: string[] | undefined; + + if (app.launchPreference?.options?.type === "native") { + if ( + launchPreference?.options?.type === "native" && + Array.isArray(launchPreference.options.updatable) && + launchPreference.options.updatable.length > 0 + ) { + for (const option of launchPreference.options.updatable) { + if (option.name === "args" && Array.isArray(launchPreference.options.native?.args)) { + args = launchPreference.options.native?.args; + logger.debug(`Using passed launch preference for the args for app ${app.appId}`, args); + } + } + } + if (isEmpty(args) && Array.isArray(app.launchPreference?.options?.native?.args)) { + args = app.launchPreference?.options?.native?.args; + logger.debug(`Using app definition based args for app ${app.appId}`, args); + } + } + if (isEmpty(args) && isStringValue(options.arguments)) { + args = [options.arguments]; + } else { + args = []; + } + if ( snapProvider.isEnabled() && nativeOptions?.type === "native" && @@ -989,11 +1006,6 @@ async function launchExternalProcess( instanceId = app.instanceMode === "single" ? app.appId : randomUUID(); } - let args = nativeOptions.snap?.args; - if (!isStringValue(args) && isStringValue(options.arguments)) { - args = [options.arguments]; - } - const launchIdentity = await snapProvider.launchApp( path, args, @@ -1017,7 +1029,9 @@ async function launchExternalProcess( } if (isEmpty(identity)) { - const launchIdentity = await fin.System.launchExternalProcess(options); + const clonedOptions = objectClone(options); + clonedOptions.arguments = args.join(" "); + const launchIdentity = await fin.System.launchExternalProcess(clonedOptions); identity = { ...launchIdentity, appId: app.appId }; } diff --git a/how-to/workspace-platform-starter/client/src/framework/shapes/app-shapes.ts b/how-to/workspace-platform-starter/client/src/framework/shapes/app-shapes.ts index b3c401814f..d57ed6d52a 100644 --- a/how-to/workspace-platform-starter/client/src/framework/shapes/app-shapes.ts +++ b/how-to/workspace-platform-starter/client/src/framework/shapes/app-shapes.ts @@ -204,7 +204,7 @@ export interface ViewPreferenceUrl extends ViewPreference>; + native?: { + /** + * Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap. + */ + args?: string[]; + }; /** * What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified. @@ -293,12 +298,6 @@ export interface HostLaunchOptions { * Additional options that apply to the app when used in a snap context */ export interface SnapLaunchOptions { - /** - * Snap requires args as a string array, not a single string like in app assets. - * So we provide the ability to include them here. - */ - args?: string[]; - /** * The strategy for launching and locating the application. */ diff --git a/how-to/workspace-platform-starter/client/types/module/shapes/app-shapes.d.ts b/how-to/workspace-platform-starter/client/types/module/shapes/app-shapes.d.ts index b9900792fb..967ebc3a83 100644 --- a/how-to/workspace-platform-starter/client/types/module/shapes/app-shapes.d.ts +++ b/how-to/workspace-platform-starter/client/types/module/shapes/app-shapes.d.ts @@ -181,7 +181,7 @@ export interface ViewPreferenceUrl extends ViewPreference>; + native?: { + /** + * Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap. + */ + args?: string[]; + }; /** * What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified. * By default nothing can be set outside of the app definition when launching the app. @@ -255,11 +260,6 @@ export interface HostLaunchOptions { * Additional options that apply to the app when used in a snap context */ export interface SnapLaunchOptions { - /** - * Snap requires args as a string array, not a single string like in app assets. - * So we provide the ability to include them here. - */ - args?: string[]; /** * The strategy for launching and locating the application. */ diff --git a/how-to/workspace-platform-starter/public/schemas/fdc3v1.2-appd.schema.json b/how-to/workspace-platform-starter/public/schemas/fdc3v1.2-appd.schema.json index 61073b13a9..c402e60654 100644 --- a/how-to/workspace-platform-starter/public/schemas/fdc3v1.2-appd.schema.json +++ b/how-to/workspace-platform-starter/public/schemas/fdc3v1.2-appd.schema.json @@ -315,6 +315,20 @@ "additionalProperties": false, "description": "Additional options that apply to a native app", "properties": { + "native": { + "additionalProperties": false, + "description": "Launch Preferences related to native apps", + "properties": { + "args": { + "description": "Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, "snap": { "$ref": "#/definitions/SnapLaunchOptions", "description": "If specified it indicates the native app should be included when snapping." @@ -323,11 +337,35 @@ "const": "native", "description": "Native options type", "type": "string" + }, + "updatable": { + "description": "What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.\nBy default nothing can be set outside of the app definition when launching the app.", + "items": { + "$ref": "#/definitions/NativePreference" + }, + "type": "array" } }, "required": ["type"], "type": "object" }, + "NativePreference": { + "additionalProperties": false, + "description": "Which Launch Options are updatable and are there any constraints", + "properties": { + "name": { + "$ref": "#/definitions/NativePreferenceName", + "description": "What setting is updatable?" + } + }, + "required": ["name"], + "type": "object" + }, + "NativePreferenceName": { + "const": "args", + "description": "A list of native related settings that can be updated.", + "type": "string" + }, "Partial": { "$ref": "#/definitions/__type" }, @@ -343,13 +381,6 @@ "additionalProperties": false, "description": "Additional options that apply to the app when used in a snap context", "properties": { - "args": { - "description": "Snap requires args as a string array, not a single string like in app assets.\nSo we provide the ability to include them here.", - "items": { - "type": "string" - }, - "type": "array" - }, "strategy": { "$ref": "#/definitions/LaunchStrategy", "description": "The strategy for launching and locating the application." diff --git a/how-to/workspace-platform-starter/public/schemas/fdc3v2.0-appd.schema.json b/how-to/workspace-platform-starter/public/schemas/fdc3v2.0-appd.schema.json index 3f99381a06..ab70325871 100644 --- a/how-to/workspace-platform-starter/public/schemas/fdc3v2.0-appd.schema.json +++ b/how-to/workspace-platform-starter/public/schemas/fdc3v2.0-appd.schema.json @@ -491,6 +491,20 @@ "additionalProperties": false, "description": "Additional options that apply to a native app", "properties": { + "native": { + "additionalProperties": false, + "description": "Launch Preferences related to native apps", + "properties": { + "args": { + "description": "Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, "snap": { "$ref": "#/definitions/SnapLaunchOptions", "description": "If specified it indicates the native app should be included when snapping." @@ -499,11 +513,35 @@ "const": "native", "description": "Native options type", "type": "string" + }, + "updatable": { + "description": "What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.\nBy default nothing can be set outside of the app definition when launching the app.", + "items": { + "$ref": "#/definitions/NativePreference" + }, + "type": "array" } }, "required": ["type"], "type": "object" }, + "NativePreference": { + "additionalProperties": false, + "description": "Which Launch Options are updatable and are there any constraints", + "properties": { + "name": { + "$ref": "#/definitions/NativePreferenceName", + "description": "What setting is updatable?" + } + }, + "required": ["name"], + "type": "object" + }, + "NativePreferenceName": { + "const": "args", + "description": "A list of native related settings that can be updated.", + "type": "string" + }, "OnlineNativeAppDetails": { "additionalProperties": false, "description": "Online native application details.", @@ -560,13 +598,6 @@ "additionalProperties": false, "description": "Additional options that apply to the app when used in a snap context", "properties": { - "args": { - "description": "Snap requires args as a string array, not a single string like in app assets.\nSo we provide the ability to include them here.", - "items": { - "type": "string" - }, - "type": "array" - }, "strategy": { "$ref": "#/definitions/LaunchStrategy", "description": "The strategy for launching and locating the application." diff --git a/how-to/workspace-platform-starter/public/schemas/platform-apps.schema.json b/how-to/workspace-platform-starter/public/schemas/platform-apps.schema.json index 40207d948b..4789421963 100644 --- a/how-to/workspace-platform-starter/public/schemas/platform-apps.schema.json +++ b/how-to/workspace-platform-starter/public/schemas/platform-apps.schema.json @@ -384,6 +384,20 @@ "additionalProperties": false, "description": "Additional options that apply to a native app", "properties": { + "native": { + "additionalProperties": false, + "description": "Launch Preferences related to native apps", + "properties": { + "args": { + "description": "Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, "snap": { "$ref": "#/definitions/SnapLaunchOptions", "description": "If specified it indicates the native app should be included when snapping." @@ -392,11 +406,35 @@ "const": "native", "description": "Native options type", "type": "string" + }, + "updatable": { + "description": "What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.\nBy default nothing can be set outside of the app definition when launching the app.", + "items": { + "$ref": "#/definitions/NativePreference" + }, + "type": "array" } }, "required": ["type"], "type": "object" }, + "NativePreference": { + "additionalProperties": false, + "description": "Which Launch Options are updatable and are there any constraints", + "properties": { + "name": { + "$ref": "#/definitions/NativePreferenceName", + "description": "What setting is updatable?" + } + }, + "required": ["name"], + "type": "object" + }, + "NativePreferenceName": { + "const": "args", + "description": "A list of native related settings that can be updated.", + "type": "string" + }, "Partial": { "$ref": "#/definitions/__type" }, @@ -628,13 +666,6 @@ "additionalProperties": false, "description": "Additional options that apply to the app when used in a snap context", "properties": { - "args": { - "description": "Snap requires args as a string array, not a single string like in app assets.\nSo we provide the ability to include them here.", - "items": { - "type": "string" - }, - "type": "array" - }, "strategy": { "$ref": "#/definitions/LaunchStrategy", "description": "The strategy for launching and locating the application." diff --git a/how-to/workspace-platform-starter/public/schemas/settings.schema.json b/how-to/workspace-platform-starter/public/schemas/settings.schema.json index b3276991ba..cbc4e0ca57 100644 --- a/how-to/workspace-platform-starter/public/schemas/settings.schema.json +++ b/how-to/workspace-platform-starter/public/schemas/settings.schema.json @@ -3087,6 +3087,20 @@ "additionalProperties": false, "description": "Additional options that apply to a native app", "properties": { + "native": { + "additionalProperties": false, + "description": "Launch Preferences related to native apps", + "properties": { + "args": { + "description": "Arguments are set as an array for compatibility with appAssets, launchExternalProcess and Snap.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, "snap": { "$ref": "#/definitions/SnapLaunchOptions", "description": "If specified it indicates the native app should be included when snapping." @@ -3095,6 +3109,13 @@ "const": "native", "description": "Native options type", "type": "string" + }, + "updatable": { + "description": "What can be specified when launching a native app. This is an array of named types to reflect the properties you are happy to be specified.\nBy default nothing can be set outside of the app definition when launching the app.", + "items": { + "$ref": "#/definitions/NativePreference" + }, + "type": "array" } }, "required": [ @@ -3102,6 +3123,25 @@ ], "type": "object" }, + "NativePreference": { + "additionalProperties": false, + "description": "Which Launch Options are updatable and are there any constraints", + "properties": { + "name": { + "$ref": "#/definitions/NativePreferenceName", + "description": "What setting is updatable?" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "NativePreferenceName": { + "const": "args", + "description": "A list of native related settings that can be updated.", + "type": "string" + }, "NotificationClientDefaultOptions": { "additionalProperties": false, "description": "A set of default options that will apply against all notification clients unless they\nhave a setting of their own.", @@ -3941,13 +3981,6 @@ "additionalProperties": false, "description": "Additional options that apply to the app when used in a snap context", "properties": { - "args": { - "description": "Snap requires args as a string array, not a single string like in app assets.\nSo we provide the ability to include them here.", - "items": { - "type": "string" - }, - "type": "array" - }, "strategy": { "$ref": "#/definitions/LaunchStrategy", "description": "The strategy for launching and locating the application."