COMMANDbatch. VLink COMMANDbatch Interface Setup & Operation. Last Updated 3/16/16 COMMANDbatch V & Later

Transcription

1 COMMANDbatch VLink COMMANDbatch Interface Setup & Operation Last Updated 3/16/16 COMMANDbatch V & Later

2 Command Alkon Incorporated. All rights reserved. The contents of this document are for informational purposes only and are subject to change without notice. Command Alkon Incorporated ("CAI") may, without notice, modify its products in a way that affects the information contained in this publication. CAI HEREBY DISCLAIMS ALL REPRESENTATIONS OR WARRANTIES EITHER EXPRESSED OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT, OR FITNESS FOR A PARTICULAR PURPOSE. In no event will CAI be liable for any direct, indirect, or consequential damages arising out of the use of, inability to use, or implementation of any information contained in this publication, even if CAI has been advised of the possibility of such damages, or for any claim by any other party. The information contained herein is subject to change without notice and may contain inaccuracies or errors. CAI assumes no responsibility for any errors that may appear in this document. This publication is intended only for the direct benefit of authorized users of CAI products. This publication may not be used for any purposes other than those for which it is provided, and it is subject to the terms of the applicable software license or subscription agreement. This publication and the information disclosed herein is the property of CAI, and, except for rights granted by written consent, may not be disclosed, disseminated, or duplicated in whole or in part. Command Alkon Incorporated 1800 International Park Drive, Suite 400 Birmingham, AL (205) Main Customer Support Phone Number: 1 (800) COMMANDseries (and the names of its components, such as COMMANDconcrete and COMMANDnetwork), Spectrum, Eagle, and COMMANDbatch are registered trademarks of Command Alkon Incorporated. All rights reserved. Microsoft and Windows are trademarks of Microsoft Corporation. Other names may be trademarks of their respective owners. 2 3/16/16

3 Contents Contents... 3 Introduction... 4 Purpose...4 Audience...4 Revision Summary...4 VLink COMMANDbatch Interface... 6 Prerequisite Software...7 COMMANDbatch Configuration...8 EDX Server Installation EDX Gateway Configuration SmartEDX Installer (Install EDX Client and CMDbatch Plugin) Troubleshooting No Messages in EDX Log Viewer No Transaction Profile Database Connectivity Issues Error Codes /16/16 3

4 Introduction Topics in This Section Purpose Audience Revision Summary Purpose This guide explains how to configure COMMANDbatch and the EDX Gateway so that mix data can be extracted from batching systems for use by third party systems (such as the Verifi system). Audience This guide should only be used by Command Alkon installation and service personnel, or plant/management personnel specifically authorized to configure COMMANDbatch. Revision Summary Date CMDbatch Version Revision Apr. 3, Document created. Apr. 25, Minor revisions per QA review. Apr. 30, Added samples of XML packest for ShipmentSummary and ProductionPerformance. Added a Troubleshooting section. May 23, Removed XML samples from the document. Jun. 3, Minor revision to overview. Jul. 2, Revised EDX installation sections. Jul. 16, Changed name of manual to VLink COMMANDbatch Interface Setup Guide. Removed all instances of Verifi except for those used in screen shots and folder paths. Aug. 6, Revised procedures for configuring the EDX Gateway for EDX V Sep. 10, Added a table of error codes to Troubleshooting section. 4 3/16/16

5 Sep. 23, Removed section on configuring the COMMANDbatch Plugin because the Publish Scope functionality now takes care of this. Added notes to the Prerequisite Software section regarding software requirements when the VLink interface is installed on systems that are currently running CPM. Feb. 3, Corrected screen example of EDX Configuration form to show fewer Outbound Data options. Added a note stating that the Publish Scope box should not be checked for systems currently receiving tickets via CPM. May 6, Added section on troubleshooting database connectivity issues. Jul. 17, Updated cover/title page. Aug. 24, Replaced sections on EDX Client and CMDbatch Plugin installation with a simpler installation procedure that automatically installs both the EDX Client and the CMDbatch Plugin. Aug. 25, Removed references to Windows XP. Feb. 11, Revised the section on the smartedx installer for EDX v Mar. 16, Revised the section on the smartedx installer for EDX v /16/16 5

