Courseware:IT Plus - Fax

Book on Fax App

Preparation

If you don't have an AP running on the SSD of your IP411LEFT, please set up an Application Platform as described in the book. So don't proceed if you don't have an AP running on your IP411LEFT.

As we start we need a new start configuration for you. Therefore, please load a new configuration onto your devices:

Upload new configuration to your Devices

This book also has a start configuration for your AP. So don't forget to click on the  Load initial lesson configuration to your Application Platform button once it appears. This may take a while, so bear with us and keep trying

To log into myApps use ckl and ip411 as password.

Use this link: http://hq.dvl-ckl2.net/PBX0/APPCLIENT/appclient.htm?lang=en

The Fax App

The fax app allows you to send and receive fax messages. Users can send faxes by uploading a pdf-file (this is the only supported file type) in their fax app or they can send a mail with a pdf attachment to the app service (#mail2fax). Received faxes can either be downloaded from the app or a notification with a PDF attachment can be sent via email (#fax2mail).

In addition to the permission to use the fax app, extensions (PBX users and group fax Apps) need also a fax license (e.g. included in the UC license) to be able to send/receive fax messages. The license for a user can be assigned through the Templates PBX Manager plugin. For Group Fax Apps a fax license is assigned automatically on creation through the AP FAX PBX Manager plugin (we will see later what a Group Fax App is).

The Fax app relies on hardware resources to send and receive faxes. Many innovaphone gateway devices have a so called Fax interface that is used for this purpose. The amount of concurrent fax calls depends on the device type and is limited by so called Fax channels. You can check the Hardware section in the  product data-sheet or use the  Fax AP PBX Manager to find out how many fax channels your devices have. Also, it is shown on the  device's home page.

You must assign a free number in your dialing plan to the fax App, all fax extensions will use this number as prefix. E.g. if 9 is your fax App number and you have a user with extension 10, the user fax number is 910. A fax message received on the 910 number will be displayed in the fax App of this user. Also when this user sends a fax, it will have the number 910 shown as sender-id.

To install the fax app, open the PBX Manager and then  the app installer plugin. Then follow the steps below:

• Search for fax in the upper right corner
• Install the version marked as srTraining
• After the Install, please close the PBX Manager

If your app installer only shows an empty page, please refresh your myApps session with F5 and try again.This typically happens when the connection to the AP is lost (unlikely here but happens regularly when you update the AP manager or web server)

Configuration

The PBX Manager plugin called  AP fax allows you  to configure the fax app service and to create and edit a fax and a group fax app. So go ahead and open  the Add fax app dialog to have a first look at it.

Fax basic settings

Let's first discuss the fax app. You can configure the following parameters:

• Name: the name of the Fax App. It must be unique in the system. It will be shown in myApps and should describe the function of this fax extension (e.g. Personal-Fax)
• SIP: this has no relevance for the user or admin and is used only for PBX intern mechanisms. It must be unique in the system, you can use the same name as above.
• Number: this is the already explained Fax App number. It must be unique in the system and is used as a prefix for the user's personal fax number.
• Internat. Fax number: When a fax is sent, the fax senders number is also transmitted and printed in the header line of the received fax. This number should be reachable from the PSTN, in case the recipient wants to send a fax message back. Your fax extension number is appended to this number.
• Company name: Similar to the internat. Fax number above, this info is also sent to the recipient and printed in the header line of the received fax
  

FAX interface

In addition to the parameters above, it is also necessary to define which Fax-interface to use.

If you click on  "Search" in the FAX-interfaces menu, you will see all available FAX-interfaces in your domain. By selecting one FAX-interface, detail info like the device name, type, hardware-ID and more important the amount of FAX-channels is displayed. If you select multiple fax interfaces in the plugin, the fax interface that registered first is always used. If the fax interface fails or has no more channels available, it will automatically switch to the next fax interface. The next one is the registration with the second highest uptime.

Configuration templates

The configuration of the fax application allows you to assign the fax or group fax app to the required users by config template. Simply enable the config template you want users to receive the fax application from. Of course, you could also use the Templates PBX Manager plugin.

---

Now go on and configure your FAX-app with the following parameters:

• Name: Fax

• SIP: fax

• Number: 9

• Internat. Fax number: +4962134282319

• Company name: your company name
  
  
• In the Fax interface section: Use the IP811 as a device (leave the default settings as they are)
  
  Make sure  both sliders (T.38 allowed and Audio fax allowed) or turned on.
  
  These are two alternative methods of sending faxes over IP. In general, you should enable both, as the actual method used is negotiated between the parties. Only if you run into compatibility issues (for example when sending faxes via your SIP provider), you may need to disable one or the other.
  
  
• In the Configuration Templates section: Assign the App to the Config User template
  
  
  

All other configuration options can be left as is at the moment. We will talk about some of them later on in this book.

To test our Fax app

• Open your fax app (check the All Apps section of myApps)
  
  
• send a Fax from your myApps client to Mario. If you have no pdf file at hand, you can use  this one
  
  
• wait for the  transfer to complete
  

You need to use Mario's fax extension (i.e. 913), sending a fax to a users normal extension is not possible. Also, you can normally not search for a local fax extension (such as the one of Mario) by name in the fax client App. You can however search for fax destinations in your Contacts App. This is why we have prepared a little Contacts instance in this setup (which has a single contact entry, which is Mario)

To see if your fax was successfully delivered, you need to login to Mario's myApps. We would recommend using a different browser than you already use.

Browse to http://hq-dvl-ckl2.training.innovaphone.com/PBX0/APPCLIENT/appclient.htm?lang=en and use the Username and Password for Mario (mro and ip411).

You can then open Mario's Fax App and  see the document in the in-box

Cover page

When you send a document, you have the option to  add a cover page. Alternatively, if you don't want to send a PDF, you can also select the  option Text Only option to send just a cover page.

You cannot change the appearance of the cover page, but you can add a subject and text to the cover page. HTML code is not possible.

Additional options

Default recipient

If you go back to the configuration of the Fax App, you find the section  Default recipient. If a fax message is sent to a number that does not exist, directly to your Fax App number (i.e. missing the user extension) or to a user that is not allowed to receive fax messages (no fax license), the fax is rerouted to the Default recipient. The rerouted destination can be either a user or a Group fax app.

You should, for obvious reasons, make it a habit to always configure a default recipient.

External resource

Each fax and group fax app requires a connection to a fax interface. Because each device has only one fax interface, multiple fax objects must be able to share a fax interface. Therefore, if you need to set up a second fax or group fax application, you must specify the SIPid of the original fax app as an external resource.

As a pro tip, you can also configure the SIPid of a gateway object as an external resource. This allows you to route fax calls to other devices even if the device is not part of your devices installation.

Node and PBX

In this course, we won't use nodes or multiple PBXs. If you are keen on learning more about Nodes and PBX, please do the Structured numbering plans topic in  our Plus training. As a rule of thumb, you want to create a fax object for every node with user objects.

If this would result in multiple fax objects on a single PBX, you must configure the original fax object, you have linked to the fax interface, as an external resource on all other fax objects.

Header of fax pages

You can select a predefined header from a variety of different languages or you can customize the header to suit your needs. You can find a list of all variables  in our wiki.

Coder channels

Closely related to Fax-channels are the Coder channels (sometimes also called DSP-Channels) of a device. Each fax call requires not only a fax channel, but also 2 of these coder channels if the fax is transmitted as audio fax. If the source and destination of the fax call supports T.38, no coder channel is required. In real life this is rarely the case as many providers do not support T.38 or have to route the call to another provider that does not support T.38.

The amount of available coder channels depends on the device type. You should check  the Hardware section in the respective data-sheet on how many DSPs your gateways have or you have a look  at our wiki.

Note that an IPVA or IP0011 has no coder channels at all, making it unsuitable as a fax interface device. Although the fax interface is configurable, only T.38 can be used to send/receive a fax, resulting in the problem discussed earlier: a fax connection cannot be established because not all devices from source to destination support T.38.

It is important to know that coder channels are also consumed/used by conference calls (1 per participant) and ISDN calls (1 per participant). If there are not enough channels available at the moment, a fax-call will be retried later.

E-mail configuration

A received fax can not only be displayed in your fax app, it can also be sent and received as an email. For this to work, we need to configure an SMTP connection to the mail server to send email notifications to users, and we need to allow incoming SMTP connections from SMTP connectors so that an incoming email can be converted into an outgoing fax.

If you have a single SMTP server or a hosted mail solution (Office 365) that is not located your local network, we recommend that you configure TCP port forwarding on your Internet router for ports 25, 465 and 587 (depending on the protocol used). You will also need to create an SMTP send connector to send mail data to the external IP of your network on this external mail solution, which will then be forwarded to the AP via the port forwarding.

The configuration of the SMTP connection is done in the  fax PBX Manager plugin. Simply click on  the Configuration button.

SMTP server configuration

To convert an email with an optional PDF attachment to a fax (mail2fax), you need to configure an SMTP send connector on your mail server. The destination of this send connector must be the application platform. This mail must be encoded by UTF-8 or ISO 8859-1(Latin1). In order for the app service to accept and process mails received through this send connector, we need to configure the following options. You can find a sample configuration for Microsoft Exchange  in our wiki.

• E-mail reception: This option must be enabled, otherwise the app service will not accept incoming SMTP traffic on port 25. At the time of writing, no other port is usable. STARTTLS is supported.
• Domain: When the fax app service receives a mail, it looks at the domain part of the mail's recipient address. The app service will only process mails with a domain part that matches the domain configured here. As a rule of thumb, we recommend to configure a subdomain of your domain here (e.g. fax.dvl-ckl2.net).
• User name: To configure an SMTP authentication, you need to configure the same username as configured on the SMTP send connector.
• Password: To configure an SMTP authentication, you need to configure the same password as configured on the SMTP send connector.

Please set  these options:

• E-mail reception: Enable
• Domain: fax.dvl-ckl2.net
• User name: fax
• Password: ip411

SMTP configuration

To send mails from the app service to the destination, you need to configure the following options.

• Hostname: The best practice is to configure the DNS name of the app platform, for example, apps-dvl-ckl2.training.innovaphone.com. Alternatively, you can also specify the IP address of the app platform in square brackets. Please note that you must configure the external address of your router here if the SMTP server is on a public network
• Server: You have to configure the address of the SMTP server here. If no port is specified, port 25 is used. If you want to use a different port, add the port to the address and separate it with :
• User name: In order to authenticate to the mail server, you must configure a user name here. Please note that this configuration cannot be omitted
• Password: Like the username, this configuration option is also used for authentication and cannot be omitted
• Sender address: Any e-mail address you configure here will be displayed to the recipient as the sender e-mail address.
• Sender name: Any name you configure here will be displayed to the recipient as name of the sender.

For our scenario please configure the  following options:

• Hostname: apps-dvl-ckl2.training.innovaphone.com
• Server: training-mail.innovaphone.com
  (or training-mail.innovaphone.com:587 if checkconn.ps1 in  How to verify IP port availability said SMTP available on port 587 but not on port 25)
  
• User name: dvl-ckl2@class.local
• Password: ckl-pw
• Sender address: dvl-ckl2@class.local
• Sender name: Fax Service

Please be aware that our Training Mail Server is configured overnight. This means your email account will be available the day after you first enroll in a Plus course.

How does it work?

In this chapter we will take a closer look at how a fax is transmitted as a email and how a email is converted to a fax.

Fax to Mail

Before we can start our explanation please be aware that the user receiving the fax must have a valid email address and a fax license which is included in the UC license bundle.

In today's world, the incoming call is usually received on a SIP interface. The CDPN is stripped of the country code, area code, and subscriber number so that only the fax prefix and extension number are passed from the relay to the PBX.

The PBX knows the fax prefix because it is the number of the fax object. If you recall, we set this number to 9 in our configuration example. At this point, the fax application service is notified of the incoming call via the websocket connection. The VoIP call is forwarded to the fax interface.

When the fax interface receives a fax, it creates a temporary .sff file. In the case of an audio fax it uses two DSP channels for this purpose, a T.38 call does not require a DSP channel. If you want to know more about DSP channels please go back to the chapter Coder channels in this book.

The fax interface sends the .sff file via an HTTPS PUT to the fax app service where it is stored. Note that the fax interface must be able to communicate with the fax app service using HTTPS. The fax app converts the .sff file to a PDF, which is then sent via email (SMTP) to your mail server.

The FROM and TO addresses of these emails are:

• The  FROM address is taken from the SMTP configuration of the fax app service configuration
• The  TO address is taken from the user object. The PBX receives the extension number as the last digits of this fax call. The fax app service searches for this user in the same node where the fax objects reside.

Mail to Fax

For mail to fax, we have to go the other way around. First, you need to create an SMTP send connector in your company's mail server. As best practice send all mails for a subdomain of the company (e.g.: fax.dvl-ckl2.net) to the fax app service. An example configuration of Microsoft Exchange can be found  in our wiki.

The TO and FROM addresses must be:

• The  FROM address must be the email address of the user sending the email. The fax app service will use the user's extension number to create the CGPN.
• The  TO address must consist of the destination number as user part and the domain configured in the fax app service as domain part.

The received PDF is then converted into a temporary .sff file and additionally the fax app service initiates a call from the PBX to the relay fax interface. The fax interface then retrieves the .ssf file from the fax app service via HTTPS GET.

Next, a fax call is created that has to be routed to the trunk object in the fax and then to the destination in the PSTN. The CDPN of this call will be the number configured as the user part of the TO address. The CGPN routed to the trunk object will be the fax prefix and extension.

Testing it - fax to mail

To test our configuration please log into Mario Rossis Outlook account.

Therefore,

• go to  training-mail.innovaphone.com: owa and use the following credentials to log in:

Email username: mario.rossi.dvl-ckl2@class.local

Email password: ckl-pw

• Open your Fax app and send a fax from your fax app to Mario (913) again.
• Once again it will take some time but in the end the fax transmission will be completed. Unfortunately, you will not receive an email although Mario receives the fax. Please go to the next page to find out why.

User specific configuration

Open Mario Rossi's fax app again and click the burger menu top right. As long as the user has an email address configured, each user has the ability to enable these options.

• Incoming notification: An email is generated when the user receives a fax.
• Forwarding as PDF: When the user receives a fax, an email is generated containing the fax as a PDF.
• Transmission confirmation: An email is sent to the user when the fax has been successfully delivered.
• Transmission report as PDF: The user will receive an email with the fax in PDF format when the fax is successfully delivered.
• Error Notification: The user will receive an email in case of an error.
• The last line (which currently shows English (Standard)) allows you to select the language of the emails sent to you.

Please set the Forwarding as PDF check mark and Transmission Report as PDF check mark  in Mario's fax app.

Please send an fax from your fax app to Mario (913) again. This time he will receive the fax as PDF mail attachment.

Testing it - mail to fax

To test mail to fax we will use Thunderbird, so please  download the application from the link. Of course, this only simulates the mail server. In a real environment, you would need to create an SMTP connector on your mail server.

After the installation we will create a mail account.

So,

• click on  Setup another Email account.
  
  
• then configure the  mail parameter manually.
  
  
• Your full name: Christoph Künkel
• Email address: dvl-ckl2@class.local
• Password: ckl-pw

• Protocol: POP3
• Hostname: training-mail.innovaphone.com
• Port: 110
• Connection Security: None
• Authentication method: Normal Password
• Username: dvl-ckl2@class.local

• Hostname: apps-dvl-ckl2.training.innovaphone.com
• Port: 25
• Connection security: STARTTLS
• Authentication method: Encrypted password
• Username: fax
  
  
• you can ignore  the Warning for now
  
  
• afterwards go to the account settings -> Copies & Folders and deactivate Place a copy in: checkmark

As a next step we want test our configuration so send a new message(email) to 913@fax.dvl-ckl2.net. Please attach a PDF like  this one and enter any subject. Then send the mail.

Enter a password for authentication to the Application Platform. This must be the same password as the SMTP server configuration. In this case, enter ip411

Afterwards you need to create  a security exception because Thunderbird (as a mail client) that doesn't trust the certificate of the AP. An SMTP connector on the other hand will not validate the server certificate of the AP.

Then try sending the mail again. This time the mail/fax will work and Mario will receive the fax in his fax app and mail client.

Fax group App

This feature allows you to configure one fax number for a group of users. By assigning the Fax Group App to users you decide who can read and send faxes on this specific extension. You can  create a new Fax Group app in the AP fax PBX manager plugin.

Fax Group Configuration

The configuration of a fax group App is very similar to the configuration of the fax app.

• Name and SIP: their role and restrictions are the same as with the Fax App
  
  
• Number: it must be a free number in your dial-plan, similar to the extension of a new user
  
  
• Internat. fax number: like for the normal fax App, this shall be the international number of your group fax but with its own Number omitted (e.g. not +49621342823918 but +496213428239 if 9 is your fax number and 18 is your fax group number)
  
  
• E-Mail Addresses: the email address(es) where incoming faxes shall be sent to. You cannot configure an email address already configured on a user object in the PBX. We recommend to configure an email distribution group here. This distribution group should be named <SIP>@<domain>, e.g. orders@dvl-ckl2.net

Please note that you have to  enable email forwarding for every email address in the fax group App the same way we did for the personal fax App.

External Resource

You may have noted that the fax group App has no selection of a Fax interface, there is only the selection of an External resource. This is because the group App will use the fax interface defined for the normal fax App. You need to select the name of this fax object as External resource therefore.

The fax group App behaves somehow like an extension in the scope of the related fax App. To send a fax to the fax group therefore, you must put the fax prefix (that is, the number of the fax App object) in front of its own number. For example, if your regular fax App object has the Number 9 and the fax group App has the number 18, you would call 918 to reach the fax group.

---

Now let's  configure a fax group App

• called (Name) orders
  
  
• with SIP id orders
  
  
• with Number 18
  
  
• Internat. fax number +496213428239 (see note above in the Fax Group Configuration section)
  
  
• assigned to all users inheriting from the configuration template Config User
  
  
• with a Company name of your choice
  
  
• without any E-mail addresses (as we have no distribution group email address at hand and also can not configure the email system)
  
  
• External resource: fax

To test your configuration, open your fax App and send a  testfax as pdf to the new fax group orders. Since the Fax prefix is 9 and the fax group number is 18, you will use 918 to send a fax to the fax group.

Afterwards you can log in to any other user (e.g Mario Rossi). Since all of your users share the Config User Template you can open the orders App and check if the fax was successfully received.

Of course, you can also send a fax using the fax group App. In this case, the  fax identification will not show your own identity, but the group's identity. Note that the Number of the fax group App is appended to the Internat. fax number you configured for it.

A Fax Group App needs a fax license as well. The license is already assigned to it when it is created by the PBX Manager, you only need to calculate this license when buying licenses for a customer installation. If the user has no personal fax extension and will only receive faxes through the fax group, the user itself needs no fax license.

Further options

Let's take a look at some of the remaining configuration options you can find in the fax app service.

Delete fax jobs automatically

All faxes are stored in the database and are not deleted by default.  In the configuration part of the Fax PBX Manager plugin you can  enable automatic deletion of faxes after a certain number of days.

In many cases, it is a good idea to enable the automatic deletion of fax jobs. Otherwise, accounts which send or receive faxes but do not take care to delete them in time may flood the Application Platform's database storage.

HTTP API

3rd party applications can send a HTTP POST command to trigger a new fax job. For further explanation please  refer to the wiki.

Customized texts

Since the fax app generates emails on demand, you  can define custom texts in the configuration part of the fax PBX Manager plugin to customize the outgoing email.The Section Customized Texts in the wiki  Apps/PbxManager/App Fax explains the available options. Customized texts cannot be localized, which means you can define the text only in a single language.

Mail background logo

The converted fax is sent to the recipient as an email. This mail contains a myApps logo as a background image. You can  replace this image with any base64 encoded png file. Note that this image must be small enough to fit into this config line, otherwise it will not take effect. We recommend to use a black and white picture with 1 bit color depth.

To compress PNG files you can use  pngquant.

---

The remaining options explained here can be found in  the Fax object in the Advanced UI.

Modem capability

You can set the maximum speed at which a fax is sent or received. By default, the maximum speed is 14400 bps, but during the beginning of the fax transmission, both fax endpoints negotiate the speed. As a result the transmission speed might be lower.

Append user number

By default the fax app appends the user number to the subscriber ID. This may not be desirable if you have an MSN trunk because you want to have a fixed number as subscriber ID. In this case you can disable this feature here.

ECM

By default, we use Error Correction Mode to send and receive a fax. ECM automatically detects and corrects fax transmission errors, so we recommend that you always enable it as long as support doesn't tell you otherwise.

Receiving with 400dpi allowed

When this option is enabled (which is the default value), the fax interface is allowed to receive a fax with a resolution of 400 dpi.