funnel.travel® - Documentation

The corporate post-booking travel management tool

Getting started

After signing up for funnel.travel, there are a few optional steps to refine the setup

Also, some points regarding your account you need to be aware of:

GF67M1

General

funnel.travel has a fairly simple structure. The sections are:

Trip

The dashboard shows business trips as they progress from "departing soon"” to "currently away" to "recently returned". The home button () navigates back to the dashboard

Setup

Finances and numbers

Most pages show a search bar. The search term(s) entered cover all searchable properties, ie. searching for "jackson" on the user page will search for "jackson" in the username, first and last name etc.

Property-specific search
To restrict a search term to a specific property, prefix the the term with the property name. Valid property name can be found by clicking on the help icon help next to the search.
lastname:jackson
Range search
When searching for dates or numbers, often a range restriction is desirable. Valid restrictions are <=, >=, <, >
lastLogindate:>=01.01.2019
Wildcard search
For literal search terms, funnel.travel will automatically use a 'contains' strategy, ie. searching for 'ack' will find 'Jackson' because that literal contains 'ack'. By providing wildcards, and/or adding operators indicating your intent, you can help funnel.travel deliver better search results.
lastname:=jackson
lastname:=jack%
lastname:~jack
The first example will find users with an exact last name of 'Jackson'. The second example will find users with a last name starting with 'Jack'. The second example will find users with a last name containing 'jack' (this is the same as not providing an operator).
10HBF5

Auto-complete

There are two input field types which support auto-complete. References to other funnel.travel entities always offer autocomplete, while regular input fields for dates (or date/time) will also expand the entry to a valid date

Entity references
Date auto-complete
Date(time) fields attempt to expand a user entry to the next date in the future. For European users (date format day-month-year):
153 will expand to the nearest March 15th in the future
15317 will expand to March 15th, 2017
GB6M8O

Data scope

funnel.travel shows your name, organization and account name in the navigation bar (top left). For users with the authority to manage multiple organizational units (arrangers, client admin) or even accounts (community admin, system admin), the displayed organization and account name switch to a dropdown on hover.

UH7M23

Dashboard

The "home" page of funnel.travel is a configurable dashboard. Available gadgets are:

The video below illustrates how the dashboard can be configured:

Billing account

A billing account serves several purposes:

Is the entity funnel.travel will invoice. Defines a set of rules for password security. Allows for adding a logo and/or changing some CSS styles Also, described in extensions in detail, the billing account holds the core extension setup.

Company nameCompany name, max. length is 128 characters
Addressthe address printed on the invoice
CountryThe country relevant for invoicing. Note that each organization has a separate location/country
Contact email
CodeThe account code is mainly used internally, eg. in URLs
Financial settings
VAT IDIf present, the VAT ID is printed on the invoice. Some countries have restrictions regarding tax handling and require a VAT ID to be printed on the invoice.
System behavior
Default localeLocale used for new users
Max age returned tripTrips with a return date older than the set value (in days) are deleted. Set to 0 to disable.
Delete idle user afterUsers with a 'last returned' older than the set value (in days) are deleted. Set to 0 to disable.
Use arrangersIf activated, arrange-specific fields on user / organization are visible.
Traveler handling When receiving booking data from a producer extension, funnel.travel attempts to assign a traveler based on email address. If no traveler is found:
  • "Auto-create travelers": if no matching user is found, a new one is created on-the-fly. The failure to create and/or match a user is registered as a quality issue.
  • "Manually create travelers": users are not created from booking data, but are assumed to be present. Thus, the failure to create and/or match a user is registered as a quality issue.
  • "Never create travelers": users are not created from booking data, and are not assumed to be present. The failure to create and/or match a user is never registered as a quality issue.
Password fields These fields allow for adjusting the password security:
  • Expire password after (days)
  • Min. password length
  • Min. digits in password
  • Min. special characters in password
Profilesync systemAllows for connecting funnel.travel to a traveler profile suite
Next trip IDThe next value for the funnel.travel trip identifier. Update with care, as setting to a lower value might result in the system attempting to generate trips with an already used identifier.
Look & feel
CSS / LogoSee Look & feel

