API for importing handling requests via email

FBO One is able to process email messages containing attachments with a specific XML file format. 

How to develop for this interface

  • You can request a test instance of FBO One for testing your message at support@amsterdamsoftware.com.
  • The messages can contain both new handling requests as well as updates to existing requests. The HandlingRequestID is used as a unique key. If you cannot provide such a technical ID for each handling request, the system is also capable to match and update flight legs based on the flight number field. Based on the Registration field, the system is even capable to swap an outbound leg to another handling order. This may be useful in the event of an aircraft change.
  • The messages to be processed and imported into FBO One must be sent to a dedicated email address in the form of 'message_format.queue_name@...com'. This email address will be provided by our support team.

Overview of the XML data

General description of the elements in the XML file

  • HandlingRequestBatch
    • This is the root element of the message. A batch contains one or more handling requests.
    • Contains fields to indicate the FBO to which the batch of requests is addressed.
  • HandlingRequest
    • The arrival and departure movements for a ground handling can be combined in a single HandlingRequest. Each movement is represented by a Leg. It is acceptable to FBO One to receive separate HandlingRequests for the arrival leg and for the departure leg. The decision to send one or two legs in the HandlingRequest is up to the operator to decide. A private owner would typically have a single handling request for both the arrival and the departure legs. An air-taxi company may prefer to send handling requests where the arrival and departure legs are kept in separate requests. Internally, FBO One will automatically combine arrival and departure legs based on the Registration code and the arrival and departure times.
    • Indicates the debtor (customer to charge on the receipt) of the requested order.
  • Leg
    • A leg represents an arrival at or a departure from the FBO. 
    • The fields contain information about the flight leg like a/c registration, a/c type, flight number. For arrival legs, it contains the origin station (airport) and for departure legs the onward destination station.
  • ServiceRequest
    • A service request can be inserted for any service that is of interested to FBO. It can be service to be delivered in-house by the FBO, or a service request executed by a third party such as catering company. In FBO One, the users will review each request, and create applicable charges and tasks as necessary.
    • The free text fields in this table indicates the supplier that should be used for the service request, the operator's order number of the service request, and the name/description for the service.
  • Passenger
    • Information about a passenger. This can be used by the FBO to create immigration forms.
  • CrewMember
    • Information about a crew member.


Based on the ID fields, the system will know which handling request will belong to the handling request batch or which service or passenger information belongs to which flight leg. The above figure shows the exact relationships.

Detailed description of the elements

Restrictions

  • All the ID fields must be integer numbers and they are used as identifiers for the information stored in one XML file. The IDs will be used only during the importing process of data into FBO One and will not be used later to identify this information.
  • IDs must always reference data included in the same XML file and not from previous requests.
  • The ID value of the handling request batch, handling request and leg must be unique. They are used as a link between other data included in the file. The 'key' symbol in the Preview figure indicates the ID's that must to be unique in the XML file.
  • When FBO One will process such files, it automatically assumes that debtor names, ICAO codes, FBO Location Names exist already in the system.

HandlingRequest

  • HandlingRequestID
    • Mandatory unique integer number.
  • HandlingRequestBatchID
    • Mandatory ID value referencing the HandlingRequestBatch.
  • OperatorName
    • Name of the operator associated with the request.
  • DebtorName(deprecated with Version 2.0.0)

ServiceRequest

  • LegID
    • Mandatory ID value referencing the leg that the service belongs to.
  • Supplier
    • Optional text value. Name of the supplier to be used for this service.
  • OrderNumber
    • Optional text value. Indicates the service request number used with the supplier.
  • Description
    • Optional text value. Description for the service that needs to be provided.

Leg

  • HandlingRequestID
    • Mandatory ID referencing the handling request.
  • LegID
    • Mandatory unique integer number identifying this leg.
  • DebtorOrderNo
    • Mandatory text value. Order number for this handling, as known by the operator/debtor. Based on this value, FBO One will decide if the request is an updated of an existing order or a new order should be created.
  • Registration
    • Optional text value. Registration of the aircraft.
  • AircraftTypeIcaoCode
    • Optional text value. A/c type ICAO code.
  • IsCancelled
    • Optional Boolean value: ''true'' or '"false". Indicates if the flight leg should be canceled or not. The values true/false must be in lower case.
  • FlightNumber
    • Optional text value: Flight number associated with the order request.
  • DepartureStationIcao
    • Optional text value: ICAO code of the departure station.
  • ArrivalStationIcao
    • Optional text value: ICAO code of the arrival station.
  • StdUtc
    • Optional datetime value. Indicates the STD of the flight leg.
  • StaUtc
    • Optional datetime value. Indicates the STA of the flight leg.
  • PaxCount
    • Optional integer value. Indicates the number of passengers for this flight leg.
  • CrewCount
    • Optional integer value. Indicates the number of crew members for this flight leg.
  • FlightType
    • Optional text value. Indicates the type of the flight (e.g.: 'Ferry', 'Private').

