1. Abstract

"Tradeshift API Sandbox Quick-start" overviews the Tradeshift (http://www.Tradeshift.com) language-independent 2-legged OAuth Application Programmer's Interface (API). In this class the student creates buyer and seller accounts in the Tradeshift sandbox (http://sandbox.Tradeshift.com). Documents are exchanged using the web interface and using the programming-language-independent API through an open-source Python implementation of that API and sample programs. Attendees interested in the API are assumed to be programmers, but a working knowledge of Python is not required in order to understand how the Python code accesses the interface. The independence of the Tradeshift API allows access to Tradeshift using any programming language to implement the principles covered in this class.

This is a course including information regarding the deployment and use of UBL artefacts on Tradeshift, but this is not a course in the interpretation of specific UBL information items in a business context or the adaptation of financial systems to the semantics expressed by UBL.  The instructor is not in a position to offer financial or legal advice regarding the application or suitability of UBL to any particular scenario or purpose.

Hands-on exercises form the basis of this class. In a classroom setting, students are expected to have access to the Internet. In a web-conference setting, this class is taught on a one-on-one basis where the instructor has the opportunity to monitor the student and, where helpful, operate the student's computer remotely to assist.

At the end of the class the student will have successfully set up sample buyer and seller accounts in the sandbox, sent documents back and forth between accounts using both the web interface and the API interface, downloaded documents from an account to their computer, edited and validated documents, uploaded documents from their computer to an account, and forwarded uploaded documents from one account to the other. Principles of XML, UBL and the Tradeshift API are overviewed and related so that the student understands what aspects of the document exchange are under what purview.

This course is not a survey of the entire Tradeshift API. This course does not include an example of nor a practicum for the 3-legged OAuth invocation of the API.

2. Length and scheduling

This course is three hours long in either the classroom setting or the web conferencing setting.

Until further notice, classes delivered in the web conference setting are available to be taught in two time slots on the available days: 12:00UTC-15:00UTC and 17:00UTC-20:00UTC.

Please contact Crane Softwrights Ltd. at info@CraneSoftwrights.com to schedule one of the available dates and time slots. Should another time of the day be required for where you live, please mention this when you contact us.

3. Expected Audience

This course is aimed at people needing to save hours or days of time finding all the information needed to get up and running in the Tradeshift sandbox. The class does not involve any original programming, but the student should be comfortable reviewing program source code that illustrates the use of the API.

Important:

This class is designed to be a quick-start overview of the API to the extent of getting a good understanding of the principles and a working demonstration up and running in your environment. This short class is not intended to be a comprehensive and detailed treatise. If you are already successfully engaging the Tradeshift API with your own programming language, then this class likely is not for you.

4. Prerequisites

There are no formal prerequisites for this course. The instructor assumes the student who participates understands they will be working with XML at the markup level, and inspecting programming source code. The student does not need to be a Python programmer to engage the free API interface used in the classroom, as the student is not asked to write programs. The instructor will, however, be reviewing Python source code to illustrate the use of the API.

This is not a course to attend to learn XML, UBL or Python in detail, but rather to learn an overview of the technologies.

There is an optional exercise in which the student copies, opens and edits an XML document (invoice), but this can be avoided when requested and other techniques used.

The hands-on aspects of the class require the student to run command-line sample programs in order to interact with the sandbox API. Attendees must have a firm knowledge of the operating system environment as there is no time for coaching from the instructor regarding the command-line environments of today's operating systems.

The student will be given a list of resources to download and unpack in their environment if they wish to save some of the alloted time by doing so. Included in this list is an exercise package sent from the instructor to the student. This unpacking ahead of time is not obligatory as such retrieval and unpacking can be done as part of the class. At the student's request, the instructor can operate the student's computer through the collaborative screen/keyboard sharing application in order to perform the necessary installations.

The instructor uses the Cisco WebEx product for collaborative screen/keyboard sharing. This requires the student to allow the browser to download and run an executable component to engage the student interface. When the student encounters problems with command invocation or execution, the instructor can be given temporary control of the keyboard/mouse to work directly with the student's environment.

5. Exercise environments

The exercises in this class are facilitated by the student having two independent web browsers installed in their environment, say for example, Firefox and Chrome (there are some functions on Tradeshift not supported by the Internet Explorer browser).

As well, a single active Google email account (preferred), or two active and distinguished email addresses, is important to establish and distinguish two temporary tenancies on Tradeshift.

The Python 2.6 environment must be up and running on the student's machine for the exercises to work (other versions of Python may or may not work depending on the library dependencies):

• http://www.python.org/download/releases/2.6/
  • note that the precise combination of library files needed to run Crane's library under Python 2.7 and later versions of Python has not yet been determined

An additional exercise package will be sent by email to the student in advance of the class. This exercise package includes all or part of the following publicly-available resources:

• Crane's Tradeshift API in Python - http://www.CraneSoftwrights.com/resources/ubl/#tspython
  • two dependencies in Crane's API may need to be satisfied if not already installed in your system:
  • http://code.google.com/p/httplib2/
  • http://github.com/dgouldin/python-oauth2
    • this has an installation dependency that may require you first installing http://pypi.python.org/pypi/setuptools
• UBL W3C Schema - http://docs.oasis-open.org/ubl/os-UBL-2.0.zip and http://docs.oasis-open.org/ubl/os-UBL-2.0-update-delta.zip
  • note that the original os-UBL-2.0.zip package is unpacked to a given location and then the os-UBL-2.0-update-delta.zip package is unpacked over top of the first unpacked set of files, thus replacing the original package files with the update package files

6. Synopsis/syllabus

This class is designed to help the student save hours or possibly days of time tracking down all of the information needed to get a running Tradeshift API environment on their computer. While not everyone uses Python as their choice of programming language, the publicly-available resources using Python illustrate how the features of the API work and demonstrate these features working on the student's machine.

It is then left as an independent exercise for the student to port the working demonstration of the concepts to their own programming environment.

The syllabus of the class is as follows, overiewing the API and the use of XML:

• installing Python
• installing Crane's implementation of the Tradeshift API
• overviewing the role of the API and its relation to the browser GUI
• concepts of identity in the Tradeshift environment
• creating a "buyer/customer" account and a "seller/supplier" account in the sandbox
• obtaining API credentials for both accounts in the sandbox
• using the GUI to send an invoice from the seller/supplier to the buyer/customer
• using the API to download the document to the buyer/customer computer
• using the GUI to send an invoice from the buyer/customer to the seller/supplier
• using the API to download all documents to the buyer/customer computer
• understanding XML documents and the UBL schemas (including validation)
• editing a copy of the previously-sent invoice
• using the API to send the newly-edited invoice from the buyer/customer to the seller/supplier
• using the API to delete Tradeshift copies of the buyer/customer documents
• reviewing the program source code and its use of the API