The purpose of this knowledge base article is to apprise the reader of the topics listed below.
How to download and install the new SAP Integration tool pack
All versions of the SAP Integration tool pack can be found in the partner area of our website via Community -> Partner Area.
Once the downloaded zip file has been extracted, the installation folder is present alongside the release notes of the version that’s been downloaded. The ‘Package’ folder contains the installers for each component of the tool pack.
SBOIntegrationAgent.msi
This is the first installer that should be run and this must be done on the server that hosts the DI API (commonly the server hosting SAP Business One itself). Once the install is complete, a Windows service named ‘SAP Business One Integration Agent’ should appear in the ‘Running’ state.
SBOEventAgent.msi
This installer will deploy the TaskCentre SAP Integration Event Agent (used for triggering TaskCentre tasks from SAP Business One events). It must be installed directly on the SQL server that hosts the SAP company databases. Once the installer is complete, the TaskCentre Configurator will open; this is where event agent instances can be optionally configured for each of your SAP companies.
– SAP Business One Communication Agent (yoursqlinstancename\yoursapdbname)
– SAP Business One Event Agent (yoursqlinstancename\yoursapdbname)
SBOIntegrationToolpack.msi
This installer will deploy the TaskCentre SAP Integration tools to the TaskCentre Client. The TaskCentre Client must be present on the system onto which the package is being installed. Once the installation is complete, two new tools (SAP Business One Event and SAP Business One Integration) will be added to the TaskCentre Client under the ‘Specialist (Third Party)’ tool category.
Core architectural differences
TaskCentre tools for SAP Business One 
The legacy toolset requires an IIS 7 or above installation to host the TaskCentre Tools for SAP Business One web service. This is used when communicating to the SAP DI Server and is mandatory to service all calls to and from TaskCentre.
The below diagram illustrates the communication architecture of the legacy tools:
Figure 1. TaskCentre Tools for SAP Bussiness One – Architecture diagram.
TaskCentre SAP Business One Integration tool pack 
The new toolset has no requirement for IIS or the SAP DI Server. An intermediary web service is still used, but it is now under the guise of a Windows service (named SAP Business One Integration Agent) as opposed to an IIS website.
Also, the DI API is now used directly as opposed to going through the DI Server.
The below diagram illustrates the communication architecture of the new tools:
Figure 2. TaskCentre SAP Business One Integration Tool Pack – Architecture diagram.
New features and handling recordset/XML I/O in TaskCentre Tasks
Overview
The overall concept of mapping, dynamic connection assignment and consuming step input are all very much the same, but there are differences in how some of them are handled. There are also some additional features that have been added to the new tools.
Step I/O
TaskCentre tools for SAP Business One
- Input data – XML or recordset.
- Output data – XML. Optional XML to recordset conversion via separate tool (SAP Business One XML to Recordset).
TaskCentre SAP Business One Integration tool pack
- Input data – XML or recordset.
- Output data – XML. Optional XML to recordset conversion via a built-in tool (Convert XML to Recordset).
Supplementary Reference
TaskCentre tools for SAP Business One
Not available.
TaskCentre SAP Business One Integration tool pack
This is a new feature that allows users to map a ‘floating’ value alongside their input. The value isn’t physically sent within the request XML to the web service, but TaskCentre will include it in the response XML if it is mapped. This is especially useful when dealing with batched calls in combination with Memory as it allows, for example, an external ID to be passed into each call which could then be used as the key for writing back to a staging table.
Figure 3. Location of ‘SupplementaryReference’ within the tree.
Dynamic connection assignment
Both tools allow for connections to be dynamically assigned at runtime via TaskCentre variables.
Mapping
TaskCentre Tools for SAP Business One
Tabs are used to represent nested/related XML schema structures.
TaskCentre SAP Business One Integration tool pack
XML schemas are now displayed in a single screen under the Mapping tab with collapsible nodes to represent child objects.
Recordset structure handling
TaskCentre Tools for SAP Business One
Each tab within a step had the option to make separate calls based on the change of an input value. This allowed for a single, unstructured input to be shaped into the required format.
TaskCentre SAP Business One Integration tool pack
A new technology called Recordset Shaping has been developed into the new tool. This is only available when recordset input is selected (the ‘Recordset’ tab will not display if XML or no input is selected).
Figure 4. SAP Business One Integration tool – Recordset tab.
The purpose of Recordset Shaping is to generate a nested relational input from a flat input structure. For example, you can create a Business Partner with multiple contacts and addresses from a single query. This technology is similar to that of TaskCentre’s ‘Convert Recordset to XML’ tool.
Conversion process from TaskCentre Tools for SAP Business One to TaskCentre SAP Business One Integration Tool
This section is divided into two parts; converting the event tool and the connector tool. Be sure to consult the release notes supplied with your download package before attempting to configure the new tools for the first time.
TaskCentre SAP Business One Integration Event Tool
- Ensure you’ve correctly configured the TaskCentre SAP Business One Integration Event Tool via the Configurator.
- Identify the below properties of your existing event step(s):
- The object and the type of event you’re triggering from (i.e on Add/Update of Business Partners (OCRD)).
- If you’re only triggering on change of a particular set of fields, note which these are.
- If any Task Variables are capturing data, note which these are and what fields they’re extracting from.
- Create the new TaskCentre SAP Business One Integration Event tool step and configure it as per the details noted above.
TaskCentre SAP Business One Integration Connector Tool
There are some functional changes in the new connector tool that may require some data adjustments to perform the conversion.
One of the primary changes is the introduction of the ‘LineSeqNum’ field that is used when updating child records of certain SAP objects. The below example illustrates the process of updating addresses for a Business Partner in SAP using the old connector and the new.
Updating Business Partner addresses using TaskCentre Tools for SAP Business One
The below screenshot shows a simple address update using the legacy tools. The two main things to consider are:
- The usage of ‘Change Of Value’ to loop through and correctly identify and update address entries from a potentially amorphous recordset.
- ‘Address’ is used as the key for identifying and updating the relevant SAP address record.
Figure 5. TaskCentre Tools for SAP Business One – Mapping tab.
Updating Business Partner addresses using TaskCentre SAP Business One Integration Tool
The below screenshots show how to achieve a simple address update using the new tools from the exact same database query input. Again, there are two main things to consider.
- Recordset Shaping has been used to create a parent/child relationship from the database query input.
Figure 6. TaskCentre SAP Business One Integration Tool Pack – Recordset tab. - ‘LineSeqNum’ has been mapped to only update the relevant Business Partner address entry.
Figure 7. TaskCentre SAP Business One Integration Tool Pack – Mapping tab.
What is LineSeqNum, how is it calculated and what is its purpose?
If you’re familiar with SAP Business One’s underlying table structure, you may have seen the ‘LineNum’ column within some child tables for various objects (CRD1, for example). This is an auto-incrementing value that indicates the occurrence of a record.
For example, if you create two addresses for a new Business Partner, they’ll have LineNum values of 0 and 1. If you tried to perform an update through the API and supplied 0 and 1 as the LineNum keys, the call would successfully update the appropriate addresses.
However, if you then for example delete the second address (LineNum = 1) and then create another, the newly created address will have a LineNum of 2. You’re then left with LineNum values of 0 and 2, which isn’t intuitive when it comes to dynamically attempting to calculate the correct LineNum value without first querying SAP.
To remedy this issue, LineSeqNum has been incorporated into the new tool. The purpose of this is to correctly find and update the relevant child record without needing to find the true value from SAP. It works by calculating the true occurrence of each record as opposed to the reported LineNum.
For example, the below screenshots illustrate a Business Partner with 2 addresses. But when querying CRD1, the LineNum values are 2 and 3. This is due to the 2 previous addresses having been deleted.
Figure 8. Example Business Partner from SAP Business One.
Figure 9. Example SQL query returning the ‘LineNum’ values.
The LineSeqNum values for these addresses would be 0 and 1 respectively, as there are a total of two records. To calculate this, we need to perform the following query on CRD1:
SELECT Address, CAST(ROW_NUMBER() OVER(ORDER BY LineNum) -1 AS int) AS LineSeqNumAddr, LineNum FROM CRD1 WHERE CardCode = 'C60000'
This returns:
Figure 10. Results from the modified SQL query.
These values can then be used in a subsequent SAP Business One Integration Connector step to update the relevant address.
LineSeqNum values can also be obtained by performing a GET operation (Search/GetByKey) using the connector tool.
Error handling and output XML
There are some changes and additional features when it comes to working with output from the new connector tool.
Error handling
Full support has been added for the FailCount property at step level within the new tool. This is designed to work even when a step is set to continue on error, meaning that the FailCount will be accurately set to 1 or 0 as opposed to always being 0 when set to continue on error.
Figure 11. FailCount property located within the task browser.
This provides enhanced flexibility when it comes to error handling with successive logic, such as the use of a Decision step – example below:
Figure 12. Adding a Decision step to a task to enable error handling.
Figure 13. Example configuration of a Decision step implementing error handling.
Output XML
TaskCentre Tools for SAP Business One
The old tools would return a ‘RetKey’ value from successful transactions. This value would typically be the primary key of the underlying SAP record.
An output variable would also need to be created and assigned to a step in order to receive and process the response XML. This is no longer necessary in the new tools.
TaskCentre SAP Business One Integration tool pack
The new tools return the full XML response provided by the DI API. This allows for more complex decision making and data extraction within the task.
To capture/parse specific content of the output XML for both errors and successful calls, the following properties are available in the new tools:
Figure 14. Success and error XML properties located within the task browser.
These can be directly consumed by successive steps in a task, most commonly Decision/Parse Text steps. The XmlString property of ErrorData is often combined with alerting and exception handling logic within tasks.
FAQ
Q. Can both the old and new sets of tools be installed simultaneously?
A. Yes.
Q. Can a single task contain steps from both the old and new connector/event tools?
A. Yes.
Q. Do I need to install and license the DI Server in order to use the new tools?
A. No, the new tools do not interact with the DI Server.
Q. How do I loop on child objects within the mapping screen?
A. This is either achieved via predefined XML input or by using the Recordset Shaping feature of the new connector tool. See Section 3 above.
Q. Is there a troubleshooting guide for the new tools?
A. Yes, it can be found here.
Q. Which versions of SAP Business One do the new tools work with?
A. Version 8.82 (any PL) upwards.
