Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languagede

Das RTI (Remote Tracking Interface) ermöglicht den Zugriff auf YellowFox Funktionen und Daten über HTTP von Software DritterDrittanbietern. Die technische Dokumentation und Funktionsübersicht finden Sie hier.

Panel
titleInhaltsverzeichnis

Table of Contents
maxLevel3
indent20px

Einleitung

Die RTI Schnittstelle bietet Ihnen die Möglichkeit Daten aus YellowFox in andere Systeme zu übertragen. Ebenso haben Sie die Möglichkeit Daten an YellowFox zu übergeben. So können Sie beispielsweise:

  • Positionsdaten abrufen
  • Fahrzeugeinstellungen ändern
  • Formular- und Auftragsdaten holen
  • neue Aufträge und Nachrichten versenden
  • Dateien hochladen
  • Zeitbuchungen verwalten
  • Adressen importieren

Die RTI Schnittstelle bietet noch viele weitere Funktionen, die Sie unserer technischen Dokumentation entnehmen können. Wenn Sie sich dafür interessieren Touren an YellowFox zu übergeben oder Tourdaten abzurufen, sollten Sie sich unseren separaten Tour Webservice anschauen.

Voraussetzungen und Einrichtung

Die RTI

muss vom YellowFox Innendienst für Ihre Firma freigeschaltet werden. Nach erfolgter Freischaltung finden Sie im Menü "Extras" das Untermenü "RTI (Schnittstelle)".

Schnittstelle muss für Sie durch unseren Innendienst freigeschaltet werden. Kommen Sie dazu gern auf uns zu. Nachdem das Modul freigeschaltet wurde, finden Sie im Portal über das Hauptmenü → Verwaltung → Administration → RTI Schnittstelle die nötigen Einstellungen.

Um RTI Funktionen nutzen zu können, müssen Sie zunächst die benötigten RTI Schlüssel erzeugen.


Was ist ein RTI Schlüssel?

Die RTI Schnittstelle nutzt eine 2-stufige Authentifizierung. Das bedeutet, dass Sie bei jedem Zugriff 2 Schlüssel mitgeben müssen um unautorisierte Zugriffe zu vermeiden. Diese Schlüssel können Sie über das Portal erzeugen. Ein Schlüssel ist ein zufällig erstellter hexadezimaler Code. RTI Schlüssel sind vertrauliche Informationen und sollten nur weitergegeben werden, sofern es nötig ist. Nur mithilfe dieser Schlüssel sind Daten über die Schnittstelle abrufbar. YellowFox unterscheidet in 4 Arten von Schlüssel:

  • Firmenschlüssel: dieser Schlüssel identifiziert Ihre Firma und muss bei jeder Anfrage mitgegeben werden.
  • Fahrzeugschlüssel: dieser Schlüssel identifiziert ein einzelnes Fahrzeug. Er wird für Anfragen benötigt, die fahrzeugbezogene Daten wie z.B. Ortungsdaten zurückgeben.
  • Gruppenschlüssel: dieser Schlüssel identifiziert eine Fahrzeuggruppe. Mit einem Gruppenschlüssel können Sie z.B. Ortungsdaten aller Fahrzeuge abrufen, die dieser Gruppe zugeordnet sind. ACHTUNG: Es werden nur Daten für Fahrzeuge ausgegeben, die auch selbst einen Fahrzeugschlüssel besitzen!
  • Importschlüssel: dieser Schlüssel agiert als universeller Schlüssel. Er wird benötigt um Daten von allen Fahrzeugen abzurufen oder auch auf personenbezogene Daten zuzugreifen.


RTI Schlüssel erzeugen

RTI Schlüssel müssen über das Portal erzeugt werden. Gehen Sie dazu in die RTI Einstellungen. Unter Globale Schlüssel können Sie den Firmen- und Importschlüssel erzeugen. Wenn Sie bereits einen Schlüssel erzeugt haben, können Sie diesen auch ändern oder löschen. Eine Änderung würde dazu führen, dass der Schlüssel neu erzeugt wird. Das ist beispielsweise hilfreich wenn Sie den Schlüssel versehentlich an jemanden weitergegeben haben, der nicht auf Ihre Daten zugreifen können soll. Wenn Sie den Schlüssel löschen, sind Funktionen, die diesen nutzen, nicht mehr erreichbar.

