@sapui5/sap.fe.core 1.97.0 → 1.100.0

package/src/sap/fe/core/actions/draft.ts

@@ -0,0 +1,566 @@
+import Dialog from "sap/m/Dialog";
+import Button from "sap/m/Button";
+import Text from "sap/m/Text";
+import MessageBox from "sap/m/MessageBox";
+import messageHandling from "sap/fe/core/actions/messageHandling";
+import CommonUtils from "sap/fe/core/CommonUtils";
+import Log from "sap/base/Log";
+import AppComponent from "sap/fe/core/AppComponent";
+import { SideEffectsService } from "sap/fe/core/services/SideEffectsServiceFactory";
+import ResourceBundle from "sap/base/i18n/ResourceBundle";
+import View from "sap/ui/core/mvc/View";
+import Context from "sap/ui/model/odata/v4/Context";
+import ODataMetaModel from "sap/ui/model/odata/v4/ODataMetaModel";
+import ResourceModel from "sap/ui/model/resource/ResourceModel";
+
+/**
+ * Interface for callbacks used in the functions
+ *
+ *
+ * @author SAP SE
+ * @since 1.54.0
+ * @interface
+ * @name sap.fe.core.actions.draft.ICallback
+ * @private
+ */
+
+/**
+ * Callback to approve or reject the creation of a draft
+ * @name sap.fe.core.actions.draft.ICallback.beforeCreateDraftFromActiveDocument
+ * @function
+ * @static
+ * @abstract
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the active document for the new draft
+ * @returns {(boolean|Promise)} Approval of draft creation [true|false] or Promise that resolves with the boolean value
+ *
+ * @private
+ */
+
+/**
+ * Callback after a draft was successully created
+ * @name sap.fe.core.actions.draft.ICallback.afterCreateDraftFromActiveDocument
+ * @function
+ * @static
+ * @abstract
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the new draft
+ * @param {sap.ui.model.odata.v4.Context} oActiveDocumentContext Context of the active document for the new draft
+ * @returns {sap.ui.model.odata.v4.Context} oActiveDocumentContext
+ *
+ * @private
+ */
+
+/**
+ * Callback to approve or reject overwriting an unsaved draft of another user
+ * @name sap.fe.core.actions.draft.ICallback.whenDecisionToOverwriteDocumentIsRequired
+ * @function
+ * @public
+ * @static
+ * @abstract
+ *
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the active document for the new draft
+ * @returns {(boolean|Promise)} Approval to overwrite unsaved draft [true|false] or Promise that resolves with the boolean value
+ *
+ * @ui5-restricted
+ */
+/* Constants for draft operations */
+const draftOperations = {
+	EDIT: "EditAction",
+	ACTIVATION: "ActivationAction",
+	DISCARD: "DiscardAction",
+	PREPARE: "PreparationAction"
+};
+/**
+ * Static functions for the draft programming model
+ *
+ * @namespace
+ * @alias sap.fe.core.actions.draft
+ * @private
+ * @experimental This module is only for experimental use! <br/><b>This is only a POC and maybe deleted</b>
+ * @since 1.54.0
+ */
+const draft = {
+	createDraftFromActiveDocument: createDraftFromActiveDocument,
+	activateDocument: activateDocument,
+	deleteDraft: deleteDraft
+};
+/**
+ * Determines action name for a draft operation.
+ *
+ * @param {sap.ui.model.odata.v4.Context} oContext The context that should be bound to the operation
+ * @param {string} sOperation The operation name
+ * @returns {string} The name of the draft operation
+ */
+function getActionName(oContext: any, sOperation: string) {
+	const oModel = oContext.getModel(),
+		oMetaModel = oModel.getMetaModel(),
+		sEntitySetPath = oMetaModel.getMetaPath(oContext.getPath());
+
+	return oMetaModel.getObject(sEntitySetPath + "@com.sap.vocabularies.Common.v1.DraftRoot/" + sOperation);
+}
+/**
+ * Creates an operation context binding for the given context and operation.
+ *
+ * @param {sap.ui.model.odata.v4.Context} oContext The context that should be bound to the operation
+ * @param {string} sOperation The operation (action or function import)
+ * @param oOptions Options to create the operation context
+ * @returns {sap.ui.model.odata.v4.ODataContextBinding} The context binding of the bound operation
+ */
+function createOperation(oContext: any, sOperation: string, oOptions?: any) {
+	const sOperationName = getActionName(oContext, sOperation);
+
+	return oContext.getModel().bindContext(sOperationName + "(...)", oContext, oOptions);
+}
+/**
+ * Check if optional draft prepare action exists.
+ *
+ * @param {sap.ui.model.odata.v4.Context} oContext The context that should be bound to the operation
+ * @returns {boolean} True if a a prepare action exists
+ */
+function hasPrepareAction(oContext: any) {
+	return !!getActionName(oContext, draftOperations.PREPARE);
+}
+/**
+ * Creates a new draft from an active document.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the action should be performed
+ * @param {boolean} bPreserveChanges If true - existing changes from another user that are not locked are preserved and an error message (http status 409) is send from the backend, otherwise false - existing changes from another user that are not locked are overwritten</li>
+ * @returns {Promise.<sap.ui.model.odata.v4.Context>} Resolve function returns the context of the operation
+ * @private
+ * @ui5-restricted
+ */
+function executeDraftEditAction(oContext: any, bPreserveChanges: boolean) {
+	if (oContext.getProperty("IsActiveEntity")) {
+		const oOptions = { $$inheritExpandSelect: true };
+		const oOperation = createOperation(oContext, draftOperations.EDIT, oOptions);
+		oOperation.setParameter("PreserveChanges", bPreserveChanges);
+		const sGroupId = "direct";
+		const localI18nRef = sap.ui.getCore().getLibraryResourceBundle("sap.fe.core") as ResourceBundle;
+		const sActionName = localI18nRef.getText("C_COMMON_OBJECT_PAGE_EDIT");
+		const oEditPromise = oOperation
+			.execute(sGroupId, undefined, CommonUtils.fnOnStrictHandlingFailed.bind(draft, sGroupId, sActionName, oContext.getModel()))
+			.then(function(oDraftDocumentContext: any) {
+				return oDraftDocumentContext;
+			});
+		oOperation.getModel().submitBatch(sGroupId);
+		return oEditPromise;
+	} else {
+		throw new Error("You cannot edit this draft document");
+	}
+}
+
+/**
+ * Activates a draft document. The draft will replace the sibling entity and will be deleted by the back end.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the action should be performed
+ * @param {object} oAppComponent The AppComponent
+ * @param {string} [sGroupId] The optional batch group in which the operation is to be executed
+ * @returns {Promise.<sap.ui.model.odata.v4.Context>} Resolve function returns the context of the operation
+ * @private
+ * @ui5-restricted
+ */
+function executeDraftActivationAction(oContext: any, oAppComponent: AppComponent, sGroupId?: string) {
+	const bHasPrepareAction = hasPrepareAction(oContext);
+
+	// According to the draft spec if the service contains a prepare action and we trigger both prepare and
+	// activate in one $batch the activate action is called with iF-Match=*
+	const bIgnoreEtag = bHasPrepareAction;
+
+	if (!oContext.getProperty("IsActiveEntity")) {
+		const oOperation = createOperation(oContext, draftOperations.ACTIVATION, { $$inheritExpandSelect: true });
+		const localI18nRef = sap.ui.getCore().getLibraryResourceBundle("sap.fe.core") as ResourceBundle;
+		const sActionName = localI18nRef.getText("C_OP_OBJECT_PAGE_SAVE");
+		return oOperation
+			.execute(
+				sGroupId,
+				bIgnoreEtag,
+				sGroupId ? CommonUtils.fnOnStrictHandlingFailed.bind(draft, sGroupId, sActionName, oContext.getModel()) : undefined
+			) //3rd parameter<------
+			.then(function(oActiveDocumentContext: any) {
+				return oActiveDocumentContext;
+			})
+			.catch(
+				//if ACTIVATE action fails then we request either the sideEffects against PREPARE action (if annotated) or the messages as fallback:
+				function() {
+					if (bHasPrepareAction) {
+						const sActionName = getActionName(oContext, draftOperations.PREPARE),
+							oSideEffectsService = oAppComponent.getSideEffectsService(),
+							oBindingParameters = oSideEffectsService.getODataActionSideEffects(sActionName, oContext),
+							aTargetPaths = oBindingParameters && oBindingParameters.pathExpressions;
+						if (aTargetPaths && aTargetPaths.length > 0) {
+							oSideEffectsService.requestSideEffects(aTargetPaths, oContext).catch(function(oError: any) {
+								Log.error("Error while requesting side effects", oError);
+							});
+						} else {
+							requestMessages(oContext, oSideEffectsService).catch(function(oError: any) {
+								Log.error("Error while requesting messages", oError);
+							});
+						}
+					}
+					return Promise.reject();
+				}
+			);
+	} else {
+		throw new Error("The activation action cannot be executed on an active document");
+	}
+}
+/**
+ * Execute a preparation action.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the action should be performed
+ * @param {string} groupId The optional batch group in which we want to execute the operation
+ * @returns {Promise.<sap.ui.model.odata.v4.Context>} Resolve function returns the context of the operation
+ * @private
+ * @ui5-restricted
+ */
+function executeDraftPreparationAction(oContext: Context, groupId?: string) {
+	if (!oContext.getProperty("IsActiveEntity")) {
+		const oOperation = createOperation(oContext, draftOperations.PREPARE);
+
+		// TODO: side effects qualifier shall be even deprecated to be checked
+		oOperation.setParameter("SideEffectsQualifier", "");
+
+		const sGroupId = groupId || oOperation.getGroupId();
+		return oOperation
+			.execute(sGroupId)
+			.then(function() {
+				return oOperation;
+			})
+			.catch(function(oError: any) {
+				Log.error("Error while executing the operation", oError);
+			});
+	} else {
+		throw new Error("The preparation action cannot be executed on an active document");
+	}
+}
+/**
+ * Determines the message path for a context.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the path shall be determined
+ * @returns {string} Message path, empty if not annotated
+ * @private
+ * @ui5-restricted
+ */
+function getMessagesPath(oContext: Context): string {
+	const oModel = oContext.getModel(),
+		oMetaModel = oModel.getMetaModel() as ODataMetaModel,
+		sEntitySetPath = oMetaModel.getMetaPath(oContext.getPath());
+	return oMetaModel.getObject(sEntitySetPath + "/@com.sap.vocabularies.Common.v1.Messages/$Path");
+}
+/**
+ * Requests the messages if annotated for a given context.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the messages shall be requested
+ * @param {object} oSideEffectsService Service for the SideEffects on SAP Fiori elements
+ * @returns {Promise} Promise which is resolved once messages were requested
+ * @private
+ * @ui5-restricted
+ */
+function requestMessages(oContext: any, oSideEffectsService: SideEffectsService) {
+	const sMessagesPath = getMessagesPath(oContext);
+	if (sMessagesPath) {
+		return oSideEffectsService.requestSideEffects([{ $PropertyPath: sMessagesPath }] as any, oContext);
+	}
+	return Promise.resolve();
+}
+/**
+ * Executes discard of a draft function using HTTP Post.
+ *
+ * @function
+ * @param {sap.ui.model.odata.v4.Context} oContext Context for which the action should be performed
+ * @returns {Promise.<sap.ui.model.odata.v4.Context>} Resolve function returns the context of the operation
+ * @private
+ * @ui5-restricted
+ */
+function executeDraftDiscardAction(oContext: any): Promise<boolean> {
+	if (!oContext.getProperty("IsActiveEntity")) {
+		const oDiscardOperation = createOperation(oContext, draftOperations.DISCARD);
+		const localI18nRef = sap.ui.getCore().getLibraryResourceBundle("sap.fe.core") as ResourceBundle;
+		const sGroupId = "direct";
+		const sActionName = localI18nRef.getText("C_TRANSACTION_HELPER_DRAFT_DISCARD_BUTTON");
+		const oDiscardPromise = oDiscardOperation.execute(
+			sGroupId,
+			undefined,
+			CommonUtils.fnOnStrictHandlingFailed.bind(draft, sGroupId, sActionName, oContext.getModel())
+		);
+		oContext.getModel().submitBatch(sGroupId);
+		return oDiscardPromise;
+	} else {
+		throw new Error("The discard action cannot be executed on an active document");
+	}
+}
+/**
+ * Creates a draft document from an existing document.
+ *
+ * The function supports several hooks as there is a certain coreography defined.
+ *
+ * @function
+ * @name sap.fe.core.actions.draft#createDraftFromActiveDocument
+ * @memberof sap.fe.core.actions.draft
+ * @static
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the active document for the new draft
+ * @param {AppComponent} oAppComponent The AppComponent
+ * @param {object} mParameters The parameters
+ * @param {boolean} [mParameters.oView] The view
+ * @param {boolean} [mParameters.bPreserveChanges] Preserve changes of an existing draft of another user
+ * @param {sap.fe.core.actions.draft.ICallback.beforeCreateDraftFromActiveDocument} [mParameters.fnBeforeCreateDraftFromActiveDocument] Callback that allows veto before create request is executed
+ * @param {sap.fe.core.actions.draft.ICallback.afterCreateDraftFromActiveDocument} [mParameters.fnAfterCreateDraftFromActiveDocument] Callback for postprocessiong after draft document was created
+ * @param {sap.fe.core.actions.draft.ICallback.whenDecisionToOverwriteDocumentIsRequired} [mParameters.fnWhenDecisionToOverwriteDocumentIsRequired] Callback for deciding on overwriting an unsaved change by another user
+ * @returns {Promise} Promise resolves with the {@link sap.ui.model.odata.v4.Context context} of the new draft document
+ * @private
+ * @ui5-restricted
+ */
+function createDraftFromActiveDocument(
+	oContext: any,
+	oAppComponent: AppComponent,
+	mParameters: {
+		oView: View;
+		bPreserveChanges?: boolean | undefined;
+		fnBeforeCreateDraftFromActiveDocument?: any;
+		fnAfterCreateDraftFromActiveDocument?: any;
+		fnWhenDecisionToOverwriteDocumentIsRequired?: any;
+	}
+) {
+	const mParam = mParameters || {},
+		localI18nRef = sap.ui.getCore().getLibraryResourceBundle("sap.fe.core") as ResourceBundle,
+		bRunPreserveChangesFlow =
+			typeof mParam.bPreserveChanges === "undefined" || (typeof mParam.bPreserveChanges === "boolean" && mParam.bPreserveChanges); //default true
+
+	/**
+	 * Overwrite or reject based on fnWhenDecisionToOverwriteDocumentIsRequired.
+	 *
+	 * @param {*} bOverwrite Overwrite the change or not
+	 * @returns {Promise} Resolves with result of {@link sap.fe.core.actions#executeDraftEditAction}
+	 */
+	function overwriteOnDemand(bOverwrite: any) {
+		if (bOverwrite) {
+			//Overwrite existing changes
+			const oModel = oContext.getModel();
+			const draftDataContext = oModel.bindContext(oContext.getPath() + "/DraftAdministrativeData").getBoundContext();
+			let oResourceBundle: ResourceBundle;
+
+			return ((mParameters.oView.getModel("sap.fe.i18n") as ResourceModel).getResourceBundle() as Promise<ResourceBundle>)
+				.then(function(_oResourceBundle: any) {
+					oResourceBundle = _oResourceBundle;
+					return draftDataContext.requestObject();
+				})
+				.then(function(draftAdminData: any) {
+					if (draftAdminData) {
+						// remove all unbound transition messages as we show a special dialog
+						messageHandling.removeUnboundTransitionMessages();
+						let sInfo = draftAdminData.InProcessByUserDescription || draftAdminData.InProcessByUser;
+						const sEntitySet = (mParameters.oView.getViewData() as any).entitySet;
+						if (sInfo) {
+							const sLockedByUserMsg = CommonUtils.getTranslatedText(
+								"C_DRAFT_OBJECT_PAGE_DRAFT_LOCKED_BY_USER",
+								oResourceBundle,
+								sInfo,
+								sEntitySet
+							);
+							MessageBox.error(sLockedByUserMsg);
+							throw new Error(sLockedByUserMsg);
+						} else {
+							sInfo = draftAdminData.CreatedByUserDescription || draftAdminData.CreatedByUser;
+							const sUnsavedChangesMsg = CommonUtils.getTranslatedText(
+								"C_DRAFT_OBJECT_PAGE_DRAFT_UNSAVED_CHANGES",
+								oResourceBundle,
+								sInfo,
+								sEntitySet
+							);
+							return showMessageBox(sUnsavedChangesMsg).then(function() {
+								return executeDraftEditAction(oContext, false);
+							});
+						}
+					}
+				});
+		}
+		return Promise.reject(new Error("Draft creation aborted for document: " + oContext.getPath()));
+	}
+
+	function showMessageBox(sUnsavedChangesMsg: any) {
+		return new Promise(function(resolve: (value: any) => void, reject: (reason?: any) => void) {
+			const oDialog = new Dialog({
+				title: localI18nRef.getText("C_DRAFT_OBJECT_PAGE_WARNING"),
+				state: "Warning",
+				content: new Text({
+					text: sUnsavedChangesMsg
+				}),
+				beginButton: new Button({
+					text: localI18nRef.getText("C_COMMON_OBJECT_PAGE_EDIT"),
+					type: "Emphasized",
+					press: function() {
+						oDialog.close();
+						resolve(true);
+					}
+				}),
+				endButton: new Button({
+					text: localI18nRef.getText("C_COMMON_OBJECT_PAGE_CANCEL"),
+					press: function() {
+						oDialog.close();
+						reject("Draft creation aborted for document: " + oContext.getPath());
+					}
+				}),
+				afterClose: function() {
+					oDialog.destroy();
+				}
+			});
+			oDialog.addStyleClass("sapUiContentPadding");
+			oDialog.open();
+		});
+	}
+
+	if (!oContext) {
+		return Promise.reject(new Error("Binding context to active document is required"));
+	}
+
+	return Promise.resolve(
+		mParam.fnBeforeCreateDraftFromActiveDocument
+			? mParam.fnBeforeCreateDraftFromActiveDocument(oContext, bRunPreserveChangesFlow)
+			: true
+	)
+		.then(function(bExecute: any) {
+			if (!bExecute) {
+				throw new Error("Draft creation was aborted by extension for document: " + oContext.getPath());
+			}
+			return executeDraftEditAction(oContext, bRunPreserveChangesFlow).catch(function(oResponse: any) {
+				//Only call back if error 409
+				if (bRunPreserveChangesFlow && oResponse.status === 409) {
+					return Promise.resolve(
+						mParam.fnWhenDecisionToOverwriteDocumentIsRequired ? mParam.fnWhenDecisionToOverwriteDocumentIsRequired() : true
+					).then(overwriteOnDemand);
+				} else {
+					throw new Error(oResponse);
+				}
+			});
+		})
+		.then(function(oDraftContext: any) {
+			return Promise.resolve(
+				mParam.fnAfterCreateDraftFromActiveDocument
+					? mParam.fnAfterCreateDraftFromActiveDocument(oContext, oDraftContext)
+					: oDraftContext
+			);
+		})
+		.then(function(oDraftContext: any) {
+			const sEditActionName = getActionName(oDraftContext, draftOperations.EDIT);
+			const oSideEffects = oAppComponent.getSideEffectsService().getODataActionSideEffects(sEditActionName, oDraftContext);
+			if (oSideEffects?.triggerActions?.length) {
+				return oAppComponent
+					.getSideEffectsService()
+					.requestSideEffectsForODataAction(oSideEffects, oDraftContext)
+					.then(() => {
+						return oDraftContext;
+					});
+			} else {
+				return oDraftContext;
+			}
+		})
+		.catch(function(exc: any) {
+			return Promise.reject(exc);
+		});
+}
+/**
+ * Creates an active document from a draft document.
+ *
+ * The function supports several hooks as there is a certain choreography defined.
+ *
+ * @function
+ * @name sap.fe.core.actions.draft#activateDocument
+ * @memberof sap.fe.core.actions.draft
+ * @static
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the active document for the new draft
+ * @param {object} oAppComponent The AppComponent
+ * @param {object} mParameters The parameters
+ * @param {sap.fe.core.actions.draft.ICallback.fnBeforeActivateDocument} [mParameters.fnBeforeActivateDocument] Callback that allows veto before create request is executed
+ * @param {sap.fe.core.actions.draft.ICallback.fnAfterActivateDocument} [mParameters.fnAfterActivateDocument] Callback for postprocessiong after document was activated.
+ * @returns {Promise} Promise resolves with the {@link sap.ui.model.odata.v4.Context context} of the new draft document
+ * @private
+ * @ui5-restricted
+ */
+function activateDocument(
+	oContext: any,
+	oAppComponent: AppComponent,
+	mParameters: { fnBeforeActivateDocument?: any; fnAfterActivateDocument?: any }
+) {
+	const mParam = mParameters || {};
+
+	if (!oContext) {
+		return Promise.reject(new Error("Binding context to draft document is required"));
+	}
+	return Promise.resolve(mParam.fnBeforeActivateDocument ? mParam.fnBeforeActivateDocument(oContext) : true)
+		.then(function(bExecute: any) {
+			if (!bExecute) {
+				return Promise.reject(new Error("Activation of the document was aborted by extension for document: " + oContext.getPath()));
+			}
+
+			if (!hasPrepareAction(oContext)) {
+				return executeDraftActivationAction(oContext, oAppComponent);
+			}
+
+			/* activation requires preparation */
+			const sBatchGroup = "draft";
+			// we use the same batchGroup to force prepare and activate in a same batch but with different changeset
+			const oPreparePromise = executeDraftPreparationAction(oContext, sBatchGroup);
+			oContext.getModel().submitBatch(sBatchGroup);
+
+			const oActivatePromise = executeDraftActivationAction(oContext, oAppComponent, sBatchGroup);
+
+			return Promise.all([oPreparePromise, oActivatePromise])
+				.then(function(values: [any, any]) {
+					return values[1];
+				})
+				.catch(function(exc: any) {
+					return Promise.reject(exc);
+				});
+		})
+		.then(function(oActiveDocumentContext: any) {
+			return Promise.resolve(
+				mParam.fnAfterActivateDocument ? mParam.fnAfterActivateDocument(oContext, oActiveDocumentContext) : oActiveDocumentContext
+			);
+		})
+		.catch(function(exc: any) {
+			return Promise.reject(exc);
+		});
+}
+/**
+ * HTTP POST call when DraftAction is present for Draft Delete; HTTP DELETE for Draft(when no DraftAction)
+ * and Active Instance uses DELETE always.
+ *
+ * @function
+ * @name sap.fe.core.actions.draft#deleteDraft
+ * @memberof sap.fe.core.actions.draft
+ * @static
+ * @param {sap.ui.model.odata.v4.Context} oContext Context of the document to be discarded
+ * @private
+ * @returns {Promise}
+ * @ui5-restricted
+ */
+function deleteDraft(oContext: any): Promise<boolean> {
+	const sDiscardAction = getActionName(oContext, draftOperations.DISCARD),
+		bIsActiveEntity = oContext.getObject().IsActiveEntity;
+
+	if (bIsActiveEntity || (!bIsActiveEntity && !sDiscardAction)) {
+		//Use Delete in case of active entity and no discard action available for draft
+		if (oContext.hasPendingChanges()) {
+			return oContext
+				.getBinding()
+				.resetChanges()
+				.then(function() {
+					return oContext.delete();
+				})
+				.catch(function(error: any) {
+					return Promise.reject(error);
+				});
+		} else {
+			return oContext.delete();
+		}
+	} else {
+		//Use Discard Post Action if it is a draft entity and discard action exists
+		return executeDraftDiscardAction(oContext);
+	}
+}
+
+export default draft;