Integrations

The Integrations page holds the connections TrakIT uses to reach other systems: the SMTP servers it sends email through, the FTP servers it saves files to, the channels it sends text and chat messages through, the web APIs that workflow actions post to, and the shipping lines it asks for container events.

To open it, select Admin > Integrations. Only system administrators can open it.

The page has five tabs. It opens on SMTP.

• SMTP: the servers TrakIT sends email through.
• FTP: the FTP and SFTP servers TrakIT saves files to.
• Messaging: SMS, WhatsApp and group chat channels.
• API: calls to other systems’ web APIs.
• DCSA: carrier tracking with the shipping lines’ DCSA Track & Trace APIs.

On every tab, select a row to open it. On the SMTP, FTP, Messaging and API tabs, inactive rows are shown in red.

Caution

Deleting a server, channel or integration with the X at the bottom left of its window happens at once: TrakIT doesn’t ask you to confirm. Only removing a carrier on the DCSA tab asks first.

SMTP tab

TrakIT sends all its email, such as notifications, reports and documents, through an SMTP server. Each company sends through the SMTP Server chosen on its company page. Emails of a company with no server of its own, and emails that don’t belong to a company, go through the first active server in the list.

The server with ID 1 is [System Default]. TrakIT Support looks after it: you can’t open or delete it.

Column	Shows
ID	The server’s number.
Title	The server’s name, as the company page lists it.
Host, User, Port	Where TrakIT connects and the account it signs in with.
Encryption	SSL, or None.
Subject Prefix	The text put before the subject of its emails. Default in grey: your installation’s default prefix.
Sender	The sender name, with the sender address below it.
Max Conn	How many connections TrakIT opens to it at the same time.
Updated By	Who last changed the server, and when.

Create or modify an SMTP server

1. Select Create, or select a server in the list. The Create SMTP Server or Modify SMTP Server window opens.
2. Fill in the fields below.
3. To check the settings, select Send Test Email. TrakIT sends a test email to the address of your own user account, with the settings as they are in the window, saved or not. If it works, TrakIT says SMTP connection succeeded and names the address; otherwise it shows the server’s error.
4. Select Create, or Save for a server that already exists.

Field	What to enter
Title	A name for the server. Required, and different from the other servers’ titles.
Host	The SMTP server’s host name. Required.
User	The user name of the account TrakIT signs in with.
Password	The account’s password.
Port	The port to connect to. Leave it empty to use the default port.
Encryption	On to connect over SSL/TLS.
Subject Prefix	Text put before the subject of every email sent through this server, in place of your installation’s default prefix. #CLIENT# is replaced with the name of your installation. Leave it empty to keep the default prefix.
Sender Email	The address the emails come from. Required.
Sender Name	The name the emails come from. Required.
Reply To	The addresses replies should go to, separated by commas. Leave it empty for replies to go to the sender address.
Max Connections	How many connections TrakIT opens to this account at the same time, from 1 to 25. New servers start at 3, which is what Office 365 allows; some mail services allow more. Servers with the same host and user share this limit.
Active	Turn it off to stop using the server. Emails that would go through an inactive server are not sent.

To delete a server, open it and select the X at the bottom left. A server that a company still uses can’t be deleted: TrakIT says Unable to delete server.

If an email can’t be sent because of a connection or server problem, TrakIT tries again by itself. The Message log shows each email TrakIT sent and why one failed.

FTP tab

TrakIT saves files to an FTP or SFTP server for:

• event and data actions of the type Save to FTP Location, which save a message or a generated document when an event or data field is updated (see Event and data definitions);
• reports delivered By FTP: query reports and advanced report subscriptions;
• on some installations, reading rate files from an SFTP folder (see Feeds).

The list is sorted by title.

Column	Shows
ID, Title	The server’s number and name.
Host, User, Port	Where TrakIT connects and the account it signs in with.
Type	SFTP, or FTP/FTPS.
Encryption	SSH for SFTP; otherwise None, Implicit (SSL) or Explicit (TLS).
Updated By	Who last saved the server, and when.
Last Attempt	When TrakIT last connected, with Success in green or the error in red. - if it never has.

Create or modify an FTP server

1. Select Create, or select a server in the list. The Create FTP Server or Modify FTP Server window opens.
2. Fill in the fields below.
3. To check the settings, select Test Connection. TrakIT uploads a small file, TrakIT-FTP-Test.txt, to the working directory and deletes it again, with the settings as they are in the window, saved or not. If it works, TrakIT says FTP connection succeeded.
4. Select Create, or Save for a server that already exists.

Field	What to enter
Title	A name for the server, different from the others. Letters, numbers, spaces and - ' ( ) [ ].
Host	The server’s host name. Required.
User, Password	The account TrakIT signs in with.
Port	The port, for FTP and FTPS. Leave it empty to use the default port.
Is SFTP	On for an SFTP (SSH) server. Off for FTP or FTPS.
Encryption	For FTP and FTPS: None, Implicit (SSL) or Explicit (TLS).
SSL Protocol	For FTPS: the protocol to use, or [Default].
Working Directory	The folder TrakIT works in on the server. Files are saved there.
Ignore Cert. Error	For FTPS: on to accept the server’s certificate even if it is not valid.
Active	Turn it off to stop using the server: saving files to it fails with FTP Server is disabled.

To delete a server, open it and select the X at the bottom left. A server that a query report or an advanced report subscription delivers to can’t be deleted: TrakIT says Unable to delete server. Event and data actions are not checked: change any action that saves to the server first.

Messaging tab

A messaging channel is a service TrakIT sends short messages through:

• SMS and WhatsApp send to a person’s mobile number;
• Google Space, MS Teams, Telegram and Discord post to a shared space, channel or group chat.

TrakIT uses the channels for:

• Notifications. An active channel with User Specific on appears as a column on the Notifications page of the users of its company (or of every company), so each user can choose to get notifications as text messages to their mobile number.
• Event and data actions. An action of the type Send Message sends its message through a channel of the workflow’s company or of all companies. SMS and WhatsApp go to the recipients’ numbers; the other channels post to their space or chat. See Event and data definitions.
• Sign-in codes. Users whose two-factor authentication is SMS And Email also get their code by SMS, through the SMS channel of their company or else one for all companies. See Two-factor authentication.

TrakIT queues each message and sends the queue every minute. The Messages Sent tab of the Message log lists them.

Column	Shows
ID, Title	The channel’s number and name.
Vendor Type	SMS, WhatsApp, Google Space, MS Teams, Telegram or Discord.
Code	The vendor code.
Office	The company the channel is for. Empty for all companies.
URL, Sender	The channel’s address and sender.
Created	Who created the channel, and when.

Channels that TrakIT Support set up are shown in grey, and you can’t open them.

Create or modify a messaging channel

1. Select Add New, or select a channel in the list. The Create Messaging Channel or Modify Messaging Channel window opens.
2. Choose the Type. The window shows the fields that type uses.
3. Fill in the fields below.
4. Select Create, or Update for a channel that already exists.

Field	What to enter
Type	SMS, WhatsApp, Google Space, MS Teams, Telegram or Discord. It can’t be changed once the channel exists.
Title	A name for the channel. Required.
Company	The company the channel is for, or — Select — for all companies.
URL	For SMS: the provider’s address for sending one message, with [RECP] where the mobile number goes and [MSG] where the text goes. TrakIT calls it for each message. For Google Space, MS Teams and Discord: the incoming webhook address of the space or channel. Must start with https://. Not used for WhatsApp.
Vendor Code	Required for SMS and WhatsApp: letters, numbers and underscores. Only WhatsApp uses it, and there it must be GUPSHUP, the WhatsApp provider TrakIT supports.
API Key	For WhatsApp: the provider’s API key.
Params:	For WhatsApp: the app name registered with the provider.
Sender	For WhatsApp: the number messages are sent from. Letters, numbers, - and _.
Chat ID	For Telegram: the chat to post to. Required.
Bot Token	For Telegram: your own bot’s token. Leave it empty to post as the TrakIT Telegram Bot.
Active	Turn it off to stop sending: messages queued for the channel are marked as failed with Channel is not active.
User Specific	On for channels that message individual users, such as SMS and WhatsApp: users can then choose them on their Notifications page. Off for shared channels, such as Google Space, MS Teams, Telegram and Discord.

SMS uses only the URL: Vendor Code, API Key, Params: and Sender are for WhatsApp.

To delete a channel, open it and select the X at the bottom left.

API tab

An API integration describes a call to another system’s web API: its address, how TrakIT signs in, and what it sends. Event and data actions of the type Post to API make the call, for example to send a work order’s details or a generated document to a customer’s system when an event is completed. An action can use the active integrations of its workflow’s company and those for all companies. See Event and data definitions.

