KC Data Integration Web Service Developer Guide

KC Data Integration Web Service Developer Guide

Kewill Copyright Notice Copyright 2016 by Kewill Inc. All rights reserved. This document is the property of Kewill and the information contained herein is confidential. This document, either in whole or in part, must not be reproduced or disclosed to others or used for purposes other than that for which it has been supplied without Kewill s prior written permission, or, if any part hereof is furnished by virtue of a contract with a third party, as expressly authorized under that contract. This edition applies to the current version of the Kewill product and to all subsequent releases and modifications until otherwise indicated. Kewill reserves the right to make improvements and/or changes in the product(s) and/or programs(s) described in these publications at any time. No part of this document may be reproduced or transmitted in any form or by means without the prior written permission of Kewill Limited or one its subsidiaries. If there are any problems encountered in the documentation, please report them to Kewill in writing. Kewill does not warrant that this document is error-free. Third-party Copyright and Trademark Notice Kewill Customs U.S. is legally licensed to operate in conjunction with the following third-party hardware and software: Adobe Acrobat Copyright 2016 Adobe Systems Incorporated. All rights reserved. Apache Tomcat Copyright 1999-2016, The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Citrix Citrix product names referenced herein are trademarks of Citrix Systems, Inc., and/or one of its subsidiaries, and may be registered in the United States Patent and Trademark Office and in other countries. Hewlett Packard (HP) -- Copyright 2010 Hewlett-Packard Development Company, L.P. IBM MQ Server Copyright International Business Machines Corporation 2012. All rights reserved. IBM Tivoli Workload Scheduler (Load Leveler) Copyright International Business Machines Corporation 2005. All rights reserved. Intel Copyright Intel Corporation. All rights reserved. Intel Corporation, 2200 Mission College Blvd., Santa Clara, CA 95052-8119, USA. Java Software Development Kit (JDK)/Java Runtime Environment (JRE) Copyright 1994-1999 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. Linux Linux Foundation in accordance with Linux Foundation trademark policy. Mozilla Firefox Mozilla Firefox is a registered trademark of the Mozilla Foundation. Oracle Trademark and Copyright 2004, 2016, Oracle and/or its affiliates. All rights reserved. PuTTY (SSH/TelnEt Client) PuTTY is copyright 1997-2007, Simon Tatham et al. TSS Server Copyright 2011 Trusted Security Solutions, Inc. 1500 Orchard Lake Dr., Charlotte, NC 28270. All rights reserved.

1. Overview This guide describes how to integrate with KC Data Integration Web Services (shortened as KC Service in this guide). It is written for the application developer who uses web services to design and deploy applications enabled by Kewill. It describes how to get started with application development and how to use the Application Programming Interface (API). Customers can use KC Service to transfer their master data and other data to Kewill Customs. The service can be consumed directly or by using an FTP process. 2. Authentication Whether a customer consumes KC Service directly or by using an FTP process, the user account information should be provided for authentication. The user account is a Kewill Customs user with the ALLOW_KC_DATA_INEGRATION property set to Y. To configure a user (or user group), open Security Administration in Kewill Customs (menu path: Tools > Security Admin). Add the ALLOW_KC_DATA_INEGRATION property on the Security tab and set it to Y. See image below. After configuring a user, log in to Kewill Customs with that user profile to activate that user. pg. 1

3. Predefinitions 3.1 Category The category defines the objects that can be transferred. The table below lists all of the available categories. Category Description Allowed sub actions Allowed Partial Update Company Company/Broker Control file All Yes Mid Manufacturer ID All Yes Message Message All Yes FdaProduct FDA Product Codes All Yes Carrier Carrier Codes All Yes Charge Charge All Yes Parts Parts tree All Yes Customer Customer tree All Yes Shipment Shipment Read NA Vendor Vendor tree All Yes Profile Charge Profiles All Yes DistrictPort District Port All Yes HarmonizedTariff Tariff All Yes EdiShipment EDI Shipment Create, Update, CreateUpdate Full Update 3.2 Action The predefined action for KC service is KC. 3.3 Sub Action The predefined Sub Actions are: Read Allow customers to get objects from Kewill Customs. Currently, the service provides the Read sub action only for the primary key. Reading by other fields will be extended in a future release. Create Add one or multiple records in Kewill Customs. Update Update one or multiple records in Kewill Customs. Full Update requires providing all of the fields. We recommend using a Read sub action first, and then changing the fields that you want to update. Partial update allows you to update specific fields by providing field values and all of the primary keys in a hierarchy. pg. 2

