Unifaun XMLPosting

Transcription

1 Unifaun XMLPosting This document is intended for suppliers of web based ERP systems and describes the integration method XMLPosting with Unifaun Online and Pacsoft Online

2 1 Contents 1 Contents Overview Unifaun ERPConnect using OnlineConnect Unifaun ERPConnect using XMLPosting User handling Using Unifaun Online from your ERP system In the ERP system In Unifaun Online Create an order file Post an order file to Unifaun Online or Pacsoft Online More webservices and features... 15

3 2 Overview Unifaun Online is an online service for printing freight documents, handling EDI (sending transport instructions and receiving feed-back electronically) and tracking of shipments. Freight documents produced by Unifaun Online are always up to date with the carriers specifications and demands. Depending on the carrier and the different services the freight documents might contain different elements, such as bar codes for shipment-/package IDs, customer number, service, information about sender and receiver, local service centre, route codes. If route codes or local service centre are not provided by the ERP system, Unifaun Online may suggest the best choice available. Shipment lists and various customs documents may also be produced if needed. Accurate freight documents make the entire delivery chain more efficient and the transport buyers may avoid additional costs due to incorrect documents or labels. When carriers make changes to their specifications, Unifaun is responsible for updating the layouts which means you do not have to worry about not having the latest version. EDI is also handled according to each carrier s specification. EDI is normally sent right after the freight documents have been printed (provided that the shipment date is not set in the future), usually in a carrier specific IFTMIN (transport instruction) format. Most carriers demand this and Unifaun Online will automatically provide it. Unifaun is responsible for updating the EDI formats as well. The carrier may also send EDI back to Unifaun Online with status information on shipments, for example if the shipment is on its way or has been delivered. Depending on carrier and service this is displayed in Unifaun Online s shipment history. From the shipment history it is also possible to search for a specific package if this service is provided by the carrier. Unifaun Online works in the same way for all carriers supported by the system (not taking differences between different carriers services into account). In order to use Unifaun Online you must sign an agreement with Unifaun and also have a customer number tied to an agreement with the carriers you plan to use. 2.1 Unifaun ERPConnect using OnlineConnect ERPConnect using the software Unifaun OnlineConnect is an additional feature to Unifaun Online provided by Unifaun, charging an extra fee. It enables your ERP system to connect directly to Unifaun Online. You can then place orders in your ERP system and have freight documents printed and EDI sent without using Unifaun Online s user interface. To use the OnlineConnect method you need a signed agreement with Unifaun tied to a user identity in Unifaun Online. Your ERP system must be able to create order files approved by Unifaun. Also, you have to install a Java based software, Unifaun OnlineConnect, used for posting the order files to Unifaun Online and provide directprinting of freight documents and feedback report. More information is available on Unifaun ERPConnect using XMLPosting ERPConnect using XMLPosting is a service which makes it possible for web-based ERP systems to post orderfiles directly to Unifaun Online. It is not developed for end users but is a method for the ERP system suppliers for technical integration with Unifaun Online, for their customers to be able to use Unifaun ERPConnect. The prerequisites of using the XMLPosting method is that the ERP system is operated, developed and configured by the ERP system supplier on behalf of the end user/customer. This means that the end user can create and post orderfiles without having to install and use the client software from Unifaun. As for the client software, you need a signed agreement with Unifaun tied to an ERPConnect approved user-id in Unifaun Online. Your ERP system must be able to create orderfiles approved by Unifaun and posted with an approved developerid (User-id for developers and retailpartners). Please note that you still need Unifaun OnlinePrinter for printing freight documents. More information is available on The ERP system supplier must have a Unifaun developer id and each end user/customer needs a Unifaun ERPConnect license to be able to benefit from the integration.