6 VLink COMMANDbatch Interface The VLink COMMANDbatch Interface extracts ticket and mix design data from dispatch and local tickets and transmits this data over a secure connection (via Command Alkon's EDX Gateway) to a cloud server which makes the data available to third party systems (such as the Verifi system which uses the data to calculate slump for mixes in concrete trucks). Data Flow Refer to the diagram above. Whenever a load is started, ticket and mix design data is sent in a ShipmentSchedule XML message. Additional ShipmentSchedule messages can be sent to communicate truck change information and the actual ticket number. The truck code can be changed until the ticket is printed. The third party system receives and processes the ShipmentSchedule message and returns a 204 response code if there are no issues with the message. If there is an issue processing the message, a 200 response code is sent, along with a BOD Response message providing details of the issue. Refer to the diagram above. A ProductionPerformance message is sent to the third party system whenever a load is completed or cancelled. The message contains data for the Max Water Allowed calculation, along with relevant status information that the third party system needs to complete the request sent in the associated ShipmentSchedule message. The third party system receives and processes the ProductionPerformance message and returns a 204 response code if there are no issues with the message. If there is an issue processing the 6 3/16/16

7 message, a 200 response code is sent, along with a BOD Response message providing details of the issue. IMPORTANT - PLEASE READ!! If the VLink interface is being installed on a system that is currently running CPM, the following software must be upgraded (or left alone) as described: The current EDX Server must be upgraded to (installs the new Protocol Bridge / Gateway functionality). COMMANDbatch must be upgraded to the latest GA version. The COMMANDbatch CPM Plugin must be upgraded to latest GA version. The EDX Client on the COMMANDbatch PC must be upgraded to version COMMANDseries, the COMMANDseries Plugin, and the EDX Client versions can remain at their current versions. Important! The COMMANDseries V2 Plugin does not support EDX 3.2.7, so its EDX Client version needs to remain at (or whichever version is currently installed). The EDX Server is backward compatible so that older EDX Client versions can still communicate with newer Server versions. EXCEPTION: When the COMMANDseries Plugin, EDX Client, and EDX Server are all running on the same machine, the EDX Server should be moved to another machine. Prerequisite Software COMMANDbatch or later Microsoft.NET 4.0 EDX or later COMMANDbatch Plugin SP4 or later 3/16/16 7

8 COMMANDbatch Configuration 1. Login to COMMANDbatch and open the EDX Configuration form. 2. On the Configuration tab. a) Check the Enabled box. b) Set all Inbound Data values to Ignore. 3. On the Interfaces tab, check the Publish Scope option. Note: When Publish Scope is checked, the Plant Code on the Plants form must be set to the Unique Plant Code prior to Plugin Installation. Important! If the system currently receives tickets via CPM, DO NOT check the Publish Scope box. 4. On the Behavior tab, check the Enable Alerts box to allow error messages to be presented to the Batch Operator. 8 3/16/16

9 Optional: To filter which error messages will be presented to the operator, open the COMMANDbatchPluginCPM.dll.config file and in the "ErrorFilter" section un-comment out the errors that you DO NOT want displayed. By default, all Error Codes are commented out as shown below and will be displayed. <ErrorFilter> <!-- <ErrorCode key="notauthorized" value="401" /> <ErrorCode key="notfound" value="404" /> <ErrorCode key="badrequest" value="400" /> <ErrorCode key="servererror" value="500" /> <ErrorCode key="unknownerror" value="2901" /> <ErrorCode key="itemnotfound" value="2902" /> <ErrorCode key="itemalreadyexists" value="2904" /> <ErrorCode key="uomerror" value="2908" /> <ErrorCode key="invalidxml" value="2909" /> --> </ErrorFilter> 5. Save your changes to the EDX Configuration form. 6. Once EDX is enabled, Require Reconciliation is automatically turned on. Unless the customer wants to use this feature, go to the Rules tab of the System Parameters form and disable it. 7. Save your changes on the System Parameters form. 3/16/16 9

