This post was contributed by EYEMAGINE, an award-winning full-service marketing agency that creates relationship marketing and ecommerce programs to help businesses grow customers, revenue, and profit.
Integrating with ShipStation results in better automation, more efficient operations, and new business opportunities, but setting up an integration can be complicated. Luckily, our friends at EYEMAGINE have outlined the four critical steps needed to successfully integrate with ShipStation below.
1. Start with a Plan
As any engineering team worth their salt knows, the first step is planning—one wrong character can break an entire program.
Time spent planning the ShipStation integration is the most valuable use of time on the entire effort. A good plan will uncover potential hazards and obstacles in any software project, especially when connecting two softwares through integration. There are three main helpful models that are outlined below:
Data Flow Diagrams
Use a standard format for creating a data flow diagram to identify every piece of data that will be sent across platforms in order to avoid surprises. When integrating systems, the dependencies of each data type are easy to implement when they have been included in a plan. Being surprised by an unknown data relationship can introduce significant delays and workarounds that harm maintainability.
First, start with the big chunks and work your way into the details. For example, start with the highest level of data classifications (if we are working with vehicles, start with the vehicle type, like car, truck, motorcycle, etc.) and then identify sub-types (i.e., sedans, coupes, convertibles, etc.) or dependencies (i.e., tires, steering wheels, windshields, etc.).
UML Sequence diagrams help show the chronological order of the integration application. Get this right and the code exercise should be a breeze—cut corners here and plan on late nights with Costco-sized palettes of merchandise.
Ensure that every piece of data from the data flow diagrams are represented in the sequence diagram.
Design the database according to the data that has been identified. Consider standard database practice like unique identifiers and timestamps. Always maintain a local unique identifier, like an ID field rather than trusting the data from one of the platforms being integrated to manage uniqueness.
Know that platforms change, scale, and release new versions. Plan your data schema to be scalable as adding fields and entities should be non-disruptive.
When one of the platforms being integrated deprecates an API or changes a response dataset, the integration should be adaptable enough to allow the original integration author to update the application while following the original architecture.
“Expect the best, plan for the worst, and prepare to be surprised.”
– Dennis Waitley
A successful integration between two platforms will handle unexpected data gracefully. When data from one platform is not acceptable to another platform, the integration software is expected to handle the anomaly and continue operations.
A single bad character should not halt operations. It will have to be reported and the integration must continue to the next operation.
When building an integration, the application will most likely run on a timer like cron. On every run, new data should be fetched while bad data is flagged and reported.
Network Connection Problems
Networks have come a long way since the Internet was born. As networks improve and ISPs roll out new technology, we see hiccups. It is not uncommon for a misconfigured network appliance (firewall, router, switch, DNS server, etc.) to prevent network data from passing through.
The integration software application should expect such problems and handle this case gracefully. In the event of a network error, it is common to leave the state of the data as it was before the attempt to integrate was made and try again on the next run, while reporting an error.
Error Messages and Notifications
Good readable error messages are always helpful to engineering teams. Recording errors in large log files is a bare minimum. Recording error messages in a lookup table for future reference is ideal.
Send error notifications via email to users that opted in and administrators. If you want a real pat on the back, send a daily digest email with a link to a password-protected interface with a history of actions and errors.
Handling Bad Data
The age-old expression about data is: “garbage in, garbage out.”
Expect bad data to come from one platform and be rejected by the other. When reporting errors, record as much detail as possible to help trace the source and patch the application for maintainability.
Handling Unexpected Characters
Select a character encoding that works with both platforms and use it consistently throughout the application. Small character variations between platforms are common.
Avoid creating an integration in a vacuum. Invite beta users to participate in giving feedback, and offer the users something in exchange for their honest responses.
Beta users will give you critical feedback that could set you apart from the competition. Do not wait until the integration is public to get initial reaction from users; it could get ugly. Launch the product with many happy users.
Support is a critical factor for any integration. Because of this, amounts of effort have gone into software projects that die because of poor customer and/or technical support.
Staffing a support team with knowledgeable, qualified staff is critical for good customer satisfaction. Plan on first-tier support questions all the way to bug reporting by customers, and definitely be prepared to receive it all, with a smile.
In summary, building an integration with ShipStation requires good planning, knowledge of APIs, and rigorous testing. As long as you follow the four main steps to setting up an integration, you should be golden, but there are plenty of resources available (like EYEMAGINE) if you need help.