Extending SAP Batch Release Hub for Life Sciences

The reference documentation for CAP model is CAPire | CAPire (cloud.sap).

Several developer tutorials on CAP are available at SAP Tutorial Navigator | Tutorials for SAP Developers.

See also the SAP microlearningBTP Multitenant CAP - Extend - openSAP Microlearning.

And also Multitenant Business Applications with CAP | Hands-on Video Tutorials | SAP Blogs

As registered SAP customers, report issues by creating incidents in  SAP Support Portal (SAP Support Portal Home) , using these components

• BC-XS-CDX for CAP in general
• BC-XS-CDX-COR for CDS and Compiler
• BC-XS-CDX-JAV for CAP Java SDK
• BC-XS-CDX-NJS for Node.js Runtime
• BC-XS-CDX-TLS for Tools, IDEs, Build, Deployment

Please be aware that any changes performed to the production could impact detrimentally the application and therefore are entirely at the responsibility of the customer that is deploying such extensions it is good practice to first do all developments locally and /or against a non-production instance.

It is essential that the reader of this tutorial be well acquainted with the contents of the SAP Business Technology Platform | SAP Help Portal and need to rely on a strong support through the SAP BTP Administrator of their SAP BTP account / subaccount.

Configuration and Extension are two terms often used to describes means to achieve the same goal: making something "general" better fitting specific needs.

In SAP Batch Release Hub for Life Sciences these two terms have very specific meaning:

Configuration: through *data* make the application more specific.

Additional information: SAP Batch Release Hub for Life Sciences | SAP Help Portal

Examples:

• The BTP administrator has to create and configure Destinations with specific information so that services can be connected
• The application administrator has to create rules and assign release types to enable automation
• The application administration has to create the "Quality Department" and configure it so that specific users only can use it with specific roles
• The users themselves can modify the User Interface by applying specific filters and see only specific columns in table visualizations

Extension: through *code* make the application more specific

Additional information:

• Extensibility of SAP Batch Release Hub for Life Sciences | SAP Help Portal
• Extensibility | SAP Help Portal

Examples:

• The "Plants" data model needs to be extended in order to have additional field that did not exist before
• The User Interface needs to be extended to show the newly introduced field

In this tutorial we address the need of a customer in showing additional information in the Data Monitoring User Interface.

That cannot be done through configuration, since the configuration possibilities do not allow to add a new field.

Therefore we have to extend:

1. the "Plants" data model with an additional property called "Z_ext_p_ext_desc" ,
2. the API so that the extended Plants model be retrieved and posted
3. the UI to show the new property in the Data Monitoring User interface both in "Staging" and in "Active"

Before to dive into the details on how to do that, we need to understand the anatomy of the application, and how to develop software extensions , this is covered in the next pages.

As described in the CAP documentation, to develop or extend a CAP application one can either use SAP Business Application Studio, or any preferred IDE or command line.

Please see Tools, Programming Models, Programming Languages, and APIs | SAP Help Portal for comprehensive introduction on the various choices available to developers.

SAP Business Application Studio is aa modern cloud-based development environment, tailored for efficient development of business applications such as SAP Fiori, SAP S/4 HANA extensions, Workflow, Mobile and more. Extensive documentation and professionally made tutorials are available (for example: Develop Full-Stack Applications Using SAP Business Application Studio | SAP Learning) to facilitate the fast adoption of this tool. The main advantages of using SAP Business Application Studio is that no local installation is required, and the licensing costs (SAP Business Application Studio | CPQ Configurable Category) are very low.

The main advantage of using a local installation is that, as the name says, one can use the developer preferred tools for editing, and does not have to learn the (nevertheless intuitive) editing tool embedded in the SAP Business Application Studio. The major disadvantage of the local installation are the higher complexity in setting up the local working environment , and as well the need of extra effort for sharing the work performed with other developers (for example, through a company git repository or private github ) and also accessing the code from other devices.