4 ERP system Log in to Unifaun Online for printing and follow-up Freight documents Shipment history Order file in Unifaun Online s XML format. Unifaun s client software for printing Send order file Unifaun Online Internet Status report EDI format Transport instruction EDI format Carriers Figure 1 Förenklat schema över Unifaun Onlines funktion Implementation ERP system supplier Be able to save user identity, password and profile in the ERP system for the Unifaun Online end users. Please refer to chapter 3. Create an order file in XML format for the carriers, services and add on services in question. Please refer to chapter 5. Be able to post the order file to Unifaun Online. Please refer to chapter 6. Let the end users log in to Unifaun Online, either from or directly from a URL. Please refer to chapter 7. Functionality end user The end user creates the order in the ERP system. Printing of freight documents is done in Unifaun Online. Follow-up on shipments is done in Unifaun Online.

5 3 User handling All endusers in the ERP system that uses Unifaun/Pacsoft Online must have an user-id. This means that they must have an active user identity tied to a password. Both the user identity and the password is handed out and administrated by Unifaun/Pacsoft online support and cannot be changed by the users themselves. When a user identity has been registered, it is tied to one (or several) customer numbers at the carrier s, and those customer numbers will be charged for the services handled in Unifaun/Pacsoft Online. Customers with a large and complex goods flow may also have one or several profiles tied to their user identity. The profile name (max. 50 characters) and password are in these cases decided by the customer. Profiles are used for controlling user rights and access to information in order to streamline each user s way of working in the system. Profile management is included in Unifaun Online Plus. The ERP system need a User Account (user-id) in Unifaun Online for the platform developer. It is necessary to provide contact information to the developer to secure that vital system information reach the developers and that the developers keep the ERP systemplatform up to date for the endusers. The ERP system need to store user identity and password for those endusers that should be able to post order files to Unifaun Online through the ERP plattform. If necessary, the ERP system must also be able to store one or several profile names tied to the user identity. The ERP system must enclose the correct user identity and password when order files are posted. If URLs should be used for logging into Unifaun Online directly from the ERP system it must contain developer identity (developerid), user identity, password and possibly profile. It is recommended to use some kind of event log to be able to track problems that might occur. The security aspect around handling of developer identity, user identity, password and profile are extremely important to ensure the integrity of the system and avoid erroneous charges. Each enduser identity must also have an agreement for ERPConnect to be able to receive posted order files. This is an agreement between the enduser/customer and Unifaun. The following process needs to be implemented by the ERP system supplier to get new or existing customers into operation in Unifaun Online: 1. developerid is the mandatory User Account (user-id) of the developer in Unifaun Online. It is necessary to provide contact information to the developer to secure that vital systeminformation reach the developer and that the developers system platform is kept up to date for the endusers. 2. Account in Unifaun Online. If not already a Unifaun Online customer and hence not having a user identity, the customer might get this by contacting Unifaun Support and signing agreement. 3. User identity, Password and Profile. Enter the customer s user identity, password and profile in the ERP system and store them in an appropriate place where they can be picked up when logging in to the system and posting order files. 4. Order Unifaun ERPConnect. Ask the customer to get a license for Unifaun Orderkoppling ERPConnect tied to their user identity in Unifaun Online, by contacting Unifaun Support. Also, please send a message to Unifaun Support concerning that a customer is about to order Unifaun ERPConnect, preferably with the customer s user identity if possible. Unifaun will then inform the ERP system supplier when ERPConnect has been activated and is ready to take into operation. 5. Send test files. For the first customers or if new functionality or services should be introduced, it is very important to send test files to Unifaun before the customer is taken into operation. The ERP system supplier s own user identity (developerid) can be used for testing order files. Please contact Unifaun before sending any test files. The normal procedure for activating a user to Unifaun ERPConnect includes test and approval of orderfiles. For the XMLPosting method this is done by the ERP system supplier and the enduser has not to repeat this stage of the procedure. Tests do not have to be performed for each new customer but only for new functionality and services this is validated through the developerid.p lease visit for contact and order information. The ERP system supplier with developerid is responsible for the orderfiles posted to Unifaun Online being correct formatted and containing the information according to the carriers product conditions for transport services 1. The ERP system 1 Normally you find the product conditions for services at the carriers web site or by contacting customer services. Unifaun is not responsible for the carriers product conditions.

6 supplier is also responsible for the connection between orderdata, Unifaun Online developerid and user identity being correct.