10 8. On the Plants form, set the Plant Code to a unique plant-specific number that matches what the third party will use for the site. a) Right click on the Plant field and select Rename. The Plant field becomes editable. b) Enter the correct Plant Code and save your changes. c) Restart COMMANDbatch so your changes will take effect. 9. IMPORTANT! Check the time zone settings in Windows and configure for the proper time zone setting and daylight savings time options. 10. Restart the EDX Client Service in order to publish the Scope to the EDX Server. 10 3/16/16

11 EDX Server Installation If an EDX Server is not currently installed, perform the following procedure. Note: The EDX Server should reside on a separate machine from the COMMANDbatch PC. The EDX Server, Client, and Protocol Bridge are installed on the EDX Server. 1. Verify that the full version of.net 4.0 is installed. Note: The.NET 4.0 installer (dotnetfx40_full_x86_x64.exe) is available on the install media under the EDX Integration folder. 2. Run the COMMANDedx installer program. 3. On the Installation Directory window, choose a destination directory. The default destination is: 4. On the Auto Update Selection window, leave Server and Client unchecked. 5. On the Component Selection window, select Server and Client and Install Protocol Bridge. 6. When prompted to Select Gateway Template, browse the install media and choose the Gateway.xml template file (under the EDX Integration directory) for the proper partner and click Next. 3/16/16 11

12 7. On the Client Architecture Selection window, check Force bit (x86). 8. On the Server, History, and Client Database Options windows, select the database and enter the username, password, server name, and database name (IP Address or Computer Name). Server Database Options History Database Options Client Database Options 12 3/16/16

13 EDX Gateway Configuration The third party will supply each customer with URI's and a unique set of User Credentials for posting messages. As explained next, you will need to add these URI's and Credentials for that Partner using the Gateway Configuration utility. 1. Run the Gateway Configuration utility by selecting Start > All Programs > COMMANDedx > Gateway Configuration. 2. From the Partners tab, select the Partner created from the Gateway Template that was selected during EDX installation and click on the Edit button as shown next. 3. When the Partner editor opens, select the Protocol Bridge tab and enter the Username / Password Credentials provided by the third party. 4. If needed, the URI can be modified in the REST Adapter section of the Partner editor. (Default URI s are defined from the Gateway Template that was selected during installation.) 3/16/16 13

14 5. After all changes have been made, click OK. 6. Restart the EDX Client Service so that your changes take effect. 14 3/16/16

15 SmartEDX Installer (Install EDX Client and CMDbatch Plugin) The SmartEDX Installer installs both the EDX Client and the COMMANDbatch Plugin with very little user intervention. Prerequisites: Write down the EDX Server Name or IP Address. Verify that the full version of.net 4.0 is installed. (The.NET 4.0 installer [dotnetfx40_full_x86_x64.exe] is available on the install media under the EDX Integration folder.) Installation: 1. Run the smartedx_install_ exe. (Your version number may be different than , depending on your COMMANDbatch version.) 2. Do one of the following to specify which EDX Server to use: Option 1 Leave the Use found EDX Server option checked then click the Find All button to search for EDX Servers. (Only EDX Servers with EDX v or later will be found.) Option 2 Select the Specify EDX Server option and manually enter the EDX Server Name or IP Address. (If a previous version of EDX was recently installed, the EDX Server Name will be pre-populated from the EDX Client configuration file.) If you choose Option 1: A progress window is displayed until EDX Servers are found. 3/16/16 15

16 Select the server to use then click Install. If you choose Option 2: Select the Specify EDX Server option, manually enter the EDX Server Name or IP Address, and select the Version. If you are not sure of the Version, click the Find Version button which selects the correct version for you. Only EDX Servers that run v or later are capable of returning Versions. If the specified EDX Server does not return a Version, you must manually select it. Click Install. 3. Once installation is complete, click the Close button. 16 3/16/16

