Reference14r2:Concept App Service Fax
Applies To
- innovaphone PBX from version 14r1
Overview
The App Service Fax is an app service which can be installed on an innovaphone App Platform. It provides sending or receiving FAX documents with the innovaphone PBX and a user app to manage the documents.
Features
- The App Service Fax sends PDF documents as FAX documents and converts received FAX documents to PDF.
- Cover page with user content for outgoing FAX documents.
- The Fax app can forward the received fax documents by mail, as notification only or with the document in PDF.
- Transmission reports and error notifications
- Contact search by using myApps search API providers, inclusive removing number decorations
- PBX node support
- Using several fax interfaces
- Group fax accounts
- Automatic deletion of older fax documents
- Customized email texts
- Mail2Fax
- App API (HTTP Post)
Requirements
- innovaphone App Platform
- Device with a FAX interface
- One port license to register the fax interface towards the fax object
- A UC or fax license for each PBX user which is allowed to receive or send personal fax documents
- A fax (or UC) license for each group fax account
Apps
Fax App (innovaphone-fax)
This app is provided for the users to send fax documents and view or download received documents. The app reads the argument mailbox=<sip name> to work with the given account instead of the user logged in. It uses the com.innovaphone.search API to search for contacts with FAX numbers.
Technical Overview
Technical Concept
The innovaphone fax feature needs three parts:
- An innovaphone PBX with one or more fax objects
- One or more FAX interface registered to fax objects
- The Fax app on the App Platform (AP)
The app service on the AP provides a user app. Users can upload and download PDF documents. The app service converts them from and to a fax protocol compatible file (SFF). The app service controls calls between the FAX interface and an external remote party. To do this, it requires a websocket connection to the PBX. The FAX interface accesses the file with authenticated WebDAV. The documents saved in the app service are available with WebDAV with the app instance name as user name and the app instance password as password and in the directories
- <app-web-path>/sff for the SFF files
- <app-web-path>/doc for the PDF files
Additional Information
- Files of deleted fax jobs are permanently deleted after two weeks.
- The myApps background picture (myapps.png) is also included in all HTML mail bodies with customized mail texts, if these texts contain the string "url(cid:myapps.png)".
Configuration
PBX Manager Plugin
All possible configurations can be done with the PBX Manager plugin of the Fax App. The app service options can be set as well as the corresponding app objects in the PBX can be added, modified or deleted. Additionally, available devices with a fax interface can be found and configured.
As with any app, the Fax App needs to be assigned to users and licensed accordingly.
Mail Configuration (SMTP Server)
The fax service has a built-in SMTP server, which is needed for Mail2Fax. Here, you activate the mail reception for the fax service, enter the fax domain and configure the credentials for the authentication against the SMTP server. The mails can contain a subject and body for the cover page, and one PDF document can be appended as attachment. The destination number must be included in the recipient mail address in this format: <destination number>@<fax server domain>. The fax server domain is the app service domain or the configured domain if different. Recipient addresses do not match are discarded.
The supported charsets are UTF-8 and ISO 8859-1 (Latin 1).
For the Fax service to receive the mails in the first place, the mailserver needs to forward mails for the fax-domain to the APs IP address.
An example for an Exchange configuration can be found here
Mail Configuration (SMTP Client)
The SMTP configuration is to be set in the Fax App PBX Manager plugin to make mail forwarding, transmission reports and notifications available. Only email addresses of the user configured in his PBX object are used and each user has to enable the several mails in the burger menu of the Fax app. Available types of mails:
- Forwarding of a received document as PDF
- Incoming notifications without a document
- Error notifications for outgoing fax jobs
- Transmission confirmations
- Transmission reports for outgoing fax jobs as PDF
The mails are sent in the language the user set in myApps when the Fax app was last used, unless the language for mails was explicitly set within the app.
If a failure occurs and mails cannot be sent, the app service retries the mail transmission of a mail every 30 minutes, but no longer than two days.
PBX Node Configuration
The Fax app object can be assigned to a certain PBX node. If so, the node number is included within the user's fax number.
Group Fax Account
If a Group Fax app is configured, all users have the same group account with this app, and the same jobs. The mail addresses configured in this Group app are available and used instead of the user's mail addresses.
Sharing FAX Interfaces
FAX interfaces are normally registered to one app object. Other PBX Fax objects use these fax resources for calls if they are configured as external resource in the objects.
App API
A document has to be sent can be uploaded with the HTTP post command. The arguments within the HTTP URL sets the data of the new fax job. The job is created in the context of an user and is shown in the app. If the file is successfully saved, the job is directly queued for sending.
An API key must be configured to enable this feature and to authenticate the command.
Arguments of the HTTP post command in the URL:
- api-key: The configured authentication key. Mandatory.
- user-sip: The SIP of the user which sends the document. Mandatory.
- contact-name: An optional contact name shown in the app as contact.
- contact-number: The contact number used for sending the document. Mandatory.
- cover-page-subject: The subject of an optional cover page if should be created.
- cover-page-content: The content of an optional cover page if should be created.
- cover-page-content-html: Is set to true if the cover page content is in HTML.
- app-object: The app object of the PBX used for sending. If not set, any is used.
- file-name: An optional file name of the uploaded file. Not used in the app.
Troubleshooting
Log Files
The progress of fax jobs is reported in the log file:
Info job id 58, direction 0, progress 0, result 0
- direction
- 0: incoming job
- 1: outgoing job
- progress
- 0: job created
- 1: job queued
- 2: job converted
- 3: job finished
- result
- 0: no error or successfully completed
- 1: call aborted, repeating
- 2: job stopped with an error
- 3: job stopped caused by a conversion failure
App Service Log
- App
- App WebSocket
- Browser
- SMTP (only if the problem is related to mail forwarding etc.)
App Service Logs for Mail2Fax
- App
- Smtp
- TLS
- TCP
- DB files
-> Since these options creates huge logs, please just enable for tracing a current problem and deactivate afterward
Known Issues
- Enabling of non-T.38 coder (audio-fax) is also possible for T.38-only capable devices.
- Has to be judged by the user himself, if selected fax interface features audio-fax.
- An IPVA is not capable of sending faxes with a non-T.38 coder (audio-fax coder, e.g. G.711A), because it has no DSPs which are needed for an audio-fax. Therefore, only T.38 faxes work on an IPVA FAX interface.
- Important: T.38 is to be enabled on all interfaces are used in the call flow, e.g. FAX, GW, SIP interface.
- Important: Often "exclusive" is activated on SIP interfaces. This prevents the renegotiation with the provider and T.38 can not be used. Therefore, the "exclusive" flag is to be disabled for such configurations.
- If the name (H.323) of an user is changed in the PBX, the data in the fax service are not accessible for this user and a new account is created for him in the service.
- With 14r1, faxes will be sent with 400dpi per default, and tried with a lower resolution again, if the remote side doesn't support 400dpi faxes. In a 13r3 fax app (no 400dpi support), you will see the first - non working - try, which is the normal behavior, since all faxes (working and non working) are shown in the fax app.
Related Articles
- For a more detailed description about the configuration, please refer to our IT Connect Training.
- PBX Manager plugin for the Fax App
- Howto: Mail2Fax with Exchange 2019