A nice blog (Setting up my Mac for SAP Development | SAP Blogs) is giving a developer perspective on this topic, with a comprehensive list of things to do for setting up a local setup on mac, and its conclusion being "As mentioned before, depending on the type of SAP development you do, your setup may vary. It took me far longer than what I was expecting to setup my new laptop, which made me realize how easy and fast it is to spin up a cloud environment, like the SAP Business Application Studio, and once it is running, it will be ready with all the tools that I need to solve problems with code."

The Extensibility capability provided through CAP is continuously improved.

At the time of this writing there are two major versions: mtx and mtxs.

Batch Release Hub for Life Scienes Release 2 is relying on "mtx" described at Extending and Customizing SaaS Solutions (Old) | CAPire (cloud.sap).

Starting with Release 3 of BRH the Extension will be performed using "mtxs" as described in Extending SaaS Applications | CAPire (cloud.sap).

A migration guide for moving from mtx to mtxs (not specific for SAP BRH) is also available (Migration from Old MTX | CAPire (cloud.sap)).

To extend data model, API and UI we need to rely on the API endpoint of theintegration service.

For these reasons, after having setup the development environment (regardless if using the recommended SAP Business Application Studio or the commandline) you will need to have access information to your specific tenant.

It is good practice to first develop extensions in a non-productive instance, and then to apply them to the production instances.

Therefore, from the keys of the integration service, you need to have the following information:

the endpoints.inbound_api - for example: https://iron-prod-prod-iron-inbound.cfapps.BTPDataCenter.hana.ondemand.com

the uaa.url - for example https://mysubdomain.authentication. BTPDataCenter.hana.ondemand.com

the uaa.identityzone - for example mysubdomain

#derive the following information

iron-provider-subdomain: the string before "iron-inbound" from the endpoints.inbound_api - in this example iron-prod-prod

landscape: this is the fourth string counting from right, from the uaa.url - in this example BTPDataCenter

subdomain : this is the uaa.identityzone - in this example mysubdomain

Hereafter the above information as table:

Additionally you also need to have your account properly setup so that it can generate one time passcode.

paste the uaa.url/passcode in the browser and then through sso get the passcode (one use only)

for example https://mysubdomain.authentication. BTPDataCenter.hana.ondemand.com/passcode

Hereafter is shown the command to be issued, using as example the configuration we described previously.

"npx cds extend -s mysubdomain https://iron-prod-prod-iron-mtx.cfapps.BTPDatacenter.hana.ondemand.com"

That command will automatically download not only the Plants schema but also all other CDS, and therefore also those required for extending the API and extending the User Interface.

Please always remember that with CAP the customer can *extend* existing objects but cannot create *new*. This is an important and essential concept that should guide the developers of extensions on what is possible to achieve.

As a result of cds extend, an extension project is created in the specified folder. As an example, the following file/folder structure is generated on the local disk:

The node_modules folder should be hidden when using an IDE, because it contains artifacts (the base CDS model of BRH) that can't be changed.

This project structure follows the same conventions as introduced for developing entire CDS applications.

Model extension files, which are relevant for a database deployment, must be placed in the db/ folder.

Service extension files must be placed in the srv/ folder.

The base model is treated like a reuse model. You can refer to it in extension files simply by using ... from '_base/...'

