In this blog I describe how to create and run a local version of the promotion pricing service (PPS) based on the artifacts delivered with SAP Customer Activity Repository application bundle (CARAB). This delivery offers the central PPS as part of the omnichannel promotion pricing (OPP) module.
In a previous blog (https://blogs.sap.com/2018/10/11/sap-opp-black-box-concept-implementation-guidance-for-non-sap-environments/), my colleague Ingo Woesner described how to assemble a custom Java Web Application containing both the price calculation and the upload of regular prices and promotions. This stand-alone application could then be used for various purposes, for example, easy prototyping, developing, or debugging custom extensions to the SAP standard logic.
To bring all needed artifacts together for this approach, you had to have both the central PPS to access the database of the corresponding SAP Customer Activity Repository (SAP CAR) installation, as well as the SAP Commerce, integration package for SAP for Retail containing the SAP Commerce extension “sapppspricing”. This extension offers an embedded version of the price calculation and the upload of IDocs for regular prices and promotions.
With SAP Customer Activity Repository application bundle 5.0 SPS06 the situation has changed. The central PPS of this shipment comes with all artifacts that are needed to create a stand-alone version of a local PPS box, formerly known as “Black Box”.
Besides the necessary artifacts, this delivery also allows the simple creation of a running application. Therefore, the previous blog by Ingo can be replaced by the following steps described in this blog.
The local PPS box is not an official SAP product! Any productive usage is outside of any SAP support contract. Therefore, there is no responsibility on SAP side for any issue you may be facing during the usage of the local PPS box. If you encounter an issue and rank it as a bug, make sure you can reproduce it with an official SAP standard product, like for example:
If this is not possible, you cannot rely on any SAP support.
For more information about things to be considered when using the local PPS box, see section “Gaps”.
Note that the following procedure is based on a specific environment setup. For this blog, I am using the following programs:
For the extraction of data, I am using WinRar which is associated with the file extensions “.zip”, “.mtar” and “.war”. Obviously, many other tools can be used to open the archives as well, including Windows built-in functionality.
If you are using a different setup, the prerequisites and the procedure may differ from the description below.
To create your local PPS box, you need to fulfill the following:
The italic paragraphs in this procedure contain additional information, which is not necessarily needed to create your local PPS box. If you just want to get it running, you can skip those paragraphs.
Visit https://me.sap.com/softwarecenter/search/xsac_opp_pps_2 and download the Software Component archive of your choice.
Downloading the Software Component Archive
Keep in mind, only support packages >= SP07 (which are shipped with SAP CARAB 5.0 SP6) contain all needed artifacts for the local PPS box. The patch level may be different from the screenshot. If you are not sure which version of the central PPS belongs to which CARAB delivery, see the following overview about OPP-related versions: https://help.sap.com/docs/CARAB/e95c8443f589486bbfec99331049704a/ea5a162ff18d49b2bc41fc0cd447407a.html?q=opp%20versions – note that there may be newer versions of the page available in the meantime, make sure you select the newest CARAB version to see the most complete list:
Selecting the right CARAB version to lookup the name of the software component archive
On your computer, create a folder of your choice. This will later contain temporary data, as well as the database file etc. For this blog I am using the folder C:\my_local_pps_box
Creating the folder for the Local PPS Box
This folder will later be accessed from the web application running in a Docker container. Make sure this folder is not protected.
Open the downloaded software component archive (XSACOPPPPSxx_xx-xx.ZIP) and in that, open the contained MTA archive (sap-xsac-opp-pps-x.xx.mtar). Extract the following folders to C:\my_local_pps_box:
Content of the software component archive
Local folders
Additionally, open the web application archive (“WAR”) file ppservice-webapp-central.war and navigate to folder WEB-INF\lib. Extract the files ppengine* and pricing* to folder “additional” in C:\my_local_pps_box
Relevant JARs of Java web application
All JARs extracted
With this, you have extracted all necessary information from the delivery to your local disk. The JAR files in folder “additional” are required for the Maven build of the local PPS box. The folder “sampleproject” contains a Maven module from which the local PPS box will be built. The folder “localppsresources” contains configuration files. When running the local PPS box, also the application log and the DB file will be stored there. The file ppe-local.properties in this folder contains a reasonable default configuration proposed by SAP if you want to start from a greenfield. This slightly deviates from the default configuration of the standard delivery which has the priority to avoid any incompatibilities during upgrade.
Open a command rompt, cd to folder “additional” and execute the command
install_jars.bat.
Installing the needed JARs in local repository
This will install the program code, Javadoc and sources to your local maven repository which is sufficient for the purpose of this blog. Most likely, you want to also upload these files to the artifact repository of your company (Nexus / Artifactory or similar). This step is not described here.
Note, if you have access to the SAP internal artifact repository, you should skip this step.
If you use maven > 3.8, add the parameter -DgeneratePom=true to each statement in install_jars.bat.
If you run on unix or mac, you can remove all the “call” commands and execute the file as follows: source install_jars.bat.
cd to folder sampleproject and execute the command mvn install
Building the Local PPS Box
With this, you have created the web application archive and installed it in your local maven repository. The sample project contains the bare minimum needed to create a working web application:
If you want to use the local PPS box more than once, you probably want to adjust the pom.xml to your needs, including adjustment of. groupId, artifactId, version etc.
Start Docker in your Linux environment, and execute the following command (note, we are accessing a file in the Windows file system from Linux here):
docker build /mnt/c/my_local_pps_box/localppsresources -t tomcat-for-localpps
Building the Docker image
To execute the Java web application, you need a stable runtime environment. The command above creates a Docker image with a well-defined Java and Tomcat installation. In addition, an additional folder within the Docker container (“/extern”) is mounted to the Java classpath and much more. See the comments in the Dockerfile (located in folder C:\my_local_pps_box\localppsresources) for more information.
Start a Docker container for the image you just created. This should only take a few seconds.
docker run -it –name myLocalPPS -p 8888:8080 -v /mnt/c/my_local_pps_box/localppsresources:/extern tomcat-for-localpps
Starting the Docker container
With this you have started the Tomcat running within the Docker container. The http port 8080 exposed by default is forwarded to port 8888 on the host machine (i.e. your Windows machine running WSL2). The folder /extern within the Docker image – which is added to the Tomcat classpath – is mapped to the folder /mnt/c/my_local_pps_box/localppsresources (which is identical to C:\my_local_pps_box\localppsresources)
Hint: Have a look at the Dockerfile. There, you can also see how to execute the container in debug mode!
Deploy the Java web application into Tomcat. In your browser, open the following URL: http://localhost:8888/manager. When prompted for user and password, enter “opp” and “opp”.
Login to Tomcat Manager app
In section „Deploy“ > „WAR file to deploy”, press “Choose File” and select the WAR you created in the sampleproject folder:
Choosing the web application for deployment
Then, press “Deploy”. After some waiting, you should see the following:
After successful deployment
Congratulations, you have the local PPS box running! This should also become visible in folder localppsresources, where you can see the application log and the DB file:
DB file and more
Let’s see if the local PPS box indeed works. To do so, we upload an IDoc with a promotion and see if it is considered during the price calculation. Afterwards, we will also have a look at the database.
First, upload a single promotion. This is done via a POST request against http://localhost:8888/localpps-0.0.1-SNAPSHOT/idocinbound
As XML payload, you can use this one:
<?xml version="1.0" ncoding="utf-8"?>
<_-ROP_-PROMOTION05>
<IDOC BEGIN="1">
<EDI_DC40 SEGMENT="1">
<DOCNUM>0000000000084229</DOCNUM>
<IDOCTYP>/ROP/PROMOTION05</IDOCTYP>
<MESTYP>/ROP/PROMOTION</MESTYP>
</EDI_DC40>
<_-ROP_-E1_PROMOTION SEGMENT="1">
<CHANGED_ON>20210208141329</CHANGED_ON>
<EFFECTIVE_DATE>20230601000000</EFFECTIVE_DATE>
<EXPIRY_DATE>20230630235959</EXPIRY_DATE>
<LOGSYS>CHANGEME</LOGSYS>
<MIN_PPS_RELEASE>11000000</MIN_PPS_RELEASE>
<ORIGIN>01</ORIGIN>
<PROMOTION_ID>757575</PROMOTION_ID>
<STATUS_TCD>AC</STATUS_TCD>
<_-ROP_-E1_PROMOTION_BU SEGMENT="1">
<BU_ID>SO|DC</BU_ID>
<BU_TYPE>2001</BU_TYPE>
</_-ROP_-E1_PROMOTION_BU>
<_-ROP_-E1_PROMOTION_RULE SEGMENT="1">
<ELIGIBILITY_ID>757575</ELIGIBILITY_ID>
<PRICE_RULE_ID>757575</PRICE_RULE_ID>
<PROMO_RULE_ID>757575</PROMO_RULE_ID>
<SALE_RETURN_TCD>00</SALE_RETURN_TCD>
<SEQUENCE>757575</SEQUENCE>
<_-ROP_-E1_ELIGIBILITY SEGMENT="1">
<EFFECTIVE_DATE>20230601000000</EFFECTIVE_DATE>
<EXPIRY_DATE>20230630235959</EXPIRY_DATE>
<ELIGIBILITY_ID>757575</ELIGIBILITY_ID>
<THRESHOLD_TCD>QUT</THRESHOLD_TCD>
<LIMIT_QTY>10.000</LIMIT_QTY>
<PARENT_ELIGIB_ID>757575</PARENT_ELIGIB_ID>
<PROMO_RULE_ID>757575</PROMO_RULE_ID>
<ROOT_ELIGIB_ID>757575</ROOT_ELIGIB_ID>
<STATUS_TCD>AC</STATUS_TCD>
<THRESHOLD_QTY>1.000</THRESHOLD_QTY>
<TYPE_CODE>ITEM</TYPE_CODE>
<ITEM_ID>MY_ITEM</ITEM_ID>
<UOM_ISO_CODE>EA</UOM_ISO_CODE>
</_-ROP_-E1_ELIGIBILITY>
<_-ROP_-E1_PRICE_RULE SEGMENT="1">
<CALCULATION_BASE>00</CALCULATION_BASE>
<CALC_BASE_SEQUENCE>1-</CALC_BASE_SEQUENCE>
<CONSIDER_PREVIOUS_RULES>X</CONSIDER_PREVIOUS_RULES>
<CURRENCY_ISO_CODE>EUR</CURRENCY_ISO_CODE>
<DISC_METHOD_TCD>00</DISC_METHOD_TCD>
<ITEM_METHOD>00</ITEM_METHOD>
<PRICE_MODIF_PERC>13.000</PRICE_MODIF_PERC>
<PRICE_RULE_ID>757575</PRICE_RULE_ID>
<ROUNDING_METHOD>00</ROUNDING_METHOD>
<ROUND_DECIMALS>2</ROUND_DECIMALS>
<ROUND_DESTINATION>1</ROUND_DESTINATION>
<RULE_CTRL_CODE>PO</RULE_CTRL_CODE>
<STATUS_TCD>AC</STATUS_TCD>
<TYPE_CODE>RB</TYPE_CODE>
<PRICE_MODIF_CODE>RP</PRICE_MODIF_CODE>
</_-ROP_-E1_PRICE_RULE>
</_-ROP_-E1_PROMOTION_RULE>
</_-ROP_-E1_PROMOTION>
</IDOC>
</_-ROP_-PROMOTION05>
You should see a success message:
Successful upload
Will it be considered for a price calculation? Let’s see – send a POST request against http://localhost:8888/localpps-0.0.1-SNAPSHOT/restapi with the following payload:
<PriceCalculate xmlns="http://www.sap.com/IXRetail/namespace/" InternalMajorVersion="10" InternalMinorVersion="0">
<ARTSHeader ActionCode="Calculate" MessageType="Request">
<MessageID>1</MessageID>
<DateTime>2240-02-20T00:00:00.0</DateTime>
<BusinessUnit TypeCode="DistributionChain">SO|DC</BusinessUnit>
<MasterDataSourceSystemID>CHANGEME</MasterDataSourceSystemID>
</ARTSHeader>
<PriceCalculateBody TransactionType="SaleTransaction">
<TransactionID>1</TransactionID>
<DateTime>2023-06-07T15:10:00.0</DateTime>
<ShoppingBasket>
<LineItem>
<SequenceNumber>0</SequenceNumber>
<Sale ItemType="Stock" FixedPriceFlag="true">
<RegularSalesUnitPrice Currency="EUR">100.00</RegularSalesUnitPrice>
<ItemID>MY_ITEM</ItemID>
<Quantity Units="1" UnitOfMeasureCode="EA">1</Quantity>
</Sale>
</LineItem>
</ShoppingBasket>
</PriceCalculateBody>
</PriceCalculate>
Voilà, a discount is granted:
Price calculation response
How about the database content? To examine it, stop the Docker container first (simultaneous access to the DB file from the UI and the web application is not supported) and start the UI of the H2 database via command h2.bat:
Starting the DB console
In the browser window, enter the following:
H2 login
And here it is:
Promotion header on database
Besides not being covered by any SAP support agreement, the local PPS box is also lacking essential aspects, which you would expect from a production-ready-product. This includes but is not limited to the following: