Set up AI providers and freight document templates

Guide information

Audience: Administrator

Time required: about 10 minutes

Outcome: at least one AI Provider carries a working API key and passes Test Connection, and the 5 freight document templates are confirmed ready for Fill a booking or shipment from a document with AI

Requirements

This tutorial requires the installation of the following applications/modules:

• Document Parsing - a paid add-on you install separately (installing it, with Freight Forwarder Management already active, activates Freight Document Parsing automatically - this is what loads the 5 freight document templates confirmed in this guide)

Every AI-assisted extraction in Fill a booking or shipment from a document with AI depends on at least one provider that actually answers. Skip this setup and the first person who clicks Import from Document hits a connection or API-key error instead of a filled-in shipment - and mistakes a configuration gap for a broken feature. This is a one-time setup per company, not a per-shipment step.

Running scenario: Hai Long Logistics starts with the six providers included in the module. Google Gemini is marked as the default after installation; for this walkthrough, the administrator makes the approved OpenAI provider the default and tests its connection before the Documentation team uses it.

Open the AI Providers screen

Go to Settings ‣ Document Parsing ‣ AI Providers.

Note

This screen sits directly under the Settings app - it needs no Developer Mode and is not under Technical. Only a user in Settings –> Users & Companies –> Users, tab Access Rights, section Administration, with the Settings access level (base.group_system) can create or edit a provider here; this is a different, more technical level than the freight Administrator access level described in the user’s Freight access in Settings > Users & Companies > Users - on a small team like Hai Long Logistics, the same person (Duc) usually holds both.

The list shows six providers, seeded with a name and a default model but no API key yet: Google Gemini, Groq, OpenRouter, OpenAI, Anthropic Claude and Ollama (Local). The Google Gemini row already carries the Default flag - the provider the Import from Document wizard pre-selects until you change it.

Tip

The setup is correct when: the list shows all 6 seeded providers, and the Google Gemini row is the one flagged Default.

Decide which AI provider to set up

Option	Use when	What changes
Use a seeded provider (OpenAI in this walkthrough)	Your company has approved the provider and model for the documents being processed	No new record is needed; add the provider’s API key and set it as default only if the team should have it preselected
Create a Custom (OpenAI-compatible) provider	Your company runs its own LLM endpoint, or uses a vendor not in the seeded list	You create the record by hand and must fill in API Base URL yourself - Custom has no seed to start from
Switch the Ollama provider’s model to llava or llama3.2-vision	You run AI locally through Ollama and need it to read scanned images or PDFs	Ollama’s seeded default model (llama3) reads text only - the vision-capable models let it read the same files Google Gemini or OpenAI can

Use a provider and model approved for your company’s data, security and cost requirements, and confirm the model can read the file types your team processes. If that approval or the model’s capability is unclear, ask the AI/IT administrator before adding a key or changing the default provider.

Enter the API key for your provider

A seeded provider already has a model and endpoint configured. Before using it, confirm that the model is approved for your documents and can read their file type; an API key is also required for the connection test to pass.

Open the OpenAI row, set Default Provider on for this example, and fill in its API Key using the credential supplied through your company’s approved secret-management process. The field shows only masked dots once saved; Viindoo does not show a saved key back to you.

Note

API Base URL is not shown for OpenAI because the provider uses its configured endpoint. It is available for Ollama (Local) and Custom (OpenAI-compatible), where the endpoint depends on your environment.

Tip

This step is done when: the API Key field shows the masked dots instead of being empty, and the form has been saved.

Test the connection

A saved key can still be wrong - typed with an extra space, copied from the wrong project, or already revoked. Testing now catches that before Ops or Sales hits it in the middle of processing a real Shipping Instruction.

Click Test Connection, at the top of the provider’s form.

After you click it, Viindoo sends a minimal request to the provider and reads back the answer. With the OpenAI key configured for this walkthrough, the notification reads Connection Successful - “Provider ‘OpenAI’ is reachable and responding correctly.” A wrong key or unavailable endpoint shows an error instead.

Tip

Step is done when: the green “Provider ‘OpenAI’ is reachable and responding correctly.” notification appears - not an error.

Confirm the freight document templates are ready

The freight document templates are data the module loads on install, not something you create here - this step only confirms they came in intact, because a missing template means Ops cannot pick the right document type at all when running Fill a booking or shipment from a document with AI.

Go to Settings ‣ Document Parsing ‣ Document Templates.

The list shows 5 rows: Booking Confirmation, Shipping Instruction (FCL), Shipping Instruction (LCL), Bill of Lading (Ocean) and Arrival Notice. Check the Target Model column: Booking for the first row, Logistics Shipment for the other four.

See also

• Fill a booking or shipment from a document with AI - the wizard that reads a document against these templates and the provider you just configured.

Tip

The setup is correct when: all 5 rows are present, none of them archived, and the Target Model column reads Booking or Logistics Shipment as listed above.

Known limitations

Step	What Viindoo does today	What you do instead
Test the connection	A markup defect on the form places the button at the top of the form instead of in the usual button bar; the button still works	Look for Test Connection at the top of the provider’s form, not in the status bar
Create a Custom provider	No sample record to copy from - unlike the other 6 providers, Custom has nothing pre-filled	Fill in every field by hand, starting with API Base URL, which is required for this provider

Troubleshooting

“Unsupported provider” when analyzing a document

Symptom: The Import from Document wizard shows “Unsupported provider: …”.

Cause: The provider’s record was written with a value outside the 7 supported ones (OpenAI, Anthropic Claude, Google Gemini, Groq, OpenRouter, Ollama (Local), Custom) - this normally only happens if the value was written through a route other than this screen, such as an import or an API call.

Fix:

1. Open the provider from Settings ‣ Document Parsing ‣ AI Providers.

2. Re-select a valid value for Provider, then save.

“Ollama requires an API Base URL…”

Symptom: Test Connection or Analyze Document fails with a message asking for an API Base URL.

Cause: Provider is Ollama (Local) but API Base URL was left empty - Ollama has no single well-known address the way a cloud provider does.

Fix:

1. Enter your Ollama server’s address in API Base URL (for example http://192.168.1.100:11434).

2. Click Test Connection again.

“Model ‘…’ cannot read images or PDF pages”

Symptom: Analyzing a scanned PDF or a photo fails with this message, even though Test Connection passed.

Cause: The model assigned to the provider is marked Vision Support: No in the AI Models catalog - Test Connection only checks that the provider answers, not that its model can read images.

Fix:

1. Go to Settings ‣ Document Parsing ‣ AI Models and check the model’s Vision Support value.

2. Assign the provider a model marked Vision Support: Yes instead (for Ollama, llava or llama3.2-vision).