7 4 Using Unifaun Online from your ERP system Users of web-based ERP systems need Unifaun Online if they regularly ship pallets, parcels or certain kinds of letters. The interaction between the ERP system and Unifaun Online is simplified by XMLPosting. The method enables the ERP system to send all information necessary for printing freight documents, sending EDI and tracking of shipments directly to Unifaun Online and hence not having to do the same work in two different systems. Below is a brief description of the user processes in the ERP system and in Unifaun Online. 4.1 In the ERP system The user registers an order in the ERP system and indicates how and by which carrier the order should be conveyed. The order must contain information regarding receiver, service, additional services, weight, number of parcels, contents and reference. Depending on the situation the ERP system can automatically add some information, such as contents, weight and reference. The user may add information by Unifaun Online s interface if the ERP system is not able to provide all mandatory information. After the order has been registered the ERP system creates an order file according to Unifaun s specification. The order file may contain all data about the sender or it may be entered in Unifaun Online in advance and only referred to in the order file. The ERP system posts the order file to Unifaun Online. The user can log in to Unifaun Online either by or by a link from the ERP system. 4.2 In Unifaun Online Orders from the ERP system are stored in Unifaun Online ready to be printed. Additional changes can be made in the Unifaun Online interface if the order file was not complete. The user prints the freight documents from Unifaun Online and EDI is automatically sent to the carrier (provided that the carrier can handle EDI). Tracking of all shipments conveyed during the last six months (or less if the amount of shipments is very large) can be made from Unifaun Online, including tracking of individual packages for those carriers and services that allow this. Single shipments that is not registered through the ERP system may be registered directly in Unifaun Online and then printed together with an order from the ERP system or separately. Printers and labels to be used together with Unifaun Online can also be ordered from Unifaun Online. More detailed information on how to use Unifaun Online is available in Unifaun Online s user interface.

8 5 Create an order file The order file format is XML-based and follows normal standards for XML-files as specified by This means that modern tools for creating XML-files should be used to minimize the risk of errors. A big advantage of using XML is that the format allows continuous development of functionality in Unifaun Online without calling for the ERP system supplier to act immediately. The ERP system must: Provide an interface where the end user can enter address data, including telephone number and address if required. The carrier s product descriptions and product conditions (provided by the carrier) indicates which information is required for each service. The ERP system normally stores this in their customer register. Since information can be added in Unifaun Online after the order has been posted from the ERP system, some information may be left out. Provide an interface where the end user can enter shipment data, including number of parcels, contents and weight if required. The carrier s product descriptions and product conditions (provided by the carrier) indicates which information is required for each service. The ERP system normally stores this in their order register. Since information can be added in Unifaun Online after the order has been posted from the ERP system, some information may be left out. Store service codes and additional service codes to be able to create correct order files. Store descriptions of services and additional services in plain language to be displayed to the end user. Be able to create an order file in XML format according to the specification below. The structure of the order file: An order file follows the general XML standard, Modern, off-the-shelf tools should always be used to create and read XML-files in order to avoid problems with character encoding and format/syntax. The first line, the XML header, must contain character encoding. The most common in Sweden are ISO (Latin 1) and UTF-8. You must always state this information in the XML header and thereafter consequently use that encoding throughout the file. Ex. <?xml version="1.0" encoding="iso "?> Then follows the main XML block <unifaunonline> which contains the following types of XML blocks: meta <meta>, sender <sender>, receiver <receiver> and shipment <shipment>. There should be one meta block, zero, one or more sender blocks, zero, one or more receiver blocks and one or more shipment blocks. The meta block contains information about who created the file and when it was created. This information is essential for troubleshooting and support. The sender block contains information about the sender. sndid (sender identity) in the sender block is referred to from the shipment block s from tag. Most often, one and the same sender block is used for all shipment blocks in the order file. If there are more than one sender block in the order file the sndid must be unique for each block. The sender block may be left out if the information already has been entered in Unifaun Online. The receiver block contains information about the receiver. rcvid (receiver identity) in the receiver block is referred to from the shipment block s to tag. Most often, one receiver block is created for each shipment block. If there are more than one receiver blocks in the order file the rcvid must be unique. The sender block may also be left out if the information already has been entered in Unifaun Online, for example by importing a register. The shipment block represents a shipment from one sender to one receiver using one transport service, zero, one or more additional service and contains information about the parcels included in the shipment. XML orderfile Specification:

