Shipping Director

! Important for Upgrading !
!  There were major changes made in the core for nopCommerce 4.30 that may have impact on the expressions used in your Shipping Director configuration.
!  Be sure to test your configuration.
!  You will no longer have direct access to sub-properties (navigation properties) that you previously used. For example
!  Don't use
!      ShippingAddress.StateProvince.Abbreviation
!  Just use
!      State
!  Alternately we've provide some helper methods
!      ShippingAddress.GetState().Abbreviation
!      ('State' returns the state abbreviation.)
!
!  Similarly, rather than using ShippingAddress.Country.TwoLetterIsoCode, just use Country, or  ShippingAddress.GetCountry().TwoLetterIsoCode
!
! (We'll be updating the blogs with more information)



Download the Shipping Director install package (.zip file) from nopTools.com.  Click the "DOWNLOAD TRIAL" button on the product page for your version of nopCommerce.  (This readme.txt file is in the download .zip file.)  
I recommend that you "unblock" the downloaded .zip file.

Installation
------------
1) New Install  (You should not already have the ShippingDirector table in DB)
- In Admin > Local Plugins, use the "Upload plugin or theme" button, and choose the Shipping Director install .zip file you downloaded.
- Follow the instructions to apply changes / restart.
 - When the site restarts, go back to Admin > Local Plugins and verify that the plugin is installed.  The, Configure it.

2) Upgrade
If you did an in-place upgrade of your DB (i.e. you have a table called ShippingDirector in your DB), and your prior version of nopCommerce was older than 4.30, then execute this upgrade script:

INSERT [MigrationVersionInfo] ([Version], [AppliedOn], [Description]) 
VALUES (637283796551687541, GetDate(), N'Shipping.Director base schema')

Then there are two ways to do the install / upgrade:

a) Automatic
Although you have the ShippingDirector table in DB, follow the instructions in the "New Install" section above.
or 
b) Manual
- Download the Shipping Director install. package (.zip file).  (I recommend that you "unblock" the .zip file.)
- Open the .zip and copy the Shipping.Director folder to your \Plugins folder.
- Add this to the end of the "InstalledPlugins" section of your   \App_Data\plugins.json file
,

    {

      "SystemName": "Shipping.Director",

      "Version": "1.55"

    }


(Put it at the end of the "InstalledPlugins" section.  Be sure to put that comma before.)

Then "reload list of plugins" or restart the site.



If during an upgrade, you get an exception "There is already an object named 'ShippingDirector' in the database", then you may not have applied the above upgrade script properly.  Use SQL to check the MigrationVersionInfo:
   select * from [MigrationVersionInfo] where description like '%director%'

License File 
If you have a license file, then you must manually upload it to your site \Plugins\Shipping.Director folder.  Then "Reload list of plugins", or restart the site.   If you have multiple license files (e.g. multiple stores), they are all downloaded named as License.txt.  Be sure to rename them so the names are unique, but be sure that the names start with "License" and have .txt extension  - e.g.   License_SD_yourdomain.com.txt


Configuration
-------------
Now, in nopCommerce administration, Configuration > Shipping > Shipping Rate Computation Methods, you will see Shipping Director. 

When using Shipping Director, it should be the only "Is Active" method.  Click its Edit button, and check its Is Active checkbox; then click its Update button.   Be sure to uncheck Is Active for all the other methods.  If you need to call the other methods from Shipping Director, you can still configure them with their Configure link, but be sure that the only active method is Shipping Director.

Click Shipping Director's Configure link to configure Shipping Director.

In the Shipping Director configuration page, click the Import button to import the included 'ShippingDirector (Hello World).txt' file.  Then, go to the public store, add an item to the cart, and then processed through checkout to see the result.  (Or, you can use Estimate Shipping from the cart page.) 


If you see the message "Sorry, we are unable to calculate your shipping. Please contact the store.", then look in the Admin > System > Log for more details.

For additional debugging information, add the $Debug variable to the rules - e.g. 
0	(active)	$Debug		true

It's easiest to test your shipping rules by using the "Test" button on the configuration page.



At this time, there is no formal user manual.  Refer to the blogs at www.nopTools.com for more information.  You can contact us at support@noptools.com .  If you need help in setting up a shipping scenario, be sure to provide us with a few examples of "what's in the cart", and the expected shipping rate (and why).   