This tab is for calls TrakIT makes to other systems. For other systems that call TrakIT, see the API reference.

Column	Shows
ID, Title, Code	The integration’s number, name and code.
Office	The company it is for. All in grey: all companies.
Endpoint	The method, in bold, and the address called.
Auth, Body	The Auth Type and Body Mode.
Updated By	Who last changed it, and when.
Last Call	When it was last called, with Success in green or the error in red. - if never.

Create or modify an API integration

1. Select Add New, or select an integration in the list. The Create API Integration or Modify API Integration window opens.
2. Fill in the fields below. Choosing the Auth Type, Body Mode or File Mode shows the fields they need.
3. To add a header or parameter, select + Add Parameter and fill in the new row.
4. To try the call, select Test Call (see Test the call).
5. Select Create, or Save for an integration that already exists.

To delete an integration, open it and select the X at the bottom left. Actions that use it then fail with API Integration not found: change them first.

General

Field	What to enter
Title	A name, different from the other integrations’ titles. Letters, numbers, spaces and - ' ( ) [ ].
Code	A short key, different from the others: letters, numbers and underscores. TrakIT saves it in capitals, without spaces.
Endpoint	The address to call. It must start with https://, and can hold placeholders such as [WOID].
Company	The company it is for, or — Select — for all companies.
Method	GET, POST, PUT, PATCH or DELETE. New integrations start on POST.

Authentication

Auth Type	How TrakIT signs in
None	It doesn’t.
Basic	With a User and Password.
Bearer	With a Token.
API Key	With a Key Value, sent in the header or query parameter named in Key Name. Key Sent In is Header or Query.
OAuth2 Client Credentials	TrakIT gets an access token from the Token URL with the Client ID and Client Secret, and sends it with each call.
OAuth2 Refresh Token	As above, with the Refresh Token you enter. When the provider issues a new refresh token, TrakIT keeps the new one.
OAuth2 Password	TrakIT gets the access token with a Username and Password. No client secret is sent: if the provider needs a client ID, add it in Extra Token Fields, for example client_id=yourapp.

The OAuth2 types also have these fields:

Field	What to enter
Token URL	The provider’s token address. It must start with https://.
Scope	The scopes to ask for, separated by spaces. Optional.
Credentials Sent As	Basic Auth Header or Client Secret In Body: how the client ID and secret are sent to the token address.
Extra Token Fields	More fields for the token request, as name=value&name=value.
Token Status	The access token TrakIT holds: No token yet, Valid until a time, Expired, or the error from the last attempt.

TrakIT gets a new access token when it has none or the one it holds expires within 5 minutes.

The Password, Token, Key Value, Client Secret and Refresh Token are stored encrypted and never shown again. Next to the field, (configured) means a value is stored and (not set) that none is. Leave the field empty to keep the stored value.

Body and file

The file is what the action sends: its message, or the document it generates.

Field	What to enter
Body Mode	None: no body. JSON: the Payload Template, as JSON. Form URL Encoded: the Form Field parameters. Multipart: the Form Field parameters and the file, as parts. Raw: the Payload Template as it is, or the file itself.
File Mode	None: no file. Multipart Part: the file as a part of a Multipart body. Base64 In Template: the file, base64 encoded, where [FILE] is in the Payload Template of a JSON body, or in a Form Field of a Form URL Encoded one; up to 10 MB. Raw Body: the file itself is the body of a Raw body.
Content Type	For Raw: the content type, for example application/xml. Required with Raw Body.
File Field Name	For Multipart Part: the name of the file’s part. [FILENOEXT] is the file name without its extension.
File Name	The name to send the file under, if it should differ from its own. Placeholders are allowed, for example [WOID]_[NAME].pdf.
Payload Template	For JSON and Raw: the body to send, with placeholders.

When an action makes the call, TrakIT first fills in the Payload Template like a form template, so it can also use the work order and job tags of form definitions. In a JSON body, the values TrakIT puts in are escaped so that they can’t break the JSON.

These placeholders work in the Endpoint, the Payload Template, the File Name and the parameter values:

Placeholder	Is replaced with
[VALUE], [OLDVALUE]	The new and the previous value of the event or data field that ran the action.
[REM]	The remarks entered with it.
[NAME]	The name of the event or data field.
[USERID], [USERNAME]	The user ID and name of the user who updated it.
[WOID], [BOLID]	The work order ID and the job ID.
[FILE]	The file, base64 encoded. Base64 In Template only.
[FILENAME], [FILENOEXT]	The file’s name, with and without its extension.