Passenger

  • LegID
    • Mandatory ID value referencing the flight leg to which the passenger belongs.
  • Name
    • Optional text value. Indicates the full name of the passenger as it will be displayed in FBO One. If empty, the Name will be formatted form the First Name Middle Name and Last Name fields, where at least the Last Name value must not be empty to import correctly the data into FBO One.
  • DateOfBirth
    • Optional datetime value. Indicates the date of birth for the passenger.
  • PassportNumber
    • Optional text value. Indicates the passport number of the passenger or the international ID.
  • Country
    • Optional text value. Indicates the origin country of the passenger.
  • MiddleName
    • Optional text value. Indicates the middle name of the passenger.
  • LastName
    • Optional text value. Indicates the Last Name of the passenger. For a passenger record, at least the last name needs to be provided to be imported into FBO One.
  • FirstName
    • Optional text value. Indicates the First Name of the passenger.


Note that the XML format accepts to have the same crew member details multiple times (there is no restriction in this case), to cover situations where one person holds multiple passports and this information helps during the Customs process.

CrewMember

  • LegID
    • Mandatory ID value referencing the flight leg to which the passenger belongs.
  • Name
    • Optional text value. Indicates the full name of the passenger as it will be displayed in FBO One. If empty, the Name will be formatted form the First Name Middle Name and Last Name fields, where at least the Last Name value must not be empty to import correctly the data into FBO One.
  • DateOfBirth
    • Optional datetime value. Indicates the date of birth for the passenger.
  • PassportNumber
    • Optional text value. Indicates the passport number of the passenger or the international ID.
  • Country
    • Optional text value. Indicates the origin country of the passenger.
  • MiddleName
    • Optional text value. Indicates the middle name of the passenger.
  • LastName
    • Optional text value. Indicates the Last Name of the passenger. For a passenger record, at least the last name needs to be provided to be imported into FBO One.
  • FirstName
    • Optional text value. Indicates the First Name of the passenger.
  • CrewType
    • Optional text value. Indicates the type of the Crew member. Use for Pilot in Command the code PIC, Second in command as SIC, FA for flight attendant and PAX for passenger.


Note that the XML format accepts to have the same crew member details multiple times (there is no restriction in this case), to cover situations where one person holds multiple passports and this information helps during the Customs process.

HandlingRequestBatch

  • HandlingRequestBatchID
    • Mandatory unique integer number identifying this batch handling request.
  • BatchNumber
    • Optional text value. Indicates the number of the batch inside the document.
  • FboName
    • Mandatory text value. Indicates the name of the Fbo Location that will receive the handling order request.
  • HandlingStationIcao
    • Mandatory text value. Indicates the ICAO code of the handling station. The FBO Location can be different than the Handling Station where the order will actually be handled.
  • GeneratedUTC
    • Mandatory date time value. Indicates the date time when the batch was created.
  • Version 
    • <Version>2.0.0</Version>


Note that it is good practice to include an additional PDF document in the email message. This can contain a human readable version of the request. Such attachments will be processed by FBO One and attached to the handling order in FBO One so end users can review it.

Appendix: XSD Schema for the XML format

