A Guide to Developing and Deploying Content Packages for SAP Build Work Zone, Standard Edition

[jens_kristen]

Introduction

In this blog post I'll describe a simplified way how to create and deploy an UI Integration Card to SAP Build Work Zone, standard edition. To make UI Integration Cards available in SAP Build Work Zone, standard edition you must add it to a Content Package.

We will create a Content Package project with a sample UI Integration Card but you can also add your own cards to this project. A good introduction how to develop UI Integration Card can be found here. 

Now, let's get started with the implementation of the Content Package!

Create a Content Package Project with SAP Business Application Studio

Step 1: Open SAP Business Application Studio and create and activate a SAP Fiori or a Full Stack Cloud Application Dev Space.

Give the dev space a meaningful name and select the SAP Extension Development Tools for SAP Build Work Zone.

Step 2: Choose hamburger menu -> File -> New Project from Template

Step 3: Choose Content Package.

The Content Package project provides a collection of sample UI Integration Cards, Workflows and Workspaces.

Step 4: Maintain the values for:

• Project Name
• Namespace
• Title
• Set Include Content Samples -> True

Modify the Content Package Project

The Content Package project bundles different content artifacts such as:

• manifest.json - The Content Package descriptor
• content.json - maintains the content of a Content Package
• i18n - folder contains reference localization files. 
• internalsamples - folder contains samples of UI Integration Cards, Workflows and Workspace templates

A few files must be modified and added before the Content Package can be deployed to the SAP Build Work Zone, standard edition.

Step 1: Change the following values in manifest.json:

• Change the id with an abbreviation of your company specific namespace. Note: The Content Package id can’t be more than 20 chars!
• Set the title and subTitle for the Content Package.

Sample code for manifest.json:

{
	"sap.package": {
		"id": "ns.sap.cp",
		"packageVersion": {
			"version": "1.0.0",
			"upgradeNotification": "all"
		},
		"i18n": "i18n/i18n.properties",
		"icon": "sap-icon://accept",
		"title": "MyContentPackage",
		"subTitle": "UICards",
		"shortTitle": "",
.....

Step 2: Maintain the Role, Space, Workpage and UI Integration Card entities for the Content Package.

The Content Package must include a role, a space and a workpage before it can be deployed to SAP Build Work Zone, standard edition. These entities need to be defined as part of the content.json file. 

To enable the UI Integration Card usage, you must define at least one role in the Content Package to which the card is assigned to. 

Sample content.json code:

{"sample-role": {
    "type": "role",
    "src": {
      "from": "./internalsamples/src",
      "content": "role.json"
    }
  },
  "sample-space": {
    "type": "space",
    "src": {
      "from": "./internalsamples/src",
      "content": "space.json"
    }
  },
  "sample-workpage": {
    "type": "workpage",
    "src": {
      "from": "./internalsamples/src",
      "content": "workpage.json"
    }
  },
    "card-sample": {
        "type": "card",
        "src": {
            "from": "./internalsamples/card",
            "path": "./",
            "build": "",
            "package": "sap-workzone-cpkg-card-sample.zip",
            "manifest": "src/manifest.json"
        }
    }
}

In this sample, the artifact sources are located in the internalsamples folder. The from parameter references a folder relative path where the artefact sources (Space, Workpage, Role,UI Integration Card) are located. In the next steps we create this folder and the respective .json files.  

Step 3: Add a new folder in the project folder internalsample and name it src. 

Step 4: Create the files for the role, workpage and space in the src folder:

• role.json
• workpage.json
• space.json

Step 5: Copy the example code and paste it into the respective files:

Sample code for role.json :

{
    "_version": "3.2.0",
    "identification": {
      "id": "my.company.ns.contentpackage.role1",
      "title": "ContentPackageRole",
      "entityType": "role"
    },
    "payload": {
      "spaces": [
        {
          "id": "my.company.ns.contentpackage.space"
        }
      ],
      "apps": [
        {
          "id": "sap.workzone.cpkg.card.sample.app"
        }
      ]
    }
  }

Note: Pay attention to compose the referencing app id, you must merging the card id with .app at the end!

The apps array contains all the card references you want to assign to the defined role. Once the Content Package is deployed you will find a corresponding Role Collection in the subaccount. Later you assign this Role Collection to the users and to the SAP Build Work Zone business site.

Sample code for workpage.json:

{
    "_version": "3.2.0",
    "identification": {
      "id": "my.company.ns.contentpackage.workpage",
      "entityType": "workpage"
    },
    "payload": {
      "workpageConfig": {
        "title": "My Workpage"
      },
      "rows": [
        {
          "id": "row-1",
          "rowConfig": {},
          "columns": [
            {
              "id": "col-11",
              "columnConfig": {},
              "cells": [
                {
                  "id": "cell-111",
                  "cellConfig": {},
                  "widgets": [
                    {
                      "id": "widg-1111",
                      "viz": {
                        "appId": "sap.workzone.cpkg.card.sample.app",
                        "vizId": "sap.workzone.cpkg.card.sample.viz"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }

Sample code for space.json:

{
    "_version": "3.1.0",
    "identification": {
      "id": "my.company.ns.contentpackage.space",
      "title": "MySpace",
      "entityType": "space"
    },
    "payload": {
      "contentNodes": [
        {
          "type": "workpage",
          "id": "my.company.ns.contentpackage.workpage"
        }
      ]
    }
  }

Step 6: Create the Content Package .zip file. Right click on the manifest.json and choose in the menu: Content Package:Package

The direct deployment of Content Packages from SAP Business Application Studio into the SAP Build Work Zone, standard edition is not supported. The Content Package must be downloaded as a ZIP file, then you can upload it with Channel Manager of SAP Build Work Zone, standard edition.

Step 6: Download the Content Package. Right click on the  package.zip -> Download 

Create a Business Site in SAP Build Work Zone, Standard Edition

Before moving on to the deployment of the Content Package ensure that your SAP Build Work Zone, standard edition, is correctly set up and configured. 

Step 1: Open the SAP Build Work Zone, standard edition Service and Create a new Site in the Site Directory

Step 2: Go to the Site Settings

Step 3: Choose Edit. In the Assignments area on the right you can now assign the ContentPackageRole to the site by clicking '+'.

Make sure that the Spaces and Pages - New Experience is chosen and save the site settings.

SAP Build Work Zone, standard edition has a New Site Experience with spaces and pages. The pages are based on the Horizon visual theme for SAP Fiori and they have a flexible grid-based layout. UI Integration Cards and app tiles for the visual representation of applications on the different widget areas can easily added. Further information can be found here.

Upload the Content Package into SAP Build Work Zone, Standard Edition

To upload the Content Package you can use the Channel Manager of SAP Build Work Zone, standard edition.

Step 1: Go to the Channel Manager and press New Content Package. Browse to the package.zip file and set a Runtime Destination. This sample Content Package does not require navigation to a back-end system, so you can choose a dummy destination with only a name, type HTTP, and any URL. For more information, see Create Runtime Destinations to Access Apps.

Step 2: Check if the Content Package contains all the needed entities by clicking the Report link in the column Status. In this sample you see that the Content Package contains a role, app, space and page.

Step 3: Go to the Content Manager and search for the new role ContentPackageRole. You should see now that a app and a space is assigned to the ContentPackageRole.

Step 4: Assign a Role Collection to your SAP Build Work Zone, standard edition user in the Business Technology Platform Cockpit. Go to Users -> Assign Role Collection and search for ContentPackageRole

Test the Business Site

Step 1: Click Go to site icon to open the business site.

Great, that's it, you done! You have added the Content Package including the UI Integration Card to your business site.

Note: This guide is based on a GitHub sample about developing Content Packages. Here you find additional documentation and further sample source code.

Additional helpful links:

SAP Build Work Zone, standard edition Help Portal

SAP Build Work Zone Learning Journeys 

SAP Build Work Zone Integration Samples on Git Hub