Notes: o o 0 and empty string are specific. These two values in Update will be skipped. The existence check is performed against the root level entity only. If the primary keys in sub trees do not exist, the sub trees will be added. CreateUpdate This is a combination of Create and Update. Note: The only sub action for the Shipment category is Read. The Read sub action is not available for the EDI Shipment category. 4. Consume Web Service Directly 4.1 Import WSDL file To develop a web service client, we can use the wsimport tool to import the WSDL file and generate files to access KC Service. Suppose the WSDL file location is http://hostname:8080/kcadapter/service/kcservice?wsdl The source code will be generated under folder: c:\myclient\src\ The command will be: C:\>wsimport s c:\myclient\src\ -keep http://hostname:8080/kcadapter/service/kcservice?wsdl The generated package is com.kewill.icustoms.service.core As an alternative, if the WSDL file and xsd file are in place, you can use the following command to import: C:\wsdl>wsimport kcservice.wsdl s c:\myclient\src\ -keep Note: The wsimport version must be 2.1.6 or newer. 4.2 Consume Web Service 4.2.1 Create KC Service client. The following is an example of web service client. When WSDL is imported, the client is generated as KcServiceService.java. You can use this directly or create another by copy and paste. pg. 3

package com.kewill.icustoms.adaptertest.client; import java.net.malformedurlexception; import java.net.url; import java.util.logging.logger; import javax.xml.namespace.qname; import javax.xml.ws.service; import javax.xml.ws.webendpoint; import javax.xml.ws.webserviceclient; import javax.xml.ws.webservicefeature; import com.kewill.icustoms.service.core.kcservice; @WebServiceClient(name = "KcServiceService", targetnamespace = "http://core.service.icustoms.kewill.com/", wsdllocation = "http://hostname:8080/kcadapter/service/kcservice?wsdl") public class KcClient extends Service { private final static URL KCSERVICESERVICE_WSDL_LOCATION; private final static Logger logger = Logger.getLogger(com.kewill.icustoms.service.core.KcServiceService.class.getNa me()); static { URL url = null; try { URL baseurl; baseurl = com.kewill.icustoms.service.core.kcserviceservice.class.getresource("."); url = new URL(baseUrl, "http:// hostname:8080/kcadapter/service/kcservice?wsdl"); catch (MalformedURLException e) { logger.warning("failed to create URL for the wsdl Location: 'http:// hostname:8080/kcadapter/service/kcservice?wsdl', retrying as a local file"); logger.warning(e.getmessage()); KCSERVICESERVICE_WSDL_LOCATION = url; public KcClient(URL wsdllocation, QName servicename) { super(wsdllocation, servicename); public KcClient() { super(kcserviceservice_wsdl_location, new QName("http://core.service.icustoms.kewill.com/", " KcServiceService")); /** pg. 4

* * @return * returns KcService */ @WebEndpoint(name = "KcServicePort") public KcService getkcserviceport() { return super.getport(new QName("http://core.service.icustoms.kewill.com/", "KcServicePort"), KcService.class); /** * * @param features * A list of {@link javax.xml.ws.webservicefeature to configure on the proxy. Supported features not in the <code>features</code> parameter will have their default values. * @return * returns KcService */ @WebEndpoint(name = "KcServicePort") public KcService getkcserviceport(webservicefeature... features) { return super.getport(new QName("http://core.service.icustoms.kewill.com/", "KcServicePort"), KcService.class, features); 4.2.2 Consuming Example The following example shows the process of adding an FDA Product into Kewill Customs. package com.kewill.icustoms.adaptertest.client; import java.text.simpledateformat; import java.util.date; import com.kewill.icustoms.service.core.fdaproductentity; import com.kewill.icustoms.service.core.kcdata; import com.kewill.icustoms.service.core.kcservice; import com.kewill.icustoms.service.core.request; import com.kewill.icustoms.service.core.requests; import com.kewill.icustoms.service.core.responses; public class KcClientMain { public static void main(string[] args) { try { Requests requests = createrequests(); KcClient kcclient = new KcClient(); KcService kcservice = kcclient.getkcserviceport(); pg. 5

Responses responses = kcservice.process(requests); if (responses.getresponse().size() > 0) { if (responses.getresponse().get(0).issuccess()) { // do success else { //do fail catch (Exception e) { //do exception handling private static Requests createrequests() { Requests requests = new Requests(); //Authentication requests.setuserid("userid"); requests.setpassword("password"); //request Request request = new Request(); //action, category and subaction request.setaction("kc"); request.setcategory("fdaproduct"); request.setsubaction("create"); //kcdata KcData kcdata = new KcData(); //FdaProduct KcData.FdaProducts fdaproducts = new KcData.FdaProducts(); FdaProductEntity fdaproduct = newfdaproduct(); fdaproducts.getfdaproduct().add(fdaproduct); kcdata.setfdaproducts(fdaproducts); request.setkcdata(kcdata); requests.getrequest().add(request); return requests; private static FdaProductEntity newfdaproduct() { pg. 6

FdaProductEntity fdaproduct = new FdaProductEntity(); Date dnow = new Date(); SimpleDateFormat fdate = new SimpleDateFormat("yyyyMMdd"); SimpleDateFormat ftime = new SimpleDateFormat("hhmm"); fdaproduct.setproductcode("32bve88"); fdaproduct.setproductdesc("product Description"); fdaproduct.setmodifiedby("obama"); fdaproduct.setdateupdated(integer.valueof(fdate.format(dnow))); fdaproduct.settimeupdated(integer.valueof(ftime.format(dnow))); fdaproduct.setdatelastaccessed(integer.valueof(fdate.format(dnow))); fdaproduct.setfdapriornoticereq(""); return fdaproduct; Note: Although we can put all of the categories into one xml file by adding different requests, one xml file per category is preferred. pg. 7

5. FTP Process 5.1 Process Config FTP Server Config KC to enable kcserviceintegrationhandler Create Request XML file Change the extension from xml to txt Drop the txt file to FTP inbound folder When drop is complete, change the extension from txt to xml The schedule will pick up the xml file and process When complete, a response xml file will be created in outbound folder pg. 8

5.2 FTP Server Folders Folder Name /inbound/ /outbound/ /backup/ /process/ Comment The folder where the xml file should be placed. The folder where response xml files will be placed. The folder where backups of all of the processed files are saved. The working folder. 5.3 Configuration in Kewill Customs 5.3.1 Enable KcServiceIntegrationHandler. Open the Schedule Maintenance screen in KC (menu path: SupportSS-SGSchedule). Find the KcServiceIntegrationHandler Schedule ID then select the Enable check box for it. See image below. 5.3.2 Set Up FTP parameter On the Schedule Maintenance screen, click the Parameters button to open the Schedule Parameter Maintenance screen. Edit the parameters to match the FTP folder setup. Please note: Kewill recommends using PFTP (Passive FTP protocol) if you are experiencing issues communicating with the FTP server. Type pftp instead of ftp for the upload_location parameter value as shown highlighted below. pg. 9

Also, you must include the home directory at the end of the upload_location parameter value as shown below (in the example below, folder/ is the home directory of the FTP login account). 5.3.3 Confirm that the KcServiceIntegrationHandler is up and running Open the Admin Utility in KC (Tools menu) then select the Scheduler tab. Make sure KcServiceIntegrationHandler is running. If not, click the Start button to start it. pg. 10

5.4 Request XML file The schema of the request xml is defined in request.xsd. The following is an example of a request xml. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <requests> <password>?</password> <!--1 or more repetitions:--> <request> <action>?</action> <category>?</category> <kcdata> <fdaproducts> <!--Zero or more repetitions:--> <fdaproduct> <!--Optional:--> <datelastaccessed>?</datelastaccessed> <!--Optional:--> <datelastaccesseddt>?</datelastaccesseddt> <!--Optional:--> <dateupdated>?</dateupdated> <!--Optional:--> <dateupdateddt>?</dateupdateddt> <!--Optional:--> <fdapriornoticereq>?</fdapriornoticereq> <!--Optional:--> <modifiedby>?</modifiedby> <!--Optional:--> <productdesc>?</productdesc> <!--Optional:--> <timeupdated>?</timeupdated> <!--Optional:--> <productcode>?</productcode> </fdaproduct> </fdaproducts> </kcdata> <subaction>?</subaction> </request> <userid>?</userid> </requests> pg. 11

Please refer to the previous sections for Action, Sub Action, and Category definitions. The xsd file for each category is available from Kewill. Notes: Except for the request.xsd and response.xsd, all of the other xsd files define only complex types. Request.xsd has single-element requests and response.xsd has single-element responses. Although we can put all of the categories into one xml file by adding different requests, one xml file per category is preferred. 5.5 Example 5.5.1 Read FDA Product (the primary key is product code) <?xml version="1.0" encoding="utf-8" standalone="yes"?> <requests> <password>password</password> <!--1 or more repetitions:--> <request> <action>kc</action> <category>fdaproduct</category> <kcdata> <fdaproducts> <!--Zero or more repetitions:--> <fdaproduct> <productcode>02aab03</productcode> </fdaproduct> </fdaproducts> </kcdata> <subaction>read</subaction> </request> <userid>userid</userid> </requests> pg. 12

5.5.2 Create a FDA Product <?xml version="1.0" encoding="utf-8" standalone="yes"?> <requests> <password>password</password> <!--1 or more repetitions:--> <request> <action>kc</action> <category>fdaproduct</category> <kcdata> <fdaproducts> <fdaproduct> <datelastaccessed>20140630</datelastaccessed> <dateupdated>20131114</dateupdated> <fdapriornoticereq/> <modifiedby>customs</modifiedby> <productdesc>test product desc</productdesc> <timeupdated>1623</timeupdated> <productcode>02aabaa</productcode> </fdaproduct> </fdaproducts> </kcdata> <subaction>create</subaction> </request> <userid> USERID</userID> </requests> 5.5.3 Update specific fields The following example performs two updates: 1) Update modifiedby of the Part to tom. 2) Update commercialdesc of the CatTariffClassAux in seqno 1 to test description. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <requests> <password>password</password> <request> <action>kc</action> <category>parts</category> pg. 13

<kcdata> <parts> <part> <modifiedby>tom</modifiedby> <id> <custno>erica</custno> <dateeffective>20130923</dateeffective> <partno>08sign8888</partno> </id> <CatTariffClassAuxList> <CatTariffClassAux> <commercialdesc>test description</commercialdesc> <custno>erica</custno> <dateeffective>2013-09-23t00:00:00-04:00</dateeffective> <partno>08sign8888</partno> <seqno>1</seqno> </CatTariffClassAux> </CatTariffClassAuxList> </part> </parts> </kcdata> <subaction>update</subaction> </request> <userid>userid</userid> </requests> Notes: In the database definition, the field dateeffective in CatTariffClassAux is a timestamp type, but dateeffective in Part (Cat_Ci_Line) is an integer. Different date formats are used in the example. Please check the xsd and make sure you are using the correct data type. 6. Understanding the Response 6.1 Understanding the Response Structure If the KC service is consumed directly, a response object will be returned. If the service is consumed by using an FTP process, a response.xml file will be generated in the outbound folder. Because the response.xml is the marshalled results of the response object, we will use the xml file to explain the response. The following is a typical response xml of a successful update. pg. 14

<responses> <response> <kcdata/> <Messages> <Message> <Code>E00008</Code> <Content>Successfully updated Customer.</Content> <Type>Informational</Type> </Message> </Messages> <Success>true</Success> </response> </responses> It has three main elements: Success: This is the overall status of the process and can be true or false. kcdata: If the overall status of the process is true, the kcdata is empty (no children). Otherwise, it includes all of the failed records and has the same structure as the request. Messages: If the overall status of the process is true, the message is informational. Otherwise, each message will give the reason why the corresponding record failed. In the following example, there are seven customer nodes and seven error messages. The first customer node corresponds to the first error message and so on.. pg. 15

6.2 Understanding the Message KC Service does not provide field-level validation. All of the error messages are retrieved from the database. These messages might be confusing. Example 1: The message is about the NOTE_CUST field in the CUST_NOTES node. It is saying that the actual data provided in the xml is 62 characters but that the maximum for the field is 60 characters. This is the first message. Opening the first Customer node, we can see that one of the data items supplied is indeed too long for the field. So shortening your data value is the solution for these errors. pg. 16

Example 2: In example 2, the error is stating that it cannot persist the CustAddressesPK which is a composite PK of custno and addressnoalpha as seen above. It indicates more than one addresses have been specified using the same combination of custno and addressnoalpha thus failing the PK unique constraint. Example 3: Example 3 shows the value is larger than the specified precision allowed for this column, but it does not tell us which column. Usually, this is a number field and you need to spend some time in finding it. 6.3 Including File Number in Response To return the file number in an EDI shipment Web Service response file, add the new element, <asyncedishipment> to the EdiShipment request and set its value to Y as shown below: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <requests> <password>password</password> <request> <action>kc</action> <category>edishipment</category> pg. 17

<asyncedishipment>y</asyncedishipment> <kcdata> The <asyncedishipment> element applies only to the EdiShipment category. The value Y will return the fileno in the response file. Otherwise, the fileno will not be returned in the response file. See these scenarios: The <asyncedishipment> element is set to N or the element does not exist. After the Web Service loads the EDI to the database successfully, an entry in Dashboard Work Management is created. The Hand Free Scheduler and Hands Free Handler will pick up the work and load the EDI to the shipment. The dashboard record holds the loading status and file number. If the loading fails (for example, because of invalid custno or fatal validations), please check the status and follow the existing process for removing fatal validations. The <asyncedishipment> element is set to Y. After the Web Service loads the EDI to the database successfully, it calls the Hands Free process and tries to load the EDI to the shipment. If the process is a success, the fileno is included in the response file. If the process fails, the dashboard work id is returned in the error message. Check the dashboard record to find the reason for the failure. Update EDI If the loading of the EDI to the shipment fails, you can update the EDI via Web Service at any time. If it is a success, update will not be allowed. To perform the update, you need to purge the shipment in the KC user interface, wait for the background process to clear the edi_assigned_file field in the edi_shipment_header table, and then make an update. 7. Resources Schema, sample xml, and definition from Kewill pg. 18