Sending and response

Field	What to enter
Timeout (sec)	How long to wait for an answer, from 1 to 300 seconds. New integrations start at 30.
Retries … every … sec	How many times to try again, up to 5, and how many seconds apart, up to 60. TrakIT tries again only after a timeout, a connection error, or a 429 or 5xx answer, never after another 4xx answer. Leave it at 0 unless the other system can safely receive the same call twice.
Success Codes	The status codes that count as success, separated by commas, for example 200,201,202. Leave it empty to accept any 2xx code.
Response	Ignore, Log or Return. At present, actions don’t use the response: whether it is logged depends on Log Payload.
Log Payload	On: the body TrakIT sends and the body it gets back are kept in the API log, which TrakIT Support uses to look into failed calls. Stored secrets are masked. Off: only the answer’s status is kept. Turn it off if the data is sensitive.
Active	Turn it off to stop the calls: actions that use it fail with API Integration is not active.

Headers & Parameters

Each row of Headers & Parameters is sent with every call:

Column	What to enter
Kind	Header: a request header. Query: a parameter added to the address. Form Field: a field of a Form URL Encoded or Multipart body.
Name	Letters, numbers, - and _. A header can appear only once.
Value	The value. Placeholders are allowed; [FILE] is not allowed in a Query parameter.
Secret	Tick it for a value that must stay hidden, such as a key. It is stored encrypted and shown as asterisks. Leave the asterisks as they are to keep the stored value.

Select the X at the end of a row to remove it.

Test the call

Test Call sends a real request straight away, with the settings as they are in the window, saved or not, even if the integration is not active. The placeholders get test values, such as TEST for [VALUE], 0 for [WOID] and [BOLID], and your own user ID and name, and the file is a small text file. The form template tags are not filled in by a test.

If the call succeeds, TrakIT says API call succeeded and shows the status and the start of the answer. Otherwise it shows the error. The other system receives the test like any other call.

Messages

Message	What to do
Title specified already exists, Code specified already exists	Choose another title or code.
Base URL must start with https://	Correct the Endpoint.
Payload Template is required for this Body Mode	Enter a Payload Template, or choose another Body Mode.
File Mode ‘Multipart Part’ requires Body Mode ‘Multipart’, and the like	Choose a File Mode that fits the Body Mode.
Form Field parameters need Body Mode ‘Form URL Encoded’ or ‘Multipart’	Change the parameter’s Kind, or the Body Mode.
Duplicate header	Remove the second row with the same header name.
Token refresh failed	The token address refused the credentials. Check them and the Token URL.
Timed out after … seconds	The other system didn’t answer in time.
API Response: followed by a status	The other system answered with a status that is not a success code.

DCSA tab

With carrier tracking, TrakIT asks shipping lines, through their DCSA Track & Trace APIs, for the events of the containers on your jobs. It shows them on the job’s Tracking tab, and can write values such as the ETA and the port of discharge into the work orders’ fields.

A job is tracked with a carrier when:

• it has an open work order with a container number, whose carrier entity has that shipping line as its Shipping Line (SCAC) (see Entity fields);
• the carrier is set up and active here;
• the job was created within the carrier’s Track Jobs Created Within days, and is in one of its Workflows, if any are chosen.

Every 5 minutes, TrakIT finds the jobs to track and looks up those that are due. If background jobs are switched off on your installation, the tab says so: carriers are then not looked up on their own, but users can still select Track now on a job’s Tracking tab.

Column	Shows
Carrier	The shipping line, with its code.
Status	Active; Inactive; or Switched off, when TrakIT turned it off after the carrier kept refusing its calls (point at it to see the error).
Key	Own key, or Bitmetric for a key that TrakIT Support holds. Sandbox below it when the carrier’s test system is used.
Carrier Entities	The active carrier entities with this shipping line. In red if there are none: no work order will be tracked until you set the Shipping Line (SCAC) of the carrier entities.
Poll Every	How often each tracked job is looked up.
Jobs Tracked	How many jobs are being tracked.
Last Poll	When the carrier was last called, with Success or the error.
Updated By	Who last changed the carrier, and when.

Add or modify a carrier

Before you start, get API access from the shipping line: most carriers grant it on their developer portal or on request. About this carrier in the window says what each carrier needs, with a link to its portal.