Über Fahrzeugschlüssel können Sie die Schlüssel für die Fahrzeuge erzeugen. Fahrzeuge können auch ohne den Schlüssel zu entfernen vorübergehend für das RTI gesperrt werden. So können Sie einem Partner vorübergehend Zugriff auf ein Fahrzeug geben, z.B. während es eine bestimmte Tour fährt und anschließend den Zugriff wieder unterbinden. Sie können Fahrzeuge jederzeit aktivieren und wieder deaktivieren. Fahrzeuge sind nicht nur über den RTI Schlüssel identifizierbar, sondern optional auch über einen so genannten RTI Ident. Während der Schlüssel automatisch durch das System vergeben wird, können Sie den Ident frei vergeben. Das ist beispielsweise hilfreich um die Schlüssel einfacher in einem anderen Programm verwalten zu können. RTI Idents können nur in Kombination mit einem passenden Gruppenschlüssel verwendet werden. Eine Anleitung dazu finden Sie in der technischen Dokumentation. Über das Aktionsmenü können Sie weiterhin über RTI Links einige Beispielaufrufe sehen. 

Unter Fahrzeuggruppen Schlüssel können Sie die Schlüssel für Fahrzeuggruppen erzeugen. Hier sehen Sie auch noch einmal übersichtlich welche Fahrzeuge sich in den jeweiligen Gruppen befinden, ob diese bereits einen Schlüssel haben oder derzeit gesperrt sind. Fahrzeuge ohne Fahrzeugschlüssel werden in Abfragen mit Gruppenschlüsseln auch wenn sie der Gruppe zugeordnet sind nicht aufgeführt.


Netzwerkzugangsprofile

Wenn Sie für Ihre Firma Netzwerkzugangsprofile angelegt haben, so haben diese auch Auswirkungen auf RTI Anfragen. In den Einstellungen des Moduls können Sie Ihrer Firma Profile zuweisen. Anfragen die aus einem unbekannten Netz kommen werden dann automatisch unterbunden.

