This article will explain how to set up Shipment Server to run on-premises (SSOP). It covers the following topics:

• Introduction 
• Setting up Shipment Server to run on-premises
• Creating a key and verifying the connection
• Using import engine with Shipment Server
• Using the SubmitShipment method
• Updating nShift On-premises
• Troubleshooting
• Download files

Introduction

Local integration with nShift On-premises has until now been done by file drop. The ERP/WMS system drops a file that On-premises picks up and reads, and the different fields in the file are defined in the Import Setup in On-premises. To communicate back, nShift On-premises can drop a file with shipment information that the ERP/WMS can read.

The file drop communication is asynchronous which is sufficient in many cases. If you have the need for synchronous communication with your local nShift On-premises it is possible to set up Shipment Server locally. With Shipment Server you will get a REST webservice interface to most of the functionality in nShift On-premises. You can find our documentation for the API here.

Shipment Server is designed and tested to run as ISAPI DLL under IIS (Internet Information Services) on Windows. IIS comes as a standard with Windows. It may also be possible to run it under other web servers like Apache, but that is not verified and tested by nShift.

It is also possible to call into a local Shipment Server from a remote location running the ERP/WMS system, but ports must be opened in the firewall and the requests have to be routed to the computer running Shipment Server.

nShift On-premises Client (COP Client), nShift On-premises Server (COP Server) and Shipment Server may run on separate machines but can also run on the same machine.

Setting up Shipment Server to run on-premises 

Note: .NET Core Hosting Bundle is required to run Shipment Server On-premises since it allows core apps to run with IIS. The update should install it but if the app pool name is not "nShift" the update doesn't recognize it. Insufficient permissions may also cause the bundle update to fail.

1. Install nShift On-premises server. (See our article about installing nShift On-premises Server here). Skip this step if it is already installed. In this article, we assume that you will run Shipment Server on the same server as nShift On-premises.
   
   
2. Copy the two script files (Enable_IIS and ShipmentServer_IIS) found in the Download files section and add them to a local folder. In this example, they are placed in C:\Consignor\Consignor\Scripts
   
   
3. Enable IIS in Windows. It is not enabled by default but you can enable it by running the PowerShell script file Enable_IIS:
   
   1. Press Windows key and type powershell.
   2. Right-click on Windows PowerShell and select Run as Administrator.
      
   3. In the Powershell window type "C:\Consignor\Consignor\Scripts\Enable_IIS.ps1" and press Enter. If you do not have access to run the script, you may need to configure the execution policy in Powershell. Enter Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine.
      
      
4. Create a Shipment Server site in IIS. This is done by typing C:\Consignor\Consignor\Scripts\ShipmentServer_IIS.ps1 in the same window as used in step 3.

If you experience errors when running the PowerShell script, please read our Trouble shooting section.

Creating a key and verifying the connection