<?xml version="1.0" encoding="utf-8"?>
<xs:schema
id="HandlingRequestDataSet" targetNamespace="http://fboone.aero/HandlingRequestDataSet.xsd"
xmlns:mstns="http://fboone.aero/HandlingRequestDataSet.xsd"
xmlns="http://fboone.aero/HandlingRequestDataSet.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
attributeFormDefault="qualified" elementFormDefault="qualified">
  <xs:element name="HandlingRequestDataSet" >
    <xs:complexType>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="ServiceRequest">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="LegID" type="xs:int" minOccurs="0"/>
              <xs:element name="Supplier" type="xs:string" minOccurs="0"/>
              <xs:element name="OrderNumber" type="xs:string" minOccurs="0" />
              <xs:element name="Description" type="xs:string" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Leg" >
          <xs:complexType>
            <xs:sequence>
              <xs:element name="LegID" type="xs:int" />
              <xs:element name="HandlingRequestID" type="xs:int" minOccurs="0" />
              <xs:element name="DebtorOrderNo" type="xs:string" />
              <xs:element name="Registration" type="xs:string" minOccurs="0" />
              <xs:element name="AircraftTypeIcaoCode" type="xs:string" minOccurs="0" />
              <xs:element name="IsCancelled" type="xs:boolean" minOccurs="0" />
              <xs:element name="FlightNumber" type="xs:string" minOccurs="0" />
              <xs:element name="DepartureStationIcao" type="xs:string" minOccurs="0" />
              <xs:element name="ArrivalStationIcao" type="xs:string" minOccurs="0" />
              <xs:element name="StdUtc" type="xs:dateTime" minOccurs="0" />
              <xs:element name="StaUtc" type="xs:dateTime" minOccurs="0" />
              <xs:element name="PaxCount" type="xs:int" minOccurs="0" />
              <xs:element name="CrewCount" type="xs:int" minOccurs="0" />
              <xs:element name="FlightType" type="xs:string" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Passenger">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="LegID" type="xs:int" minOccurs="0" />
              <xs:element name="Name" type="xs:string" minOccurs="0" />
              <xs:element name="DateOfBirth" type="xs:dateTime" minOccurs="0" />
              <xs:element name="PassportNumber" type="xs:string" minOccurs="0" />
              <xs:element name="Country" type="xs:string" minOccurs="0" />
              <xs:element name="MiddleName" type="xs:string" minOccurs="0" />
              <xs:element name="LastName" type="xs:string" minOccurs="0" />
              <xs:element name="FirstName" type="xs:string" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="CrewMember" >
          <xs:complexType>
            <xs:sequence>
              <xs:element name="LegID" type="xs:int" minOccurs="0" />
              <xs:element name="Name" type="xs:string" minOccurs="0" />
              <xs:element name="DateOfBirth" type="xs:dateTime" minOccurs="0" />
              <xs:element name="PassportNumber" type="xs:string" minOccurs="0" />
              <xs:element name="Country" type="xs:string" minOccurs="0" />
              <xs:element name="MiddleName" type="xs:string" minOccurs="0" />
              <xs:element name="LastName" type="xs:string" minOccurs="0" />
              <xs:element name="FirstName" type="xs:string" minOccurs="0" />
              <xs:element name="CrewType" type="xs:string" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="HandlingRequest">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="HandlingRequestID" type="xs:int" />
              <xs:element name="HandlingRequestBatchID" type="xs:int" />
              <xs:element name="OperatorName" type="xs:string" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="HandlingRequestBatch" >
          <xs:complexType>
            <xs:sequence>
              <xs:element name="HandlingRequestBatchID" type="xs:int" />
              <xs:element name="BatchNumber" type="xs:string" minOccurs="0" />
              <xs:element name="FboName" type="xs:string" />
              <xs:element name="HandlingStationIcao" type="xs:string" />
              <xs:element name="GeneratedUTC" type="xs:dateTime" minOccurs="0" />
              <xs:element name="Version" type="xs:string" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:choice>
    </xs:complexType>
  </xs:element>
</xs:schema>


Sample file