Connecting to a traveler profile suite

Some extensions might require traveler profile data which is not present in funnel.travel. By connecting to a traveler profile suite such as Umbrella Faces, funnel.travel can retrieve traveler profiles and feed that data into the configured extensions.

Profiletool systemUmbrella Facescytric cCPS
Profiletool endpointURL of Umbrella Faces serverURL of cCPS endpoint
Profiletool API keyAPI key provided by UmbrellaCLIENT ID
Profiletool group- not used -cCPS system name
Profiletool secretAPI secretCLIENT password

Password security

The password security fields allow for defining password guidelines which are in line with your corporate standards.

Look & feel

funnel.travel allows for two basic means of adjusting corporate identity. A logo can be placed at the upper left corner, the logo height is limited to 50px. Furthermore, a custom CSS can be uploaded, with all the styling power which comes with CSS.

1VSG87

Organization

While an account gives you some global settings, the main entity defining your corporate structure is the “organizational unit”. Users are connected to an organizational unit, and - by proxy - so are trips. Thus, whatever structure defines your travel rules (budget, expense limits) and/or processes (eg. arranger assignment) should reflected as organizational unit. The name was chosen to be very generic, because organizational units could be many things:

Organizational units can have a parent organizational unit, which allows to map a hierarchy. Child organizational units inherit from their parent.

NameName of the unit, max. length is 128 characters
Parent organizationBy setting a parent organization, hierarchies can be defined. This is especially useful when working with organization-wide travel arrangers
LocationGeographical location of this organization unit. This location is used when processing trip data to determine what is the "home base"
DescriptionA free-text description of the organization unit, max. length is 128 characters
LocatorsTravel agency locators such as a CETS agency ID, Amadeus OID or Galileo PCC. If the producer extension(s) used have a status ""source", locators can be used to assigned generated trip to organizations (and consequently consumer/modify extensions can be called with overriding settings).
Extension setting overridesIf the account has activated extensions which allow for per-organization settings overrides, those settings are listed here

Cross-account organizations

An organizational unit is linked to a billing account. It's noteworthy to point out that not all organizations of a hierarchy need to have identical billing accounts. While these are exceptional cases, funnel.travel allows for a travel arranger to access trip data in a organization hierarchy while the underlying usage might get billed to different accounts.

The structure illustrated above allows for a variety of administration mappings:

7H8ZMQ

Users

Users in funnel.travel are held to a rather minimal data structure. Note that funnel.travel is not a traveler profile management tool. Users are identified by email address, which is this expected to be unique per user.

FQZYLC

Merging users

Two additional users can be merged. This functionality is mainly used when "Auto-create participants" is enabled on the billing account, as this might occasionally produce multiple entries for the same user.

TT5GB2

When merging a user Jonny to another user John:

  1. The properties 'firstname', firstname for non-APS bookings' and 'email' are copied from Jonny to John, provided they corresponding property is empty on John.
  2. All associations to bookings and transport documents (tickets, EMD) are moved from Jonny to John.
  3. If Jonny is an arranger, all arranger mappings are moved from Jonny to John. If John is not already marked as arranger, that flag is set, and the arranger type copied from Jonny to John.
  4. Finally, the user Jonny is deleted

Custom fields

Custom fields can be defined to add corporate information to a trip. Typical examples are a cost center or invoicing guideline. Custom fields are always linked to a specific account, but can be further restricted to individual organization units.

Data types, edit directives

QOG1SB

Providers

funnel.travel holds a global list of travel providers. Additional contact information and a comment field are available per account.

R6C4Z6

Data export

funnel.travel allows for exporting both configuration data, as well as trips to JSON files.

VATNZC

Extensions

Extensions are where things get interesting. There are three kinds of extensions

Producers
will retrieve booking data from an external source such as an e-mail server, GDS or a TMC's midoffice system
Modifiers
take booking data and enhance or change it.
Consumers
read booking data and report it to a third-party system.

Without at least one producer extension, all trips would need to be entered manually in funnel.travel. Without at least one consumer extension, trip data would reside in funnel.travel only.

