Integrating with SuiteCommerce Connector

About the ShipHawk SuiteCommerce Connector

The ShipHawk SuiteCommerce Connector allows your organization to use ShipHawk’s in-cart rating functionality with your SuiteCommerce website. By connecting your SuiteCommerce solution with the ShipHawk extension, your organization can ensure your customers are receiving the optimal shipping rate at the time of checkout.

The ShipHawk extension is built for NetSuite’s SuiteCommerce and SuiteCommerce Advanced solutions. The extension allows you to apply ShipHawk’s features to your SuiteCommerce solution. These features enable users to carry out their organization’s fulfillment needs.

To learn more about the features included with the SuiteCommerce ShipHawk Connector, refer to How the ShipHawk SuiteCommerce Connector Works.

Local Development Setup

Required Prerequisites

• An Integrated Development Environment (IDE) is required. Visual Studio Code is recommended.

• Ensure the latest version of Node.js is installed. If you have a higher version, downgrade to the required version.

“ShipHawk SCA Connector” Bundle Setup

1. Go to the TMS Netsuite Sca Connector repository, and clone it to your local machine.

2. Install the SuiteCloud CLI and use the SuiteCloud Development Framework to deploy scripts to your dev account.

3. From Visual Studio Code. Open a new terminal by navigating to Terminal > New Terminal

4. In your terminal, enter the following command:

npm install -g @oracle/suitecloud-cli

5. To check if SuiteCloud CLI was successfully installed, type in the command suitecloud. A list of all commands you can run after SuiteCloud CLI is installed will populate in the terminal.

6. Enter the following command to setup your account to use with SuiteCloud CLI:

suitecloud account:setup

7. Select browser-based authentication

8. Choose "Create a new authentication ID" if you don’t have one yet, or select an existing authID from the list below.

8. You will be prompted to enter a new authentication ID (auth ID). Enter any value that is clear and meaningful to you.

9. A new NetSuite browser window will populate and prompt you to log in to your account. Ensure you are logged into your account

10. Click Allow.

11. You have now established you are working with this NetSuite account from your IDE.

12. After making any changes, you need to deploy the modified files back to your NetSuite account.

13. Enter the following command in your terminal: suitecloud project:deploy

“ShipHawkSCExtension” Extension Setup

1. Log in to your NetSuite Dev account and install the ShipHawk SCA Connector bundle from the “ShipHawk Integration - 2017A V1.0” account by following the installation instructions.

2. Go to the Bundles list find the SuiteCommerce Extension Management bundle and remember the bundle ID.

3. Go to Documents > File > File Cabinet in NetSuite.

4. On the File Cabinet page, locate the SuiteBundles folder in the directory on the left side.

5. Inside the SuiteBundles folder, find the folder titled Bundle 521562 (specific to SuiteCommerce Extension Management).

6. Download the file named ExtensionDevelopmentTools-24.2.10.zip or the latest available version.

7. Locate the downloaded zip file in your Downloads folder.

8. Right-click on the zip file and select Extract All...

9. Move the unzipped folder to your work directory. You can rename it if you want.

10. Open ExtensionDevelopmentTools-24.2.10 via the IDE that you use.

11. The folder will populate on the left-hand sidebar.

12. Now you need to set up token-based authentication (TBA) for your site. To take advantage of this, complete the following steps:

    1. Create an integration record.

       

    2. In the Name field, enter a name for the integration record.

    3. In the State field, select Enabled.

    4. Check the Token-Based Authentication box.

    5. Check the TBA: Authorization Flow box.

    6. In the Callback URL field, enter: http://localhost:7777/tba.

    7. Clear the Authorization Code Grant box.

    8. Check the User Credentials box.

    9. Save the integration. Be sure to copy the consumer key/secret before closing the page.

    10. Paste the consumer key/secret in the .env file in your ExtensionDevelopmentTools-24.2.10 project.

13. Set up a development environment for your extension by running a series of commands in Visual Studio Code.

14. In Visual Studio Code, navigate to the Terminal tab. Select New Terminal.

15. In your terminal, enter the following command:

    npm install

16. After running the npm install command, you must ensure the gulp command is installed in your local directory. A list of available commands should populate in your terminal.

16. Enter the following command. This command extracts the related files (themes) from your SuiteCommerce Site

    gulp extension:fetch --to

