While many MoversSuite processes interact with Standard XML Pipeline internally, you can customize it to directly communicate with additional external applications and processes. Use the following steps as a guide to create your own connection to the Standard XML Pipeline. There is also a Standard XML Pipeline Example topic to assist you.
The following table describes the steps needed in MoversSuite to support importing of Standard XML Pipeline files into MoversSuite.
|
Step |
Description | |||||||||||||||||||||||
|
1 |
Create an interface that connects MoversSuite to an external system. Use the XML Interface Setup to define one or more interfaces. The interfaces are referenced by other setup areas.
The XML Interface Setup allows you to also define multiple interfaces and allows you to assign specific van lines and/or branches to them, if desired. | |||||||||||||||||||||||
|
2 |
Define an XML System Setup record for your interface or interfaces. XML System Setup records allow you to set options needed to support your integration as well as to establish data types that determine the type of information that is exchanged through the pipeline.
XML System Option The XML System Option available vary between each interface and many related to a specific interface, i.e., SIRVA and UniGroup. These options are programmed into the application as needed. Therefore, any option currently not available may need to be coded into the software for use with the Standard XML Pipeline.
Refer to XML System Option for a complete list of system options currently in use.
XML System Data Types XML System Data Types are pre-defined values and are used to instruct MoversSuite on the type of data being imported, such as “Order Information” for the basic order data. Valid data types include Documents, Notes, Order Information, Rating, and Statement. Refer to XML System Setup for more information on these options and types and other settings available.
For specific information on a particular defined setup, refer to the following links: Atlas Integration Setup and Administration EasyDPS Integration Setup and Administration Pass Thru Connector Setup and Administration SIRVA QLAB Integration Setup and Administration UniGroup Quotes to Go Setup and Administration XML System Data Type Mappings (UniGroup)
| |||||||||||||||||||||||
|
3 |
If needed, link MoversSuite to external codes established for the interface or interfaces to various supported processes in MoversSuite. If your requests include container codes defined on the external interface, then link them to MoversSuite containers within XML Item Code Setup. When the import request is processed, MoversSuite creates necessary containers based on defined External Code values for the particular interface.
The following is a list of MoversSuite setup areas that can be linked to codes supported by external interfaces. In most of these setup areas, set the External Code as the value defined for a particular interface (typically found within the Interface Item section within the setup). See Third Party Application Setup and Administration for a complete list of setup areas that affect external integrations.
Note: Link van line and branches to an interface through the XML Interface Setup.
Importing and Validating Personnel and Personnel Data
To import and validate a Driver from an external system, you must have the Auto Dispatching enabled and the Hauling Agent associated to the order (Agents tab) must be a Sister Agent (refer to Agent Setup). An unmatched driver returns an error and halts processing. When driver is matched but auto-dispatching is off, then driver data is not validated and an error is logged (Third Party Application Error Management).
To import and validate a Coordinator, Logistics Coordinator, Revenue Clerk, or Salesperson, the Booking Agent associated to the order (Agents tab) must be a Sister Agent (refer to Agent Setup).
To import and validate an OA Coordinator (maps to Transportation Coordinator) or OA Surveyor, the Origin Agent associated to the order (Agents tab) must be a Sister Agent (refer to Agent Setup). (7515)
| |||||||||||||||||||||||
|
4 |
Generate XML schema that is compliant with MoversSuite. Reference the appropriate schema document titled InternalImport.xsd to create your XML import files. Click the following link to download the latest schema: XML Internal Import Schema. You can create XML files that perform one of four requests to add or update an order or estimate in MoversSuite.
STANDARD XML PIPELINE REQUESTS Provide one of the following attributes within the MSS:Order declaration.
UPDATE AN ORDER Set the Orders.PriKey within the OrderID attribute within the <MSS:Order> element.
UPDATE OR ADD AN ORDER Set all of the following attributes within the <MSS:Order> element for the MoversSuite order. They must match an existing order for an update or be unique to have an order created. ExternalVanlineCode (External Code assigned to the Van Line Item within XML Interface Setup) OrderSeg PSeg OSeg SSeg
Example of an “Update or Add an Order” request: <MSS:Order xsi:schemaLocation="" OrderSeg="XX12345" PSeg="" OSeg="" SSeg="" EstimateNo="" ExternalVanlineCode="X" xmlns:MSS="MssXsd-InternalImport.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
UPDATE OR ADD AN ESTIMATE Set the EstimateNo attribute within the <MSS:Order> element. If the EstimateNo matches one defined, then the record in MoversSuite is updated. If there is no match, then a new sales lead/estimate is created.
ADD A NEW ORDER Set the <MSS:ExternalID> value within the <MSS:Order> element to a unique value.
When adding a record to MoversSuite, a branch must be provided along with a valid booking agent, origin agent, hauling agent, or destination agent must be supplied. Of these, at least one must be a Sister Agent of the branch assigned to the order (see Branch Setup).
XML SCHEMA FORMATTING Listed here are requirements when creating XML files to work within the Standard XML Pipeline. •XML must be UTF-8 encoded. UTF-16 encoding will cause errors. •The MSS: namespace must be on all element names. •The XML must include <MSS:ExternalApplication>[ External System from XML System Setup ]</MSS:ExternalApplication>. •One of the standard requests (listed above) must be provided. •The xsi:nil attribute should be set to “1” on any element marked in the schema as nillable=”true”, if there is no data for that element, i.e. data value is null, and the XML intends to make the file null in the database. If there is data then the xsi:nil attribute is ignored. For example, if no Origin Agent will be set for the order, then OrgAgent elements would appear similar to the following: <MSS:OrgAgent xsi:nil=”1” /> <MSS:OrgAgentCode xsi:nil=”1” />
The following is an example of a correct element setting to set an agent with an Agent ID of “00001” that links to a Van Line Code of “U” (which must be assigned to the agent and to the interface). <MSS:OrgAgent>00001</MSS:OrgAgent> <MSS:OrgAgentCode>U</MSS:OrgAgentCode> •Provide elements in the XML that should be set or modified in MoversSuite. Providing empty elements (especially those with the xsi:nil=”1” attribute set) may clear out any existing data for that field.
| |||||||||||||||||||||||
|
5 |
Test the XML file by executing the XmlImportProcessCompleteOrder stored procedure by passing in the XML file as text. The stored procedure returns an error code through the @outOrderErrorCode parameter and returns a status code through the @outOrderStatusCode parameter.
ERROR CODES A @outOrderErrorCode of zero (0) indicates a successful call. All other values indicate an error that can be viewed by matching the code to the ErrorCode.ECPriKey field in the MoversSuite database and viewing what corresponds to the Description.
Example: SELECT [ECPriKey] ,[Description] ,[spName] ,[LogLevelFID] FROM [MoversSuite2].[dbo].[ErrorCode] WHERE ECPriKey = '17'
Additionally, errors are recorded to the third party error log, which includes the contents of the XML itself. This log is stored within the XmlImportError table and can be found by searching based on the OrderFID or XmlID passed, or OrderFID on this table. The contents of the XML list within the XMLData value. MoversSuite also manages these types of errors through the Third Party Application Error Management screen.
Example: SELECT [XmlImportErrorID] ,[DataDescription] ,[DateDownloaded] ,[ErrorCodeFID] ,[XmlID] ,[XMLData] ,[XmlSystemDataTypeMapFID] ,[OrderFID] ,[XmlImportHistoryFID] FROM [MoversSuite2].[dbo].[XmlImportError] WHERE OrderFID LIKE '59020209'
If the error is outside of the XML data, such as an incomplete mapping setup or the XML for a new order request is missing the Sister Agent, then you can make corrections as needed and reprocess the same XML file through the Third Party Application Error Management screen.
STATUS CODES The XmlImportProcessCompleteOrder stored procedure returns the following status code values:
|