Release2ERP for SAP Business One
- Morten Lindequist Køhler
- Jeppe Hatting
The Perfion Release2 ERP for SAP Business One is a standard integration between Perfion and SAP Business One, which allows Perfion items to be imported into SAP Business One using the Perfion API.
This document will describe the configuration of Perfion Release2ERP for SAP Business One.
The Release2ERP for SAP Business One is part of the Boyum B1 Usability Package. The full documentation for this can be found here: B1 Usability Package
Prerequisites
Perfion:
The following requirements must be met:
Perfion Database: Version 5.2 or above
Perfion API: Version 5.2 or above
The Perfion Web Client must be installed, so that it is accessible from the SAP Business One server.
For instructions on how to install and configure the Perfion API, please refer to support Installation guide for documentation.
For help creating Perfion API queries please refer to our example page: Perfion Query Reference .
SAP Business One:
The following requirements must be met:
Boyum IT Solutions SAP B1 Usability Package must be installed.
Release2ERP is added in B1UP version 2023.12.00.
Configuration
The Perfion Extension configuration can be found on the following path: Administration > Add-Ons > B1 Usability Package > Module configuration > Perfion Extension > Configuration
The configuration has two parts, Data Display Settings, for viewing Perfion item data within SAP B1, and Data Import Settings for importing item data from Perfion to SAP B1.
Data Display Settings
Data Display Settings contains the configuration needed for viewing Perfion items in SAP B1 on the Item Master Data form and contains the following fields which needs to be filled:
Field | Value |
Url | The main url for the Perfion FactBox site up to, but not including, the hashtag. |
Main Feature | The name or number id of the Perfion feature for the products. |
Lookup Feature | The name or number id of the feature in Perfion that is equivalent to SAP B1's Item No. on Item Master Data. |
For example:
The above screenshot would be equivalent to using the Perfion FactBox url https://localhost/#/factbox/Product/String/
Data Import Settings
Data Import Settings contains the configuration needs for import items from Perfion to SAP B1 and has the following fields:
Field | Value |
API Base Url | The main url for the Perfion API. This is used both to get the authentication token (by adding /token) and retrieving data from Perfion (by adding /perfion/getdata.asmx) |
API Username | The username for the user used to authenticate against the Perfion API. |
API Password | The password for the user used to authenticate against the Perfion API. |
Using the "Test Connection" button allows you to check that the API url and authentication information is valid.
The above screenshot would be equivalent to using the Perfion FactBox url https://localhost/Perfion/
Usage
The Perfion Extension Import Setup can be found on the following path: Administration > Add-Ons > B1 Usability Package > Module configuration > Perfion Extension > Import Setups
Import Setups allows you to define which data is imported from Perfion and the mapping of said data.
You can have multiple setups for importing things differently.
While most of the definition of what data is imported and how is contained in the two tabs "Query" and "Mapping", each setup also has a name you can define to easily recognize what the import is for and an automatically generated number.
Each setup also has a page size, which determines how many products are retrieved with each call to the Perfion API, which in turn can affect performance if set too high or too low. Default page size is 100.
You can also import and export your setups using the "Import" and "Export" located on the bottom right of the form.
Any changes or updates to the Import Setup will require you to reopen the Perfion Manual Import form (if it is open) to take effect.
The Query tab
The Query tab contains the query used for defining what data to retrieve from the Perfion API:
If you want to make sure not to import data that hasn't been changed in Perfion since the last import you can use [%LastImport] in a where clause of the query to filter out unchanged data.
Using the "Test query" button you can test that the query is valid and save the response if you want to.
The Mapping tab
The mapping tab contains both the record root node and the mapping between SAP B1 item fields and the XPaths to the values those fields should be filled with and any default value for those fields.
Field | Description |
|---|---|
Object Type | The object type of the imported data. Together with Interface it determines what business object is created in SAP B1 from the imported data. Also determines which UDFs are available in the Field Name field. |
Interface | The interface type for the imported data. Together with Object Type it determinate what business object is created in SAP B1 from the imported data. Also determines SAP B1 fields are available in the Field Name field. |
Field Name | Name of the field in SAP B1. Available choices depend on which object type and interface is chosen. When the combo box for field name is open you can see the available fields based on the chosen object type and interface. You can also see the data type and whether or not the field is user defined. |
Is Primary Key | Whether or not the chosen field is key for the business object. At least one field must be set as primary key for each object type. In order for updating objects on import to work one field must be set as primary key for each interface, with the primary key for subobjects (like lines) functioning as the key for the subobject. |
XPath to value | The XPath to the value which the field will be filled with. You can use [%enumerator] as a placeholder in the XPath for subcollections. F.ex. if making a bill of materials then "Items/Item[%enumerator]/Value" would be a way to get the item code for each row in the Items collection. |
Default value | Default value for the field if no value was found using the XPath (or a constant value that is always used if XPath is left empty). |
Skip on error | If value could not be found using XPath, there is no default value and this is not checked, then the import for the product will fail with an error message on the import result form. If this is checked it will not fail the import of the product, but instead leave the field for which this was check empty. |
Skip on empty | If checked and empty value is received from Perfion, then the field skipped. If not checked, then the field will be set to the empty value, meaning number fields will be set to zero, text fields will be set to empty and BoYesNoEnum field will be set to no. |
Enabled | Whether or not the field is enabled. Only fields that are enabled will be imported. |
Field data types
Fields in SAP B1 can have one of several different data types.
The most common ones are:
Data type | Description |
|---|---|
String | Meaning text data. For example UserText (remarks) on item master data. |
Int32 | Meaning whole numbers. For example ToleranceDays (tolerance days) on item master data. |
Double | Meaning decimal numbers. For example MinOrderQuantity (minimum order qty) on item master data. |
DateTime | Meaning date and time data. For example ValidFrom (active from) on item master data. |
BoYesNoEnum | Meaning boolean data aka true/false or yes/no. For example SalesItem (sales item) on item master data. This data type has an special layer of interpretation and will accept the following values as yes/true/checked: •Yes •tYES •True •1 And the following as no/false/unchecked: •No •tNO •False •0 This data interpretation is case insensitive. |
In addition to the above SAP B1 has a number of enum data types.
An example of this is the ItemTypeEnum used by the ItemType field on item master data:
What values are valid for SAP B1 enums depend on the specific enum as they each have their own collection of valid values. The valid values are case sensitive.
For example the ItemTypeEnum accepts itItems, itLabor, itTravel and itFixedAssets, while the ItemClassEnum accepts itcService and itcMaterial.
It is recommended to look up the enum in question on biuan.com to see which values the specific enum accepts.
Schedule Item Import
The Perfion Extension Schedule Item Import can be found on the following path: Administration > Add-Ons > B1 Usability Package > Module configuration > Perfion Extension > Schedule Import
Schedules allow you set up automated import of business objects from Perfion using selected setups.
Note: This requires the B1UP Server Component to have been installed and email settings needs to have been provided during the setup of the server component!
Field | Description |
|---|---|
Name | This is your name for the configuration for reference. This is also the name that will be shown in success and error emails from the scheduler. |
Import Setup | Here you select the setup to use for the import. |
Success email | If set you will receive an email confirming that the schedule where run correctly. |
Error email | The email that will receive an error report if the schedule encounters and error. |
Server start time (24 H/M) | When the schedule should be executed the first time. |
Recurrence pattern | There are currently five supported types: Minutely: Run the schedule every X minutes. Hourly: Run the schedule every X hours. Daily: Run the schedule once each day on the server start time. Weekly: Run the schedule on specific days of the week on the server time. Monthly: Run the schedule every X day of the month on the server time. Only ones: Run the schedule only on the start date and the server start time. Last day of month: Run the schedule on the last day of the month on the server start time (hour and minute) |
Range of recurrence | Start: Start date of the recurrence. No end date: The schedule should never end. End by: The schedule should end by the specific date. |
Manual Item Import
The Perfion Extension Manual Import can be found on the following path: Administration > Add-Ons > B1 Usability Package > Module configuration > Perfion Extension > Manual Import
Normal import
Choosing an import setup and pressing the import button will retrieve the data from Perfion PIM.
If no items were available for import then it will give a system message to that effect:
Otherwise it will give a prompt with the amount of business objects found and ask if you want to import them now:
Pressing yes will start the import, during which progress will be shown in the system messages log:
Once done a result form will open showing which objects were import, if the import was successful, what the primary key for the object is and a message saying if the object was added or updated:
If an object could not be could be imported then the message will give an error explaining why it couldn't be imported and the exception column will show the full error message:
In order to find out which specific fields are creating issues for import of objects, use debug mode.
Debug mode
If debug mode is checked then the import will be tested for issues for each object that the import would have, but no objects will be created or updated in SAP B1.
During normal imports objects are made from a template, all the fields are filled out and then the object is added in one step.
During debug mode a transaction is created, the object is created if it doesn't already exist, then the fields are updated one by one and finally the transaction is rolled back, removing any changes made by the import.
This allow us to tell which specific fields have issues unlikely during normal imports, however it is much slower than a normal import.
When the debug import is completed the Perfion Import Results will show which issues where found:
Right-clicking on a line in the message column and selecting copy will copy the message to your clipboard allowing you to paste it into a text editor for easier reading.
Note: The error "-5002 - Internal error (-5002) occurred" is a generic error from SAP B1, it may be a genuine error or it may be caused by a prior object encountering an issue. Fix other issues and retry the import to see if the error is genuine.