Connecting your systems

A warranty process touches other systems: the ERP that holds parts and prices, the finance system that pays claims, the SAP service a manufacturer already runs. Fleetlane connects to them under Settings › Integrations, which has four tabs: External Systems, Webhooks, API Keys and Traffic.

flowchart LR
  PR["Claim item pricing<br/>catalogue search"] --> ES["External system<br/>address, encrypted credentials"]
  LA["Lifecycle actions<br/>Call and OData"] --> ES
  ES --> ERP["Your ERP and<br/>other systems"]
  ES -.-> TR["Traffic log"]

External systems

An external system records how Fleetlane reaches one of your systems:

• Identity: a unique code, a name and a description
• Environment: development, staging or production, so test and live systems are never confused
• Base URL: an HTTP or HTTPS address, with no credentials, query string or fragment in it
• Authentication: see below
• Request settings: a timeout (30 seconds by default, up to five minutes) and custom headers sent with every request

Fleetlane supports these authentication methods:

Method	What you provide
None	Nothing
Basic	Username and password
API key	The key, and the header it is sent in
Bearer token	A token
OAuth 2.0 client credentials	Client ID, client secret, token URL and optional scope

Credentials are encrypted before they are stored. A system can be switched off without deleting it.

External systems belong to a lane. A test lane has its own, usually pointing at test copies of your systems; production’s connections are not visible from it, and the reverse. See Lanes.

OData services

Many manufacturers expose their back-office data as OData, SAP systems in particular. For any external system with a base URL, you can import an OData service by giving the path to its metadata document. Fleetlane fetches the metadata using the system’s own authentication. It then records the service’s entity sets, entity types and OData version. Importing again refreshes the stored description.

Parts catalogue and pricing from your ERP

Materials and prices usually already live in your ERP. Fleetlane sources them from there, so nobody keys parts or prices in twice. Each ERP is reached through a catalogue adapter, built for the system you run. This is set up in two places:

1. The external system is marked as your parts catalogue, with the catalogue’s currency.
2. Each material type (for example parts) gets a pricing mode:
   • Manual: the amount is entered by hand
   • Local: priced from Fleetlane’s own material list
   • External: priced from your ERP, through the chosen external system

For an externally priced material type, a search policy controls which products users can pick. It sets a base filter on the catalogue, and whether to search by internal reference, by name or both. It also sets a default unit and the sort order.

When catalogue search is switched on, users search your catalogue directly while adding a claim item. The price comes from the catalogue and the quantity. Fleetlane stores a snapshot on the item: the part number, description, unit price, currency and the time the price was fetched. A claim keeps the price it was raised with, even if the catalogue price changes later.

The same approach extends to other data your ERP owns: Fleetlane holds the vehicle and warranty data, and refers to documents in your other systems rather than copying them.

Lifecycle actions that call your systems

Every status change in Fleetlane is decided by a lifecycle policy, and each policy runs actions. Several action types can reach outside Fleetlane:

• Call actions send an HTTP request to a configured system, using GET, POST, PUT, PATCH or DELETE.
  • The path, headers, query parameters and body can include values from the claim and the action’s inputs.
  • The response is mapped into named outputs.
  • Success is judged by HTTP status and, where you need it, by a business field in the response, for example accepted: true.
  • Error messages and codes can be read from the response, so a rejection shows your system’s own reason.
  • Timeout and retry attempts are set per action.
• OData actions read or update an OData service. They target an entity set or a single entity by its key fields, with select, expand, filter, ordering and paging options.
• Check actions evaluate rules against the claim’s data without calling anything.
• Code actions run small pieces of custom logic that return explicit outputs.

The result of each action decides the next status. Every run is recorded in the claim’s lifecycle history. You can therefore submit a claim to a manufacturer’s system, read its decision back and move the claim on, without anyone copying data between screens.

API keys

API keys authenticate systems that deliver events into Fleetlane. The lifecycle engine’s own event deliveries use this mechanism, with a key limited to event delivery.

• A key belongs to one organisation’s Fleetlane and cannot be used against another.
• Each key is limited to the scopes chosen when it is created. It can also be given an expiry date.
• The full key is shown once, when it is created. After that Fleetlane only shows its prefix.
• A key can be revoked at any time. Revoked or expired keys are refused.
• Keys are sent in the x-api-key header.

Traffic

When an integration misbehaves, the first question is what was actually sent and what came back. The Traffic tab lists recent integration activity, including calls Fleetlane made to your systems and event deliveries that failed. Each entry shows:

• direction (inbound or outbound)
• the system or integration involved
• the event type, and the claim or vehicle concerned
• outcome (success, failure or rejected), with the HTTP status and any error code
• a message, and previews of the request and response
• duration and a correlation ID

For outbound calls, each entry also shows the HTTP method and path.