2OFF4N

Producers

Producers deliver trip data into funnel.travel. There are several delivery mechanisms:

All producers share a basic configuration (and then additional, custom configurations per extension):

PurposeFree text field to describe the setting, eg. "Import Amadeus PNR"
Execution trigger Can be either "Time" or "Webhook"; the former represents a "pull" mechanism, the latter a push. When choosing "Time", two additional settings are available:
  • "Limit execution": "Once" will only process a booking if it's not already present in funnel.travel, ie. modifies are not processed. "Unlimited" will process modifies.
  • "Time expression": A CRON expression defining when and how often the "pull" is executed. See eg. the Cron Expression Generator & Explainer - Quartz to generate an expression
When choosing "Webhook", funnel.travel will generate a webhook URL to be used by the third-party system to push booking data.
Override retriesAllows to override the default retry behavior
Override notificationsAllows to override the default notification behavior
Include travel preferencesGDPR-related setting to indicate whether traveler preferences should be processed.*
Include passport dataGDPR-related setting to indicate whether passport data should be processed.*
Include remarksGDPR-related setting to indicate whether booking remarks should be processed.*

* Whether or not to activate these settings depends on the data stream, ie. the activated modifiers and consumers. Only enable processing for data elements which a modifier and/or consumer extension needs.

Modifiers

Modifiers read trip data from funnel.travel and send trip data back. This can be to augment booking data with eg. flight statistics, but can also execute a ticketing robotic and thus modify the PNR.

Modifiers have the same set of common configuration as Consumers, see the field table there.

Consumers

Consumers read trip data from funnel.travel. There are two delivery mechanisms: "Event" and "Time".

All consumers share a basic configuration (and then additional, custom configurations per extension):

PurposeFree text field to describe the setting, eg. "Feed Viselio API"
Execution trigger Can be either "Time" or "Event". When choosing "Time", an additional setting "Time expression" is available: When choosing "Event", two additional settings "Booking event" and "Offset to booking event" are available:
  • Created
  • Created / modified
  • Created / modified / deleted
  • Departure
  • Return
Note that an "Offset to booking event" can be set. Setting -168(h) on a 'Departure' consumer will notify the consumer 7 days prior to departure.
Limit execution"Once" will only process a booking once, "Unlimited" will consume the booking whenever the execution trigger fires.
Override retriesAllows to override the default retry behavior
Override notificationsAllows to override the default notification behavior
Process bookings fromAllows to limit modifier/consumer to selected producers.

A common mistake is to choose an "Event"-based execution with "Created / modified" in order to process new bookings as well as modifies, but then to leave "Limit execution" at "Once". This effectively disables the modify, as the booking creation will trigger the single execution, after which no more processing occurs.

Extension states

Upon entering funnel.travel, extension states are stored per booking and configured extension. If the extension is only triggered in the future, the states remains as 'PENDING' until execution time is reached.

For calls which resulted in an error:

EP09Q2

Notifications and retries

funnel.travel has a simple but powerful retry / notification configuration in case of extension errors.

Defaults for error handling
Retry on errorIf enabled, funnel.travel will re-try calling the extension periodically (about every 15min). If disabled, the ERROR state can only be resolved manually.
Retry for how many hoursOnly relevant if "Retry on error" is set. Describes the maximum time span since the first call attempt during which retries should be attempted.
Notify via channelCurrently available options are:
NONE | EMAIL | SLACK | RINGCENTRAL | TEAMS
ChannelFor 'EMAIL': the email address the notification should be sent to. For 'SLACK': the Slack webhook the notification should be sent to. For 'TEAMS': the Teams 'Incoming Webhook' URL

The default settings can be overridden per extension. The workflow is:

Extensions provided by WaNT GmbH

Read Amadeus AIRs

The "Amadeus AIR files" extension allows to read PNRs from files created by the Amadeus ProPrinter. The extension can work both as "pull" or "push".