Vollständige Funktionsübersicht

  • Für jedes Fahrzeug und jede Fahrzeuggruppe für die das RTI genutzt werden soll, muss ein Schlüssel erzeugt werden, der Fahrzeug oder Gruppe eindeutig identifiziert. Außerdem muß für Ihr Unternehmen ein Sicherheitsschlüssel erzeugt werden. Die Kombination aus Fahrzeug-, Gruppenschlüssel und Sicherheitsschlüssel verhindert unberechtigten Zugriff auf Ihre Fahrzeuge.
  • Einleitung YellowFox Remote Tracking Interface

    Mit Hilfe des YellowFox Remote Tracking Interface (RTI) können unter anderem folgende Funktionen außerhalb des
    Portals augeführt werden:

    • einmalige, sofortige Ortung eines Fahrzeuges oder einer Gruppe von Fahrzeugen
    • automatische Ortung eines Fahrzeuges alle X Km
    • automatische Ortung eines Fahrzeuges alle X Min
    • Aktivierung des Bewegungsmelders für eine Fahrzeuge
    • Ermittlung er letzen Positionsmeldungen eines Fahrzeuges oder einer Gruppe von Fahrzeugen
    • Darstellung der letzen Positionsmeldung auf einer Karte
    • Versenden von Aufträgen an Fahrzeuge
    • Empfangen von Auftragsstatus aus Fahrzeugen
    • Versenden / Empfangen von Nachrichten an Fahrzeuge
    • Einrichten von Fahrzeugen für Auftragsverwaltung/Nachrichten
    • Addressimport über YellowFox Geocoder

    Die verfügbaren Funktionen und deren Gebrauch sind unter diesem Link detailliert beschrieben.

    Generierung der benötigten Schlüssel

    1. Wählen Sie bitte das Untermenü "RTI (Schnittstelle)" in "Extras" aus.
    2. Zuerst erstellen Sie bitte den Sicherheitsschlüssel für Ihre Firma.
      1. Wählen Sie dazu als Aktion "RTI Schlüssel erzeugen"
      2. Der neue Schlüssel wird dann direkt angezeigt
    3. Erzeugen Sie nun die Schlüssel für alle Fahrzeuge oder Gruppen, die sie mit RTI steuern oder abfragen wollen.
      1. Wählen Sie hierzu entweder für jedes Fahrzeug und/oder für jede Gruppe die Aktion "RTI Schlüssel erzeugen" oder haken Sie alle Fahrzeuge oder Gruppen an und klicken jeweils oben auf das Icon "RTI Schlüssel für ausgewählte Elemente anlegen"
      2. Nach einer kurzen Wartezeit werden die neuen Schlüssel angezeigt und können sofort verwendet werden.
    4. Um den Zugriff auf ein Fahrzeug oder eine Gruppe zu unterbinden können Sie wiederum die Einzelaktion "RTI Schüssel löschen" wählen oder erneut mehrere Fahrzeuge oder Fahrzeuggruppen auswählen und oben die Funktion "RTI Schlüssel für ausgewählte Elemente löschen" anklicken.
    5. Sie können Schlüssel jederzeit neu erstellen oder auch löschen, beachten Sie bitte das bei jeder Erzeugung ein neuer Schlüssel erstellt wird, und der alte Schlüssel für das RTI nicht mehr benutzt werden kann.

    Das Remote Tracking Interface ist nun eingerichtet und kann verwendet werden.

    Für Fahrzeuge und Fahrzeuggruppen kann über die Aktion "RTI Links" ein Beispielaufruf generiert werden. Dies gibt Ihnen die Möglichkeit zu sehen, wie ein Aufruf im Betrieb erfolgen sollte und wie eine Rückgabe aussehen kann.

    Beachten Sie bitte, dass Sie jedem Fahrzeug, dass einer Gruppe angehört, auch einen Fahrzeugschlüssel zuweisen, dass Zuweisen nur eines Gruppenschlüssels reicht nicht, um dieses Fahrzeug mit dem RTI nutzen zu können!

    Einstelltungen

    Netzwerkzugangsprofile

    Um den Zugriff auf die RTI Schnittstelle auf vertrauensvolle Netzwerkadressen zu beschränken (z.B. Unternehmensnetzwerk), gibt es die Möglichkeit Profile zu erstellen und zu verwalten, die bestimmte Netzwerkadressen oder -bereiche beschreiben.

    Diese Profile können dann der Firma zugeordnet werden. Wenn eine Anfrage über das RTI gestellt wird, wird dann als erstes überprüft, ob die Anfrage von einer IP-Adresse kommt, die über eines der zugeordneten Profile erlaubt ist.

    Ansonsten wird die Anfrage mit einer Fehlermeldung abgewiesen.

    Weiterführende Informationen

    Technische Dokumentation

    Sv translation
    languageen

    The RTI (Remote Tracking Interface) allows you to use YellowFox functions and access its data via HTTP in third party software. You can find the technical documentation here.

    Panel
    titleIndex

    Table of Contents
    maxLevel3
    indent20px

    Requirements

    Introduction

    • the RTI function must be activated for your company by YellowFox indoor service. After a succesful activation you will find in the "Extras" menu the "RTI (interface)" option.
    • For every car or group you want to use with the RTI must be get a authorization code. The combination of the object and the company key denied the unauthorized access of one of your vehicles.

    Introduction YellowFox Remote Tracking Interface

    With the YellowFox Remote Tracking Interface (RTI) has among others following portal functions:

    • track a vehicle or group once
    • set automatic trace every X KM
    • set automatic trace every X Min
    • activate the motion detector
    • get the last poistion of a vehicle or a group
    • Show the last position on map
    • send orders to vehicles
    • receive order states from vehicles
    • send/ receive messages
    • set up vehicles for Order Management/Message Management
    • address import via YellowFox Geocoder

    The description for available functions and their usage can be found via this link.

    Generate the authorization keys

    1. Go to the RTI (Extras --> RTI(interface))
    2. Generate the key for the company. 
      1. Just select the "Create RTI key" action.
      2. The new 32 char key will be shown directly
    3. Generate now the keys for you vehicles and groups you want to use for RTI. 
      1. For a single vehicle or group just use the action "Create RTI key" similar to get the company key.
      2. To generate the keys for multiple (or all) vehicles or groups first check the desired vehicles or groups and then use the upper left icon to "create RTI keys for selected elements"
      3. after a short waiting dialog the keys will be shown directly
    4. To reject access to a vehicle or group either use the action "Delete RTI key" or again check the desired vehicles or groups and use the icon "delete RTI keys for selected elements" on top of the page

    At every time you are able to generate new keys or to delete them. Please note, that if a new key was generated, the old one will be invalid.

    The Remote Tracking Interface setup finished and you can use this function.

    For each vehicle and group with a key there is an additional action "RTI links". Select this action will show a dialog with some example links to see how to use the rti functions with according return values.

    Please note, if you want to use a group, all belonging vehicles must have a vehicle key. The allocation of a group key is not enough!

    Settings

    networkt access profiles

    In order to limit access to the RTI interface to trustworthy network addresses (e.g. company network), there is the option of creating and managing profiles that describe certain network addresses or areas.

    The RTI interface offers the possibility to access data from YellowFox and import it into another system. You might also import new data to Yellowfox. You might for example:

    • access position data
    • change vehicle settings
    • get form or order data
    • send new orders or messages
    • upload files
    • manage time bookings
    • import addresses

    The interface offers much more functions, which you can read about at the technical documentation. If you are interested to import Tours to YellowFox or to access tour data, you might take a look at the separate Tour Webservice

    Requirements and Setup

    The RTI interface must be activated by our in-house staff. Feel free to contact us. After the module has been unlocked, you can access its settings via the mainmenu → Administration → Administration → RTI Interface.

    To use the interface you have to generate RTI keys first.


    What is a RTI key?

    The RTI interface uses a 2-step-authentification. This means you always have to pass 2 keys to avoid unauthorized access. These keys are generated at the portal. A key is a random hexadecimal code. RTI keys are sensitive information and should only be shared if needed. Only by using these keys you can get data via the interface. YellowFox distinguishes 4 types of keys:

    • company key: This key identifies your company and is needed for any request.
    • vehicle key: This key identifies a single vehicle. It is needed for accessing vehicle data, like e.g. position data.
    • group key: This key identifies a vehicle group. By using a vehicle key you might e.g. get position data of all vehicles which are part of this group. Attention: Only data of vehicles which own a vehicle key will be returned!
    • import key: This key is an universal key. It is used to access all cars or personnel data.


    Create RTI keys

    RTI keys are generated via the portal. Go to RTI Interface settings. At global keys you can generate the company and import key. If you already generated a key, you might also change or delete it. A change would lead to the key being generated again. This might be helpful if you unintentionally shared a key with someone who wasn't supposed to see it. If you remove a key, all functions which use it are not accessible anymore.

    Via vehicle keys you can generate a key for each vehicle. Vehicles might be deactivated without having to remove the key. For example you could activate a key for a partner while the vehicle is working on a specific tour and after the tour is finished, you can lock the vehicle again. Vehicles can not only be identified by a key, but also by a so called RTI ident. While the key is generated automatically, you can set the ident by yourself. This might be helpful to manage keys easier in another program. Idents can only be used if you combine them with a valid group key. You can find the instructions to use RTI idents at the technical documentation. You can use the action menu to get some example calls via RTI Links.

    Via vehicle group keys you can generate the keys for vehicle groups. Here you can also see the assignments of vehicles to each group and if the vehicles even have a key or are currently locked. Vehicles without vehicle keys are not considered in group requests even if they are assigned to the group.


    Network assign profiles

    If you created network assign profiles for your company, these do also influence RTI requests. You can assign them to your company at the settings. Request from an unknown network will be quit automatically.

    Full documentation

    These profiles can then be assigned to the company. When a request is made via the RTI, the first thing that is checked is whether the request comes from an IP address that is permitted via one of the assigned profiles.

    Otherwise the request will be rejected with an error message.Further Informations

    Technical documentation