17 Troubleshooting No Messages in EDX Log Viewer No Transaction Profile Database Connectivity Issues Error Codes No Messages in EDX Log Viewer If you do not see messages in the EDX Log Viewer, check the following items: If no data is being sent to the third party, but the Plugin is initializing within EDX: Verify that CPM is enabled in the COMMANDbatch license file. Verify that the third party Interface is enabled on the EDX Configuration form. Verify that the COMMANDbatch Plugin Transaction Profile was created on the EDX Server: Select Start > All Programs > COMMANDedx > Server Maintenance. Click on the Transaction Profiles tab and click the Refresh button. You should see an entry similar to the one outlined below for each COMMANDbatch Plant that is brought online. No Transaction Profile If you do not see the Plugin's Transaction Profile: Restart the CommandEDXClient Service on the COMMANDbatch PC and check the Transaction Profiles tab again. Verify that the ShipmentSchedule and ProductionPerformance messages are being sent to the third party and accepted. The following two screen examples show what to look for in the EDX Client Log on the EDX Server: 3/16/16 17

18 ShipmentSchedule ProductionPerformance 18 3/16/16

19 Database Connectivity Issues Errors in the EDX Log Viewer that are related to Selecting Data from the EDX Database may indicate problems with the EDX Database connections. Here is an example. To confirm that there are database connectivity issues, open the EDX Configuration Editor Utility (select Start > All Programs > CommandEDX > Configuration Editor). Navigate to the Databases section, select the database in question, and click Test Connection to see if a Success or Failure message is returned. If a Failure message is returned, then further troubleshooting needs to be performed. 3/16/16 19

20 Error Codes Type Error Code Reason Description Rejected 3701 No Ticket Number in ShipmentSchedule Rejected 3702 No Production Request ID in ShipmentSchedule or ProductionPerformance Rejected 3703 No PlantCode in ShipmentSchedule Rejected 3704 Load size or target slump unit in ShipmentSchedule or ProductionPerformance not recognized as a supported unit type (unless ProductionPerformance is a cancel message) Rejected 3705 Load size or target slump unit is missing, when the value is set (if a load size or load size unit is not sent, the message is not rejected; it is only rejected if a load size is sent without a unit) Rejected 3706 Load Size and/or load size unit are missing from ProductionPerformance (unless ProductionPerformance is a cancel message) Rejected 3707 Unrecognized max water unit in ProductionPerformance (unless ProductionPerformance is a cancel message) Rejected 3708 No Actual load start or end times in ProductionPerformance (unless ProductionPerformance is a cancel message) Ticket number not found. The ticket number was not provided in the ShipmentSchedule message. Production Request ID is missing or invalid. Cannot process message without primary key. Invalid plant code received. The plant code was not provided or was not found in the VLink system. Invalid Unit of Measure received for Load size and/or Target Slump. The Unit of Measure was not provided or is not defined in the VLink system. Load size or Target Slump not received in ShipmentSchedule message. Invalid Load size received in ProductionPerformance message. Invalid Unit of Measure received for Water to Add field. The Unit of Measure was not provided or is not defined in the VLink system. Actual Load Start / Load End times not received in ProductionPerformance message. 20 3/16/16

21 Type Rejected 3709 Truck number not found. There currently is no way to tell if the ticket was sent for a truck that doesn t have slump measuring equipment installed, or if the truck name doesn t match between systems. So this error will be sent in both cases Type Description Error Code Reason Description Invalid truck number received. The truck number was not provided or was not found in the VLink system. Rejected 3710 Driver not found Invalid driver name/code received. The driver information was not provided or was not found in the VLink system. Rejected 3711 PlantCode in ShipmentSchedule is not found in VLink system Rejected 3712 ShipmentSchedule has not already been received and saved before ProductionPerformance has been received Invalid plant code received. The plant code was not provided or was not found in the VLink system. Data transfer messages were received out of order. ProductionPerformance message received prior to ShipmentSchedule. Rejected Protocol Message could not be saved in the VLink system due to missing data or malformed XML. Protocol error has prevented the message from being transmitted to the VLink system. The error code and a brief description will be displayed for the error. 3/16/16 21