Getting Started
Deployment Strategy¶
We recommend centralized deployment for this component, as the decentralized or packaged deployment has known issues when used with ABAP systems and SAP Business Technology Platform (BTP). Use decentralized deployment only if centralized deployment is not feasible.
For decentralized deployment in ABAP, see ABAP Component Deployment. For BTP deployment, special considerations are necessary, which are detailed in BTP Deployment. A full BTP deployment example is available in this sample project.
Decentralized Deployment¶
Decentralized Deployment
This method is not recommended. Please use the Central Deployment instead.
In decentralized deployment, the component is included directly in each app and deployed with it. For ABAP-specific instructions, refer to ABAP Component Deployment.
Central Deployment¶
In centralized deployment, the Spreadsheet Upload component is stored centrally, either in an on-premise ABAP system or in BTP. For detailed instructions, see the Central Deployment page.
Setup¶
To integrate the ui5-cc-spreadsheetimporter
component manually, follow the steps below. For a simplified setup, you can also use the Yo generator.
Requirements¶
- Node.js v16.18.0, v18.12.0 or higher
- npm v8.0.0 or higher
- UI5 CLI v3.0.0 or higher
Setup for Decentralized Deployment¶
1. Install the component from npm:
2. Add resourceRoots
to your manifest.json
under sap.ui5
:
!!! warning "Version Management" Ensure your ui5-cc-spreadsheetimporter
version is up to date in your manifest.json
whenever updating the module. For more information, see Version Namespace.
"resourceRoots": {
"cc.spreadsheetimporter.v1_4_1": "./thirdparty/customcontrol/spreadsheetimporter/v1_4_1"
}
3. Update your build script in package.json
by adding --all
:
4. Add componentUsages
to your manifest.json
under sap.ui5
:
!!! warning "Version Management" Ensure your ui5-cc-spreadsheetimporter
version is up to date in your manifest.json
whenever updating the module. For more information, see Version Namespace.
5. Optional: Handle the "component does not exist" error
If you encounter the component does not exist
error when deploying to an SAP System (S/4 On-Premise or SAP BTP ABAP environment), add the following to your manifest.json
:
!!! warning "Resource Roots Path" Ensure the resourceRoots
path is correct, especially the lowercase format change since version 0.34.0.
Setup for Central Deployment¶
1. Deploy the component using your desired version. Refer to Central Deployment for detailed instructions.
2. Add componentUsages
to your manifest.json
under sap.ui5
:
!!! warning "Version Management" Ensure your ui5-cc-spreadsheetimporter
version is up to date in your manifest.json
whenever updating the module. For more information, see Version Namespace. Ensure the version is available in the system.
Starting with the Fiori Elements Application¶
OData Version Differences
There are different implementations for Fiori Elements depending on the OData version.
To start the Spreadsheet Upload Dialog, add a button in your Fiori Elements App. The Guided Development extension is a recommended way to add a custom action:
After adding the custom action, implement your custom code either with V2 or V4. You can also use a controller extension in Fiori Elements. See the Fiori Elements V4 Example App for an example.
Starting with Fiori Elements (OData V4)¶
Manifest.json Extension¶
Here is an example of a custom action from the sample app for the object page. This example adds a button to the order items table on the object page. If there are multiple tables, always specify the relevant tableId
. Use "enabled": "{ui>/isEditable}"
to automatically disable the button when the page is not in edit mode.
"OrdersObjectPage": {
"type": "Component",
"id": "OrdersObjectPage",
"name": "sap.fe.templates.ObjectPage",
"options": {
"settings": {
"editableHeaderContent": false,
"entitySet": "Orders",
"navigation": {
"Items": {
"detail": {
"route": "Orders_ItemsObjectPage"
}
}
},
"controlConfiguration": {
"Items/@com.sap.vocabularies.UI.v1.LineItem": {
"actions": {
"ObjectPageExtController": {
"press": "ui.v4.ordersv4fe.ext.ObjectPageExtController.openSpreadsheetUploadDialogTable",
"visible": true,
"requiresSelection": false,
"enabled": "{ui>/isEditable}",
"text": "Spreadsheet Upload"
}
}
}
}
}
}
}
Custom Code¶
The following code sets the busy indicator, creates the component if not already created, and opens the dialog. The context
attribute is mandatory to allow the component to access the app's context, including binding paths and the model. You can pass options like context
at runtime using the openSpreadsheetUploadDialog
method. This is useful when opening the dialog for specific tables (see TableSelector).
openSpreadsheetUploadDialog: async function (event) {
this.getView().setBusyIndicatorDelay(0);
this.getView().setBusy(true);
this.spreadsheetUpload = await this.getView()
.getController()
.getAppComponent()
.createComponent({
usage: "spreadsheetImporter",
async: true,
componentData: {
context: this,
},
});
this.spreadsheetUpload.openSpreadsheetUploadDialog();
this.getView().setBusy(false);
}
Example¶
See the live demo at https://livedemo.spreadsheet-importer.com/.
Starting with Fiori Elements (OData V2)¶
Manifest.json Extension¶
Here is an example of a custom action from the sample app for the object page.
"extends": {
"extensions": {
"sap.ui.controllerExtensions": {
"sap.suite.ui.generic.template.ObjectPage.view.Details": {
"controllerName": "ui.v2.ordersv2.ext.controller.ObjectPageExt",
"sap.ui.generic.app": {
"Orders": {
"EntitySet": "Orders",
"Sections": {
"Items::com.sap.vocabularies.UI.v1.LineItem": {
"id": "Items::com.sap.vocabularies.UI.v1.LineItem",
"Actions": {
"spreadsheetImporter": {
"id": "spreadsheetUploadButton",
"text": "Spreadsheet Upload",
"applicablePath": "ui>/editable",
"press": "openSpreadsheetUploadDialog",
"requiresSelection": false
}
}
}
}
}
}
}
}
}
}
Custom Code¶
openSpreadsheetUploadDialog: async function (event) {
this.getView().setBusyIndicatorDelay(0);
this.getView().setBusy(true);
this.spreadsheetUpload = await this.getView()
.getController()
.getOwnerComponent()
.createComponent({
usage: "spreadsheetImporter",
async: true,
componentData: {
context: this,
},
});
this.spreadsheetUpload.openSpreadsheetUploadDialog();
this.getView().setBusy(false);
}
Deployment of Your App¶
ABAP Stack¶
Component Deployment¶
These instructions apply generally to UI5 Reuse Components, not just the Spreadsheet Importer (see UI5 Reuse Components).
When deploying the component decentrally to an ABAP system, its namespace is registered in the app index, the same as with central deployment. After deploying decentrally for the first time, you can use the component centrally (see Setup Central Deployment). However, you can only deploy the component decentrally once because the namespace can only exist once in the app index.
This is why we recommend starting with central deployment.
Using the Component Outside the App Index¶
If the component is used outside the Fiori Launchpad, or if it cannot be found even after deployment, you can direct the app to the correct path using url
and name
in the createComponent
method:
openSpreadsheetUploadDialog: async function (oEvent) {
this.getView().setBusyIndicatorDelay(0);
this.getView().setBusy(true);
this.spreadsheetUpload = await this.getView()
.getController()
.getAppComponent()
.createComponent({
usage: "spreadsheetImporter",
async: true,
componentData: {
context: this,
},
url: "/sap/bc/ui5_ui5/sap/Z_XUP_v0_33_2",
name: "cc.spreadsheetimporter.v1_4_1"
});
this.spreadsheetUpload.openSpreadsheetUploadDialog();
this.getView().setBusy(false);
}
This method can be used as an alternative to resourceRoots
in the manifest.json
when you do not have access to the manifest.json
(e.g., in adaptation projects).
Error: Library/Component Used in Application Does Not Exist¶
When deploying the app to your ABAP system, you might encounter an error like SAPUI5 library/component cc.spreadsheetimporter.v1_4_1 used in application Z*** does not exist
. The application is deployed, but the service returns an error.
To avoid this error, add the following to your manifest.json
file:
Resource Roots Path
Ensure the resourceRoots
path is correct, especially the lowercase format change since version 0.34.0.
This addition should resolve the issue, making resourceRoots
unnecessary.
File Unknown When Deploying the App¶
If the ABAP system does not recognize .ts
files, create a .Ui5RepositoryTextFiles
file in your app's webapp
folder, as described here. An example file is available here and might look like this:
If you use the deploy-to-abap
command, you can exclude these files from the deployment by adding the exclude
option to your ui5.yaml
file:
customTasks:
- name: deploy-to-abap
afterTask: replaceVersion
configuration:
target:
url: https://XYZ.sap-system.corp:44311
client: 200
auth: basic
credentials:
username: env:XYZ_USER
password: env:XYZ_PASSWORD
app:
name: /TEST/SAMPLE_APP
package: /TEST/UPLOAD
transport: XYZQ300582
exclude:
- .*\.ts
- .*\.ts.map
- .*\.js.map
BTP Environment¶
Running with CAP¶
If you are using CAP and installing the component as a dependency to your UI5 App, you need to use cds-plugin-ui5
to ensure the UI5 Tooling loads the installed component.
Configuring ui5-task-zipper
in Your Deployment YAML File¶
A full example can be found in this sample project.
If you use the ui5-task-zipper
task, ensure that ui5-cc-spreadsheetimporter
is included in the zip file.
builder:
customTasks:
- name: ui5-task-zipper
afterTask: generateComponentPreload
configuration:
archiveName: uimodule
includeDependencies:
- ui5-cc-spreadsheetimporter-v1-4-1
The metadata name is defined in the ui5.yaml
file of the component.
Metadata Name
Before version 0.34.0, the metadata name was ui5-cc-spreadsheetimporter
without the version.
Updating "sap.cloud".service
in Spreadsheet Importer manifest.json
¶
When using decentralized deployment, deployment may fail with the following error:
"Service name 'spreadsheetimporter_v1_4_1' and public setting 'true' in embedded manifest.json have to be equal to service name 'xxxxxxx' and public setting 'true' of root manifest.json"
SAP currently does not provide a fix for this.
Workaround 1¶
Manually update the service
name in the manifest.json
of the Spreadsheet Importer to match the service name in your app's manifest.json
.
To automate this, you can use the custom UI5 Tooling task ui5-task-btp-manifest
.
Install the Task¶
Add the Task to Your ui5.yaml
¶
This task will update the Spreadsheet Importer manifest with the app's service name at this path: dist/thirdparty/customcontrol/spreadsheetimporter/v1_4_1/manifest.json
.
Workaround 2¶
According to a comment from user TravelTechCode, you can try the following deployment sequence:
- Deploy your app without the UI5 Spreadsheet component first.
- Add the UI5 Spreadsheet component and deploy the app again.
This approach avoids deployment errors and allows the component to be accessed in the content explorer.