9 Troubleshooting and support It is very important to include information about when the file was created. This information is essential for troubleshooting and support. Order file examples Exemple Posten A shipment consisting of two parcels containing books. One parcel weighs 2 kg and the other 3 kg. The ERP system s order number is used as identity ( in this example). Service: PostNord MyPack, code: P19. Additional service: Cash on Delivery (sw. Postförskott), code: COD. (In this example, 450 SEK to an account (sw. bankgiro) and with an OCR number as reference.) Additional service: Notify by text messaging (sw. SMS-avisering), code: NOTSMS, to a mobile phone number. Cash on Delivery, C.O.D. means that the receiver pays the amount when the parcel is delivered and Posten transfers the money to a pre-defined account with a pre-defined reference. Notify by SMS text messaging means, in connection with postförskott, that an SMS is sent to a pre-defined mobile number when the parcel has arrived to the local service centre, and also that a reminder is sent if the parcel has not been picked up within a certain amount of days. Service: notification, code: enot. This message is sent in connection with EDI being sent to Posten. Sender data has already been entered in Unifaun Online (which is normally the case) together with a Quick ID ( AVS1 in this example). Receiver data is enclosed in the order file. As identity the ERP system s customer number can be used ( in this example). If Receiverdata is not present in orderfile, all receiverdata will be retrieved from matching receiver quickid in onlinesystem if it is possible. Please note! A list of available carriers services and code is found in the online system, Help > Code Lists. If you do not find a certain carrier, please contact Unifaun Support. <?xml version="1.0" encoding="iso "?> <unifaunonline> <meta> <val n= origin > creator user-id. on behalf of (User-id.)</val> Removed ver2 <val n= created >yyyy-mm-dd HH:mm</val> <!-- created: when this file was created. Example: :35 --> </meta> <receiver rcvid="81010"> <!-- Receiverinformation. Rcvid refers to shipment tag "to" in shipment block below. A receiverblock can be used in several shipmentblocks. If several Receivers will be used in one orderfile each receiver has to have a unique receiverid, use for example the unik customernumber. All necessary receiverinformation is sent in this example, but can also be retrieved from the onlinesystem. If no rcvid in the orderfile match the value of shipment tag to the system will search and collect all necessary receiver information from the receiver in the onlinesystem with the corresponding. --> <val n="name">bästa Kunden</val> <val n="address1">att: Mats Ryding</val> <val n="address2">smedjegatan 5</val> <val n="zipcode">411 13</val> <val n="city">göteborg</val> <val n="country">se</val> <val n="contact">mats Ryding</val> <val n="phone"> </val> <val n="fax"> </val> <val n="orgno"> </val> <val n="doorcode">1234</val> <val n=" ">[email protected]</val> <val n="sms"> </val> <!-- Depending on transportservices some data above is mandatory. Check the conditions for the transportservice. You can fulfill missing data in the user interface if needed. --> </receiver> <shipment orderno="928374"> <!-- Shipmentinformationen. One or more shipmentblock can be used in an orderfile. Ordernumber this example.

10 --> <val n="from">avs1</val> <!-- Sender quickid AVS1 in this example. --> <val n="to">81010</val> <!-- Receiver quickid in this example.--> <val n="reference"> </val> <service srvid="p19"> <!-- P19 = PostNord MyPack. For more transportservice codes check in the onlinesystem under Help > Code lists > Services ERP-Connection XML. --> <addon adnid="cod"> <!-- COD = Cash on delivery. For more transportservice codes check in the onlinesystem under Help > Code lists > Services ERP- Connection XML. --> <val n="amount">450.00</val> <val n="account"> </val> <val n="accounttype">bg</val> <val n="reference"> </val> <val n="referencetype">ocr</val> <!-- Amount = amount in kronor. account = account for deposit. accounttype = type of account, bg = bankgiro, pg = plusgiro. reference = referencetext. referencetype = type of reference, ocr = OCR, txt = text. --> </addon> <addon adnid="notsms"> <!-- NOTSMS = Notify by SMS. For more transportservice codes check in the onlinesystem under Help > Code lists > Services ERP- Connection XML. --> <val n="misc"> </val> </addon> </service> <ufonline> <option optid="enot"> <val n="message">free textmessage in notification by mail.</val> <val n="to">[email protected]</val> </option> </ufonline> <container type="parcel"> <val n="copies">1</val> <val n="weight">2</val> <val n="contents"> your contentdescription</val> </container> <container type="parcel"> <val n="copies">1</val> <val n="weight">3</val> <val n="contents"> your contentdescription </val> </container> </shipment> </unifaunonline> Please note! All data in the example are made up and should not be used in a real case. Any likeness with real names and numbers is unintentional.