If you'd like the extension to "pull" AIRs, you need to set up an SFTP server with username/password access. Configure the extension with "Time" event, set your desired CRON expression, and configure the SFTP properties. Per execution, the extension will read all available files, and subsequently delete them from the SFTP server..

If you'd like to "push" files to the extension, configure the extension with "Webhook" event and leave the file store controls empty. Once the extension settings are saved, funnel.travel provides you with a webhook URL. Upload files as multipart (using 'file' as parameter name). An example Windows Powershell script which uploads files can be found here.

Data scope settings

Process ghost segmentsIf checked, GK segments will be included in the generate booking data
Include travel preferencesIf checked, seat and meal information will be included in the generate booking data if present in the PNR
Include passport dataIf checked, SR DOCS will be included in the generate booking data
Include remarksIf checked, AIAN/RM/RX will be included in the generate booking data

Read Galileo MIRs

The "Galileo MIR files" extension allows to read PNRs from files created by the Galileo Print Manager. The extension can work both as "pull" or "push".

The behavior and handling is identical to the Amadeus AIR files extension.

Read Sabre IUR files

The "Sabre IUR files" extension allows to read IURs from files created by the Sabre Printing Module (SPM). The extension can work both as "pull" or "push".

The behavior and handling is identical to the Amadeus AIR files extension.

Read CETS WDM files

The "CETS WDM files" extension allows to read XML files from CETS created by the WebDataMover. The extension can work both as "pull" or "push".

The behavior and handling is identical to the Amadeus AIR files extension.

Atriis

The Atriis extension uses the Atriis "Get Trip" to periodically fetch new and updated trips.

Execution triggerNeeds to be set to "TIME", as Atriis has no "push" mechanism.
Use display currencyIf true, the import will favor prices in "display currency" (=agency currency) over "default currency" (=vendor currency).
Discard source systemsAllows to list Atriis source systems which should be dropped. E.g. setting "Amadeus" will then discard all services booked in the Amadeus GDS.
Access credentialsAgency ID, endpoint, username, password and "shared key for credit card" will be provided by Atriis

Note on payment import: payments are imported where the data indicates the agency has made a payment. Hotel guarantees are not imported as payments. Furthermore, low-cost carrier payments are never imported.

Slack

The Slack extension allows to set up notifications using Slack web hooks.

Webhook URLThe URL your Slack admin setup in https://api.slack.com/incoming-webhooks
Displayed usernameSlack notifications display a username. If this field is left empty, the default username defined on the web hook will be used
MessageLike most extensions, the Slack extension receives a full booking data structure. Explore the structure at the funnel.travel API definition to compose messages. Some examples:
  • Just booked trip ${header}
  • ${participants[0].firstname} ${participants[0].lastname} will be traveling on ${departuredate}
ChannelWebhooks have a default channel (used if this field is left empty), but can post on any channel.
Emoji iconAny emoji code supported by slack (https://www.webfx.com/tools/emoji-cheat-sheet/). If left empty, the extension default :airplane: is used.

Umbrella.net

The Umbrella.net extension allows to push booking data to the Umbrella.net midoffice.

Agency mappingAllows to influence the origin and agency ID sent to Umbrella.net
  • Use original agency sends origin 'Atriis' and the Atriis 'OrganizationUnitId' as agency ID
  • Use passive GDS agency sends origin as the passive source system (usually Amadeus) and the Amadeus agency ID agency)
Agency IDDefault / fallback agency ID. funnel.travel will attempt to match the incoming booking to an organization and use the agency locator from that organization. The "Agency ID" is used if that process fails.
Only confirmed/invoicedIf true, only confirmed and/or ticketed services are sent to Umbrella.net

agency) The lookup process is to take the passive GDS source system, and search for an agency locator with matching source on the organizational unit.

File dump

The "File dump" extension allows to export trip data as JSON or XML to a remote server.

Target URLThe target URL of your server. The server must be publicly accessible. While the URL format does allow for adding username and password, use the additional fields in order to prevent exposing the password. Allowed protocols are ftp, sftp and https. Use of FTP is discouraged.
UsernameUsername for authentication to your server
PasswordPassword for authentication to your server
File formatOne of: 'XML', 'JSON'
Pattern for target fileThe target filename can use a date pattern like tripdata-${yyyyMMdd-HHmmss}.xml.