1. Select Add Carrier, or select a carrier in the list.
2. Choose the Carrier. Each carrier can be set up once, and can’t be changed later.
3. Enter the credentials and the other fields below.
4. To check the settings, enter a container or transport document number in Test With, or leave it empty to use a recent container of this carrier, and select Test Connection. TrakIT calls the carrier with the settings as they are, saved or not, and shows what came back. Nothing is saved.
5. Select Create, or Save for a carrier that already exists.

Field	What to enter
Carrier	The shipping line.
Active	On to track jobs with this carrier.
Carrier Entities	Shows the active carrier entities whose Shipping Line (SCAC) is this carrier, or a warning in red if there are none.
About this carrier	Shows how the carrier grants access, a Developer portal link where it has one, and how it signs in.
Credentials	Own key: your installation’s own credentials from the carrier. Bitmetric key: a key TrakIT Support holds for the carrier; it appears only if TrakIT Support has set the carrier up with it. Calls then use that key, which is not stored in your database. You can move a carrier from it to Own key, but not back.
Environment	Production, or Sandbox to call the carrier’s test system, where it has one.
The credential fields	With Own key, the fields the carrier uses, as its developer portal names them: for example Client ID, API Key and Client Secret. Keys and secrets are stored encrypted and never shown again. Leave them empty to keep the stored values.
Certificate (.pfx), Certificate Password	For a carrier that signs in with a certificate: the certificate registered with the carrier, and its password. Leave them empty to keep the stored ones.
Scope	For carriers that sign in with OAuth: the scope the carrier gave you.
Events URL, Token URL	Shown only for carriers that hand out their own addresses on approval: enter the addresses the carrier supplied.
Look Up By	The order in which a job’s references are tried, for example Transport document, booking, container. Container numbers are looked up only for containers the carrier didn’t return.
Strip Suffix	On to ignore anything after a dash in the transport document (ABC123-CFS is looked up as ABC123) and to skip placeholders such as TBA.
Workflows	Track only jobs of these workflows. Choose none to track all.
Transport Document Fields	The codes of the fields that hold the carrier’s bill of lading, in the order to try them, separated by commas. #BOLNUM is the job number.
Booking Fields	The codes of the fields that hold the carrier’s booking number, in the order to try them.
Track Jobs Created Within	Jobs older than this many days are not picked up, from 1 to 730. Track now on the job still works.
Stop Tracking	A job stops being looked up this many days after its last container arrived, from 0 to 60.
Poll Every	How often a tracked job is looked up again: from every hour to every 24 hours.
Max Calls per Hour	The most calls TrakIT makes to the carrier in an hour, to stay within its limit. Jobs beyond it wait for the next run.
Update Job Fields	On to write the carrier’s values into the fields set in Field Mapping. Off: they are only shown on the job’s Tracking tab.
Test With	A container or transport document number for Test Connection.

To remove a carrier, open it, select the X at the bottom left and confirm. The jobs, containers and events tracked with it are removed too; the values already written into work order fields stay.

If the carrier refuses TrakIT’s credentials 10 times without a successful call in between, TrakIT switches the carrier off, shows it as Switched off and emails the system administrators (Carrier Tracking Switched Off), or TrakIT Support for a carrier on the Bitmetric key. Correct the credentials, turn Active back on and save.

Field mapping

Field Mapping sets which workflow fields the carriers’ values are written into. The mapping is the same for every carrier.

1. Select Field Mapping. The DCSA Field Mapping window opens. If no mapping is saved yet, TrakIT suggests one from the usual ETA and port of discharge fields of your workflows.
2. For each Carrier Value, choose the field codes in Workflow Fields. Point at a code to see how many workflows have it.
3. Tick Overwrite to replace a value the field already has.
4. Select Save.

Carrier values	Can go into
ETA at port of discharge, Arrival (actual) at port of discharge, ETD from port of loading, Departure (actual) from port of loading, Discharged at port of discharge, Gate out full at port of discharge, Empty returned	Event and date fields.
Port of discharge, Port of loading	Location and text fields.
Vessel, Voyage	Text fields.

A work order whose workflow doesn’t have a field skips it. Without Overwrite, a field that already has a value keeps it. Dates that move by less than 12 hours are left as they are.

Who can use this page

Only system administrators can open the Integrations page. They can set up every integration on it, apart from what TrakIT Support looks after: the [System Default] SMTP server, the messaging channels TrakIT Support set up, and moving a carrier to the Bitmetric key.