11 Exemple DB Schenker A shipment consisting of 3 parcels containing lamps with a total weight of 21 kg. The ERP system s order number is being used as identity ( in this example). Service: DB Schenker Comfort, code (srvid): BCF. Additional service: Efterkrav, code (adnid): COD (In this example, 980 SEK to a bankgiro and with an OCR number as reference.) Additional service: Avisering, code: NOT, to a contact person with a telephone number. Efterkrav means that the receiver pays the amount the parcel is delivered and Schenker transfers the money to a pre-defined account with a pre-defined reference. Avisering means that Schenker contacts the receiver by phone before the parcel delivery. Service: notification, code: enot. This message is sent in connection with EDI being sent to Schenker. Sender data, together with a Quick ID ( 1 in this example) is included in the order file. The information does not have to be included in the order file if it already has been entered in Unifaun Online. Receiver data is enclosed in the order file. As identity the ERP system s customer number is used ( in this example). Please note! For more transportservice codes check in the onlinesystem under Help > Code lists > Services ERP-Connection XML. <?xml version="1.0" encoding="iso "?> <unifaunonline> <meta> <val n= created >yyyy-mm-dd HH:mm</val> <!-- created: when this file was created. Exempel: :35 --> </meta> <sender sndid="1"> <val n="name">unifaun AB</val> <val n="address1">kaserntorget 5</val> <val n="address2">5 trappor</val> <val n="zipcode">411 18</val> <val n="city">göteborg</val> <val n="country">se</val> <val n="contact">staffan Isaksson</val> <val n="phone"> </val> <val n="fax"> </val> <val n="orgno"> </val> <val n="doorcode">1234</val> <val n=" ">[email protected]</val> <val n="sms"> </val> </ sender > <receiver rcvid="32345"> <val n="name">bästa Kunden</val> <val n="address1">att: Mats Ryding</val> <val n="address2">smedjegatan 5</val> <val n="zipcode">411 13</val> <val n="city">göteborg</val> <val n="country">se</val> <val n="contact">mats Ryding</val> <val n="phone"> </val> <val n="fax"> </val> <val n="orgno"> </val> <val n="doorcode">1234</val> <val n=" ">[email protected]</val> <val n="sms"> </val> </receiver> <shipment orderno=" "> <val n="from">1</val> <val n="to">32345</val> <val n="reference"> </val> <service srvid="bcf"> <addon adnid="cod"> <val n="amount">980.00</val> <val n="account"> </val> <val n="accounttype">pg</val> <val n="reference"> </val> <val n="referencetype">ocr</val> </addon> <addon adnid="not">

12 <val n="reference">violeta Andersson eller Mats Ryding</val> <val n="misc"> </val> </addon> </service> <ufonline> <option optid="enot"> <val n="message">ditt order är klar och paketet på väg.</val> <val </option> </ufonline> <container type="parcel"> <val n="copies">3</val> <val n="weight">21</val> <val n="contents">armaturer</val> </container> </shipment> </unifaunonline> Please note! All data in the example are made up and should not be used in a real case. Any likeness with real names and numbers is unintentional. You can find example of an XML order file in the onlinesystem under Help > Help page > Unifaun ERPConnect. XML orderfile Specification:

13 6 Post an order file to Unifaun Online or Pacsoft Online When the order file has been created it must be posted to Unifaun Online or Pacsoft Online for the user to be able to print freight documents. The order file is sent by the HTTPS protocol to using the POST method. The order file is either sent directly within the message itself or it may be attached to the message. In the first case, there is no packaging of the order file in a MIME-type message in the way a web browser would upload a file. The URL should contain the following parameters. Unifaun Online Session: developerid: User: Pin: Type: Pacsoft Online Session: developerid: User: Pin: Type: This parameter is set on the first call to "ufo_gb" and on subsequent calls to the session value returned. User Identity of the developer s account in Unifaun Online. User identity for the user placing the order. The password connected to the user identity stated in user. Format of the order file. In this case it is always "xml". This parameter is set on the first call to "po_gb" and on subsequent calls to the session value returned. User Identity of the developer s account in Pacsoft Online. User identity for the user placing the order. The password connected to the user identity stated in user. Format of the order file. In this case it is always "xml". Example of the order file directly in the message body (PHP): Exempel orderfil direkt i meddelandet (PHP): <?php // Open order file. (Full path to file.) $f = fopen("orderfile.xml", "r"); if($f!== false) { // Prepare post. $curl = curl_init(); // Select URL. // Note! Please replace UUUUUUUUUU,PPPPPPPP and DDDDDD with your data. curl_setopt($curl, CURLOPT_URL, " perid=ddddddddddd&type=xml"); // Use the POST method... curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_HTTPHEADER, array("content-type: text/xml")); curl_setopt($curl, CURLOPT_POSTFIELDS, fread($f, filesize("orderfile.xml"))); // Execute posting... curl_exec($curl); // Close handle! curl_close($curl); } // else handle file error?> Example of the order file attached to the message (PHP): <?php // Open order file. (Full path to file.) $filepath = realpath("orderfile.xml"); if ($filepath!== false) { // Prepare post. $curl = curl_init(); // Select URL. curl_setopt($curl, CURLOPT_URL, " // Use the POST method... curl_setopt($curl, CURLOPT_POST, true); // Note! Please replace UUUUUUUUUU,PPPPPPPP and DDDDDD with your data. curl_setopt($curl, CURLOPT_POSTFIELDS, array("type" => "xml", "session" => "ufo_se", "user" => "UUUUUUUUUU", "pin" => "PPPPPPPP", "file1" => "@". $filepath)); // Execute posting... curl_exec($curl); // Close handle curl_close($curl);

14 } // else handle file error?> The answer to the successful HTTPS-call is an XML file as follows: <?xml version="1.0" encoding="iso "?> <response> <val n="session">ufo_se_e9821f8b ee4a b_0</val> <val n="status">201</val> <val n="message">created</val> </response> This is an example of a successful transfer. If an error occurs or the login was unsuccessful, a different status and a different message are returned. Status codes that might be returned are: 403 (Unsuccessful login.) Please check the user identity, password and that both the Unifaun Online account and the ERPConnect functionality are active. 500 (The order file was not interpreted correctly.) Please check the order file for syntax errors. Package IDs are not generated by Unifaun Online until the freight documents are printed. Therefore they cannot be returned to the ERP system. Package IDs are often used for tracking shipments but this can be done using the ERP system s order number or reference instead. Please refer to the Unifaun Track&Trace - document on chapter 7 below. Please note! The method for posting order files to Unifaun Online may be changed in the future to enable new functionality. Unifaun will notify you in due time before any changes are made. It may be necessary to modify the method used for posting order files to Unifaun Online.

15 7 More web services and features Unifaun has provided web services and features that can support the XMLPosting function. All of these documents are available on the Helppage : SE: DK/EN: FI: Unifaun Embed&Link Used to open Stored printings in an embedded window within, for example, an ERP system. Unifaun Pickuplocator (ver. 2) Use to receive available pickup locations Unifaun ZipCheck (ver. 2) Used for Zipcode check up Unifaun TrackBack and Unifaun Discard (ver. 2) Used for automated Shipment history feedback and possibility to discard shipment. Unifaun Quicklogin Used to open Unifaun online on a specific page in the system Unifaun Track&Trace Used to present track&trace though a URL containing ordernumber or reference of shipment