- Setting up the connection and some other mandatory parameters
- Advanced configuration
- Field mapping
- Visma BOM integration
- FAQ / Troubleshooting
- Standard fields exported from Visma
- Standard fields imported to Visma
The SOA integration consists of a service (PlannerSoaService) and a client (ROB-EX with SOA plugin). The service must be installed on the ERP system. Thus it’s possible to exchange data directly over a network. The actual data which is transferred is in XML format, see XML integration.
In the following it’s described how to install the SOA integration and how to get it up and running. At last the configuration is described.
This covers the installation and the basic setup in order to establish a connection.
The requirements for the installation are listed in the table below.
- ROB-EX version 4.0 build 234 or later with license for SOA plugin. Notice that for integration to Visma 5.31 or newer it requires ROB-EX version 4.2 build 169 or newer.
- The file soaVismaSetup.xml must be found in the “custom” and/or “config” folder in the ROB-EX installation. This file is installed automatically to the “config” folder when ROB-EX is installed.
- The operations generated in ROB-EX must have an ID starting with a letter (default setup) – i.e. the prefix must not be numbers! This can be modified in “Functions->Settings->General->ID generator”.
At present time the PlannerSoaService is only compatible with the ERP system “Visma Business”.
The zip-file “PlannerSoaService.zip” contains the following files:
- Paste into Plugins_xml.txt
- Paste into Visma.BusinessHost.exe.config.txt
- Some documentation files
The dll files are located in two different folders. Folder 1 = “Visma version older than 5.31”, Folder 2 = Visma version 5.31 or newer.
The service “VismaBusinessServicesHost” must be proper installed. This is configured in the Visma installation program.
Installing the Service
First make sure the “VismaBusinessServicesHost” service is stopped. This is done in the Services list, see below.
- Browse to the “…\Visma\Business\Plugins” folder and make a backup of the “Plugins.xml” file.
- Paste the text in the “Paste into Plugins_xml.txt” file to the “Plugins.xml” file
- Paste the text in the “Paste into Visma.BusinessHost.exe.config.txt” file to the “Visma.BusinessHost.exe.config” located in the “…\Visma\Business” folder
- Start the “VismaBusinessServicesHost”.
Setting up the connection and some other mandatory parameters
In ROB-EX go to “Functions->Settings->SOA plugin” and select the “Connection” tab.
|ERP type||The only type at present time is “Visma Business”.|
|Soap version||This can be 1.1 or 1.2. At present time Visma only supports 1.1.|
|URL||The path to the PlannerSoaService. Replace “localhost” with the correct server name. This is the machine where Visma Business is installed.|
|Login||Login credentials to the connection itself. Normally not needed.|
|Password||Password credentials to the connection itself. Normally not needed.|
Before pressing the “Test connection” button some additional settings must be configured in the “Visma Business” tab.
“Visma Business” tab
The settings in this tab are specific for the Visma Business ERP system. Fill in the parameters in compliance with the ERP system.
Make sure to select the “Visma version”.
Now change back to the “Connection” tab and press the button “Test connection”.
After a few seconds the dialog shown below should appear. Refer to the Troubleshooting chapter if this is not the case.
Now everything is properly setup it should be ready for the first synchronization.
On the toolbar in ROB-EX press the small black arrow and choose “SOA integration”. Then ROB-EX will first export changed orders and then import all orders from Visma.
If starting with an empty plan and importing existing data from Visma, it’s advised to create a default calendar.
This covers some extended configuring and use – both via the “SOA plugin settings” in ROB-EX and via the setup file “soaVismaSetup.xml”.
The “General” tab
|Import only changed or new orders||Only the orders and projects which are changed since the last synchronization are imported.|
|Import all||Import all orders/projects changed since 1970, i.e. all data will be imported.|
|Update automatically||If this is checked the “SOASynchronization” macro is executed in the specified time interval.|
|Select all||If this is pressed all production orders in ROB-EX are marked as changed. Thus all orders will be exported upon the next synchronization.|
|Write XML code in the log file||If this is checked detailed information about the synchronization is written to the log file. This is used for debugging.|
The “Macro” tab
In here two macros exist, “Automatic” and “Manual”. The “Automatic” macro is executed repeatedly if the “Update automatically” setting on the “General” tab is checked. More commands can be added for execution before and/or after the “SOASynchronization” command. The commands can be selected from the list in the left side of the dialog. For more info about macros see Creating and editing macros.
A separate “SOASynchronization” command exists for respectively the “Automatic” and “Manual” macro so they can be setup individually. In order to open the “Macro line parameters” dialog shown below double click the “SOASynchronization” line in the above dialog.
The way the synchronization is performed can be setup in the command. If “doImport” is disabled (set to false) ROB-EX will only export data. Furthermore it’s possible to control if ROB-EX should export before the import and export after import.
The configuration file “soaVismaSetup.xml” gives access to some extended configuration of the SOA integration. The configuration file contains two types of settings, basic settings which gives the possibility to specify for instance the time unit, and selection criteria which gives the possibility to specify which orders to export from Visma thus all the production data isn’t exported upon each synchronization. The basic settings are shown on the “Visma Business” tab (see the dialog below). In the following the two types of settings are explained.
p(#The-basic-settings). The basic settings
The basic settings are embraced by a tag. The tag (export settings) and the tag (import settings) have individual settings. Examples are shown below.
The “ExportConfig” contains settings for Visma Business concerning the data exported from ROB-EX. Thus Visma uses the settings to determine how to parse the data received from ROB-EX.
<ExportConfig> <Settings> <!-- TimeUnit can take the values HOURS, MINUTES --> <Property name="TimeUnit">MINUTES</Property> <!-- ProgressSource can take the values CLIENT, SERVER --> <Property name="ProgressSource">SERVER</Property> <!-- ConvertOprStatus can take the values TRUE, FALSE --> <Property name="ConvertOprStatus">TRUE</Property> </Settings> </ExportConfig>
The “RequestConfig” contains settings for Visma Business concerning the data imported to ROB-EX. Visma uses the settings to generate the production data which is to be sent to ROB-EX.
<RequestConfig> <Settings> <!-- TimeUnit can take the values HOURS, MINUTES --> <Property name="TimeUnit">MINUTES</Property> <!-- ProgressSource can take the values CLIENT, SERVER --> <Property name="ProgressSource">SERVER</Property> <!-- ConvertOprStatus can take the values TRUE, FALSE --> <Property name="ConvertOprStatus">TRUE</Property> <!-- deleteAllNonImportedProdOrders can take the values TRUE, FALSE --> <Property name="deleteAllNonImportedProdOrders">TRUE</Property> <!-- IncludeMainOrderStateInterval can take the values [state]-[state] i.e. 10-90. --> <!-- Ignore orders with state less than 10 and state greater than 90. --> <Property name="IncludeMainOrderStateInterval">10-90</Property> </Settings> <DataRequest type="ProdOrder"> ... ... </DataRequest> </RequestConfig>
A description of the settings can be found in the table below.
|TimeUnit||Visma Business can operate with a time unit in either hours or minutes. However ROB-EX always operates in hours. So if the time unit is specified to minutes the transferred values will be converted. Possible values are MINUTES and HOURS.|
|ProgressSource||This setting specified in which system progress is reported. Specify CLIENT in case progress is reported in ROB-EX. Specify SERVER in case it’s reported in Visma Business.|
|ConvertOprStatus||The operation status values are different in ROB-EX and Visma i.e. the status “started” corresponds to 40 in ROB-EX and 50 in Visma. Possible values are TRUE and FALSE.|
|deleteAllNonImportedProdOrders|| Specify true in order to delete those orders from ROB-EX which wasn’t exported from Visma. Thus if an order is deleted in Visma it will also be deleted in ROB-ex upon next synchronization.
In case only some of the orders are requested from ROB-EX this setting is automatically disabled. Otherwise the rest of the orders in ROB-EX would be deleted upon synchronization.
|IncludeMainOrderStateInterval||By default this is set to “10-90” meaning that only orders with state 10 (new) to 90 (deleted) will be exported from Visma.|
|UseDelOnMainOrder||Take the delivery date from the main order (true) or from the Finished Good orderline (false). Values are TRUE and FALSE|
|wlType||Fixed workload (0) or workload calculated from capacity and quantity (1). Values are 0 and 1.|
|ignoreProjects||If true projects are not imported from Visma.|
|DEBUG||If true debug info is printed in weblog (default c:\weblog.txt) on PC where Visma is installed.|
|RemTimeRule||Should progress be reported in HOURS (default) or QUANTITY in Visma. If QUANTITY is specified the next field “RemTimeRuleQuantityField” must also be specified.|
|RemTimeRuleQuantityField|| Only relevant if “RemTimeRule” is set to QUANTITY.
Specify the field in Visma from where the progress in quantity should be read (any field on order line).
8541 = Free1 (default), 8542 = Free2, 8543 = Free3, 8544 = Free4.
|ImportBOM||BOM import. Enable this if materials and BOM should be imported from Visma. Possible values: TRUE, FALSE|
|ProductSelectionVBField||BOM import. Specify the column number where it is indicated if the product should be imported to ROB-EX. If left blank all products are imported. Most common fields: Free1=11261, Free2=11262, Free3=11263, Free4=11264|
|ProductSelectionVBMatch|| BOM import. Specify what the contents of the “ProductSelectionVBField” must match in order to get the product imported.
Not relevant if “ProductSelectionVBField” is blank.
|ProductSelectionVBFieldType||BOM import. Specify the data type. Possible values: string, decimal, int.|
Under the tag a number of selections can be specified. It’s possible to select orders or projects by id or a date. In that way the synchronization will speed up significantly because less data is exported from Visma Business.
Some “DataRequest” examples are shown below.
<RequestConfig> <Settings> ... </Settings> <DataRequest type="Project"> <Selector> <Id>1001,1002</Id> </Selector> </DataRequest> <DataRequest type="ProdOrder"> <Selector> <ChangedSince>10-05-2010 12:00:00</ChangedSince> </Selector> <Selector> <Id>2364</Id> </Selector> </DataRequest> </RequestConfig>
It’s possible to specify multiple
<DataRequest> tags and furthermore it’s possible to specify multiple
<Selector> tags under each
<ChangedSince> tag a date and time can be specified resulting in Visma only exporting orders/projects changed after the specified date. Instead of specifying a fixed date the key word “LAST_UPDATE” can be specified. Thus only orders changed after the last synchronization will be exported from Visma. Please notice that if a hardcoded date is entered instead of “LAST_UPDATE”, the “Import only changed or new orders” setting on the General tab will not have any effect! In the tag a comma separated list of order or project ids can be specified resulting in Visma only exporting orders/projects with the specified ids.
It’s possible to remap the existing fields in the integration to other fields in ROB-EX and it’s also possible to add extra fields which should be exported from Visma. It’s only upon export from Visma to ROB-EX that it’s possible to remap/add extra fields. The export from ROB-EX to Visma is fixed and cannot at present time be changed/remapped.
The field mapping is specified in the soaVismaSetup.xml file which is located in the custom folder in the ROB-EX installation. In the following a few examples will be illustrated.
In the example below some fields on the productionOrder type are remapped. The customer field is remapped so the customer is taken from the project instead of from the order. Then is the customer from the order mapped to a new field in ROB-EX, the custText1 field, thus both customer from main order and order line can be seen in ROB-EX. At last the state is mapped to the custText2 field. See the table further below for an explanation of the XML attributes.
<!-- Possible tables: Order, OrderLine, OrderCustomer (Associate), Project (OrgUnit2), ProjectCustomer (Associate) --> <FieldMapping type="ProdOrder"> <Field VBTable="ProjectCustomer" VBField="4029" Robex="cust" type="string" /> <Field VBTable="OrderCustomer" VBField="4029" Robex="custText1" type="string" /> <Field VBTable="Order" VBField="6098" Robex="custText2" type="string" /> </FieldMapping>
In this example two fields on the Operation type are remapped. The description (“desc”) field is remapped to the Visma field 6100 (TransGroup4 on the orderLine table) which represents the state of the production order on the orderline. The second field (“custText1”) is mapped to the Visma field 6098 (TransGroup4 on the Order table) which represents the state of the main order.
<!-- Possible tables: Order, OrderLine, Product --> <FieldMapping type="Opr"> <Field VBTable="OrderLine" VBField="6100" Robex="desc" type="string" /> //state - transgroup4 <Field VBTable="Order" VBField="6098" Robex="custText1" type="string" /> </FieldMapping>
Explanation of the XML attributes
| This specifies the type of the object in ROB-EX the mapping refers to. I.e. “ProdOrder” specified that the mapping is performed on production orders.
Project, ProdOrder, Prod, OprSeq, Operation
|VBTable|| This specifies which table in Visma to take the field from. In some situations the same table exists in multiple contexts. Therefore it’s needed to call them by different names. For the ProdOrder type the Associate table exists in two versions – the “OrderCustomer” and “ProjectCustomer”.
The possible tables are dependant of which type is specified. The tables are listed in the soaVismaSetup.xml file, above each different type or see Standard fields exported from Visma
|VBField||This is the external number of the field in Visma. This is the source field.|
|Robex||This is the name of the field in the ROB-EX XML import mechanism. Thus this is the target field. Refer to the “ROB-EX XML integration.pdf” paper for a list of possible fields.|
|type||Here the data type is specified – normally a String. Possible values: string, decimal, int, date, time|
Visma BOM integration
The SOA integration between Visma Business and ROB-EX supports materials and BOM (from PlannerSoaService version 1.15 and above). The following can be transferred from Visma to ROB-EX:
- Sales orders
- Purchase orders
- Countings (opening stock)
- BOM (bill of material)
The import of BOM is disabled by default. This must be enabled in the file “soaVismaSetup.xml” in the custom folder in the ROB-EX installation. Also by default the products to transfer to ROB-EX is selected on the “Free1” field in the Product table.
Change the value from “FALSE” to “TRUE” in the “ImportBOM” property:
Select the products to transfer to ROB-EX
In the “ProductSelectionVBField” it can be specified which field in the Product table to use for the product selection.
The default field to use is “Free1” which correspond to the column ID “11261”. If no selection is wanted, just leave the value blank, and thus all products will be transferred.
The contents of the “ProductSelectionVBField” must also be specified – this is by default “1” (string). This can be any value but the “ProductSelectionVBFieldType” must be adjusted accordingly.
The data type in the “Free” fields are “string”, which is the default value specified in the “ProductSelectionVBFieldType” property. Other supported types are “decimal” and “int”.
The units in Visma must be mapped to the units in ROB-EX. This is done in the “soaVismaSetup.xml” file.
Stat1 (overlap) cannot be specified on master routes in Visma – only on the unfolded BOM.
Remapped fields (field mapping) are only respected upon export from Visma. Thus export from ROB-EX is based on a standard mapping which at present time cannot be changed.
In the following the common problems and their solutions are described.
If the message below is shown when pressing the “Test connection” button, a connection could not be established to the service “VismaBusinessServicesHost”.
The “VismaBusinessServicesHost” must be running on the machine where Visma Business is installed. Also make sure the URL in the “Connection” tab is correct. It should look like
http://localhost:2001//PlannerSoaService (replace the “localhost” with the correct host name)
Also try to enter the above URL in a browser. The browser should display a web page.
If a message is displayed showing something like the text shown below it’s probably a wrong soap version. It should be soap version 1.1.
org.apache.axis2.AxisFault: Transport error: 415 Error: Cannot process the message because the content type 'application/soap+xml; charset=UTF-8; action="http://tempuri.org/IPLannerSoaService/getVersion"' was not the expected type 'text/xml; charset=utf-8'.
Delivery time is always “now” in ROB-EX
If ROB-EX receives a blank delivery date from Visma Business it will set the date to “now”. Make sure the correct fields in Visma is filled out and also check the setting “UseDelOnMainOrder” in the setup file “soaVismaSetup.xml”. If the setting is true the following fields will be read from the main order (in prioritized order):
If the “UseDelOnMainOrder” is false it will read the delivery from the order line (the finished good). The following fields will be read (in prioritized order):
How the ROB-EX material date is calculated
The material date is collected from Visma in the following order:
- orderline.DesProDt (Visma extern no. 11593). If this field is blank
- mainord.DesProDt (Visma extern no. 11592) is used instead
- If both of the above fields in Visma are blank, a blank material date is transferred to ROB-EX. If ROB-EX receives a blank material date from Visma Business it will in ROB-EX be set to either “01-01-2000” or to time “now” (depending on setting “materialCalUseTimeNowIfNull” in “Functions->Settings->General” on the Integration tab). Make sure the correct field in Visma has been filled out.
If the problem could not be solved, please contact ROB-EX A/S at email@example.com.
In order to give the best support the files listed below should be attached along with a description of the issue and possibly some screenshots of the error messages.
Files to attach:
|ROB-EX log file||In the help menu in ROB-EX select “Send log file”. A folder opens with a zip file which contains the logs – attach the zip file.|
|Visma Business log file||This is by default located in “c:\VismaLog\VismaBusinessServiceHostLog.svclog”. The path can be changed in the config file “Visma.BusinessHost.exe.config”.|
|soaVismaSetup.xml||If this is present in the custom folder in the ROB-EX installation please attach this, otherwise attach the one in the config folder.|
Standard fields exported from Visma
The “Fixed fields” cannot be remapped. The “Free fields” can be remapped.
Order, OrderLine, OrderCustomer (Associate), Project (OrgUnit2), ProjectCustomer (Associate)
|Id||Order.OrderNo + “-” + OrderLine.LineNo||Main order no + the order line no.|
|prodId||Order.OrderNo + “-” + OrderLine.LineNo|
|state||OrderLine.TransGroup4, Order.TransGroup4||First try the state on the order line, if 0 take it from the main order.|
|endCal|| useDelOnMainOrder = true:
Order.ConfirmedDeliveryDate, Order.ArrivalDate, Order.RequiredDeliveryDate
useDelOnMainOrder = false:
| “endCal” is Known as “delivery” in ROB-EX.
The fields are dependant of the useDelOnMainOrder setting in the soaVismaSetup.xml file.
|planStrat||N/A. Status >= 20 ? “none” : “|
|name||Order.OrderNo + “-” + OrderLine.ProductNo|
|oprSeqId||Order.OrderNo + “-” + OrderLine.LineNo|
|prodOrderId||Order.OrderNo + “-” + OrderLine.LineNo|
|item||“||Just a blank string is exported|
Possible tables:Order, OrderLine, OrderCustomer (Associate), Project (OrgUnit2), ProjectCustomer (Associate)
|id||Order.OrderNo + “-” + OrderLine.LineNo|
|prodId||Order.OrderNo + “-” + OrderLine.LineNo|
|name||Order.OrderNo + “-” + OrderLine.LineNo|
Possible tables:Order, OrderLine, Product
|oprId||Order.OrderNo + “-” + OrderLine.LineNo|
|lastStartCal||OrderLine.FinishDate + OrderLine.FinishAt||Progress|
|seqId||Order.OrderNo + “-” + OrderLine.LineNo|
|parentOprId||Order.OrderNo + “-” + OrderLine.LineNo||Concerning split/join|
|startCal||OrderLine.ConfirmedDeliveryDate + OrderLine.From|
|endCal||OrderLine.ArrivalDate + OrderLine.To|
|capa||1 / ((wl * time_factor) / qty)|| The capacity is calculated from the workload and the quantity.
The capacity is only respected in ROB-EX if “wlType” is set to “1” in the soaVismaSetup.xml file.
|overlapCount||OrderLine.StatisticsValue1||If greater than 0.|
|wlType||Default = 0, fixed workload.||Based on wlType setting in soaVismaSetup.xml|
Possible tables:OrgUnit2, Associate
|customer||Associate.CustomerNo OrgUnit2.CustomerNo (Associate.Name)|The customer no is looked up in the Associate table and the name of that is returned.| |manager|Associate.EmployeeNo OrgUnit2.Official (Associate.Name)||The employee no is looked up in the Associate table and the name of that is returned.|
|state||OrgUnit2.Status||Only if state is 10, 50 or 80.|
|type||OrgUnit7.MainUnit == OrgUnit7.OrgUnit7No||IsGroup ? “group” : “normal”|
|Unit class -and factor||Product.StSaleUN|
|ID||StockBalance.ProductNo + “-” + StockBalance.WarehouseNo|
|ID||OrderLine.OrderNo + “-” + OrderLine.LineNo|
|Begin -and end date||OrderLine.ArrivalDate|
|TransactionType||OrderLine.TransType||Producing or consuming|
|-||OrderLine.CustomerNo||Using the CustomerNo to look up the customer name in the Associate table.|
The sales – and purchase orders are selected from the following fields and logic.
1. Quantity must be greater than 0
2. ArrivalDate must be after time now (time for synchronization)
3. TransType must be equal to 6 (purchases) or 1 (sales orders)
4. ChangedDate and ChangedTime
|ID||Ord.OrdNo + “
||The Access ID is put together by the OrdNo, LineNo and ProductNo.|
|Type||OrderLine.TransType||Producing or consuming|
The following fields are used for selecting the BOM lines.
1. OrdNo. This is used to find BOM lines belonging only to the current order.
2. ProductType4 must be equal to 2.
3. TransType must be equal to 5 (consuming) or 7 (producing)
4. SortSequenceNo is used for sorting the BOM lines (ascending).
Standard fields imported to Visma
|state||Order.TransGroup4||Only if the state is higher than existing.|
|startCal||OrderLine.ConfirmedDeliveryDate + OrderLine.From|
|endCal||OrderLine.ArrivalDate + OrderLine.To||If endCal is greater than OrderLine.ArrivalDate it is also set on this field (on the route)|
|value (from JobEntry)||OrderLine.FinishNow||Progress in hours on setup time and workload|