<HandlingRequestDataSet xmlns="http://fboone.aero/HandlingRequestDataSet.xsd">
  <ServiceRequest>
    <LegID>-1</LegID>
    <Supplier>Rusaero / VIPPORT- VKO 1</Supplier>
    <Description>Special service. Vendor: Rusaero / VIPPORT- VKO 1. Contact: vip@gmail.com. Description: Please note passengers will be using the following passports: Demo D abcdef, exp. 13.09.19; Demo 2 ghijklm, exp. 11.01.22.</Description>
  </ServiceRequest>
  <ServiceRequest>
    <LegID>-1</LegID>
    <Supplier>Food Feel</Supplier>
    <OrderNumber>4880836</OrderNumber>
    <Description>Passenger Catering; Order #: 4880836; Delivery Date and Time: 14-May-13 12:45 ; Vendor: Food Feel; Phone: 31-22-222222 Fax: 31-22-222222 </Description>
  </ServiceRequest>
  <Leg>
    <LegID>-1</LegID>
    <HandlingRequestID>-1</HandlingRequestID>
    <DebtorOrderNo>7177369</DebtorOrderNo>
    <Registration>HZSPAA</Registration>
    <AircraftTypeIcaoCode>HS-125-800XPC</AircraftTypeIcaoCode>
    <IsCancelled>false</IsCancelled>
    <FlightNumber>TSE621K</FlightNumber>
    <DepartureStationIcao>LLBG</DepartureStationIcao>
    <ArrivalStationIcao>OEJN</ArrivalStationIcao>
    <StdUtc>2013-05-16T10:30:00+02:00</StdUtc>
    <StaUtc>2013-05-16T14:06:00+02:00</StaUtc>
    <PaxCount>2</PaxCount>
    <CrewCount>2</CrewCount>
    <FlightType>Private</FlightType>
  </Leg>
  <Leg>
    <LegID>-2</LegID>
    <HandlingRequestID>-1</HandlingRequestID>
    <DebtorOrderNo>7209917</DebtorOrderNo>
    <Registration>HZSPAA</Registration>
    <AircraftTypeIcaoCode>HS-125-800XPC</AircraftTypeIcaoCode>
    <IsCancelled>false</IsCancelled>
    <FlightNumber>TSE120A</FlightNumber>
    <DepartureStationIcao>OEJN</DepartureStationIcao>
    <ArrivalStationIcao>LLBG</ArrivalStationIcao>
    <StdUtc>2013-05-16T09:45:00+02:00</StdUtc>
    <StaUtc>2013-05-16T10:27:00+02:00</StaUtc>
    <PaxCount>2</PaxCount>
    <CrewCount>2</CrewCount>
    <FlightType>Private</FlightType>
  </Leg>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo Test</Name>
    <DateOfBirth>1938-04-26T00:00:00+02:00</DateOfBirth>
    <PassportNumber>ID# abcdefg</PassportNumber>
    <Country>Italy</Country>
    <LastName>Demo</LastName>
    <FirstName>D</FirstName>
  </Passenger>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo D</Name>
    <DateOfBirth>1938-04-26T00:00:00+02:00</DateOfBirth>
    <PassportNumber>abcdddd</PassportNumber>
    <Country>Italy</Country>
    <LastName>Demo</LastName>
    <FirstName>D</FirstName>
  </Passenger>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo D</Name>
    <DateOfBirth>1938-04-26T00:00:00+02:00</DateOfBirth>
    <PassportNumber>ddddddd</PassportNumber>
    <Country>Italy</Country>
    <LastName>Demo</LastName>
    <FirstName>D</FirstName>
  </Passenger>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo D</Name>
    <DateOfBirth>1938-04-26T00:00:00+02:00</DateOfBirth>
    <PassportNumber>rrrrrrrr / exp. 12.01.15</PassportNumber>
    <LastName>Demo</LastName>
    <FirstName>d</FirstName>
  </Passenger>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo 2</Name>
    <DateOfBirth>1973-12-10T00:00:00+01:00</DateOfBirth>
    <PassportNumber>qqqqqqq</PassportNumber>
    <Country>Italy</Country>
    <LastName>Demo</LastName>
    <FirstName>2</FirstName>
  </Passenger>
  <Passenger>
    <LegID>-1</LegID>
    <Name>Demo 2</Name>
    <DateOfBirth>1973-12-10T00:00:00+01:00</DateOfBirth>
    <PassportNumber>yyyyyyy</PassportNumber>
    <Country>Italy</Country>
    <LastName>Demo</LastName>
    <FirstName>2</FirstName>
  </Passenger>
  <CrewMember>
    <LegID>-1</LegID>
    <Name>D Crew</Name>
    <DateOfBirth>1960-03-04T00:00:00+01:00</DateOfBirth>
    <PassportNumber>223423</PassportNumber>
    <Country>United Kingdom</Country>
    <CrewType>SIC</CrewType>
    <MiddleName>.</MiddleName>
    <LastName>D</LastName>
    <FirstName>Crew</FirstName>
  </CrewMember>
  <CrewMember>
    <LegID>-1</LegID>
    <Name>D Crew</Name>
    <DateOfBirth>1960-03-04T00:00:00+01:00</DateOfBirth>
    <PassportNumber>wewqe</PassportNumber>
    <Country>United Kingdom</Country>
    <CrewType>SIC</CrewType>
    <LastName>D</LastName>
    <FirstName>Crew</FirstName>
  </CrewMember>
  <CrewMember>
    <LegID>-1</LegID>
    <Name>D Crew</Name>
    <DateOfBirth>1960-03-04T00:00:00+01:00</DateOfBirth>
    <PassportNumber>sdsdf</PassportNumber>
    <Country>United Kingdom</Country>
    <CrewType>SIC</CrewType>
    <MiddleName>v</MiddleName>
    <LastName>D</LastName>
    <FirstName>Crew</FirstName>
  </CrewMember>
  <HandlingRequest>
    <HandlingRequestID>-1</HandlingRequestID>
    <HandlingRequestBatchID>-1</HandlingRequestBatchID>
    <OperatorName>SPA</OperatorName>
  </HandlingRequest>
  <HandlingRequestBatch>
    <HandlingRequestBatchID>-1</HandlingRequestBatchID>
    <FboName>Jeddah</FboName>
    <HandlingStationIcao>OEJN</HandlingStationIcao>
    <GeneratedUTC>2013-05-16T15:26:46+02:00</GeneratedUTC>
    <Version>2.0.0</Version> 
  </HandlingRequestBatch>
</HandlingRequestDataSet>