1. Start nShift On-premises.
   
   
2. Go to Setup, right-click on any actor in the setup tree, and notice the Actor ID.
   
   
   
   
3. With the same actor selected, right-click in the pane to the right and select New > Shipment Server key.
   
   
   
   
4. Type in a key of your choice or click Generate and click OK.
   
   
   
   
5. Open the file GetProducts.html in a browser. (File be found in the Download files section. We recommend using Chrome and not IE as IE often denies API calls to be sent to this local file C:\Program Files (x86)\Consignor\ShipmentServerModule.dll.
   
   
6. Fill in ActorCSID (Actor ID) and key and click Submit Query.
   
   
   
   
7. You should now get back JSON describing all carriers, subcarriers and products activated on the actor.

Using import engine with Shipment Server

You can use all the functionality that nShift On-premises offers in the import module from Shipment Server. It is a good idea to set up an import and make sure it works with file drop. When it is working, you can start calling the local Shipment Server as described here.

Call Shipment Server with these parameters, actor, and key is as described earlier, the other parameters should be:

Example of fields mapped in import setup:

Content of the corresponding import file:

Test name,Vossiusstraat 10A,1071AC,Amsterdam,NL,DHLESU,GK,1234,Pieterse,1,2,Test goods,PA,123456789

The data section for the call will be:

{
  "filename": "file.TXT",
  "filecontent": "VGVzdCBuYW1lLFZvc3NpdXNzdHJhYXQgMTBBLDEwNzFBQyxBbXN0ZXJkYW0sTkwsREhMRVNVLEdLLDEyMzQsUGlldGVyc2UsMSwyLFRlc3QgZ29vZHMsUEEsMTIzNDU2Nzg5"
}

When using this method you don't need to specify the product ID in nShift On-premises but you can use the key (carrier code) instead. If you want to change the product, you can simply go into the import setup and remap the key to a different product instead of changing the call to Shipment Server.

See the HTML file ImportUploadKey1.html in the Download files section.

Using the SubmitShipment method

You can also call Shipment Server using the SubmitShipment method to create a shipment.

When you use SubmitShipment you must specify all the details of the shipment in JSON.

Sample request:

{
  "Kind": 1,
  "ProdConceptID": 1697,
  "OrderNo": 1234,
  "Addresses": [
    {
      "Kind": 1,
      "Name1": "John Doe",
      "Street1": "Test Street 1",
      "PostCode": "75008",
      "City": "Paris",
      "POPostCode": "0555",
      "POCity": "PARIS",
      "Phone": "98765432",
      "Mobile": "12345678",
      "Email": "john@doe.com",
      "CountryCode": "FR"
    },
    {
      "Kind": 2,
      "Name1": "nShift",
      "Street1": "Bredskifte alle 11",
      "Attention": "MT",
      "PostCode": "8210",
      "City": "AARHUS V",
      "POPostCode": "8210",
      "POCity": "AARHUS V",
      "Phone": "3333333333",
      "Mobile": "11112222",
      "CountryCode": "DK"
    }
  ],
  "References": [
    {
      "Kind": 53,
      "Value": "GK"
    }
  ],
  "Lines": [
    {
      "LineWeight": 500,
      "GoodsTypeKey1": "PA",
      "References": [
        {
          "Kind": 23,
          "Value": "Postcards"
        }
      ],
      "Pkgs": [
        {
          "ItemNo": 1
        }
      ]
    }
  ]
}

To learn more about using Shipment Server, see the list of methods here or jump to the overview of all our Shipment Server articles.

Try to test yourself using the file SubmitShipment.html from the Download files section. You must edit the data to match a product in your nShift On-premises.

Updating nShift On-premises

Follow these steps to update your on-premises solution:

1. Open Internet Information Services (IIS) Manager in Windows.
   
   
2. Click on Application Pools to see the list of application pools on the server.
   
   
3. Right-click on nShift and select Stop.
   
   
   
   
4. Next, follow all the steps described in the article Update nShift On-premises server.
   
   
5. When the update is complete, start the application pool again.

Troubleshooting

If you have trouble running the PowerShell script and get an error like "Failed to process input: The parameter 'Execute' must begin with a / or - (HRESULT=80070057).", you may be missing the correct permission settings. 

1. In the Internet Information Services (IIS) Manager window, go to ShipmentServer and open Handler Mappings. 
   
   
   
   
2. Click Edit Feature Permissions, make sure all boxes are checked and click OK.
   
   
   
   
3. Try running the Powershell scripts again.

If you get an error saying "[script file] cannot be loaded because running scripts is disabled on this system", you may need to set the execution policy. Read more about setting the execution policy here at Microsoft.

If you get an error saying "HTTP Error 500.31 - Failed to load ASP.NET Core runtime"
make sure that you are running the correct AspNetCore.App version

To see the installaled version run the command "dotnet --list-runtimes" in the command prompt

On-Premises - Version 17

On-Premises - Version 18

Download files

Here you will find the files needed to follow the tutorials in this article.