The ShipHawk-Acumatica connector is a solution designed to allow users to install the ShipHawk app for Acumatica. The app is an Acumatica Certified Application (ACA), meaning it adheres to standards set for Acumatica integration and functionality. When the application is successfully installed and configured, ShipHawk is able to sync Acumatica shipments as orders in the ShipHawk platform and complete the order fulfillment process.
...
Communication between Acumatica and ShipHawk allows your organization to access ShipHawk services to fulfill shipments created in Acumatica.
This guide covers the following topics:
| Table of Contents |
|---|
Installing the Shiphawk Application
This chapter provides a broad outline of the steps necessary to install the ShipHawk Application in your Acumatica environment. Should you need to in the future, this chapter also outlines the steps required to update, unpublish, or delete the ShipHawk package from the Customization Projects page in Acumatica.
Installation Prerequisites
To install the ShipHawk Application in your instance of Acumatica, you must first ensure you have met the following requirements, listed below:
...
✔︎ Appropriate permissions enabled for the user importing the ShipHawk package
Terminology
Term | Definition |
App / Connector | The package that can be installed and loaded into Acumatica. It contains the code that enables integration and interaction between Acumatica and ShipHawk. |
Orders | The object in ShipHawk that represents an order. |
Shipments (ShipHawk) | The object in ShipHawk that represents a shipment. Shipments in ShipHawk are created automatically after an order is set to ship. |
Sales Orders | The object in Acumatica that represents an order. |
Shipments (Acumatica) | The object in Acumatica that represents a shipment. Users sync Shipments in Acumatica to ShipHawk as an Order. |
Installation Procedures
You may begin the installation process if you have reviewed the prerequisites and determined they have been met by your organization.
This section describes the process for manually importing and publishing the ShipHawk package to your Acumatica platform. You will also find instructions for uninstalling, upgrading, and deleting the application from Acumatica. Once you have successfully imported and published the ShipHawk application, you will still need to configure your ShipHawk workspace so that ShipHawk can communicate with your Acumatica platform to fulfill orders. These procedures are intended for your organization’s system administrator.
Importing ShipHawk package
To import the ShipHawk package into your Customization Projects page
Log in to Acumatica, navigate to Configuration> Customization > Customization Projects
The Customization Projects page will appear, with a list of the customization projects available for the current application instance.
Click the Import button in the form toolbar. A drop-down menu will appear.
Select Import New Project from the drop-down menu.
Select the Choose File button in the Open Package pop-up window.
Select the ShipHawk package file from your computer’s file manager.
Click Open
The selected package will display in the open package popup. Click the Upload button to upload the file. It may take a few moments to load on the screen.
If executed correctly, you will see the imported package in the grid.
To publish the imported package into Acumatica
Locate the ShipHawk package you imported to the Customization Projects page, displayed as a row in the grid.
Ensure the row containing the ShipHawk solution is selected.
Select the checkbox to the left of the Published column.
You can publish multiple packages by selecting the checkbox for each respective package.
Click the Publish button in the form toolbar. A drop-down menu will appear.
Select the ‘Publish to Multiple Tenants’ option from the menu.
A pop-up window will appear titled Publish to Multiple Tenants. From this window, select the Selected checkbox, located in the same row as the Tenant Name ‘ShipHawk’ .
Select the ‘Execute All Database Scripts’ checkbox. Then, click OK.
Following the Publish to Multiple Tenants pop-up, the Publish Customization pop-up will appear. When prompted, click Publish.
If the package is successfully published, the checkbox under the Published column will display as selected against the ShipHawk package in the Customization Projects grid.
To unpublish your solution, deselect the Published checkbox and click the Unpublish All button in the form toolbar.
Upgrading your ShipHawk Package
To upgrade your ShipHawk package in Acumatica
Log in to the Acumatica instance that contains the published ShipHawk solution.
Navigate back to the Customization projects page. Click Configuration> Customization > Customization Projects
The Customization Projects page will appear. This page should have the published ShipHawk solution displayed as a row in the grid.
Ensure the row containing the ShipHawk solution is selected.
From the form toolbar at the top of the grid, select the Import button. The Import drop-down menu will appear.
Select the ‘Replace Highlighted Project Content’ option from the drop-down menu.
Select the Choose File button from the Open Package pop-up window.
Locate and select the updated file from your Computer’s file manager.
Verify that the correct file appears in the Open Package pop-up. Click Upload.
Navigate back to the Custom Projects page and select the recently uploaded file.
Select both versions of the ShipHawk package.
Click on the Publish button, then select the Publish with Cleanup option.
If executed correctly, the new version of the ShipHawk package will have the Publish checkbox selected and the other version will be unselected.
Deleting your ShipHawk Package
If necessary, you can entirely remove the ShipHawk solution from your instance of Acumatica.
To delete your ShipHawk Package
Log in to the Acumatica instance that contains the ShipHawk solution.
Navigate back to the Customization projects page. Click Configuration > Customization > Customization Projects
The Customization Projects page will appear. This page should contain the ShipHawk solution.
If selected, clear the checkboxes for the ShipHawk package.
Click the Publish button located in the form toolbar. The Compilation pop-up window will appear.
Click Publish in the Compilation window.
Sequentially select and delete the rows with the solution packages unpublished. This can be done by highlighting the row containing the package, then clicking the X button in the toolbar to delete the row.
If executed correctly, you will no longer see the ShipHawk package in the Customization Projects grid.
Configuring the Shiphawk Workspace
After you have installed and published the ShipHawk application to your instance of Acumatica, you must set up your ShipHawk workspace in Acumatica and ensure the two solutions have successfully connected. The setup process is accomplished by using the ShipHawk Setup and ShipHawk Mapping screens in Acumatica. Both screens are described in detail below.
...
IMPORTANT: To avoid any issues, be sure to complete the steps described in this section as part of the installation process.
ShipHawk Setup Screen
This section describes how to configure the ShipHawk Setup screen in Acumatica, and provides definitions for each of the fields in the screen. This screen contains settings you can modify to alter the way ShipHawk processes orders from Acumatica. You can also use this screen to test the connection between both solutions.
To update the ShipHawk Setup screen
If your ShipHawk package was installed correctly, an icon for the ShipHawk application will appear on the More Items menu.
The icon may also appear below the More Items menu, depending on your display size.
Navigate to the ShipHawk Setup Screen by clicking More Items > ShipHawk > Setup Screens > ShipHawk Setup.
You can modify the different fields in the ShipHawk Setup screen to better align with your organization’s needs. The fields on this screen are defined in the table below:
ShipHawk Setup Screen Field Definitions
IMPORTANT: Entering the API URL and API Key is required during the installation process. If you do not enter this information, the integration can stop working until those fields are populated.
This screen includes fields for SHIPHAWK SETUP, PURGE LOG DETAILS, and IMPORT SHIPMENTS SETTINGS.
...
Allow Delete Sales Order/Shipment | If this field is enabled it means that a user can delete the sales orders that are already synced from Acumatica to ShipHawk, and can also delete shipments in the ShipHawk portal. |
Syncing Entity | This drop-down allows you to select whether an order, shipment, or other entity is being synced to ShipHawk at any given time. You can return to this field and manually change the syncing option based on your business requirements at the time. |
Days To Keep | Users can provide a number of days in the field to keep day logs in the ShipHawk Log Details screen. For instance, if a user enters the number 7, that means log details are purged every 7 days (or once a week). |
API URL & API Key | Users retrieve this information from the ShipHawk platform connected to their Acumatica instance. The API key is used to test the connection between ShipHawk and Acumatica. This process is described in the following section. |
Update Freight Cost and Freight Price Fields | Select this option to have ShipHawk write back the freight cost and freight price data to Acumatica. |
Update Control Quantity Field | Select this option to have ShipHawk write back the control quantity data to Acumatica. |
To have ShipHawk write back the freight cost, freight price, and controlled quantity data to Acumatica, be sure to select the Update Freight Cost and Freight Price Fields option and the Update Control Quantity Field option.
To test your connection using your API Key
Log in to your ShipHawk PlatformTMS platform.
On the right side of ShipHawk’s top menu bar, click on the Settings
icon and select the Settings option from the dropdown below. The Settings screen appears.From the left-hand side menu, select the Developer API option under Integrations. The API Keys screen will appear.
Your API Key should appear in a card on the screen. You can click the Copy button to the right of the key to copy the API Key to your clipboard. The URL will also be displayed under the key.
Navigate back to the ShipHawk Setup screen in Acumatica.
Paste the API Key & API Url details you copied from the API Keys screen in the ShipHawk platform to their respective fields in Acumatica.
Click the Test Connection From the main menu, choose ⚙️ > Settings > Developer API.
Get the API URL: On the Developer API screen, the field Use this URL for all API integrations provides the API URL.
Get the API Key: To create a new API key, click CREATE API KEY. In the pop-up, enter a descriptive name for the API key.
In Acumatica, go to the ShipHawk Setup screen.
Paste the API URL and API Key details you copied from the ShipHawk TMS platform to their respective fields in Acumatica.
| Note |
|---|
Entering the API URL and API Key is required during the installation process. If you do not enter this information, the integration can stop working until those fields are populated. |
...
Click the TEST CONNECTION button located in the form toolbar. If your connection is successful a green checkmark will appear to the right of this button.
...
If your connection is successful, you will get the following message:
Finally, on the Acumatica ShipHawk Setup screen, in WEBHOOK INTEGRATIONS, click CREATE WEBHOOK.
ShipHawk Mapping Screen
Field mapping allows ShipHawk to extract data from specific Acumatica fields back to the ShipHawk platform. When the ShipHawk application is installed to your instance of Acumatica, this process is done automatically. However, you can use the ShipHawk Mapping screen to manually alter which fields in Acumatic map back to which specific fields in ShipHawk. This section describes how to override native field mappings using the ShipHawk Mapping screen.
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
It is important to note this is a one-time configuration process. Once changes are made they are irreversible. If you require assistance mapping the fields to your specifications, you can contact your ShipHawk Implementation manager. |
To update the ShipHawk Mapping screen
Navigate to the ShipHawk Mapping Screen by clicking More Items >ShipHawk > SetupScreens > ShipHawkMapping.
The ShipHawk Mapping screen will appear. The screen contains a grid that specifies which fields in ShipHawk map to which fields in Acumatica.
Click on the Mapping Entity drop-down at the top of the grid. Select whether you would like to modify the Order or Shipment mapped fields.
The grid will populate with the default field mappings of the entity you selected. To alter the default field mapping configuration, you must manually alter the fields in the grid.
The ShipHawk Object and ShipHawk Field columns will appear as read-only, meaning they cannot be modified. You can still alter field mappings by modifying fields under the Acumatica View Name and Acumatica Field columns in the grid.
Double-click a record under the Acumatica View Name or Acumatica Field column to alter it. A drop-down menu will appear prompting you to make a different selection.
For example, if you want to alter the Acumatica Field that maps back to the ShipHawk Field ‘phone_number’:
Locate the row the ShipHawk field is in.
Double-click the Acumatica Field that corresponds to the ShipHawk Field ‘phone_number’, which would be Phone1.
Make a different selection from the drop down.
Repeat this process for other fields in Acumatica you wish to change.
If you made any changes to the grid, you can click the Save icon in the form toolbar to save them.
You have configured the Setup Screens in Acumatica to better align with your organization’s shipping process.
Exporting Shipments To ShipHawk
Now that you have confirmed a connection between ShipHawk and Acumatica, you can manually create shipments in Acumatica to be exported to ShipHawk as orders.
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This section requires that you enter test data in the Acumatica system in order to verify that data is correctly transferred between your Acumatica and ShipHawk accounts. You will need to enter data in Acumatica that does not interfere with the rest of the processes in the system. |
To create a shipment to export in Acumatica
Before you begin creating sales orders, ensure the Syncing Entity field in the ShipHawk Setup screen is set to Order.
Navigate to the Sales Order screen. From the menu, click Sales Orders > New Sales Order. A blank sales order form will appear.
In the Sales Order page, Enter an order number in the Order No: field. You can use the lookup icon in the field to select an existing order that has not yet been shipped.
In the Line Details tab, verify there are multiple stock items associated with the sales order.
You can use the Add Items button at the top of the grid to add stock items if the Line Details grid is empty.
Click the Save icon in the header to save your sales order.
After you have successfully saved your sales order with multiple stock items, you must create a shipment.Click the Create Shipment button on the form toolbar of the Sales Order page. Verify the details in the Specify Shipment Parameters pop-up window. You will be redirected to the Shipments screen.
Verify that the ShipHawk Shipment Details section is completely blank by default.
Click on the ShipHawk Actions button in the header. Select ‘Export to ShipHawk’ from the drop-down.
...
You have exported the shipment you created in Acumatica to ShipHawk.
Verify the shipment was exported to ShipHawk as an Order
Log in to your ShipHawk account. Confirm the account you are using is the same account that is linked to Acumatica.
Click the Orders button in the top menu bar. This will bring you to the Orders page.
If your shipment was exported successfully, your shipment number should appear as an Order number on the Orders page.
You can verify this by entering the order number from the Acumatica Sales Order page into the search box on the ShipHawk Orders page.
Click on the Order #.
In the expanded Order page, verify the details of your shipment populated correctly:
Stock item details
Warehouse
Shipping address
Product dimensions
You can click on the Print Labels button in the Order Details page to generate the labels associated with your order.
Click Ship. Your Order details page will be updated after you opt to ship your order.
Click on the Shipment number, located on the title card under the Order number. This will redirect you to the Shipment page.
In the Shipment page, locate the Status field.
Set the Shipment status to Confirmed.
Confirm the shipment in Acumatica
Navigate back to the Shipments screen in Acumatica.
The fields in the ShipHawk Shipment Details section should populate the following information accordingly:
Sent to ShipHawk checkbox is selected.
Last Sync Date is no longer blank.
Click the ShipHawk Actions button on the form toolbar. Select the Get Shipment Confirmation action from the drop-down.
Click on the ShipHawk Info tab near the grid at the bottom of the Shipments page. The data from the ShipHawk Order details screen should be displayed in the grid below the tab.
Click on the Packages tab to the right of the ShipHawk Info tab. The shipment details you confirmed in ShipHawk, along with the order tracking number, should be displayed in the grid below the tab.
...
details you confirmed in ShipHawk, along with the order tracking number, should be displayed in the grid below the tab.
...
Webhooks for Shipment Data
For performance, webhooks are used to get the shipment information rather than API calls.
(Note that if an Acumatica user working on a Shipment record selects Actions > Get Shipment Confirmation, an API call is still used on a one-time basis to get the information immediately.)
To configure the webhook, you first create the webhook URL in Acumatica and then set up the webhook in ShipHawk.
Creating Webhook URL in Acumatica
To create a webhook URL in Acumatica:
On the Acumatica user interface, open the Webhooks page.
In the Webhook Name field, enter a name for the ShipHawk webhook, such as “SHWebook”.
Make sure the Active checkbox is selected.
In the Implementation Class field, enter the implementation class, such as “ShipHawk SHWKWebhookHander”.
Upon saving, a URL is generated and displayed in the URL field:
Copy this URL so that you can use it to set up the webhook in ShipHawk.
| Note |
|---|
IMPORTANT: If the webhook URL has spaces in it (for instance, because the Acumatica webhook URL is partially sourced from the tenant name), the webhook URL that you set up in ShipHawk MUST have %20 in place of the space in the URL. |
Setting Up Webhook in ShipHawk
To set up the webhook in ShipHawk:
On the ShipHawk user interface, select Settings (gear icon) > Settings > Webhooks to view the Webhooks Management page.
Select Actions > Create New Webhook:
In the Create a new webhook window, in the Callback URL field at the top, paste the URL you copied from Acumatica.
NOTE: Make sure Use Basic Authentication is not selected.Under Events, select the shipment.create_from_order event checkbox.
Click Create to save the new webhook setting.
Now, when a shipment is completed, the webhook will be triggered and the response will be sent to Acumatica.
On the Acumatica user interface, on the Webhooks page for the ShipHawk webhook, you can see the activity in the REQUEST HISTORY tab. You can click on a POST request to view the Request Details window.
Additional ShipHawk Screens
In addition to the setup screens, the ShipHawk app contains several other screens that allow you to fully integrate your ShipHawk and Acumatica platforms. This section describes how and when to use these additional screens.
Process Screens
There are two process screens included in the ShipHawk application. These screens allow you to perform bulk functions, such as mass import and export shipments to ShipHawk.
Send Orders/Shipments To ShipHawk screen
The Send Orders/Shipments To ShipHawk screen allows a user to manually send shipments created in Acumatica, one by one. This screen also allows users to set a scheduler to automatically sync shipments as Orders to ShipHawk. Both methods for sending shipments are described below:
Before you begin creating Shipments, ensure the Syncing Entity field in the ShipHawk Setup screen is set to Shipment.
In Acumatica, navigate to Sales Orders > New Sales Order.
Follow the instructions for creating a new sales order and shipment as detailed in steps 2-5 of the ‘To create a shipment to export in Acumatica:’ section of this guide.
Before saving your shipment in the Shipments screen, ensure the Status field is set to On Hold. When a shipment is set to On Hold, it can be exported from the Send Orders/Shipments To ShipHawk screen.
Navigate back to the Send Orders/Shipments to ShipHawk screen by clicking Other Items > ShipHawk > Send Orders/Shipments To ShipHawk. You should see the shipment you placed on hold in the grid.
If you select the checkbox in the same row as the shipment, and click the Process button, the shipment will be exported to ShipHawk from this screen. You can also send shipments in bulk by clicking the Process All button at the top of the grid to send every shipment displayed on the page.
You can log in ShipHawk and verify the shipments were exported by going to the Orders screen in ShipHawk and cross referencing order numbers with the shipment number in Acumatica.
To set up an Automation Schedule for syncing orders
From the Send Orders/Shipments To ShipHawk. Screen, click the Timer icon located in the form toolbar.
The Schedules drop-down will appear. Click Add to add a new scheduler.
Clicking Add will take you to the Automation Schedules pop-up window. Here you can specify an interval period for how often orders are automatically sent to ShipHawk.
From the Automation Schedules window, enter ‘Automatically Send New Orders to ShipHawk’in the Description field.
Click the Schedule tab at the bottom of the screen.
You can set the following parameters for your interval:
Schedule Type: Daily
Starts On: 8:00 AM
Stops On: 9:00 PM
Every: 00:15 secondsminutes
You can alter the execution time if you find you do not need your orders to sync so frequently.
Click the Save icon in the form toolbar.
You have created a schedule that automatically sends orders to ShipHawk during specified periods of time.
Import ShipHawk Confirmed Shipments screen
From the Import ShipHawk Confirmed Shipments screen. Users can manually import Shipments that have already been confirmed in ShipHawk to Acumatica.
Log in to your ShipHawk account. Confirm the account you are using is the same account that is linked to Acumatica.
Click the Shipments button in the top menu bar. This will bring you to the Shipments page.
Verify you have a shipment with Confirmed status by setting the Group By filter to Status.
A list of Shipments should appear under the Confirmed group in the Shipments grid.
If no shipments appear, you can manually change a shipment status to Confirmed by selecting a shipment from the grid and manually changing the status in the Shipment details page.
Return to Acumatica, navigate to Other Items > ShipHawk > Import ShipHawk Confirmed Shipments. The Import ShipHawk Confirmed Shipments screen will appear.
The grid should contain all the Confirmed but not Shipped shipments you verified in the ShipHawk Shipments page.
To import a shipment into Acumatica, select the checkbox in the same row as the shipment and click the Process button. You can also perform a bulk import by clicking the Process All button.
If you click the Timer icon located to the right of the Process All button, you can schedule the shipments on the grid to be imported automatically.
A processing pop-up window will appear if you opt to import the shipment. When the process is complete it will be confirmed in the window.
Log Details Screen
An additional function supported by the ShipHawk application is the ability to track the API interactions between the ShipHawk-Acumatica connector and ShipHawk’s API. Visibility regarding this process is provided by the ShipHawk Log Details screen in Acumatica.
To access the ShipHawk Log Details screen
In Acumatica, navigate to Other Items > ShipHawk > ShipHawk Log Details
The API interactions should be displayed as rows in the grid on the ShipHawk Log Details screen.
You can filter the type of interaction by selecting an Entity Type at the top of the grid.
You can view the API Request and API Response as columns in the grid.
When a user exports a shipment from Acumatica to ShipHawk, a new record should display as an Export Entity type.
You can view the Request from ShipHawk and Response from Acumatica in this grid in the API Request and API Response columns.
You can also view whether an API interaction was successful in the Success or Error Msg column in the same grid.
...