TB1300 - SAP Business One SDK

Data Interface API – Business Objects

July, 2019

PUBLIC
Business Objects: Topic Objectives

After completing this topic, you will be able to:

 Describe what business objects are
 List the most important methods of business objects
 Explain how to read or write a business object from or to an XML file
 Design a transaction involving more than one business object
 Explain how to get notified on changes in business objects

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 2

Business Objects: Overview

Business objects:
 Represent the functionality of SAP Business One application.
 Follow appropriate business logic and will not compromise data integrity.
 Any data access using business objects is platform and release-independent.

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 3

Business Objects: Architecture

Object:
<Business Object>

Methods:
Add a new Object
+Add
+GetByKey Get the object by key
+Remove Remove the object (if possible)
+SaveXML Save the object as XML file
+Update Update the object
Properties:
+ CardCode Sets or returns the customer or vendor name
Child Objects:
+ Browser Allows navigation/browsing over records
+ UserFields A collection of fields objects, which are user defined fields
+ Document_Lines Represents the line entries of a document
© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 4
Business Objects: Architecture – Child Objects

Object:
<Child Object>

Methods:
+Add Add a new record
+SetCurrentLine Set the current line
+Delete Delete a record (available for most part of objects)

Properties:
…

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 5

Business Objects: Business Partners

 Represents the business partners record in SAP

Business One

 Use this object to add, find or update business

partners

 You can use it also to handle additional user-

defined fields

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 6

Business Objects: Example – Add Business Partner

'First connect to database (see Log on sample)

…
'Some variables:
Dim oBP As SAPbobsCOM.BusinessPartners
Dim lRetCode, lErrCode As Integer
Dim sErrMsg As String

‘Prepare empty oBP Object:

oBP = oCompany.GetBusinessObject(SAPbobsCOM.BoObjectTypes.oBusinessPartners)

oBP.CardCode = "C08154711"
oBP.CardName = "James Tiberius Kirk"
oBP.CardType = SAPbobsCOM.BoCardTypes.cCustomer
'…

‘Add the new BP to the database

lRetCode = oBP.Add()

If lRetCode <> 0 Then

oCompany.GetLastError(lErrCode, sErrMsg)
MessageBox.Show("Error: " sErrMsg + “; Code: “ + lErrCode)
End If

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 7

Business Objects: Example – Child Object

'First connect to database (see Log on sample)

'…
‘Variables:
Dim oBP As SAPbobsCOM.BusinessPartners = _
oCompany.GetBusinessObject(SAPbobsCOM.BoObjectTypes.oBusinessPartners)
Dim lRetCode As Integer

If oBP.GetByKey(“C08154711”) = True then ‘here we use an existing record…

‘First line is always prepared (in any business object that has lines…)
oBP.ContactEmployees.Name = "John Cash“

‘Prepare / declare 2nd line… (automatically positions on new line)

oBP.ContactEmployees.Add() ‘No in DB here – therefore will work always…
oBP.ContactEmployees.Name = “John Walker“

‘Please note: In case you need to position on particular line…

‘oBP.ContactEmployees.SetCurrentLine(<0-based line no.>)

‘Write changes to DB now…!

lRetCode = oBP.Update()
If lRetCode <> 0 Then
…
End If
Else
MessageBox.Show(„Business Partner C08154711 not found!“)
End if

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 8

Business Objects: Items

 Represents Master Inventory Items record

 Enables you to add, update, or find item records

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 9

Business Objects: Documents

 The Documents object represents the

header of SAP Business One Sales and
Purchasing documents.

 It contains the master header data for the

document such as CardCode, Address,
Document Date, Document Total etc.

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 10

Documents: Example – Create an Order

Dim oOrderDoc as SAPbobsCOM.Documents ' Adding the new order document

oOrderDoc = oCompany.GetBusinessObject _ Dim RetVal As Long
(SAPbobsCOM.BoObjectTypes.oOrders)

' set the business partner code

' Add Order to the database
oOrderDoc.CardCode = "C20000" RetVal = oOrderDoc.Add()
' set the documents due date - mandatory
oOrderDoc.DocDueDate = Date ' Check if Add method succeeded
If RetVal <> 0 Then
' First line (no need to add line) oCompany.GetLastError( lErrCode, ErrMsg)
oOrderDoc.Lines.ItemCode = "A00001"
MessageBox.Show(lErrCode & " " & sErrMsg)
oOrderDoc.Lines.Quantity = 1
End If

' Second line

' first prepare empty line for the second line
oOrderDoc.Lines.Add()

oOrderDoc.Lines.ItemCode = "A00002"
oOrderDoc.Lines.Quantity = 1

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 11

Documents: Example – Create an Invoice (based on the order)

' Create Invoice ' Second line; first: prepare line

Sub CreateInvoiceDocument() oInvoiceDoc.Lines.Add()
' Get the DocNum for the new added order added on slide before…
Dim OrdCodeStr As String oInvoiceDoc.Lines.BaseType = _
oCompany.GetNewObjectCode (OrdCodeStr) SAPbobsCOM.BoObjectTypes.oOrders
' Get the required business object oInvoiceDoc.Lines.BaseEntry = CInt(OrdCodeStr)
Dim oInvoiceDoc As SAPbobsCOM.Documents oInvoiceDoc.Lines.BaseLine = 1
oInvoiceDoc = oCompany.GetBusinessObject oInvoiceDoc.Lines.TaxCode = "LA"
(SAPbobsCOM.BoObjectTypes.oInvoices)
' set the business partner code ' Add Invoice to the database
oInvoiceDoc.CardCode = "C20000" RetVal = oInvoiceDoc.Add
' set the document’s due date - mandatory
oInvoiceDoc.DocDueDate = Date ' Check if Add method succeeded
' First line (always there… ) If RetVal <> 0 Then
oInvoiceDoc.Lines.BaseType = SAPbobsCOM.BoObjectTypes.oOrders oCompany.GetLastError(lErrCode, sErrMsg)
oInvoiceDoc.Lines.BaseEntry = CInt(OrdCodeStr) MessageBox.Show(lErrCode & " " & sErrMsg)
oInvoiceDoc.Lines.BaseLine = 0 End If
oInvoiceDoc.Lines.TaxCode = "LA" End Sub

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 12