When setting up a complex set of shipping rules, be sure to consider what rate to calculate when there are multiple items in the cart each having their own specific rules and/or combination-specific rule.


Without a License.txt file, Shipping Director runs in evaluation (trial) mode.  In evaluation mode, you can calculate 5 rates in th epublic store, and then it will present a warning message.

When you are satisfied with Shipping Director and wish to purchase a license, note the URL (or Domain) next to the Version information on the configuration page - e.g.  Version 1.40 (Evaluation. Domain=mydomain.com; URL=www.mydomain.com) .  Be sure to copy the URL [Domain] exactly as it is presented (don't copy it from the browser address bar; don't include any http:// prefix.  You will need this when you purchase online at www.noptools.com.  If you are using the multiple store option in NopCommerce, then you need to purchase a license for each store (URL).   (Each license file generated is named License.txt;  be sure to name them uniquely when putting them in the plugin folder; the file name must be prefixed with "License" - e.g. License_store1.txt, License_store2.txt, etc.)

To uninstall, after clicking the Uninstall link in the plugin configuration page, be sure to also remove the Shipping.Director folder from your \Plugins folder and restart your web application.




NOTES!!  

In nopCommerce 3.20, a "Use Warehouse Location" setting was added to the Configuration > Settings > Shipping Settings.  If you have set warehouses on your products, this setting will cause nopCommerce to call the active shipping rate calculation method(s) once for each warehouse (with only the products that originate from that warehouse).  Depending on your Shipping Director configuration, this may not be desirable.  Shipping Director has included its own "Use Warehouse Location" setting which may be more appropriate or not depending on if you need to do Packing.  Check the blogs for more info.  If you have a complex shipping scenario, feel free to contact us at support@noptools.com

In nopCommerce 3.50, they introduced a Product field called "Ship Separately".  You must be careful if you use this field, because it will cause the core shipping to call Shipping Director multiple times. The "Items" evaluated by Shipping Director would not be the entire cart, but only the items for a specific request (which in the case of Ship Separately would be only a single item). Please contact our support if you need to get rates where you ship items separately, as Shipping Director's Packing would be needed.   (Similarly, Warehouses added in earlier nopCommerce introduced a Shipping Setting "Use Warehouse Location"; this could also cause multiple calls to Shipping Director.) 


In nopCommerce 3.90, they introduced ACL for roles (as per the release notes "Allow a store owner to manage access to plugins per customer role (ACL)"). So it can block SD, or block one of the other shipping provider plugins that SD is calling in an Option.  If you (your customers) are not getting the expected shipping methods, then be sure to check that you have not blocked them for the role.

In nopCommerce 3.90, they also combined shipping provider plugins FixedRate and ByWeight into a single "FixedOrByWeight".
When shipping rates are calculated, Shipping Director will throw an error if it sees either FixedRate or ByWeight in the configuration
Please check your configuration and make adjustments as needed.  In the Shipping.Director configuration, you should Edit the records to update Shipping.ByWeight to Shipping.FixedOrByWeight.  Similarly if you are using Shipping.FixedRate.  However, you can't now use both.  In general, you should be able to configure fixed rates right in the Shipping Director configuration. Contact us if you need help converting the Fixed Rates from the plugin into a Shipping Director configuration. (Export your configuration and send it to us). Also, if you were previously using Shipping.ByWeight and have adjusted it to Shipping.FixedOrByWeight, you should go to the configuration for the Shipping.FixedOrByWeight plugin and select "By Weight" (button in upper left of page).  Alternately, you can go to All Settings:  fixedorbyweightsettings.shippingbyweightenabled  - defaults to False, meaning use Fixed Rate, so change to True.

If upgrading - In Shipping Director for 4.00 and 4.10, the data base table was incorrectly named as ShippingDirectorRecord.  SD for 4.20 will recognize that and rename the table back to ShippingDirector.

In Shipping Director for 4.50, we introduced an 'experimental feature' - a new built-in variable that will send the $Debug tracing message to the Order Note: $SendTraceToOrderNote.
Both $Debug and $SendTraceToOrderNote must be set to true.  You can 'turn off' some tracing by setting $Debug to false/true as needed.  If $SendTraceToOrderNote is true at the end of the rules processing, then the tracing is saved in the Order Note.
Since $Debug must also be true, every rules processing will log in the System Log.  You should periodically purge those so that they don't take up too much space.  In the future, we may introduce a separate way to save the order note without having to also send the message to the log.

Thanks