17. You will be prompted  to Choose a saved token. You should opt to use a new token by selecting the New Token option at the bottom of the Choose a saved token list and press Enter.

18. You will be prompted to enter a new authentication ID (auth ID). Enter any value that is clear and meaningful to you.

19. After you input an (authID) in your IDE code editor, you will be redirected to NetSuite. NetSuite will be prompted to allow the application to access your account.

20. Click Allow

21. Navigate back to your terminal. You will then be prompted to select a website from the ‘Choose your website’ command. If there are multiple options, select the website you would like to add the extension to.

22. After you have made your selection, you will also be prompted to ‘Choose your domain’. Select the domain that corresponds with your SuiteCommerce site.

23. If there are multiple extensions, don’t select any of them just skip the step.

24. When you finish running the extension:fetch --to command, a new directory will populate inside your existing directory titled Workspace.

25. Copy the folder named ShipHawkSCExtension from the TMS Netsuite Sca Connector project located by path src/FileCabinet/SuiteScripts/ShipHawkSCExtension and Paste it to the Workspace directory.

26. Now you can add any changes to the ShipHawkSCExtension and deploy them to your account for testing.

27. Before you deploy the extension you need to change a version in the manifest.json file to the appropriate version of the current sprint. For instance, if the latest deployed version from the bundle is 4.0.1 and you work on a minor fix you need to update it to 4.0.2

28. To deploy the extension run the next command: gulp extension:deploy --to

29. You will be prompted to ‘Choose a saved token’. You can use the token created in step (17) or create a new one.

30. Select the website and domain that correspond with your SuiteCommerce site.

31. Verify that the following information appears on the list below:

    1. Vendor: (ShipHawk)

    2. Name: ShipHawk

    3. Fantasy Name: ShipHawk SCA Extension

Press Enter every time a new line appears.

32. Under ‘Selected supported products’, choose the SuiteCommerce Online option. This will upload the extension into your NetSuite account. 

33. Clear the target version from the next lines using the backspace (or delete).

34. Your extension will begin uploading to your NetSuite account. After the upload is complete, your extension will be available for activation.

35. You can confirm the connector was deployed to your NetSuite Account by navigating to Commerce > Extensions > Extension Manager. Click Edit on the target website that you selected. Then, click the Extensions tab in the Active Themes & Extensions page in NetSuite. If deployed correctly, you should see your connector on this page.

36. After testing your changes on the dev account Copy/Paste them to the TMS Netsuite Sca Connector.

Installation instructions (public)

Prerequisites

Before beginning the installation process, you must meet the prerequisites listed below. If your NetSuite account has SuiteCommerce installed, these prerequisites will likely already have been fulfilled.

The prerequisites for installing the ShipHawk SCA Connector are as follows:

• SuiteCommerce is installed on your NetSuite account and you have configured an associated  SuiteCommerce Domain. 

• Your role has the necessary permissions required to install and upload bundles to your NetSuite account

• The most recent version of bundles are listed as installed on the Installed Bundles List page:

  • SuiteCommerce Extension Management

  • SuiteCommerce Configuration

  • SuiteCommerce Base Theme

  • SuiteCommerce

  • ShipHawk

• When updating the ShipHawk bundle set the PREFERENCE to “Update Deployments“ for Shiphawk Shipping Method Map Suitelet

To install the bundle

1. Log into your NetSuite account. 

2. From the NetSuite menu at the top of the screen, select ​Customization > SuiteBundler > Search & Install Bundles.

3. The Search & Install Bundles screen is displayed. The ShipHawk SCA Connector bundle is displayed in the grid below.

4. Click on the appropriate ShipHawk SCA Connector link in the grid based on the account where you want to install it —Sandbox (548896) or Production (548895). The ShipHawk Bundle Details screen populates.

5. Click the Install button to begin the installation process for ShipHawk SCA Connector. A series of pop-up windows and prompts will populate.

6. Confirm all prompts.

Congratulations, you have installed the ShipHawk SCA Connector!

Troubleshooting:

If the ShipHawk SCA Connector is already installed on your account you might encounter the situation shown below. Then please select the Replace Existing Objects action while installing the bundle.

To activate the extantion