A visualization of the Plant data model can be seen by clicking on the "Schema View" from the API (https://api.sap.com/api/PlantsService/overview) , where also some description about each of the elements of the model is provided as well as with the data type and the allowed values.

To extend the Plants data model with the additional field one has to use the following code,and place it into the "db" folder with a file named extension.cds

12345
using {iron.common.Description} from '_base/db/common/datatypes';
using {iron.core.PlantsCore} from '_base/db';
extend aspect iron.core.PlantsCore {
Z_ext_p_ext_desc : Description;
}

Line by line Code explanation

With the first line we identify the data type to be used for the field (an iron.common.Description),

The second line imports the objects (PlantsCore) that we want to extend

Finally the last three line extend the PlantsCore object adding the specific Z_ext_p_ext_desc field (using the Z_ nomenclature inherited from the good practice of SAP S/4HANA) and specifying it that it is of type Desription.

The obvious difficulties lies in selecting

• The data type of the new field
• The object to be extended

The next step is to extend the API and the User Interface , and tie in the Data model we modified above.

This is achieved with the the following code, placed into "srv" annotations.cds

123456
using from '_base/app';
annotate PlantsService.PlantsStage with @UI.FieldGroup #DataFields: {Data: [..., {
$Type: 'UI.DataField',
Value: Z_ext_p_ext_desc,
Label: 'BRH Extended Plant Description',
}, ]};

12345
annotate PlantsService.PlantsActive with @UI.FieldGroup #DataFields: {Data: [..., {
$Type: 'UI.DataField',
Value: Z_ext_p_ext_desc,
Label: 'BRH Extended Plant Description',
}, ]};

Few helps for the developer:

1. We ANNOTATE the API and the UI, while we have EXTENDED the data model
2. PlantsService is the service that handles the API for the Plants object. This can be deduced by inspecting the URL of the help documentation for Plants API.
3. PlantsStage and PlantActive are the logical names of the endpoints (as you can see in the API, you can POST only to the Staging area, and then active to the Active, but not directly in the Active).
4. DSO is an important prefix:

   Looking into the downloaded node_modules/_base/db/dso, developers can easily understand that PlantsActive and PlantsStage inherit the PlantsCore data model.

5. Extended Fields have the same name on the UI as on the DSO.

The challenge is to extend the annotations for worklist at the right places. but a developer should be able to find anything in namespace "WorklistItemsService.<entityName>" for WorklistUI, especially WorklistItemsService.WorklistItems (as it is the main entity) for DSO UIs its Artworks_OrdersService.Artworks_OrdersActive and so on.

At this point all what you need is to try out the code. This is done in the similar way as for getting the model, however with only slightly modified syntax: instead of "extend" use "activate, and additionally prepend the URL with a "-to".

12
npx cds activate -s mysubdomain -to https://iron-prod-prod-iron-mtx.cfapps.BTPDatacenter.hana.ondemand.com"
Passcode: *********************************

Activating extension...

Now is matter of testing things out.

A very simple way for testing if the API has been extended and everything went well is to simply perform a "GET" to the "PlantsActive" ( or the "PlantsStage") .

As shown above visualizing with the Postman User Interface, after having collected an authentication token and then using that in the GET call, you can see the presence of the Z_ext_p_ext_desc field.

That field is not present in the corresponding API documentation (SAP Business Accelerator Hub) and therefore it is a good indication that comes from the extension we created. It is "null" since we have not POSTed any data to it, however that should be evident and known to the developers therefore we skip it from this tutorial.

As you can see above, the Data Monitoring User Interface for the "Plants Active" reports the new field as "BRH Extended Plant Description" exactly as in the annotation

You might want to remove the extension, if no longer needed. This could be simply at UI level or also in the database.

First of all a word of caution since if the additional data that you have used in your extension needs to be used for GXP purposes, then you might incur in a strong deviation by removing it after having deployed it. Therefore please first ensure with your QA department that it is okay to remove that.

Under the hood, the process of deactivating extensions makes use of the old MTX apis. https://cap.cloud.sap/docs/guides/multitenancy/old-mtx-apis

Before removing extensions, you have to uncomment the code in the files that you have been using, also you have to execute the command from exactly the same location where the files are located, since it makes use of the precise file names ( as documented above).

12
npx cds activate --undeploy -s mysubdomain -to https://iron-prod-prod-iron-mtx.cfapps.BTPDatacenter.hana.ondemand.com
Passcode: *********************************

After executing that command, the extensions should be deleted, if not, then contact support.