In the first part of this series, we looked at a detailed how-to guide for customization using standard ByDesign / Adobe LiveCycle processes. In this post, we’ll look at some potential possibilities for customizing SAP Business ByDesign through the Source Development Kit (SDK) – known as the Cloud Application Studio as of Feature Pack 1308.
This post is not a how-to guide for the entire SDK – that would take thousands of pages! However, it will help provide insight into the process behind customization, and what’s involved from a development standpoint. I’ll even show some example code, so you can get an idea of what development looks like in the Cloud Application Studio.
Note that the code shown in this blog is just example code. I strongly recommend that you do not use it directly – it is a good starting point to understand what’s possible and it provides direction on how you can do it, but a production deployment would have more advanced code, with better validations, more efficiency, clearer commenting, etc.
As a developer, the first thing I need is access to your Test system, so I’ll need a development user. This is set up through the standard “Create Service Agent” and “Request User” processes. Once I have that URL of your Test system, as well as the username and password, I can connect and start development! It is really that easy.
Once I’ve logged in, I see the list of your custom “Solutions”. Each customization is grouped into a “Solution” to ensure that enhancements and customizations are kept both separate and manageable – so if we’re doing a wide variety of customizations, the Solution components will be grouped together automatically, and can be tested and deployed as they’re ready. This makes the management of solutions easy and helps ensure system integrity. Each solution also has a status, to indicate where it is in the Solution Lifecycle, such as “In Development”, “Assembled”, “In Deployment”, “Deployed”, etc.
I then choose to open a Solution – it will synchronize the current data to my machine in order to ensure that I’m working with the most recent data, especially in cases with multiple developers. This means I can work from anywhere – I don’t need access to a specific computer, or have to connect to a specific environment. The ByDesign tenant request process easily allows us to keep our development test systems and Production systems in sync.
Once I’ve opened or created a Solution, I can begin to add “Items”. These Items are the building blocks of a Solution – they can be custom screens, custom code, extensions to standard functionality, etc.
The picture below shows an example of just some of the Items that can be created. While there are many that are mainly relevant to developers (such as the Embedded Component) picture, I’ll explain the use of the ones that customers would most likely be interested in. For any potential developers reading, I’ll explain a little bit of how these Items work.
Main Items – Business Object Extensions and Business Objects
Business Object Extension
A Business Object Extension is the addition of custom fields or custom scripts to standard ByDesign Business Objects. A standard ByDesign Business Object would be something like a Sales Order, Purchase Order, Customer Invoice, Supplier Invoice, Customer, Material, Project, etc. While the custom fields are something that can be handled through front-end Adaptation Mode, the custom scripts tend to generate the most interest. This tends to be the most common Item that I use to handle customer requests for customization.
For example, let’s say that you want a warning that the Sales Order you’re entering is a potential duplicate, based on whether another Sales Order for the Customer has the same value in the External Reference field.
First, I create a Sales Order Business Object Extension. To actually find the Business Object, note that they are grouped together in “namespaces”. A very useful way of viewing standard Business Objects and the documentation associated with them is through the Repository Explorer, which can be opened through the “View” menu -> “Repository Explorer”.
Then, I need to “Create Script Files”. I’ll select the particular “Event” that I want to use to trigger my code. In this example, I want to add it to the “BeforeSave” event in order to keep things simple – my code will trigger when a Sales Order is saved. However, I could add it to the “AfterModify” event, which would trigger my code when the General Sales Order information was changed.
It’s worth noting that this custom code will be used regardless of where a Sales Order is entered. So if we use external integrations that create Sales Orders, then the same checks I add here will be applied to those Sales Orders as well. So there’s no need to worry if you’ve got a widely integrated system environment – data entered through the User Interface and data from external integrations will be subject to a consistent set of validations!
Additionally, you’ll note that you see other nodes of the Sales Order as well – such as “InvoiceTerms” and “SalesOrderOverview” pictured below. I have the same option to add code to a more detailed node – so the code to trigger only when relevant – which helps maintain good performance.
Before I add code to my BeforeSave event, I want to specify that a warning message will be displayed if a potential duplicate Sales Order is found. Within the main Business Object Extension code, I add the following:
Now, I can add the code that will look up other Sales Orders to determine if a potential duplicate exists.
So, if I have a Sales Order that already exists, with the External Reference “EXAMPLE01”:
And I create a new one and save it, I get the following warning:
A brief explanation of the code: first, I create a Query to be run against all the Sales Orders in the system. I then add the parameters to the Query so it will only return orders that would be potential duplicates (the Buyer Party Key ID in the query is the same as the Buyer Party Key ID of the current order, the Buyer ID in the query is the same as the Buyer ID of the current order). I could add other Selection Parameters if necessary (such as making sure that the order in the query isn’t cancelled, etc.)
So, that’s a fairly simple example of what can be done – some other potential options:
- Query other Business Objects (either SAP Standard Business Objects, or custom Business Objects)For example, if I wanted to maintain a Sales Order Request Date Lead Time for each Customer, I could create a Business Object Extension for the “Customer” Business Object to store this duration, then, on the Sales Order Business Object Extension, I could look up the relevant Customer Business Object to grab this data and use it on the Sales Order.
- Get or adjust data based on customer-specific logicFor example, if I want to automatically push an Opportunity End Date out when the Sales Phase changes, I can add a custom field to store the original Sales Phase, and then detect changes when the Opportunity is saved, and adjust the End Date if the Sales Phase changed.
The Business Object is likely the starting point for any major customization.
A custom Business Object can store and manage just about any data you can think of. There’s far more flexibility allowed for a custom Business Object compared to a Business Object Extension.
While we won’t go into the whole process for creating your own custom Business Objects, here’s some information about what you can do and what’s involved:
- “Nodes” lets you maintain data in a logical fashion – you can create Business Objects that mimic the real-life scenarios that they’re based on, in the same way a “Sales Order” root node contains an “Item” sub-node, which contains a pricing sub-nodes, delivery sub-nodes, etc.
- “Elements” and “Data Types” let you track all the different data you may need, and ensure that data entered meets specific standards for formatting and input validation.
Additionally, data read/write is called from the elements themselves – no need to create or maintain custom tables!
- “Associations” lets you easily reference and read/write from SAP Standard Business Objects or other custom Business Objects.
- -“Messages” lets you specify communication to users, for example, to indicate errors have occurred, or actions have been performed successfully.
- “Actions” lets you have a pre-defined, standard, structured way of reading, writing, updating, or checking data.
For example, let’s say that I wanted to be able to restrict Customers to only be allowed to purchase specific Materials. I could create a custom Business Object called “ApprovedCustomerMaterialList”.
In the above example, I have three nodes:
The first is the main Root node, which represents a Customer, and uses the association ToCustomer to link to a standard Business Object.
I have an ApprovedMaterial sub-node specified as [0,n], which indicates the Customer may have none, one, or many ApprovedMaterials. The ApprovedMaterial represents a particular Material approved for sale, and an association ToMaterial to link to the Material.
Each Material has one, none, or several ValidityRanges, which indicates when the Material is approved for sale to the Customer, allowing the ability to track multiple date ranges in which it may or may not be allowed for sale.
I have a few elements:
The “Approved” element is a BOOLEAN_VALUE, so it will only accept “true” or “false” (or equivalent) values.
“ApprovalDate” is a Date, so it will only accept valid Dates.
“ActiveIndicator” is a “code list” data type, which lets me maintain a pre-defined (and potentially adjustable) set of codes that are allowed for this Element. This uses built-in functionality to help ensure that the values being entered into a field are allowed.
“CustomerID” and “MaterialID”, to use to specify the particular Customer or Material.
I have an Action:
“Approve” which I can use to execute a custom script, like we saw in the Business Object Extension – but instead of an Event executing this Action, I can have other objects or other scripts execute it as needed.
Of course, an actual custom Business Object will likely have more elements and actions.
Once I’ve created the Business Object, I can now create the scripts that validate or update data.
The User Interface
User Interface components for this custom Business Object are built using the same tools as the standard SAP User Interface Components, so they will feel like a natural part of your SAP Business ByDesign system.
Here are the UI Component Items:
Factsheet, Guided Activity Floorplan, Object Instance Floorplan, and Quick Activity Floorplan are User Interface components used for interacting with or viewing particular instances of a Business Object.
“Instance” refers to a specific created Business Object – for example, the ApprovedCustomerMaterialList for one Customer is an instance of that Business Object, and the ApprovedCustomerMaterialList for a different Customer would be another instance of that same Business Object.
Object Value Selector is a way of creating an autocomplete-like field, similar to what you see in many standard SAP User Interface Screens – suggestions appear when you start typing, and you can click the Value Selector icon to bring up a dialog box with the full list.
Modal Dialog is a pop-up screen, usually used to select data.
Object Work List is a way of displaying multiple Business Objects. This is generally a starting point to create an instance of the Business Object, open an existing Business Object to view or edit, see a portion of data from the Business Object without having to drill-down to it, and potentially execute Actions for multiple instances of the same type of Business Object.
The Port Type Package is used by developers to specify for the system how to navigate from screen to screen. This greatly simplifies the process of maintaining User Interface consistency and navigation.
The UI Switch can be used to display or hide specific data on screens based on a user’s roles or access rights.
The Work Center View is used as the foundation for a user to interact with ByDesign. The Work Center contains the relevant Work Center Views related to a common area of business or a group Views with similar functionality.
In general, the User Interface components for custom Business Objects use the above Items.
Standard SAP User Interface Components are edited through a built-in Extensibility Explorer. This makes use of stable “anchors” defined for screens, which ensure that changes you make stay valid and consistent between different releases and upgrades.
Using Custom Business Objects and Business Object Extensions
So, after I’ve created my custom Business Object, added and tested all the code and User interface Screens, I can now use that custom Business Object elsewhere.
For example, in the Sales Order Business Object Extension, I could specify in the “Item” node for each Sales Order Line Item to query my custom ApprovedCustomerMaterialList Business Object and see if the Material entered was valid for that Customer and that Material and produce a warning if the combination was not valid.
To make the validation stricter, I could even specify code on the Validation type events.
For example, Validation: OnSave would let me prevent a Sales Order from being Saved if an invalid combination of Material and Customer existed.
Or, if that would be too strict, I could specify that the “Action” of “Release” would not be allowed if the combination of Material and Customer was invalid. For example, if I wanted to prevent the release of a Sales Order if it had an invalid item according to the Approved Customer Material, I could add this code at the “Root” (main/header) node:
The above shows that, for each Sales Order Item, the ApprovedCustomerMaterialList is queried to see if that item is valid for the Customer. If one of them is not found, it returns “false”, preventing the action from being executed.
Of course, I would want additional validations in real production-quality code, such as validations against the validity range, the active status, and the approved status, as well as messages to tell users where invalid data may have occurred.
So through the use of Business Object and Business Object Extensions, I can satisfy many different potential customer use-cases.
Other Useful Items
Data Sources are useful for two purposes.
First, you can create Data Sources for your own custom Business Objects, allowing you to make use of all the standard Analytics functionality, such as reports. Additionally, this can be very useful for joining or combining your custom Data Sources with SAP standard data sources.
Second, you can create additional Data Sources for standard SAP Business Objects. A word of caution, though: while the actual process is very easy, it takes a knowledgeable developer to make sure that the Data Source created accurately represents the actual data.
For example, let’s say I wanted a Data Source for Customer Invoice Requests, as there’s not one out-of-the-box as of FP1308. I’d add a new Item for a “Data Source”.
There’s a built-in wizard for this:
Then, I select the data fields that I want available:
Note: this is why you need to be clear as to what you’re creating – for example, as pictured above, this Data Source would return incorrect data, as I’m pulling in “TotalNetAmount” for each Item, which would lead to many potentially duplicated amounts (i.e., the total would be TotalNetAmount multipled by the number of Items on the Invoice Request)
The remainder of the wizard lets you define the names of the elements in the Data Source (in case you want to re-name them), as well as defining aggregation rules.
Web Services are a standard, easy to create way of integrating external systems with ByDesign. They allow you to exchange data over HTTP(S) through the use of XML POST requests. As mentioned in the section on Business Objects, these Web Services still use the same validations as the data entered through the User Interface, so there’s no potential to create bad or invalid data just because it’s entered from another system.
Not only can you create Web Services for your custom Business Objects, but you can also create them for standard ByDesign Business Objects.
For example, let’s say I wanted to integrate an external project tracking system into ByDesign. I’d start in the Web Service Creation Wizard:
Then similar to a Data Source, I select all the elements that I would potentially want to read or write.
The elements I selected above are the potential elements. For each operation, such as “Create”, “Read”, “Update”, I define the elements that are usable within that particular operation.
I can then define if I want a Create Operation – in case I want to be able to have my external system create Projects.
Next, do I want to be able to Read information for a particular Project? If so, I can specify that I want a “Read” operation. Note that if I want to read information for multiple Projects, I can use a “Query” operation instead, though “Query” operations generally only return a portion of the data for each particular Business Object found (in order to keep web requests to a reasonable size).
If I want to update existing Projects, I can specify an Update operation. Note: if I want to add or delete sub-nodes for an existing Project, it would be as part of an “Update” operation for the main “Project”, and not a “Create” Operation for a “Project Task” sub-node as my Web Service is for the main Project Node.
Next, I can define if I want a “Query” operation. This makes use of the standard Business Object queries. Some objects may have multiple possible queries; I can pick one here, but I can add more once I’ve gone through the initial wizard setup.
Additionally, I can create an operation to execute an Action over the web as well.
As with the Queries, I can choose one here, but add more once I’ve gone through the wizard.
Next, I specify access rights if I’m allowing Web Services to be called on behalf of a user. So, for example, if I send my ByDesign username and password along with the request, the system will check whether I have access to the work center listed below to see if I’m authorized to make the request.
Note that you don’t have to use user-based authentication – you can use system/certificate authentication instead (like requests on behalf of the external system itself).
As for the Web Services themselves, they expect data in an XML format – for example, here’s a very basic Sales Order Creation XML Request:
To know what the expected format is for the XML request, you can download the generated WSDL of the Web Services you create (or those that exist already).
For example, here’s a rough layout of the raw XML request format. Note the elements (such as <Project> or <LanguageCode>) you see below – we’ll see them in the Web Service Creation wizard as well.
Once the Web Service is created and activated, you’ll still need to set up a Communication Scenario as explained below.
Communication Scenario is used to describe and capture the method of communication between ByDesign and other systems. While the Web Services themselves actually define how data is read, written, and updated, the Communication Scenario defines how Web Services are expected to be called (in what manner and which operations are allowed to be called).
There’s a wizard for this too. In the first step, you provide a Name and Communication Type.
You have two main options for the type – a Business-to-Business is when you expect a particular Business Partner (such as Customer or Supplier) to send or receive information.
The Application Integration is for when you expect to get data that is not specific to a certain Business Partner.
In the next step, you define which operations are allowed through this Communication Scenario.
Note that you can set up a Communication Scenario for a custom Business Object’s Web Services.
Or, you can create one for one of the standard SAP Web Services, many of which are described within the “Service Explorer” found within the Application and User Management Work Center.
Note that you can restrict these down to an operation level – for example, as pictured below, I can Check (Read and Validate) Customer data, but I can’t actually write anything.
Note that there’s still one more step once you’ve created and activated the Communication Scenario. You have to create a Communication Arrangement (through the SDK or in ByDesign itself), which specifies the actual authentication credentials used.
XML File Input
XML File Inputs can be used for mass entry or migration of data. You can create them for both standard ByDesign Business Objects and custom Business Objects.
This will allow you to upload XML files (like those shown in the Web Services section) to the ByDesign WebDAV folder, and schedule runs to take this data and create it in ByDesign.
As with Web Services, you specify which elements you want to be able to update through the XML File:
You can also specify the “List (mass processing)” checkbox to allow you to upload data to multiple Business Objects at once. For example, if I wanted to migrate all my ApprovedCustomerMaterialLists at once, I can use this “List (mass processing)” option.
You’ll need to specify the ID you use to distinguish one Business Object from another:
And then in Step 4, you review and finish it. Once the XML File Input is activated, you can download the generated schema, which can then be used to generate a valid XML file.
Once your XML file is generated, you can go to the “File Input” section of Application and User Management (or mount the WebDAV folder to a network drive as described in the ByDesign Help documentation) and upload your XML file to your created Service Interface.
You will then schedule a File Input Run and ByDesign will try to make use of the XML data. As this will be subject to the standard Business Object validations, it will notify you of any errors that occurred when trying to consume the XML data.
Enhancement Implementation makes use of pre-built SAP templates for adding or adjusting functionality. These tend to apply to fairly specific scenarios related to Tax or Legal requirements.
While many customer-specific enhancements don’t use these, it’s worthwhile for developers to check these before they jump into solution design.
While there are many things covered in this blog post, remember that it provides a very brief overview of what’s possible in SAP Business ByDesign and some general steps on how to do it. With any customer-specific solutions, we try to provide the same quality that we expect from SAP – so while the steps may be simple, there are rigorous tests and validations conducted before deploying any solution to production.
In general, a Business Object Extension can be deployed fairly quickly. Custom Business Objects take longer, as functional validations can vary widely based on customer requirements (for example, not only making sure that fields have data in the right format, but making sure the data within the fields actually make sense). Additionally, custom Business Objects need User Interfaces created as well. Integrating custom Business Objects and Business Object Extensions together generally doesn’t take too much longer than integrating each of them separately, as a custom Business Object with extensive validation can help reduce the validations required on the Business Object Extension.
Typically, the main portion of any customization lies in defining customer specific functional requirements– on the technical side, SAP Business ByDesign has many features to help keep development simple and efficient.
If you have questions, are interested in what customizations would be possible, or are interested in a customization, don’t hesitate to reach out to me.
Dan Edelman, SAP Business ByDesign Specialist
Posted by: Jakob Bechgaard