Though the ShipHawk SuiteCommerce Connector may be installed, it needs to be manually activated in NetSuite in order for it to display on your SuiteCommerce website.

1. Navigate to the Extension Manager page. From your NetSuite menu bar, click Commerce > Extensions > Extension Manager.

The Extension Manager screen appears, with a list of all your installed extensions.

2. Find your SuiteCommerce Domain and click Edit. This will take you to the Activate Themes and Extensions page.

3.  From the Activate Themes and Extensions page, click the Extensions tab. 

4.  Locate the ShipHawk SuiteCommerce Extension and select the Active Checkbox. 

5. Click the Activate button, located at either the top or bottom of the list.

To deactivate the extantion

1. Navigate to the Extension Manager page. From your NetSuite menu bar, click Commerce > Extensions > Extension Manager.

2. Find your SuiteCommerce Domain and click Edit. This will take you to the Activate Themes and Extensions page.

3.  From the Activate Themes and Extensions page, click the Extensions tab. 

4.  Locate the ShipHawk SuiteCommerce Extension and deselect the Active Checkbox. 

5. Click the Activate button (similar to how you would activate the extension), located at either the top or bottom of the list.

NetSuite will utilize the native Shipping Functionality when your connector becomes deactivated.

Troubleshooting:

If you opt to deactivate your SuiteCommerce Connector and it is still appearing on your SuiteCommerce site and Domain, you may need to clear your site’s cache in NetSuite for the change to take effect. This section will instruct you on how to do so:

1. Navigate to Commerce > Content Management > Cache Invalidation Requests > New.

2. You will be redirected to the Cache Invalidation Request pop-up window.

3. From here, select the Domain associated with your extension from the Available Domains field. Use the right and left arrows to the right of the field to move your Domain to the Selected Domains field, as demonstrated in the screenshot below:

4. Select the Clear cache for the whole domain option. Click Submit.

You have cleared your cache for your domain. This will update your domain with the ‘deactivated’ extension status.

Additional Settings

The last step in the installation process is to configure some additional settings in NetSuite.

 After you have successfully installed the bundle, navigate to Commerce > Website > Website list -> ‘Name of the website’ > Edit

1.  Ensure the ‘Scriptable Cart and Checkout’ checkbox is selected under the Preferences heading.

2. Ensure the related custom fields are exposed to your site. Navigate to Commerce > Websites > Configuration.

3. Select the Website and Domain you associated with your SuiteCommerce Connector from the fields. Click Configure.

4. From the Configuration screen, click the Advanced tab. Then click Custom Fields.

5. Under the Sales Order custom field add the following under Field ID:

   1. custbody_shiphawk_rate

   2. custbody_shiphawk_cart_rates

6. Click Save.

Ensuring Rates can be used at Checkout:

1. Navigate to Lists > Accounting > Shipping Items.

2. From the list, locate all Shipping Rates you want returned at the time of checkout. Repeat this for each Shipping Item necessary.

3. Click Edit.

4. Ensure the Display In Web Site checkbox is selected. If not, select the Display In Web Site checkbox and click Save.

5. Repeat this process for every shipping rate you want used at checkout.  

Troubleshooting: Cannot locate Connector from Extension Manager Page

If the connector you installed is not present on the Extension Manager page, it may be because there is an incorrect target version attached to the file. If this is the case, you can still find your connector in the SC ExtMech Extension page and clear the target version to fix this issue. 

To ensure your connector was deployed to your NetSuite account:

1. From the NetSuite search bar, enter: SC ExtMech Extension.

2. From the list of search results, locate and select: Page: SC ExtMech Extension.

You will be redirected to the SC ExtMech Extension List page.

3. Locate the ShipHawkSCEExtension record from the list. Click Edit to edit this record.

This will open an editable record of the ShipHawkSCExtension.

4. Locate the Target Version field in this record. 

5. If there is a target version present in this field, clear the target version.

6. Click Save to update the record.

7. If there was a target version on this field, this should resolve the error and you should now see the ShipHawk SCExtension populated on the Extension Manager page.

Customizations in customer installations (internal only)

A list of customers who have their own customizations for our extension (provided by Katoomi):

• stockcarsteel.com

• medstatsupplies.com

• primaryarms.com

• carrottop.com

• jeskehardware.com

Primary Arms and Carrot-Top had developers who made their own customizations to the extension.