Shipping systems
      Back to home
      1. Home
      2. BxLogistics setup - Transport solutions
      3. Shipping systems

      nShift Shipment Server integration

      Setup and configuration of nShift/Consignor Shipment Server integration with BxLogistics Pro

      During this guide we will mostly address how to set up the integration correctly and how it works towards VismaNet, although most of these principles also applies to other ERP systems.

      1. Preparations

      Printers

      Make sure that the label printer and, where needed, the A4 printer that applies the Shipment Server printouts are installed on the server available for the BxEngine service (in other words, print queue on the same server as BxEngine). If print queue cannot be installed on the BxEngine server (i.ex because of connection issues or with ASP), you can install BxSmartPrintPro as a printproxy on a warehouse PC or a local server where installing label printers are easier.
      We recommend installing print queue locally on a Bx server/PC instead of shared from a print server and so on, as it is more stabile and printouts are quicker.
      What we mean by local print queue is that the print queue can be found under Control Panel -> Devices and Printers -> and is called something like "Printer" instead of "Printer on servername" or "\\servername\Printer".

      It should look something like this: 

      If you still decide to use a shared printer from printserver or so on, it is very important that the printer is available for our BxEngine and/or BxSmartPrintPro services. Local system, which is the standard service user for these two services, does in most cases not have access to shared network printers. 

      In our setup in BxAdmin, the printer name must also be added with UNC path, i.ex. "\\servername\Printername". 

      Printers containing (Redirected) will not work as these are printers that are joined via an RDP or a Citrix session, and as soon as the session closes, so does the print queue.

      Printer format

      It is important to know what formats the printer supports, in the form of ZPL, ZPLGK, EPL or DATAMAXLP2. If it does not support any of these, PDF is normally used. Mainly it is the ZPLGK language that is used with most who integrate Shipment Server with BxLogistics. This mainly applies to the newer type Zebra printers. This decides what to fill out in the required shipmentoptions config in BxAdmin. 

      Overview of the different types of formats from documentation to nShift: 

      • All label types are encoded as Base64. 

      • none - will not return any label but creates the shipment.
      • PNG - labels in PNG format.
      • PDF - labels in PDF format.
      • EPL - labels in EPL format for printers that are supporting this e.g. LP2844, ZM400 and GK420D.
      • ZPL - labels in ZPL format but will have a margin of 30 on top of the label. This label type is optimized for LP2844-Z printers and may print too far down on the label for other printers, if this issue occurs try the ZPLGK type.
      • ZPLGK - is also in ZPL format but without the top margin. Supported by printers like GK420D, ZM400 and may also work with other printers that are supporting ZPL language. 
      • DATAMAXLP2 - label for Datamax printers. 

      Shipment Server and API key

      All of the setup in the Shipment Server regarding transport deals, freight companies and etc must also be completed. This must be done in advance by you or nShift as BxSoftware is not responsible for this.
      To integrate towards mot Shipment Server it is required that you receive API details from nShift. You will need Actor-ID and server key. 

      ERP system

      All methods of delivery must be added to the ERP system. One method per parcel must be added in nShift that you wish to use on the handheld terminals.

      Here are some examples:

      • Bring Express next day
      • Bring Business parcel
      • Bring Business partload
      • Bring Parcel home delivery
      • Bring PickUp parcel
      • Schenker Partload
      All of the above can only have one delivery method per product in the ERP system. We also recommend that you add a "self pickup" alternative that gives you the option to send the parcel without have to place the actual order for shipping via Shipment Server.

      2. Shipment Server

      nShift has a test site to check on the different details related to delivery methods and so on in Shipment Server. We usually use this to look for correct ID's per delivery method we have to send to Shipment Server so that an order can be placed. It is not necessary to use this as we import all the delivery methods from Shipment Server. But it can come in handy if a problem occurs with missing delivery methods after an import run or if you just need to send in a different ID to Shipment Server. This can in some cases for example be if you use ProdCSID instead of ProdConceptID that we send as a standard. 
      Link to the page - http://consignorsupport.no/testbench/shipmentserver.aspx - on this page we switch Type to PROD before we fill out key and actor (Server key and actor ID will be given to you by nShift). Then press Load Actor, you should now be able to see different Product -> Carriers etc. and see the different ID's. 

      3. BxAdmin

      Installation - normally applies only if the ERP is not cloud based

      If you have VismaNet or other cloud based ERP systems you can skip this step. This setup is only necessary if it is towards Visma Business or other OnPrem ERP's.

      Under Installation in BxAdmin you must add an extra Database connection. This will be the BxEngine database as it is the BxEngine database we download all the data from Shipment Server to. If the setup is towards VismaNet or other cloud based ERP's, you do not have to carry this out as the BxEngine connection has already been set up.
      image-png-Jul-20-2021-11-50-37-35-AM.png (703×467)

      Imports from ERP

      1. Create new imports under Imports from ERP by pressing New import. Fill out Import type = shipmentserver, Module = deliverymethods, Enabled = Yes.
      2. In Field mapping press Add missing defaults to add all the import parameters.
      3. In Import config press Add missing defaults to add the configuration parameters.
        1. Here you also make sure to add the correct value in dbconnection, Which in this case is 1. See the Installation step if it in example is set up towards Visma Business. BxEngine will then be the second connection added after Visma Business. If the setup is towards VismaNet or other cloud based ERP's, leaving it as dbconnection 1 (standard) will be enough.
        2. In the serverkey and actorid, add the actor-ID and the API-key retrieved from nShift.

      Export to ERP

      1. We are also adding an exporter for Shipment Server under Export to ERP. Export type = shipmentserver, Module = shipmentserver, Action = create, Enabled = Yes.
      2. In Field mapping, press Add missing defaults to add all the export parameters.

      Configuration

      1. In Configuration -> Client profile -> Choose the correct profile: Activate these parameters under Area: consignor
        1. enabled = true
        2. serverkey = serverkey from nShift. Same as in Imports from ERP. 
        3. actorid = actorid from nShift. Same as in Imports from ERP. 
        4. shipmentlabelprinter = name of the print queue as it is available for BxEngine.
        5. shipmentoptions = In this case we use ZPLGK as the printer is a newer Zebra printer with ZPL format:
          {"Labels":"ZPLGK", "PriceCalculation":"1"} - See previous section on Printerformat. PriceCalculation is also always added to our setup with 1 as standard. 
        6. url = https://www.shipmentserver.com/ship/ShipmentServerModule.dll
        7. senderaddress = sender address.
        8. sendercity = sender city.
        9. sendermobile = sender phone/mobile number.
        10. sendername  = sender name, usually a company name.
        11. senderpostcode  = sender postal code.
      2. Under Area: pickinglist, activate these parameters
        1. deliverymethod = true
        2. shipment = true
        3. downloadpackagetypes = true, used for package types from freight delivery company.
        4. showpackagetype = true, used for package types from freight delivery company.
      3. If the print proxy setup is being used. please follow these steps. If the print proxy setup is not relevant for you, then you can skip this step.
        Under Area: consignor, fill out printproxy with the company code for the BxSmartPrintPro license, printproxylicensekey is filled out with the license key for BxSmartPrintPro. 
        1. printproxy = company code/AppCode
        2. printproxylicensekey = licensekey
        image-png-May-23-2022-01-30-36-11-PM.png (1178×200)

      Data

      Open Data in BxAdmin and press Run Import to download all the delivery methods for Shipment Server. Wait a few minutes before trying to refresh as it may sometimes take some time to retrieve them all. When the download is complete, the list should look like this. We have here also filled out the DeliveryMethod column with the ID's of different Send via-codes from VismaNet, which means the ID of the delivery method from the ERP.

      SQL Integration

      Delivery Methods
      The query for delivery methods can be found under SQL Integration -> Picking -> Delivery Methods. Towards VismaNet we have standard query for different TA systems. For Shipment Server line number 4 should be commented out and line 8 and 14 should be commented in. The ID added to the delivery method column from the last step should match the ID for the ERP code here. When this is done correctly the externalid and externalproduct columns when running the query should have the correct ID from Shipment Server.

      For other ERP systems that are not cloud based, you must often merge tables for transports/delivery methods from the ERP so that our table merges with the ERP. Delivery method ID should match the ERP ID.

      Package Types
      In some cases of specific freight vendors, additional information is required, such as package content to Shipment Server. In these cases you must also fill out the DeliveryMethod column in the PackageTypes tab under Data with the correct ID from the ERP. In addition to that you must also activate the setup for it under Configuration -> area: pickinglist, showpackagetype = true and downloadpackagetypes = true. This gives an additional option for package types on the terminal in the freight image. 
      SQL query for Package Types is standard and must not be changed.

      Delivery Services
      We also support sending one or more services to carriers who has the support for this. To activate this, you must go to Configuration -> Client Profiles -> area: pickinglist, showdeliveryservices = true and downloaddeliveryservices = true. Then, you go to Data -> DeliveryServices, match the DeliveryMethod column with the ID from the ERP towards the correct carrier and delivery method. In our case BRING1 ID in the ERP is for Bring Business parcel.

      Update 18.08.23: The standard query for services takes this into consideration so that you do not have to fill out the DeliveryMethod column. If you wish to limit the available options for the delivery method, this is the simplest way to do so.


      Summary

      This is everything you need to do to set up the Shipment Server integration in BxLogistics Pro. Normally nothing more is required, but possible extra relevant setup will eventually be documented under Extra.

      Extra

      Tracking number and Shipment price

      Shipment Server sends us a tracking number, tracking ID and a shipment price with the freight label as soon as the shipment is sent from the terminal. These values can be retrieved and forwarded to the ERP system. The correct source fields for these are: 

      shipmentTrackingId - tracking number
      shipmentTrackingUrl       - tracking link
      shipmentPrice1       - shipment price 1
      shipmentPrice2 - shipment price 2

      These can be forwarded to the preferred fields within the ERP via the pickinglist create exporter.
      Certain ERP's, like VismaNet, have standard fields for this that has already been entered into the standard exporter, while with other ERP's it is necessary to add mappings towards the correct fields in the ERP. It may also become necessary to use the pickinglist addproduct exporter for the shipment price towards ERP's that does not have standard fields for pricing, where the price instead is added in as a sales order line.