Trip management

Trip detail view

The trip detail view gives an overview of the travel services, the bookings, a change log and the status of extensions related to this trip. Action buttons on the top right allow for switching to edit mode, or download the trip as a JSON file.

5BACSC

Searching

Additional to the standard search options, the trip search offers a few special keywords:

in:currently_away
.. will return all trips where the current date is between departure and return. Other valid "buckets" for trips are extension_errors, departing_soon and recently_returned.
returnedbefore:4
.. will return all trips with a return date within the past 4 months.
ref:AB12CD
.. will search for booking reference number AB12CD.

Matching to an existing

For an incoming, new booking, funnel.travel will attempt to locate an existing business trip which to append the booking to. An existing trip will be used based on the following criteria:

  1. The existing trip has at least one matching participant
    1. Attempt to match participants based on e-mail address
    2. Attempt to match participants based on full name (APS), in the versions 'firstname lastname' and 'lastname, firstname'
    3. Attempt to match participants based on full name (non-APS), in the versions 'firstname lastname' and 'lastname, firstname'
  2. One of the following time-based criteria are met:
    1. The departure date of trip and new booking match +/- one day
    2. The return date of the trip is +/- one day equal to the departure date of the new booking (ie. the new booking appends to an existing trip)
    3. The departure date of the trip is +/- one day equal to the return date of the new booking (ie. the new booking prepends to an existing trip)
    4. The travel dates of the trip are entirely encompassed by the travel dates of the new booking
    5. The travel dates of the new booking are entirely encompassed within the travel dates of the existing trip
P7UU7M

Updating trip data

When using the web client to edit trip data, an internal technical reference (UUID) is used to determine which data entries are to be updated. This approach is deterministic and always yields an updated trip (and the bookings therein) matching the data edited on the screen.

When receiving a booking data update through an extension, however, there typically is no technical reference to work with. In such cases, funnel.travel attempts to locate existing entries based on identifying properties which are assumed to be immutable. As consequence, a change in these identifying properties leads to deletion of the "old" entry and insert of the "new" entry.

Example: given an existing trip with a flight ZRH - EDI, flight no. LX123, departing June 6th at 10.15am. If an extension now sends booking information for a flight ZRH - EDI, flight no. LX123, departing June 6th at 2.20pm, funnel.travel will match this to the existing flight and update the departure time. If an extension then sends booking information for a flight ZRH - EDI, flight no. BA999, departing June 6th at 10.55am, funnel.travel will not match this as the flight number is expected to not change. Consequently, the existing LX123 flight is deleted, and BA999 is added as a new flight.

Identifying properties

ZT7P3M

Trip data issues

There are only very few data issues which influence data processing in funnel.travel

Trips with data issues are listed on the dashboard in the 'Issues' column

FG6M3R

Trip extension issues

If an extension call resulted in an ERROR, the call can be retried manually by clicking on the icon.

Using an external traveler profile suite

If a traveler profile suite is configured (see billing account setup), funnel.travel will attempt to augment booking data with extended profile data per passenger. In the following sequence, there is a distinction between the 'booking traveler' and a 'funnel.travel user'. The former is bound to the booking, and contains only data provided by the producer extension which created the booking. The latter is a user. Each booking traveler can be associated to a funnel.travel user, but it is common practice to work only with booking travelers and not maintain a funnel.travel user base.

The lookup hierarchy is:

  1. Use the booking traveler's source ID, if present. For Amadeus this would be a CSX profile locator
  2. Use the booking traveler's passport, if present.
  3. Use the booking traveler's email, if present. Results returned by the external profile system are matched against the booking traveler's name, in order to prevent mismatches when an arranger's e-mail is used
  4. If the booking traveler is associated with a funnel.travel user, use the funnel.travel user's identifiers.
GFH88M

Reports

funnel.travel offers a very basic built-in reporting. For any more advanced reporting, an extension should be used to export data in the desired format.

A5F0S9