Other Business Objects: Users and Access Log

User object UserActionRecord child object

  User Access details

Represents User record
 Enables you to add, update, or find user records
 Manage the authorization and branch assignment

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 13

Working with XML: Motivation

A Technique of saving and loading data

XML Advantages:
 Enable exchanging large-scale data between SAP Business One company database and
external systems
 Standard
 Cheap
 Convenient
 Simple

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 14

Working with XML: Relevant Methods and Properties

Company object
■ oCompany.GetBusinessObjectFromXML (FilePath_OR_XMLString, Index)
■ oCompany.GetXMLelementCount (FilePath_OR_XMLString)
■ oCompany.GetXMLobjectType (FilePath_OR_XMLString, Index)
■ oCompany.GetBusinessObjectXmlSchema (ObjectType)

Business objects
■ oBusinessObject.SaveXML (FilePath_OR_XMLString)
■ oBusinessObject.Browser.ReadXML (FilePath_OR_XMLString)
Use ReadXML to update an existing object

XML export type – specifies the types for exporting data, e.g. to export read-only data
■ oCompany.XmlExportType = SAPbobsCOM.BoXMLExportTypes.xet_ExportImportMode

Working with XML as an XML string (not as an XML file)

■ oCompany.XMLAsString = True

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 15

Working with XML: Delete Line/Sub-Object by XML

Method UpdateFromXML

• Receives and processes the XML content.

• You can remove sub-object lines from the object via the XML file.

Available for
 Items object
 BusinessPartners object
 Documents object
 ProductTrees object

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 16

Working with XML: Example – SaveXML

'First connect to database…

Dim oBP As SAPbobsCOM.BusinessPartners = _

oCompany.GetBusinessObject(SAPbobsCOM.BoObjectTypes.oBusinessPartners)

oCompany.XmlExportType = SAPbobsCOM.BoXmlExportTypes.xet_ExportImportMode

If (oBP.GetByKey("C20000“) = False) Then

MessageBox.Show("Failed to find the business partner")
Else
oBP.SaveXml ("c:\temp\BP_" + oBP.CardCode + ".xml")
End If

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 17

Working with XML: Example – Get Business Partner from XML

Dim sFileName As String = "c:\temp\BPs.xml“

Dim lEcount, ii As Long

'Get the number of Business object in the file ...

lEcount = oCompany.GetXMLelementCount(sFileName)

'Loop through the objects; when finding the first BusinessPartner

'object: load it, add it to the DB.
For ii = 0 To lEcount–1
If oCompany.GetXMLobjectType(sFileName, ii) = _
SAPbobsCOM.BoObjectTypes.oBusinessPartners Then

‘”Read” the Business object data into the object…

‘Please note:
‘If the format is not OK you might run into an exception!
oBP = oCompany.GetBusinessObjectFromXML(sFileName, ii)

iRetVal = oBP.Add()
‘…handle error…
End If
Next ii

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 18

Transaction Handling: Overview

The Data Interface API supports two different types of transactions:

Single Transaction (default)

 Each data operation performed on a business object starts a transaction
 Depending on the result (success or failure), the system automatically issues a commit or a rollback

Global Transaction
 Allows perform several data operations and then a full commit or rollback based on specific criteria
 If any of the data operations fails, the global transaction will be rolled-back entirely
 Start and end of a global transaction can be managed by using the Company object:

oCompany.StartTransaction()
Boolean oCompany.InTransaction
oCompany.EndTransaction([wf_RollBack / wf_Commit])

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 19

Transaction Handling: Flow Chart of Global Transactions

Start Transaction

Run a list of
operations on the DB

NO! Did ALL Yes? …then

operations you can still
At least one operation failed succeed? choose:

Automatic Rollback already

happened, Transaction has
Rollback? Commit?
been terminated

Stop processing and handle

error!
End Transaction
Please note: “InTransaction”
property of Company object
holds info whether or global
transaction is still active.

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 20

How to Get Notified on Changes in Business Objects

Challenge
■ There are no DI API data-driven notifications (only FormData events in the UI API – see UI API presentation)
■ Adding SQL triggers at the database level is not permitted!

Solution
■ Enable the Transaction Notification in SAP Business One (Administration > System Initialization > General Setting > Service).
This can be achieved by setting the EnableTransactionNotification property on the CompanyInfo object.
■ Insert the required object to the <companyDB>.CTNS table.
■ Consume the events from SBOCOMMON.SEVT
SAP
■ After handling the events, clean up the entry from SBOCOMMON.SEVT
not e 13 2
04 84
Important remarks:
■ The Integration Framework for SAP Business One can use the SBOCOMMON.SEVT table as well.
The table is cleaned automatically by the EventSender service.

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 21

Business Objects: Exercise

You should now:

 Work with Business Objects in general
 Use the XML capabilities
 Practice Transaction handling along the exercises at the end of this unit

© 2019 SAP SE or an SAP affiliate company. All rights reserved. ǀ PUBLIC 22