Administration Guide
07 Oct 2021
TM and copyright © 2010-2021 Imagicle spa Table of Contents Administration Guide...... 1/75 Configuration Task List...... 1/75 Description and Architecture...... 2/75 Users and faxboxes configuration...... 5/75 Administrative configuration...... 7/75 Telephony signalling and routing...... 15/75 Advanced Configuration...... 17/75 Service management...... 24/75 Email-to-Fax Microsoft OAuth2 Authentication...... 25/75 Cover pages...... 37/75 Solution-specific Configuration...... 39/75 ...... 43/75Troubleshooting...... 41/75 License Activation...... 46/75 PBX Configuration...... 47/75 Print To Fax...... 54/75
Product Integration API...... 57/75 Overview...... 57/75 Submit Fax...... 58/75 Get Outbound Fax Details...... 63/75 Download outbound fax document...... 65/75 Get Outbound Faxes List...... 67/75 Get Inbound Faxes List...... 69/75 ...... 69/75 Get Inbound Fax Details...... 72/75 Download Inbound fax document...... 74/75 Administration Guide
Configuration Task List
Warning: you must install and configure the Application Suite before being able to configure the single applications. Please go through the AppSuite Deployment, Main Configuration, and User Management sections before reading on.
You can easily configure Digital Fax trough the following mandatory steps:
• Activate the product license (within 30 days) • Configure the PBX • Configure the fax server protocols and routing • Start the service • Configure the relevant users and fax boxes through users management • Configure the application, including the email parameters and fax routing • Configure the fax service parameters
Optionally, you may want to configure:
• Print to Fax • Multifunctional printer integration • Automatic Fax Backup • Incoming Fax Print • Group Faxing • Mass Faxing
These tasks are described in the Advanced Configuration section of this guide.
Administration Guide 1/75 Administration Guide Description and Architecture
Traditional manual faxes are out of date.
Digital Fax is a complete software solution including a robust fax server based on Imagicle unique Fax to IP driver, able to interoperate directry with the PBX trough Voip comminication.
A professional fax server grants substantial savings and it improves customer service and company image; the process of sending a fax is faster and incoming faxes are automatically integrated with today's web and email-based workflow.
Digital Fax delivers a complete IP fax server solution, allowing users to send and receive faxes directly from any email client or through a dedicated web interface.
Digital Fax can be seamlessly integrated with any e-mail server using standard SMTP/IMAP-POP3 protocols without enforcing specific infrastructure requirements.
Digital Fax can automatically route incoming faxes in TIFF/PDF formats to each user's mailbox and personal web interface, picking out the right recipient by the Called Line Identifier (also known as "extension") or by the line on which the fax was received.
This enables users to check faxes from anywhere in the world using either:
• A traditional desktop email client (i.e.: Outlook, Lotus Notes...). This is the Email to Fax feature • A web browser (Internet Explorer, Chrome, Firefox...). This is the Web To Fax feature
To send a fax, each user can either:
• Create it as a new message in his/her email client, the Email To Fax feature • Upload a document via web through a dedicated web page, the Web To Fax feature • Directly print from any application to the Digital Fax network printer, the Print To Fax feature
After the fax is sent, the user receives a transmission report in his/her inbox.
Digital Fax automatically manages the outgoing queue, trying to send the fax again if it not succeeded.
Together with the other units of the Application Suite, Digital Fax completes the Unified Messaging Solution for Cisco Unified Communication.
Architecture
Digital Fax can be used as an Email To Fax gateway together with any SMTP/POP3 or IMAP mail server, allowing users to send and receive faxes directly by their email client. Special email system will be discussed later (MS Outlook). In order to set up this feature, you must create a dedicated mailbox on the mail server, from which Digital Fax will fetch the faxes that will be sent out.
Digital Fax needs an email server to:
• Download emails sent by the users to a specified account (ex. [email protected]) with the file to be faxed (this is the Outgoing faxes - POP3 behavior) • Notify each user of incoming faxes via email with the fax as attachment (this is the Incoming faxes - SMTP behavior). See the Receive a fax section for further details on how let users receive a fax
This is the architecture of the Email To Fax behaviour:
Administration Guide 2/75 Description and Architecture Users send emails to a specified recipient (for instance: [email protected]), specifying the fax recipient number in the subject field and attaching the file to be faxed.
Multiple recipients and multiple attachments are supported.
Digital Fax must be configured with the designated IMAP/POP3 account (in our example: [email protected]) and the polling interval for email checking.
Digital Fax downloads the email and converts the attached file to a fax by printing it to a graphic file. This will be queued to be sent to the specified recipient number.
Note: Digital Fax can send many faxes at the same time, limited only by the number of avaliable lines and license channels. Even if many channels are free, faxes addressed to the same recipient number will always start one after the other. This means that the second fax will start only when the first has been sent or it has exhausted its retries.
When the fax has been processed, Digital Fax notifies the sender with a return receipt in his/her mailbox.
This is the architecture for the incoming faxes:
Administration Guide 3/75 Description and Architecture Digital Fax is receiving a fax for a specific number. Digital Fax manages the dnis (called number) and ani (caller number) to pick out the user to whom the fax is addressed to (see User configuration).
Digital Fax notifies the user by email of a received fax. It can also attach the received fax.
To enable email forwarding capabilities, please double check that a fax email address has been configured for such that users. This address is exclusive to the fax. Although it can be the same of the user ordinary e-mail address, it is to be entered in a different field.
Administration Guide 4/75 Description and Architecture Users and faxboxes configuration
User Basic Configuration
You should create a IAS user for each person that you want to allowed to send or receive a fax with Digital Fax. You could also create group fax numbers, or receive all the faxes on a single mailbox, both those tasks are described in the advanced configuration.
These are the fields you must fill in the Users Management for each user who needs to send/receive faxes:
• Fax number: represents the personal fax number associated to the user. It can be an extension internal number number or a DID (Direct Inward Dial) number. For incoming faxes it must exactly match the called number sent by the PBX or voice gateway to Digital Fax. • Offnet fax number: populate this optional field if you want to send an outgoing offnet fax using a calling number different from the user fax number. It can be used, for instance, to specify the E.164 phone number corresponding to the internal fax number. If empy, the same fax number defined above will be used both for incoming and outgoing faxes. This number is not considered for internal (on-net) faxes. • Enable Receive: to enable the user to receive faxes. If this is set to "True", the faxes addressed to the user's fax number (403 in our example) will be available to him/her from the Inbox web page. If this field is set to "False" and a default user is defined for Digital Fax, the fax will be received anyway and assigned to the default user. If it is set to "False" and a default user is not configured or is not enabled to receive, the incoming fax will be rejected. • Enable Send: this gives the user the sending capabilities, from any interface. Set to "True" to enable the user to send faxes. A user who is not enabled to send faxes but still tries to use the Email To Fax or the Web To Fax features will receive a message stating that the feature is not enabled for him/her • Enable Fax To Email: a field to activate the email notification of a received fax, which causes the faxes addressed to that user (403) to be forwarded to his/her mailbox, specified in the Fax2Email address field. The user can also receive a copy of the fax attached to the email if you check the Fax To Email Attach Fax flag • Attach Fax: this flag allows to receive a fax copy together with the email notification. • Notifications preferred template: the filename (without extension) of the email template to be used for fax server notifications for this user. • Company name: the sender company name, appearing in the fax header and in the fax coverpage. This field, if populated, overrides for this user the same parameter defined at system level (Application Settings --> Company Info). • TSID: the transmitter fax ID, appearing in the fax header, normally containing the fax sender number. This field, if populated, overrides for this user the same parameter defined at system level (Application Settings --> Company Info).
To learn how to edit the user's fields, please refer to the IAS Configuration, User Management section.
User Permissions
User permission control both the capability to send/receive faxes and the service management. Following, the available access levels for Digital Fax:
• No Access: the user is not enabled to receive/send faxes, neither to consult his/her fax inbox/outbox. • Base Access: the user can send/receive faxes and consult his/her fax list (inbox/outbox), see/download his/her own fax documents. • Manage Department Faxes: in addition to the base access, this level permits the user to consult the fax list of all users (inbox/outbox) of his/her department. However, for privacy policy, the user cannot see/download the other users' fax documents. • Complete Management: the user can send/receive faxes, consult the fax list (inbox/outbox) of all users, change the service settings and start/stop the service. However, for privacy policy, the user cannot see/download the other users' fax documents.
Assigning such access levels, Digital Fax can be enabled or disabled per user. However, to enable/disable the service to all users, you do not need to change the access level for each user. In facts, you can set the default access level (base acccess is the default) inherited by all users and then set the exceptions to specific users.
Administration Guide 5/75 Users and faxboxes configuration Note: in addition of the mentioned access levels, in order to send and receive faxes,you must also ensure that:
• the user has the flags "Fax: enable send" and "Fax: enable receive" enabled. • Incoming and outgoing faxes are globally enabled at system level . Please refer to the Digital Fax Administrative Configuration section, below.
User Preferences
The users with permission level 2 or higher will be able to change some preference through the web interface: enable or disable fax to email, the fax2email destination address, and if the fax will be attached to the notification.
Fax User Configuration Example
Suppose you have a public pool of numbers like 02 97865xxx. This means a DID (Direct Inward Dial) with one thousand available numbers (from 02 97865000 to 02 97865999).
• You have reserved 3xx numbers for the phone extensions of the users • You will now reserve 4xx numbers for the related fax extensions
Then you can create a user to test fax features with the following parameters:
• Name and Surname: Christian Bianchi • Phone number: 303 • Fax number: 403 • Fax2Email address: [email protected] • Enable receive: true • Enable send: true
If you want to assign the same number to both voice and fax (for each user) or if you have only one public number for both company telephone and company fax, you can use the Auto Attendant feature of Imagicle Application Suite in order to provide an automated voice response to choose between voice and fax.
Administration Guide 6/75 Users and faxboxes configuration Administrative configuration
To configure Digital Fax click on the "Application Settings" link on the menu. Such link is available to Digital Fax administrators.
Email Configurations
Imagicle Digital Fax needs to integrate with the customer email server leveraging two different dedicated email accounts:
• A POP3/IMAP/EWS email account is needed for the mail2fax feature (tipically [email protected]). This account is periodically polled by the service to detect new faxes to be sent by end-users. NOTE: All email messages in the Inbox folder of this account will be downloaded and automatically deleted by Imagicle Digital fax as they get processed. • An SMTP account (tipically [email protected]) is needed to send email notifications to end-users about fax transmissions and receptions. Actually, for this purpose a regular email account is not strictly needed, the system can also leverage an SMTP relay mechanism enabled on the customer email server.
Please notice that the 2 mentioned accounts must have different email addresses, to avoid dangerous email loops that could lead to unpredictable results.
The following sections describe in details the configuration of the mentioned accounts.
Outgoing faxes - email download parameters
Outgoing Faxes Configuration
Select the "Set" button near "Outgoing Faxes" to open the "Email2Fax settings" page. Here flag the "Enable Outgoing Faxes" checkbox to enable the Email To Fax feature, so that all fax users can send faxes directly through their email client. Then specify the desired Email2fax "Protocol Type", by selecting from pull-down menu:
POP3/IMAP
• a DEDICATED email address, previously defined in your email server. • Server Name is the IP address/DNS name of your POP3 or IMAP4 server • Server Port dictates which protocol you are going to use to login to above email account. Any TCP port is accepted. Standard preferred ports are: ♦ 110 for POP3 ♦ 995 for SSL-POP3 ♦ 143 for IMAP4 ♦ 993 for SSL-IMAP4 • Username is the userID associated to above dedicated email2fax address • Password to login to above dedicated email2fax address • Proxy allows to optionally choose a proxy, between those configured in Proxy section • Poll server every dictates the frequency IAS connects to email server to check for new emails
Note that clicking the "Test settings" button also saves the configuration.
Administration Guide 7/75 Administrative configuration EWS - Exchange Web Services Basic Authentication (deprecated)
This email protocol is supported by IAS rel. 2020.Winter.1 up to rel. 2021.Winter.1 and it leverages basic Microsoft HTTPS-based authentication available in MS- Exchange.
• Server Base URL is the Intranet/Internet HTTPS address of local Exchange server or cloud-based Office365 email service • Username is the userID associated to a dedicated email2fax address previously defined in email server • Password to login to above dedicated email2fax address • Proxy allows to optionally choose a proxy, between those configured in Proxy section • Poll server every dictates the frequency IAS connects to email server to check for new emails
Note that clicking the "Test settings" button also saves the configuration.
Administration Guide 8/75 Administrative configuration Please be aware that EWS Basic Authentication won't be supported anymore by Microsoft after July 2021. EWS Oauth2 authentication is supported instead, starting from Imagicle rel. 2021.Winter.1.2, and it is fully documented here.
Using Gmail as Mail server to receive and send faxes
It is possible to use the Google's cloud based mail server Gmail to send and receive faxes using email.
The following steps will guide you through the configuration required on the Gmail inbox and Imagicle Digital Fax to make the integration possible:
Gmail configurations:
1) log in to you Gmail inbox, and click on the top right icon:
2) Click on the security tab and make sure that 2-steps authentication is turned off.
Administration Guide 9/75 Administrative configuration 3) Scroll down to "Less secure app" section, and if it's not already enabled, click on "turn on" access.
4) Enable Pop3 or Imap in the Gmail inbox settings to allow Digital Fax to download emails. (By default IMAP and POP3 accesses are turned off)
Go to the home page and click on the wheel on the top right, and then click on "See all settings":
Click on "Forwarding and POP/IMAP" tab at the top:
â Scroll down to POP access and enable the option "Enable POP for mail that arrives from now on".
Optionally if you would like to enable IMAP you can do so by going to "IMAP access" section and select "Enable IMAP".
Imagicle configurations:
1) Digital Fax downloads emails from the Gmail inbox using either IMAP or POP3, then translates them into outgoing faxes. Below is a sample configuration of Gmail POP3:
The same configuration can be applied for IMAP by modifying the following parameters:
1. Server name: imap.gmail.com
Administration Guide 10/75 Administrative configuration 2. Server port: 993
2) When a fax is received by Digital Fax, and if "Fax2Email" is enabled for the user, the incoming fax is translated into an email and sent to the specified email address in user management. Below is a sample GMAIL SMTP configuration:
Incoming faxes & SMTP parameters
From the "Application Settings" page press the "Set" button near "Incoming faxes (SMTP)". Here flag the "Enable Incoming Faxes" checkbox to enable the Fax to Email feature, so that all fax users can receive incoming faxes directly in their email client.
Moreover, you can set the following parameters:
• Enable Return Receipt: this flag enables overall email notifications from Digital Fax application • Attach Fax to return Receipt: checkbox to enable fax document attachment to incoming faxes notifications • Enable Fax Enqueued Receipt: if this option is enabled, whenever a fax is added to the outgoing queue a receipt is sent to the sending user • Notify Failed Incoming Calls: When an incoming fax has been notified by the PBX but not enough or partial data is received, an email notification is sent to the fax recipient. By default, a fax without body is simply ignored • Email From Address: This is the fax2email address used by Digital Fax to send email notifications. If SMTP server allows anonymous relay, here you can specify a dummy email address on company's domain • Use sender number as FROM mail field: if flagged, above email address will include sender fax number • Server Name: This is the IP address/DNS name of your SMTP server/relay • Server Port: Dictates which protocol you are going to use to communicate with SMTP server. Any TCP port is accepted. Standard preferred ports are: ♦ 25 for SMTP ♦ 465 for SSL-SMTP
Administration Guide 11/75 Administrative configuration • Use Authentication: Flag this field if your SMTP server does not support anonymous relay • â Username: if above authentication flag is checked, add the userID associated to SMTP fax2email address • Password: if above authentication flag is checked, add password to login to SMTP fax2email address
Note that clicking the "Test" Button also saves the configuration.
Warning: Do not enter here the same account you used in the POP3 configuration. Doing so can lead to unpredictable loops if Digital Fax tries to send a fax to wrong addresses or to people who set an out-of-office autoreply message.
Selecting an attachment format for Email To Fax
Incoming faxes can be forwarded to the users' mail boxes either in TIF or PDF format. You do not need to restart Digital Fax for the change to be applied. If you enable incoming fax storage, the format of the stored documents will be the same as the ones sent by email.
The conversion to PDF format for incoming faxes is performed by an internal library - there is no need to install external programs to have this feature.
Supported File Types
Email To Fax and Web To Fax load documents on the server and convert them to fax format (black and white Tiff G4). Digital Fax is able to convert to fax these file types without installing any third party application:
• Office documents: .doc, .docx, .xls, .xlsx • Standard documents: .txt, .rtf • Images: .bmp, png, .jpg/.jpeg, .tif/.tiff (single page and b/w multipage) • Adobe: .PDF
To enable additional file types, please refer to the Advanced Configuration section.
Administration Guide 12/75 Administrative configuration Reference number
Digital Fax assigns a unique reference number to each fax it receives or sends. A small banner with that number is impressed on the top of each fax page. The number can also be used to search for the fax in the web interface through the inbox and outbox pages.
The default format for the reference number is like this:
2013.00000912 i.e. the current year followed by a dot and a sequential number padded on 8 digits. The number is reset to 0 every year.
This format is not suitable for cluster installations. If you need to edit the format of the reference number, please ask Imagicle Technical Support.
Fax Service Configuration
To access to this dialog, start Digital Fax and click the "Set" button next to "Service Configuration" on the "Application Settings" page. Various fax service parameters can be configured:
• The number of times that Digital Fax will try to send a fax • The time span between retries • The maximum number of fax that can be sent at the same time. Note that this number cannot be greater than the number of ports you are licensed to use.
Reserving Fax Ports for Incoming Faxes
If your company usually has more incoming fax than the outgoing, you may want to reserve some lines for receiving. Say that you have 12 ports. You may set the "Max Concurrent Outgoing Faxes" value to 8. This way, a minimum of 4 ports will be always available to incoming fax calls. If you have no outgoing faxes, then you could receive up to 12 faxes at the same time.
Company Info
The values specified in this dialog will be showed on all the cover pages. The TSID will override the calling number on the small banner put on the top of each fax page. Remember to also enter a valid Fax Administrator email address, to which any problem or significant fax event will be notified.
Data Retention
In this section it is possible to specify values for fax data retention.
It is possible to both configure automatic faxes and call details records deletion from Inbox/Outbox in case they are older than a defined number of days, specifying the Maximum lifetime (in days) of historical data.
That is, older data will be periodically deleted.
NOTE. Setting one of these two parameters to zero (0) disables faxes/call details records automatic deletion.
Administration Guide 13/75 Administrative configuration NOTE. The "Delete fax call details records older than (days)" setting may impact on the database size.
Administration Guide 14/75 Administrative configuration Telephony signalling and routing
This section describes how to configure Digital Fax to properly interact with the PBX or voice gateway in terms of protocols and routing.
Voip configuration can be controlled through the "IP Routes" page. From the home page select "Fax" => "Application Settings" => "IP Routes".
WARNING: you have to stop and restart the Digital Fax service from the web interface after any change done in this page.
Telephony Protocol and Negotiation
Here you can choose between SIP and H.323. Adjust your PBX configuration accordingly.
The two options on negotiation ("Allow G.711 for outgoing faxes" and "Disable T.38 for incoming faxes") are to be left unchecked for most telephony systems. Please check the PBX configuration section for additional information.
Outgoing routing
Default Route
By default, Digital Fax routes all outgoing faxes to one IP address. This is called the Default Route, and should be the IP address of the PBX or Voice Gateway enabled to send the faxes.
Warning: If the Default Route is not properly configured, Digital Fax will not work.
Digital Fax T.38 engine can route the outgoing fax calls to many different IP address. Each of these addresses is a physical device which can be a PBX or a Voice Gateway supporting T.38 or G.711 passthorugh fax transmission.
Multiple routes and Least Cost Routing
Digital Fax can manage multiple routes, i.e. multiple Voice Gateways or PBX, based on the first digits of the CALLED number. E.g. you can configure it so that all the outgoing fax calls that have a recipient's telephone number beginning by 06 are routed to a specific gateway. The faxes that do not match this rule will be routed to the Default Route.
In the "Set IP Routes" dialog, just enter the prefix and the IP and click "Add".
Fallback Routes for high availability
You can add the same route multiple times associated with different IP addresses. Digital Fax will try to route outgoing faxes towards the first destination. If the routing fails, it will try the next one. When no more IP addresses associated to the same prefix are found, the call is sent to the default route.
Adding a prefixes to outgoing faxes
Digital Fax can add a prefix to outgoing fax numbers (for LCR or any other aim) through the Ip Routes Page. In the Routing Parameters box select the "Global" PBX routing type, enter the prefix and press "Save". This parameter will affect only off-net outgoing faxes, see below.
This option will affect Print To Fax, Web To Fax and Email To Fax.
Network Routing Type
Administration Guide 15/75 Telephony signalling and routing Set this option on "External only". If you want to send faxes form Digital Fax to internal ATAs, please refer to the advanced configuration chapter.
Administration Guide 16/75 Telephony signalling and routing Advanced Configuration
This section describes how to enable some Digital Fax advanced features, including:
• Defining a "catch all" default user for incoming faxes • Creating fax workgroups • Printing incoming faxes • Storing Incoming Faxes • Changing the name of the email attachment • Configuring Advanced Fax Routing • Specifying recipient numbers in the "To:" field • Enabling additional file types as attachments, or as Web to Fax documents
The default "catch all" user
The default user can be any user from the IAS users list. A user named "default" is automatically added to the user list by the setup program. To change the default user, click on Manage Service, enter the IAS username you want to use and press Save.
Warning: Ensure the user is available and has permissions suitable to receive faxes. If the user is not selected or if the user does not exist, Digital Fax will reject the fax.
When a default user is defined:
• When an incoming fax is addressed to a number which cannot be found in the users list, it will forwarded to a default user • When an incoming fax is addressed to a number associated to a user who is not allowed to receive faxes, it will forwarded to a default user • When an outgoing fax sent through print-to-fax cannot be associated to any user, it will NOT be stored in the default user outbox. You can see them through the Outgoing report web page
You can access the default user outbox and inbox as you would for a standard user; or you can see the his faxes in the Inbox/Outbox report web pages.
Some faxes received by Digital Fax may be addressed to numbers which are not in the user list. By default Digital Fax sends these faxes to the "catch all" user if it has been defined. It prints them or stores them according to this user' preferences.
To setup a "catch all" user, create it as a normal user. Then click on "Application Settings" and enter his username in the "send all faxes for unknown users to user..." textbox.
Note: Use the internal Application Suite name of the user you defined, not the Active Directory credentials.
Press the Save button to save the changes. Restart is not required.
Busy tone for unknown recipients and the "catch all" user
If this user is not defined and the recipient number of and incoming fax is unknown, Digital Fax will reject the fax (the sender will hear a busy tone).
To let the sender of a fax for an unknown fax number hear the busy tone, leave the "default user" field blank.
Fax Workgroups
The most common way to use Digital Fax is to assign a personal fax number to each user. This way each user can send and receive personal faxes which are secure and private. Sometimes the customer needs the same faxes to be accessible to multiple users through the email and the web interface.
The easiest way to do that is to share the same username, password and email account between a group of users. This method has some disadvantages: the users cannot log onto the web interface with their domain credentials, and must explicitly select the
Administration Guide 17/75 Advanced Configuration shared email account when sending faxes.
The second way is detailed here.
Fax User Groups
Suppose you have five people working in the Sales department, and you want them to have one unique fax number. All of them must be able to send faxes as "Sales department" and to view the received faxes through the web interface.
Create one additional Application Suite user for the fax workgroup; we'll call it "sales_grp". Set the "Fax number" (e.g. 794), "Fax enable send" and "Fax enable receive" fields. Optionally, fill the other fax fields too.
Then create the five application suite users in the users list with no fax number and no fax offnet number. Set the "Fax group username" to "sales_grp". The users can be created through user synchronization.
With this configuration:
• Web inbox: The users in the group will be able to see the incoming fax addressed to the group fax number (794 in our example) through the web interface by logging with their credentials. Only one copy of the fax is stored. If one of the users deletes the fax, it will be lost for all of them • Web To Fax: on the "Send a Fax" page the users can choose to send a personal fax (default) or a group fax. If the fax is sent as a group fax, it will be displayed in the other group members outbox • Web outbox: The users in the group will be able to see the outgoing and sent faxes through the web interface by logging with their credentials. Their personal faxes will be displayed too • Fax To Email: The group members who enabled "email to fax" will receive a copy of the fax in their email inbox • Email To Fax: The faxes sent by the group members with their personal email accounts will use the group user ("sales_grp") properties, including offnet fax number and cover page if specified. The fax will be available to all group members in the web interface • Print To Fax: a fax sent this way will always be considered personal, and will not be displayed in the outbox of the other users in the group
Special case: if you want a user to be able to send both personal and group faxes, set his "Fax number" field. This user will still be able to receive group faxes but will send personal faxes by default. He or she will be able to send a group fax by adding the ";shared" suffix to the email subject. Mail notification will be sent to the personal user only (not to the email configured in the user fax group)
Printing Incoming Faxes
The print incoming fax feature allows Digital Fax to print all the fax documents a user receives. The following steps are required to be able to print incoming faxes.
1. Install all the printers you need on the Digital Fax server
Digital Fax can only print incoming faxes on printers which can be reached by the server on which it runs. The printers must be either local or mapped locally. Log onto Digital Fax server to ensure that the "Local System" account can access the printers you want to use (i.e. has the "print" permission). If you want to use network printers, adjust sharing permissions of the remote printers too.
2. Select the users which will have their fax printed
You can select which users will have their incoming faxes printer by activating the "Print Incoming Faxes" checkbox field in IAS User Management page. If you must set the field for a large number of IAS users, you may export users' data to a CSV file, edit it with MS Excel, and import the data again.
3. Choose a different printer for each user
Administration Guide 18/75 Advanced Configuration You can select a different printer for each user by entering its name in the "Printer Name" field in the "User Management - Modify user" page. For Local printers, enter the name of the printer as you see it in the Control Panel. For networks printer enter:
\\RemoteServer\MyPrinter
Where "RemoteServer" is the name of the server which shares the printer to the Windows domain and MyPrinter is the NetBIOS name of the printer itself, i.e. the printer name when it is shared in the local network.
Warning: Incoming Faxes with unknown recipient number (that is addressed to numbers which are not in the IAS database) will be printed only if a default "catch all" user is defined.
Note: Since IAS 2014.1.1 you can test the access rights to a network printer from the Manage Service -> Print and Storage page.
Copy faxes to a local or network folder
Digital Fax can create a copy of faxes to a local or network folder. There are two available options:
1. Enable copy per user* 2. Enable copy system wide
*Limited to incoming fax only.
Warning: No check is made on disk usage or disk quota
Warning: Old faxes are not deleted from these folders
Enable copy per user
Valid only for incoming faxes. System will create a folder for each IAS user.
1. Select the users who will have their fax stored
You can select which users will have their incoming faxes stored by ticking the "Store to Folder" checkbox field in IAS User Management page. If you want to set the field for a large number of users, you may export users' data to a CSV file, edit it with MS excel, and import the data again.
2. (optionally) choose the storage root folder
Log onto the Application Suite server and edit this configuration file:
c:\Program Files\StonevoiceAS\Apps\StoneFax\Server\System\Stonefax.ini
Under the [Settings] section add the following line:
CopyRootFolder=c:\FaxBackup
Where c:\FaxBackup is the directory under which the incoming faxes will be stored. Digital Fax will create a subfolder for each IAS user.
By default, Digital Fax uses this directory:
c:\Program Files\StonevoiceAS\Apps\StoneFax\Stored_Faxes
3. Choose a different storage path for some users
You can override the default storage path for a user by entering an absolute directory path in the "Storage Folder" field. E.g. c:\Sales\jSmith
Administration Guide 19/75 Advanced Configuration 4. Changing the name of the stored faxes
An advanced setting controls the way the fax are renamed before storing them to target folder. If you need to change it, log onto the Application Suite server and edit this configuration file: c:\Program Files\StonevoiceAS\Apps\StoneFax\Server\System\Stonefax.ini
Under the [Settings] section add the following line:
RenameStoredFaxAs = Fax{date}{time}-{uniqueid}{rnd3}
For the list of available variables see next section.
Enable copy system wide
You can enable copy of incoming and outgoing faxes system wide. choose the storage root folder
Log onto the Application Suite server and edit this configuration file:
c:\Program Files\StonevoiceAS\Apps\StoneFax\Server\System\Stonefax.ini
Under the [Settings] section add the following line:
CopyPathFormat=c:\FaxBackup
Where c:\FaxBackup is the directory under which the faxes will be stored.
If you want to differentiate between incoming and outgoing faxes location, or if you want to enable fax copy only for incoming or outgoing it's possible to use (alternatively to CopyPathFormat) these parameters:
CopyPathFormatIncoming=c:\FaxBackup\Incoming CopyPathFormatOutgoing=e:\Outgoing-Faxes
Additional configuration
For both the options, you can apply additional configuration regarding the network credentials used in case of network share copy and the file name of the fax copy.
Copy fax on a network share
Go to the Application Settings -> Print and Storage page. Here you can set the credentials of a valid domain user to be used when accessing the network folders. You can also test the access rights to a network folder.
Dynamic file name creation
Both the options allow to dinamically create the folder and the filename using variables. The available options are:
Field Meaning {uniqueid} A unique identifier automatically generated by the Microsoft Fax Service {username} The username (in the Application Suite) of the recipient of the incoming fax {callednumber} The called number for the incoming fax as signaled by the PBX {callingnumber} The calling number
Administration Guide 20/75 Advanced Configuration {date} Receiving date in this format: "yyyyMMdd" {shortdate} Receiving date in this format: "yyMMdd" {time} Receiving time in this format: "hhmm" {pages} Number of pages of the fax {size} Size of the fax file in bytes {serial} Serial number, equivalent to the number of received faxes {rnd3} Three digits long random number {rnd4} Four digits long random number {rnd5} Five digits long random number {direction} Direction (In or Out) {nodename} Imagicle cluster node {nodeposition} Imagicle cluster node position {uniqueid} Unique identificator across cluster {reference} Fax reference number You can enter other characters but they must compatible with the file system conventions. For instance, characters like * , \ or : are not allowed.
Changing the name of the email attachment
An advanced setting controls the way the fax are renamed before sending them as email attachment. The file extension cannot be changed. The change will affect the name of the document that will be printed if the Print per user feature is enabled. If you need to change the file name, log onto the Application Suite server and edit this configuration file: c:\Program Files\StonevoiceAS\Apps\StoneFax\Server\System\Stonefax.ini
Under the [Settings] section add the following line:
NotifyAttachmentFormat=Fax-{date}-{time}_form_{callingnumber}_to_{callednumber}
This is the default value. The available options are:
Field Meaning {uniqueid} A unique identifier automatically generated by the Microsoft Fax Service for the local machine {username} The username (in the Application Suite) of the recipient of the incoming fax {callednumber} The called number for the incoming fax as signaled by the PBX {callingnumber} The calling number {date} Receiving date in this format: "yyyyMMdd" {shortdate} Receiving date in this format: "yyMMdd" {time} Receiving time in this format: "hhmm" {pages} Number of pages of the fax {size} Size of the fax file in bytes {serial} Serial number, equivalent to the number of received faxes You can enter other characters but they must compatible with the file system conventions. For instance, characters like * , \ or : are not allowed.
Advanced Fax Routing
Different calling numbers for outgoing faxes (ANI)
Digital Fax puts a different calling number in the h.323 or SIP signaling of each user's outgoing fax so that billing programs such as Imagicle Imagicle Billing will be able to correctly track the cost of each fax.
If the recipient uses a traditional fax, he / she will see the callers' number on the display.
Administration Guide 21/75 Advanced Configuration If the user's "Offnet Fax number" is not blank, this E.164 number will be put in the signaling as CALLER number if ANI signaling is enabled. If it is blank, the user's "Fax number" will be used as caller number.
On-net and Off-net faxes
Outgoing faxes reaching their destination through the PSTN or the WAN are called OFF-NET faxes.
Faxes sent to other Digital Fax users (loopback) or to fax devices connected to the same network (usually traditional fax machines connected through ATA) are called ON-NET faxes.
By default, Digital Fax considers all outgoing faxes to be off-net except the ones sent to other Digital Fax users.
There is a second Network Routing type you can choose: "Both external and internal faxes". If you choose this routing strategy, you'll have to specify a prefix (e.g. "0"). You can enter this prefix in the "Off-net pattern" field.
• All the faxes beginning with that prefix will be considered off-net • All the others will be considered on-net
Differences between On-net and Off-net faxes
The distinction between On-net and Off-net faxes affects the ANI, i.e. the calling number which will be signaled to the PBX.
• For On-net faxes, the ANI will always be the user's "Fax Number" • For Off-net faxes, the ANI will be the user's "Offnet Fax Number". If this field is blank, the "Fax Number" will be used
The distinction between On-net and Off-net faxes also affects the "Per-User" PBX Routing type:
• For On-net faxes, no prefix will be added to the called number • For Off-net faxes, the user's "Fax Routing Prefix" will be added to the called number
Note that the "Global" PBX routing type is unaffected by the distinction between On-net and Off-net faxes.
Per User routing - Fax routing based on caller
Suppose your company has two offices with two gateways and one Digital Fax. For billing purposes you want the faxes sent by the people working in office A to reach the PSTN through gateway A and the ones from office B through gateway B.
In the Routing Parameters box select the "Per User" PBX routing type.
Edit the users' properties and set the values of the "Fax Routing Prefix" field so that users form office A have (e.g.) 11 and users from office B have 22.
Those prefixes will be added to the fax recipient number. It the original called number is 045556677, the PBX will receive 11025556677 if the fax is sent form a person working in office A, 22045556677 if the fax is sent form a person working in office B.
Then create a rule on the PBX that strips the first two digits and sends the call to the right voice gateway.
If you deal directly with the gateway you can define IP routes in Digital Fax that match 11 and 22 as described in the Multiple Routes section.
This option will affect Web To Fax and Email To Fax only. User-based routing is not supported for Print To Fax.
Email To Fax: specifying recipient numbers in the "To:" field
Effective from version 2011.6.1, Digital Fax supports sending email specifying the called number in the "To:" field like this:
Administration Guide 22/75 Advanced Configuration The parameters specified in the "Subject" field will be taken into account as usual.
To be able to send faxes this way, a special configuration on your email server is need.
1. On the DNS, add a third level domain, e.g. digitalfax.Yourdomain.com 2. On the email server, create the reserved Digital Fax account as usual. E.g. [email protected] 3. On the email server, create a "Catch All" account for that domain which redirects all the email messages to the reserved Digital Fax account (E.G. *@digitalfax.yourdomain.com -> [email protected])
Multiple recipients are not supported when you specify the called number in the "To:" field.
Administration Guide 23/75 Advanced Configuration Service management
Starting Services
Access to Imagicle UC Suite web portal as administrator and go to Digital Fax â Manage Service. Here you can find the diagnostic page of Digital Fax service.
Just click on the Start button to start Digital Fax, if not already running.
You can also start Digital Fax services through Windows service console by starting the SFXAL service. SFXAL is only a stub that will start Digital Fax and then stop. It is needed to start Digital Fax when you reboot the server.
Administration Guide 24/75 Service management Email-to-Fax Microsoft OAuth2 Authentication
This authentication method is supported by Imagicle UC Suite, starting from 2021.Winter.2 release, and it relays on advanced OAuth2 authentication available for cloud-based Office 365 email service. Previous Imagicle releases are supporting OAuth2 basic authentication, which is dismissed by Microsoft starting from July 2021.
Requirements
In order to enable email-to-fax service, interfaced to Microsoft Office 365 cloud service using OAuth2 authentication, you must configure an application on Azure Web Portal, taking note of Application ID, Directory ID and Client Secret data, needed later on while configuring this authentication method on Imagicle UC Suite. Please read the following procedure to create a new application on Azure portal and add it to UC Suite web interface.
Azure web portal configurations
Please access to Azure portal and go to "App Registrations"
Click on "New registration" and choose a name like "MyOAuth2App". Then select "Accounts in this organizational directory only" and hit "Register"
Administration Guide 25/75 Email-to-Fax Microsoft OAuth2 Authentication The following window appears, including Application ID and Directory ID. Please copy both data, for later usage.
Administration Guide 26/75 Email-to-Fax Microsoft OAuth2 Authentication Now please click on "Certificates & secrets" option, included in left pane, and add a new "client secret" with the name of your choice and never expiring.
Administration Guide 27/75 Email-to-Fax Microsoft OAuth2 Authentication Once added, you'll get some data associated to it. Please copy "Value" field for later usage. Copy the field immediately after having created the client secret, because it will be automatically hidden after few minutes, for security reasons.
Administration Guide 28/75 Email-to-Fax Microsoft OAuth2 Authentication Now click on "Add permissions" and select "API's my organization users". Then search for "Office 365 Exchange online".
Select "Office 365 Exhange online" and then select "Application Permissions"
Administration Guide 29/75 Email-to-Fax Microsoft OAuth2 Authentication From the list of available permission levels, please select "full_access_as_app" from "Other permissions" category.
Once permission has been assigned, you must authorize it for your organization, by clicking on "Grant admin consent for
Administration Guide 30/75 Email-to-Fax Microsoft OAuth2 Authentication This is the resulting page.
Optional configurations to restrict EWS Application to a mailbox set
Above described API Permission level privileges allows the application to access all EWS API on all organization mailboxes.
However, it's possible to optionally apply an advanced configuration on Microsoft Office 365 to restrict the application to access only a specific mailbox.
Administration Guide 31/75 Email-to-Fax Microsoft OAuth2 Authentication This is accomplished by accessing Exchange Online Administration Portal and create a new mail-enabled security group: Go to Recipients â Groups â New mail-enabled security group
Fill the form with a name and an alias. Those will be used later as a target of an Application Policy.
Administration Guide 32/75 Email-to-Fax Microsoft OAuth2 Authentication Save form and edit the newly created group, go to membership, add a member, search for the mailbox to be granted to Digital Fax and add it:
Administration Guide 33/75 Email-to-Fax Microsoft OAuth2 Authentication Connect to Exchange Online PowerShell and create an Application Access Policy to allow Digital Fax application to only access the newly created mail security group, by executing the following command, where:
• AppId value corresponds to the application "Client ID" value created within Azure app registration portal • PolicySecurityGroupId corresponds to "Display Name" of the previously create security group
PS > New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId "da34bf4b-b01f-47e4-bfac-2f9fc3f1383e" -PolicyScopeGroupId "Imagicle Digital Fax" -Description "Restrict Imagicle Digital Fax accessible mailboxes"
RunspaceId : 2d08b315-81dd-4140-8a28-4a49431fb44d
Administration Guide 34/75 Email-to-Fax Microsoft OAuth2 Authentication ScopeName : Imagicle Digital Fax ScopeIdentity : Imagicle Digital Fax Identity : 8f8ccdec-23bd-4452-bdb3-becc0c415a99\da34af4b-b01f-47e4-bfac-2f9fc3f1383e:S-1-5-21-2724517575-989916663-4003715733-16076635;697c4a2-f812-4072-a10f-4455db66025e AppId : da34aq4b-b01f-47e4-bfac-2f9fc3f1383e ScopeIdentityRaw : S-1-5-21-2724537575-989916663-4003715733-16076635;697c48d2-f812-4072-a10f-4455db66025e Description : Restrict Imagicle Digital Fax accessible mailboxes AccessRight : RestrictAccess ShardType : All IsValid : True ObjectState : Unchanged
Verify the rule, to check if the application can properly access the needed mailbox by executing the following command:
Test-ApplicationAccessPolicy -Identity
Output should be:
RunspaceId : 2e08b315-81dd-4143-8a28-4a49431fa44d AppId : da34ee4b-b01f-44e4-bfac-2f9fc3f1383e Mailbox : fax MailboxId : c82eee91-a3e0-43f0-9a43-03e7ec7b1e96 MailboxSid : S-1-5-21-2722357575-989916663-4003711733-159675946 AccessCheckResult : Granted
Then please verify the application can't access any other mailbox, by executing the following command:
Test-ApplicationAccessPolicy -Identity
In this case, output should be similar to below sample:
RunspaceId : 2d08b235-81dd-4140-8a28-4a49431fa44d AppId : da34af4e-b01f-47e4-beec-2f9fc3f1383e Mailbox : fax MailboxId : c82eee91-a3e0-43f0-9a43-03c7ec7b1e96 MailboxSid : S-1-5-21-272451125-989916663-4003715733-15450946 AccessCheckResult : Denied
UC Suite configurations
Please access to Imagicle UC Suite admin web portal and go to the following menu item: Digital Fax â Application Settings â Outgoing Faxes.
Inside "Email to Fax Settings" panel, please select "Office365 (Active)" from Protocol type pull-down menu. New fields appear, to be compiled with data acquired during Azure portal configuration: Application ID, Directory ID and Client Secret.
Moreover, you need to add the dedicated email account to be used for email-to-fax sending, with proxy support if required. Polling time dictates how often Imagicle Digital Fax polls dedicated fax account to check for new fax document to be sent.
Administration Guide 35/75 Email-to-Fax Microsoft OAuth2 Authentication Troubleshooting
1. When you hit "Test settings" button, you get "Invalid credential" error message.
Possibile reasons:
• Invalid data entered. • Not enough permission levels on Azure application. • Dedicated email account does not exist or it is not accessible, due to restrictions applied on Azure portal.
2. When you hit "Test settings" button, you get "Server is not reachable" error message.
Possibile reasons:
• Internet is not available • Wrong proxy settings
3. When you hit "Test settings" button, you get "An error has occured testing outgoing faxes Email to Fax setting." error message.
This is a generic error message, related to API crash during a call from Digital Fax web interface.
Administration Guide 36/75 Email-to-Fax Microsoft OAuth2 Authentication Cover pages
The first page which is automatically added to each fax is called Cover Page. Its purpose is to display fax information such as the caller number, the called name, and so on.
Using Cover Pages
When the user sends a fax from the web portal or from Jabber client, he/she can choose the name of the cover page to be added before actual fax document, by clicking on a drop-down list in the "Fax Body" section.
When a user sends a fax through email, the cover page file is selected based on the "Fax: cover page name" user field. Enter here the cover page file name without extension.
If this field is blank the default cover page will be used (see below).
Managing Cover Pages
Coverpage location
Available cover pages are stored in different folders as cover files (*.cov):
• C:\Program Files (x86)\StonevoiceAS\Settings\Enterprise\Coverpages\ â Public coverpages • C:\Program Files (x86)\StonevoiceAS\Settings\Departments\
Just add cover page files in any of above directories and the users will be able to use them in their faxes.
You can still find some default cover pages in the following system folder: c:\ProgramData\Microsoft\Windows NT\MSFax\Common Coverpages\
Default cover page
The default cover page while sending faxes from email, from web portal or from Jabber Digital Fax gadget is NOCALLEDNUM.COV. This demo cover page includes an Imagicle logo, as shown in above screenshot.
If required, it is possible to assign a different cover page file as default. This is accomplished by editing the following settings file from Imagicle server's file system:
C:\Program Files (x86)\StonevoiceAS\Apps\Stonefax\Server\System\Stonefax.ini
• Under [Settings] statement, please add or amend (if already existing) the following line:
â DefaultCoverPage=
If you want to disable the cover page, leave empty the value â DefaultCoverPage=
• Save file • Restart StoneFax service
Administration Guide 37/75 Cover pages Design Your Own Cover Page
You can edit a cover page file by using FXSCOVER.EXE application, available in Imagicle server or in any Windows-based PC.
Warning: the .cov extension may not be associated with the cover editor. If you double click the cover page file and Windows asks you the program to use, you can locate FXSCOVER.exe in Windows\System32 folder. Or run "Windows Fax and Scan" on the Application Suite server.
If you delete all the cover files, the feature will be disabled and the users won't see the drop-down list with the names of the cover pages anymore.
Localized Cover Pages
In a multi language environment you may want the same cover page to be available in different languages and to be selected based on the sender user's language.
• Set the user language prefix in the User Management page • Prepare one copy of the .cov file for each language in the root cover pages folder • Name the files like this:
Administration Guide 38/75 Cover pages Solution-specific Configuration
Alice Corporate
In the "Manage Service", "Ip Routes" web page configure the following parameters.
• Protocol: SIP • Negotiation: Allow G.711 for outgoing faxes • Network routing type: Both offnet and on-net • Off-net pattern: Enter the common prefix to reach the PSTN • PBX Routing Type: Per user
Edit the default route so that it points to the PBX.
In the user's management configure the "Fax Routing Prefix" and "Fax Off-net Number" as required.
Impresa semplice
In the "Manage Service", "Ip Routes" web page configure the following parameters:
• Protocol: SIP • Negotiation: Allow G.711 for outgoing faxes, Disable T.38 for incoming faxes • Network routing type: Extenal (offnet) faxes only • PBX Routing Type: Global • Prefix to the called number: enter 0 if needed to reach the PSTN
Administration Guide 39/75 Solution-specific Configuration Edit the default route so that it points to the PBX.
In the user's management configure "Fax Off-net Number" as required.
Unigate - FastWeb
In the "Manage Service", "Ip Routes" web page, configure the following parameters:
• Protocol: SIP • Negotiation: No selection (Allow G.711 UNCHECKED and Disable T.38 UNCHECKED) • Network routing type: External (offnet) faxes only • PBX Routing Type: Global • Prefix to the called number: enter 0 if needed to reach the PSTN
Administration Guide 40/75 Solution-specific Configuration Troubleshooting
Troubleshooting a fax transaction
In below flow chart, you can perform some troubleshooting actions to verify correct communications between Imagicle Fax Server and CUCM. Moreover, you can also troubleshoot communications between Imagicle Fax Server and Company's email server.
Administration Guide 41/75 Troubleshooting Administration Guide 42/75 Troubleshooting Please note that each fax transaction can be followed in real-time from Imagicle web portal. Incoming faxes are available in"Global Inbox" Fax Server menu, while Outgoing faxes are available in "Global Outbox". Each fax transaction includes a Status message, whose meaning is explained in "Error description" spreadsheet file attached to this KB.
Other common Issues
When sending a fax, its status changes from queued to "out of service" in the outbox
• Check that the SIP trunk connecting CUCM to Digital Fax is in service • Check that the general route pattern for outbound calls is engaged to reach PSTN. • Check if a prefix is required to call outside (like 9 or 0)
When sending a fax, its status changes from queued to "destination unreachable" in the outbox.
Check that the inbound calling search space is correctly configured on the trunk that is connecting CUCM to Digital Fax.
When sending a fax, its status changes from queued to "Incomplete Address" in the outbox.
The reason this error is thrown is because the Telco is expecting a certain format of calling number such as "263XXXX", everything else is blocked. In order to rectify the issue the "offnet fax number" for every user sending fax, should be populated. Check below screenshot for more information.
In order to check which prefix is being used in the calling number, check the "External Phone Number Mask" in the Line/Directory number of any phone registered to CUCM.
Administration Guide 43/75 When sending a fax from a Fax machine registered to CUCM, internally to Digital Fax, a busy tone is heard instead of a fax tone.
Check if the ATA where the fax machine is connected has the correct Device pool.
When I send a fax from user's web portal, from email client, etc. It fails with "offline destination" message.
• Check for IAS network configuration: check that Last Fallback / Default RouteIP is properly configured (Digital Fax -> Applications Settings -> IP Routes) • Please proceed as follows in order to collect what is necessary to analyze the issue:
Enable Standard Digital Fax logs
1) Login as Administrator in the SAS web interface 2) Go to Main | Support 3) Place a flag on "EnableLog"
Enable T38 Digital Fax logs
1) Open the file
Enable Wireshark trace
• Run Wireshark and start a capture
Begin test
• Recreate the issue you are experiencing
Collect Digital Fax LOGS and Wireshark trace
1. Login as Administrator in the UC Suite web interface 2. Go to Main | Support|Logs 3. Select "Stonefax" under "For application:" 4. Select the correct date when the issue has been recreated under "With date:" 5. Click on "Download" and save the file 6. Pick up the file "t38_trace.log" in
Administration Guide 44/75 When I send a fax from user's web portal, from email client, etc. It fails with "failed negotiation" message.
• Check for codec settings both on IAS and on CuCM. If T.38 is not supported by voice gateway or carrier, please check relevant flags available into Digital Fax "IP Routes" settings.
When I send a fax from user's web portal, from email client, etc. I don't receive any notification on my personal mailbox.
• Make sure user is properly configured with a valid email address into "Fax2Email" relevant field. • You can check the issue looking at log files Stonefax.Core.Service/Stonefax.log "mail without destination address" • If the Application Suite is configured to sync with an external source, please make sure "Email" field is imported during synchronization
When I send a fax from my email client, an undesired or wrong cover page is automatically added to fax transaction.
• Make sure that each user is properly configured with own cover page in relevant field. If no cover page should be automatically added, please set the relevant field to "NONE"
When I send a fax from my email client, relevant transaction is not queued, nor sent.
• Make sure that POP3/IMAP4/EWS connection between Service Provider's email server and IAS is correctly established;
When somebody sends a fax to me, the transaction results successfully accomplished, but I can't find it on web portal, email client, etc.
• Make sure that Fax recipient number is configured in a IAS user; if not, fax is received by "default" catch-all user
When somebody sends a fax to me, I can find relevant transaction in my web portal's Inbox and on Jabber, but I don't receive the same via email
• Make sure that SMTP connection between Service Provider's email server and IAS is correctly established;
When somebody sends a fax to me, received document is often unreadable or incomplete
• Make sure that T38 FoIP protocol is enabled in both IAS server and voice gateway(s)/SBC
Somebody is trying to send me a fax, but he notices he can't due to busy tone.
• Launch Digital Fax report to check fax channels usage; likely there are no enough resources (channels) in the system
When I search for a specific fax transaction in my web portal's or Jabber's inbox/outbox, I can just find recent transactions
• Check on Digital Fax global settings what's the configured data retention. Make sure you are searching for a fax which hasn't been deleted yet.
Administration Guide 45/75 License Activation
Digital Fax is licensed per channel, regardless the number of users and gateways.
The channel number corresponds to the total amount of concurrent fax calls (incoming and/or outgoing).
Digital Fax can handle up to 90 channels per server.
Digital Fax supports high availability cluster with hot-swap redundancy and load balancing, both for incoming and outgoing faxes. Each server requires a separate license, depending on chosen active-active or active-standby required HA modes. You can add up to 8 nodes to a Digital fax cluster.
Evaluation
Digital Fax runs for 30 days in evaluation mode. During evaluation, Digital Fax allows two concurrent fax transactions (2 channels).
How to activate the license
The license can be online-activated from Imagicle Cloud Licensing portal. See here for more details.
Administration Guide 46/75 License Activation PBX Configuration
Cisco Unified Communications configuration
Digital Fax interacts with the Unified Communications system through both SIP or H.323 protocols using both T.38 or G.711 passthrough modes.
The SIP configuration is suggested. Remember to enable Digital Fax SIP engine from admin's UC Suite web portal: Digital Fax â Application Settings â IP Routes.
In the following examples, we are supposing the Digital Fax server IP address is 10.10.10.1
General concepts
• The PBX sees the Digital Fax server as a SIP or H.323 gateway • The signaling transport must be SIP over UDP or H.323 over TCP for both directions (PBX to Digital Fax and Digital Fax to PBX) • The audio encoding of RTP stream must be T.38 or G.711alaw/G.711ulaw • On the PBX you must configure routing rules to allow incoming faxes reaching Digital Fax and outgoing faxes to be routed toward PSTN
Note: if you configure Digital Fax on H.323, remember that it listens for incoming faxes on non-standard TCP port 1721
Configuring Voice Gateways using SIP or H.323 protocol
In this configuration, Digital Fax directly sends and receives SIP calls, trying to negotiate T.38 first and fallback to passthrough in case T.38 is not available (e.g.: sending fax internally to Cisco ATA devices).
This configuration can be chosen if you have Call Manager Express or if you have Call Manager with at least one voice port configured in H.323 or SIP. You cannot directly send faxes through the Voice Gateway if it is configured with MGCP.
On the voice gateway you must enable T.38 and fallback to G.711 passthrough in global configuration mode (G.711alaw in the examples)
voice service voip
fax protocol t38 fallback pass-through g711alaw
Then a dial-peer must be added to route incoming faxes to Digital Fax. The session target points to the UC Suite server and the codec is G.711alaw.
dial-peer voice 1 voip
description INCOMING FAX FROM PSTN TO DIGITAL FAX
destination-pattern 4..
session target ipv4:10.10.10.1
session protocol sipv2
codec g711alaw
no vad
Quick troubleshooting tips
Administration Guide 47/75 PBX Configuration Warning: effective from Cisco IOS ver. 15.2(1)T, calls from non-trusted IP addresses are blocked by default. To allow outgoing faxes from Digital Fax you must either add it to the ip address trusted list or disable the toll-fraud prevention application completely (with the no ip address trusted authenticate command).
• If Digital Fax does not seem to negotiate outgoing faxes, remember that you need the SIP to SIP, h323 to h323 or SIP to H323 commands on the VG global configuration • Install Wireshark on the Digital Fax machine to check negotiation (from the Telephony Menu select "Voip Calls") • If incoming faxes do not reach the Digital Fax machine, ensure that no dial-peer is diverting the call (usually dial-peers with destination pattern .T). Use the show dial-peer voice summary command • If you want the remote hardware fax machines sending faxes to your Digital Fax to get a busy tone when all Digital Fax licensed channels are in use, add the max-conn X command to the Digital Fax incoming dial-peer, where X is the number of licensed channels
Configuring Cisco Unified Call Manager
In this configuration, Digital Fax interacts with Cisco Call Manager to send and receive SIP calls, trying to negotiate T.38 first and fallback to passthrough G.711 in case T.38 is not available (ex: sending fax internally to Cisco ATA devices). This configuration must be chosen if you want to be able to bill outgoing faxes (for example with Imagicle Billing).
Since the signaling must be transported over UDP only, a new SIP Trunk Secure Profile is needed. Select System â Security â SIP Trunk Security Profile.
Click the Add New button. Leave all the options to default values except for the Outgoing transport type, which must be set to UDP. The security mode must be left "Non Secure".
Administration Guide 48/75 PBX Configuration The Call Manager must be configured by adding a new SIP trunk with the Digital Fax address and the correct inbound calling search space for Digital Fax to be able to send outgoing faxes.
Administration Guide 49/75 PBX Configuration Remember to set a valid CSS for inbound calls on the Trunk configuration, to allow Digital Fax to send outgoing faxes.
Administration Guide 50/75 PBX Configuration The Calling Party Selection in the Outbound Calls section must be set to Originator.
Please ensure that the Digital Fax SIP Trunk Security profile is selected in the SIP Information panel.
The last step is to add a Route Pattern, which is needed to route incoming faxes to the Digital Fax SIP trunk. In the following example we configure all calls in the range between 400 to 499 to be routed to Digital Fax.
Then the voice gateway must be configured to enable T.38 and fallback to passthrough in global configuration mode (G.711alaw in the examples) voice service voip
fax protocol t38 fallback pass-through g711alaw
Configuring MGCP Gateways
While dealing with Cisco Unified Call Manager using MGCP controlled voice gateways, specific commands must be issues on the gateways:
Router(config)# no mgcp fax t38 inhibit
Router(config)# mgcp package-capability fxr-package
Router(config)# mgcp default-package fxr-package
Administration Guide 51/75 PBX Configuration show mgcp command should then list the fax properties as shown below:
MGCP supported packages: gm-package dtmf-package trunk-package line-package
hs-package ms-package dt-package res-package mt-package fxr-package
MGCP T.38 Fax is ENABLED
MGCP T.38 Fax ECM is DISABLED
MGCP T.38 Fax NSF Override is DISABLED
MGCP T.38 Fax Low Speed Redundancy: 0
MGCP T.38 Fax High Speed Redundancy: 0
This would enable propagation of t38 capabilities in SDP and notifications of t38start and t38stop events as defined in fax package.
An example of IOS configuration for MGCP T.38 support follows: voice-port 0/0/0
bearer-cap Speech
!
ccm-manager mgcp
ccm-manager music-on-hold
ccm-manager config server CCM-IP
ccm-manager config
!
mgcp
mgcp call-agent CCM-IP 2427 service-type mgcp version 0.1
mgcp dtmf-relay voip codec all mode out-of-band
mgcp rtp unreachable timeout 1000 action notify
mgcp modem passthrough voip mode nse
mgcp package-capability rtp-package
no mgcp package-capability res-package
mgcp package-capability sst-package
mgcp package-capability pre-package
no mgcp timer receive-rtcp
mgcp sdp simple
mgcp rtp payload-type g726r16 static
!
mgcp profile default
!
Administration Guide 52/75 PBX Configuration dial-peer voice 2 pots
service mgcpapp
port 0/0/0
!
Warning: after configuring the voice gateway in MGCP mode, please save your configuration and reboot it.
To troubleshoot MGCP T.38 fax relay, perform the following steps:
Router# show mgcp
1. Make sure that you have a working MGCP network and that you can make a voice call 2. Make sure that T.38 fax relay for MGCP is configured on both the originating and terminating gateways 3. Use the following commands to debug problems while making the call: 1. The show mgcp [connection | endpoint | statistics] command displays information about MGCP calls. 2. The show voice call summary command indicates, during a T.38 fax transmission, a change of state from S_CONNECT to S_FAX in the VTSP STATE column and a change from the codec name to a numeric fax rate in the CODEC column (for example, g711u changes to 14400) 4. For CA-controlled T.38 fax relay, you can verify the MGCP side of the call flow by using the debug mgcp packets command. You should see the following output: 1. CRCX from the call agent with "fxr/fx:t38-loose" or "fxr/fx:t38" parameter 2. RQNT from the call agent with "R: fxr/t38" parameter 3. NTFY from the gateway with "O: fxr/t38(start)" parameter (optionally) 4. MDCX from the call agent with either "m=image" in the SDP message, or "a:image/t38" in the Local Connection Options message, or both 5. For CA-controlled T.38 fax relay, you should see the following messages in the output from a show voice call summary command on the MGCP gateway during a T.38 fax transmission: Change of state from S_CONNECT to S_FAX in the VTSP STATE column; change from codec name to numeric fax rate (such as "g711u" to 14400") in the CODEC column.
General troubleshooting tips for Cisco Unified CallManager
• On CuCm most issues are related to the partitions or Calling search spaces. The CSS for Inbound Calls on the SIP trunk must be suitable to reach the PSTN through the voice gateway • Test incoming and outgoing faxes separately • If you need to change the properties of the default SIP profile, remember to create a custom SIP profile for Digital Fax so that its SIP trunk remains unaffected by the changes • Warning for CuCM cluster installations: Placing the Digital Fax SIP trunk in the Default device pool does not ensure it can be always reached. In CCM cluster installations, ensure that the Cisco Unified Call Manager Group associated with the Default device pool contains all the CuCms in the "Cisco Unified Communications Manager Group Members" selection list
Direct Inward Dial (DID) Or Shared Numbers?
Digital Fax manages the dnis (called number) and ani (caller number) to directly address the incoming fax to the specific user. This feature requires DID (Direct-Inward-Dial) configuration from the TELCO, in order to manage a pool of public numbers. If you don't have DID, you can have a single public number dedicated to fax.
In this case, you have a simpler context with one user only (the company fax). So you can follow the sample provided in this guide and apply it to the unique available user.
Administration Guide 53/75 PBX Configuration Print To Fax
Imagicle print2fax allows Digital Fax PC users to send faxes from any application, by selecting standard "Print" option in the application and choosing "Imagicle print2fax" virtual printer.
Users leveraging this feature must be enabled for fax sending in Imagicle UC Suite users' DB. See here for more info.
Requirements
• Imagicle print2fax driver requires a 32bit or 64bit Windows PC workstation, with Windows 7 or above operating system • PC workstation should reach Imagicle UC Suite server over the IP network.
Print to Fax Driver Installation
Depending on your Windows OS, please download the relevant installation package:
• Print2fax 32bit installation package • Print2fax 64bit installation package
Both packages are provided as MSI application, which can be used for a single PC installation or for a massive deployment in all Corporate PC workstations.
• Please run the package (Windows installation wizard) and accept license agreement. • You can choose a specific installation directory or just leave the default location. • When prompted, please enter Imagicle UC Suite IP address or FQDN. • Then proceed with wizard until the end.
If the installation has been properly accomplished, you can find a new printer called "Imagicle print2fax" into Devices and Printers control panel. See below sample:
Driver first-time configuration
From your PC's Windows Start menu, please select "Imagicle print2fax GUI". The following window pops-up:
Administration Guide 54/75 Print To Fax Please click on "Configure" and add the following data:
• Imagicle server address: Imagicle IP address or FQDN • Use secure connection: if flagged, the connection to UC Suite happens through https session on port 443 • Skip server certificate checks: If checked, https connection is established even if the digital certificate is not valid • Username: User's ID (typically, same as Active Directory username) • Password: User's password (typically, same as Active Directory password) • Notification email: an email address where user can receive a notification about outbound fax transaction • Notify status: if checked, user gets email notification about ongoing fax transmissions
See below sample:
Administration Guide 55/75 Print To Fax Hit OK to save the configuration.
From now on, user who needs to send a fax from an application can just select "Print" option and choose "Imagicle print2fax" virtual printer. Printed pages are sent to specific fax recipient(s) added in Imagicle print2fax dialog. You can consult Digital Fax User's Guide for more details.
Administration Guide 56/75 Print To Fax Product Integration API
Overview
This section describes the REST API that can be used to integrate Digital Fax and third party systems, making them capable to automate fax-related activities.
Basic Authentication
The REST API identifies its user with HTTP Basic Authentication. That is, if a function requires authentication, then it requires the Authorization HTTP header, which must be as follows:
Authorization: Basic
For instance, suppose you need to call a function with user="myuser" and password="mypassword". You need to base64-encode the string "myuser:mypassword", which is "bXl1c2VyOm15cGFzc3dvcmQ=", obtaining the following HTTP header:
Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=
Postman samples
The attached ZIP file (at the end of this page) contains a json collection file that you can import into Postman. It includes some samples useful to understand how to invoke with Postman the relevant API methods.
Product Integration API 57/75 Product Integration API Submit Fax
Submits a fax job, in order to send one or more documents to one or more recipients.
Resource URL
POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound
Resource Information
• Request Content-Type: multipart/form-data • Response Content-Type: application/json • Requires authentication: Yes
URL Parameters
None
Request body
The request body is a multipart/form-data containing a part that describes the submit information and as many parts as the attachments you want to send along the fax.
The submit information part must be as follows:
• Content-Type: application/json • Content-Disposition: form-data; name=jsondata • The content of this part must be a JSON with the following model:
Fax
Name Type Required Description Default Example subject string optional The subject of the fax null "The fax subject" The name of the cover page to use (not including the COV file extension). If specified, it must match the coverPageName string optional null "BusinessCover" name of an existing cove page. If the specified coverpage does not exists, the fax will be sent without any coverpage. The recipients of the fax. It must contain at least one recipient. recipients Recipient[] required [] See below for the Recipient data structure details. sendAsUsername string optional The username to use as the fax null "userToImpersonate" sender.
• Level 2 users: can only send as the fax group they belong to • Level 6 users: like level 2 users
Product Integration API 58/75 Submit Fax • Level 10 users: can send as any valid Digital Fax user
If not specified, the sender will be the user invoking this method. True if you want to receive email notifications about the notifyByEmail bool optional false true transmission status. False otherwise Use this parameter to specify a recipient email address for the transmission report email, different from the sending user notificationEmailAddress string optional email address. null "[email protected]" If not specified, the sending user email address will be used. This parameter is ignored if notifyByEmail=FALSE The name of an existing Speedy directory. Use this parameter to send the fax to every fax contact contained of the Speedy speedyDirectoryName string optional directory (fax multicast). null "directory1"
Such contacts will be additional recipients respect to the ones specified by the Recipients[] array. The fax body (plain text). If null or empty, then the rest of the body string optional null "The fax body" multipart body must contain at least one valid attachment. A collection of custom fields. Every custom field specified must exist in Digital Fax. customFields CustomField[] optional [] See below for the customFields data strcture details.
Recipient Name Type Required Description Default Example firstName string optional Recipient's first name null "John" lastName string optional Recipient's last name null "Doe" faxNumber string required Recipient's fax number null "123456"
CustomField Name Type Required Description Default Example name string required The name of the custom field null "field1" value string required The value of the custom field null "value1"
Response
202 Accepted
Product Integration API 59/75 Submit Fax Fax has been submitted and is being processed.
Response body
Name Type Description ids string[] The submitted job ids (one per recipient)
Error response
400 Bad Request
Response body Name Type Description reason BadRequestReason The reason why the request has been rejected
BadRequestReason Value Descritpion SyntaxError The JSON part contains a syntax error and cannot be parsed InvalidRecipients No recipients provided, or at least one of the recipients has no fax number InvalidAttachments The attachments supplied are invalid InvalidDirectoryName There is no such Speedy directory having the given name InvalidCustomFieldName There is no such Digital Fax custom field having the given name InvalidUsername There is no such user having the given username
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level • Outgoing faxes disabled for the user • Outgoing faxes disabled for the impersonated user
Examples
Fax without attachments
This example sends a fax only containing a body (i.e. without attachments) to two recipients, enabling email notifications:
POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound
Request body:
--dcb45cdc-6ac3-46ad-8dea-892a8989588d Content-Type: application/json; charset=utf-8 Content-Disposition: form-data; name=jsondata
{ "subject" : "My fax subject", "coverPageName" : "BusinessCover", "recipients" : [ {
Product Integration API 60/75 Submit Fax "firstName" : "John", "lastName" : "Doe", "faxNumber" : "123456" }, { "firstName" : "Jane", "lastName" : "Doe", "faxNumber" : "789012" } ], "notifyByEmail" : "true", "body" : "Hello everybody!" } --dcb45cdc-6ac3-46ad-8dea-892a8989588d
The response body is:
{ "ids":[ "IAS-N1_6a504a1d-12d6-44a7-a249-db6c4389f413_0", "IAS-N1_6a504a1d-12d6-44a7-a249-db6c4389f413_1" ] }
Fax with an attachment
This other example sends a fax only with a body and an attachment to one recipient, enabling email notifications:
POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound
Request body:
--8176a96c-1355-400a-8d63-69a230e8c5ea Content-Type: application/json; charset=utf-8 Content-Disposition: form-data; name=jsondata
{ "subject" : "My fax subject with an attachment", "coverPageName" : "BusinessCover", "recipients" : [ { "firstName" : "John", "lastName" : "Doe", "faxNumber" : "123456" } ], "notifyByEmail" : "true", "body" : "Hello everybody! Please find the attachment." } --8176a96c-1355-400a-8d63-69a230e8c5ea Content-Disposition: form-data; name=""; filename="Attachment.txt" Content-Type: text/plain
Hi, I'm an attachment!
--8176a96c-1355-400a-8d63-69a230e8c5ea
The response body is:
{ "ids":[ "IAS-N1_1322b0b2-696f-4b0e-807d-3707e9a5d1d2_0" ] }
Product Integration API 61/75 Submit Fax Fax with multiple attachments
If you need to send a fax with two or more attachments, all you have to do is add one form part for each additional attachment you need to send. In this example we send a fax with a body and two attachments:
POST fw/Apps/StoneFax/WebAPI/Faxes/Outbound
Request body:
--8176a96c-1355-400a-8d63-69a230e8c5ea Content-Type: application/json; charset=utf-8 Content-Disposition: form-data; name=jsondata
{ "subject" : "My fax subject with an attachment", "coverPageName" : "BusinessCover", "recipients" : [ { "firstName" : "John", "lastName" : "Doe", "faxNumber" : "123456" } ], "notifyByEmail" : "true", "body" : "Hello everybody! Please find the attachment." } --8176a96c-1355-400a-8d63-69a230e8c5ea Content-Disposition: form-data; name=""; filename="Attachment1.txt" Content-Type: text/plain
Hi, I'm an attachment!
--8176a96c-1355-400a-8d63-69a230e8c5ea Content-Disposition: form-data; name=""; filename="Attachment2.txt" Content-Type: text/plain
Hi, I'm another attachment!
--8176a96c-1355-400a-8d63-69a230e8c5ea
The response body is:
{ "ids":[ "IAS-N1_1322b0b2-696f-4b0e-807d-3707e9a5d1d2_0" ] }
Product Integration API 62/75 Submit Fax Get Outbound Fax Details
Gets the details of an outbound fax identified by its id.
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/{id}
Resource Information
• Response Content-Type: application/json • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example id string required The id of the fax null IAS-N1_d53957a4-c6fa-4a89-9198-f32da47e6a58_0
Response
200 OK
Fax info have been returned.
Response body
Response body is a JSON object representing outbound fax data:
Name Type Description fax Fax The outbound fax data
Fax Name Type Description faxId string The fax id username string The username of the user the fax belongs to subject string The fax subject recipient Recipient[] The fax recipients The status of the fax. Possible values are:
• Completed status Status • Failed • Queued • InProgress • Canceled detailedStatus string A more detailed version of the fax status numberOfPages int The number of fax pages serverName string The name of the server that sent the fax submitTime DateTime The time when the fax has been submitted to the system (ISO 8601) startTime DateTime The time when the fax sending was started (ISO 8601) endTime DateTime The time when the fax sending was concluded (ISO 8601) failureReason string The possible failure reason
Product Integration API 63/75 Get Outbound Fax Details Q931Code int The Q931 Code representing the possible failure reason size int Size in bytes of the fax
Recipient Name Type Description name string The complete name (first and last name) of the recipient faxNumber string The recipient's fax number
Error response
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
404 NotFound
• No such outbound fax having the given id
Examples
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/IAS-N1_d53957a4-c6fa-4a89-9198-f32da47e6a58_0
{ "__type":"OutboundFax:StoneFax.Faxes", "detailedStatus":null, "endTime":"2016-11-25T15:57:40.0000000", "faxId":"IAS-N1_6a504a1d-12d6-44a7-a249-db6c4389f413_0", "numberOfPages":1, "recipient":{ "faxNumber":"10002", "name":"Mario Rossi" }, "serverName":"IAS-N1", "size":2897, "startTime":"2016-11-25T15:57:12.0000000", "status":"Completed", "username":"user1", "Q931Code":null, "failureReason":null, "subject":"The fax subject", "submitTime":"2016-11-25T15:56:56.0000000" }
Product Integration API 64/75 Get Outbound Fax Details Download outbound fax document
Downloads an outbound fax document.
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/{id}.{format}
Resource Information
• Response Content-Type: depending on the value of {format} parameter: ♦ tiff: image/tiff ♦ pdf: application/pdf • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example id string required The id of the fax to download null IAS-N1_d53957a4-c6fa-4a89-9198-f32da47e6a58_0 The format of the file to download. Must be one of the following: format Format required null pdf • pdf • tiff
Response
200 OK
Fax has been downloaded.
Error response
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
404 NotFound
• No such fax outbound having the given id
410 Gone
• The fax exists, but related document has been removed
Product Integration API 65/75 Download outbound fax document Examples
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/IAS-N1_d53957a4-c6fa-4a89-9198-f32da47e6a58_0.tiff
Product Integration API 66/75 Download outbound fax document Get Outbound Faxes List
Gets the list of outgoing faxes owned by authenticated user.
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/Mine
Resource Information
• Response Content-Type: application/json • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example The number of the page which we want page int optional to retrieve. It must be greater or equal 1 3 than 1. The size of the page where the results will be stored in. It must be greater or pageSize int optional equal than 0. If 0, page will be ignored 0 10 and will be returned all inbound faxes of the user. The time interval of the faxes to be retrieved. It must be specified via RHS date string optional null between:2018-01-01T00:00:00;2018-12-31T23:59:59 colon syntax using one of the following operators: "between", "after", "before".
Response
200 OK
The list of outgoing faxes is returned.
Response body
Response body is a JSON object representing outbound faxes list:
Name Type Description faxlist Fax The outbound faxes list
Fax Name Type Description faxId string The fax id username string The username of the user the fax belongs to recipient Recipient The fax recipient subject string The subject of the fax status Status The status of the fax. Possible values are:
• Completed • Failed
Product Integration API 67/75 Get Outbound Faxes List • Queued • InProgress • Canceled date string The ISO date when the fax has been submitted
Recipient
Name Type Description name string The complete name (first and last name) of the recipient faxNumber string The recipient's fax number
Error response
400 Forbidden
• The filters are not valid
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
404 NotFound
• No such outbound fax having the given id
Examples
GET fw/Apps/StoneFax/WebAPI/Faxes/Outbound/Mine
{ "faxList": [ { "__type": "LessInfoOutboundFax:StoneFax.Faxes", "date": "2020-12-02T16:20:44.0000000", "faxId": "IAS-N1_eb031e4f-58fd-45af-ae0d-77f95d5ce6d1_0", "recipient": { "faxNumber": "200", "name": "200" }, "status": "Completed", "username": "user1", "subject": "abc" } ] }
Product Integration API 68/75 Get Outbound Faxes List Get Inbound Faxes List
Gets the list of inbound faxes owned by authenticated user.
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/Mine
Resource Information
• Response Content-Type: application/json • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example The number of the page which we want page int optional to retrieve. It must be greater or equal 1 3 than 1. The size of the page where the results will be stored in. It must be greater or pageSize int optional equal than 0. If 0, page will be ignored 0 10 and will be returned all inbound faxes of the user. The time interval of the faxes to be retrieved. It must be specified via RHS date string optional null between:2018-01-01T00:00:00;2018-12-31T23:59:59 colon syntax using one of the following operators: "between", "after", "before".
Response
200 OK
The list of incoming faxes is returned.
Product Integration API 69/75 Get Inbound Faxes List Response body
Response body is a JSON object representing inbound faxes list:
Name Type Description FaxList Fax The inbound faxes list
Fax Name Type Description faxId string The fax id username string The username of the user the fax belongs to recipient Recipient The fax recipient sender Sender The fax sender The status of the fax. Possible values are:
• Completed status Status • Failed • Queued • InProgress • Canceled date string The ISO date when the fax has started to be received
Sender
Name Type Description name string The complete name (first and last name) of the sender faxNumber string The sender's fax number
Recipient
Name Type Description name string The complete name (first and last name) of the recipient faxNumber string The recipient's fax number
Error response
400 Forbidden
• The filters are not valid
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
Examples
Product Integration API 70/75 GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/Mine
{ "faxList": [ { "__type": "LessInfoInboundFax:StoneFax.Faxes", "date": "2020-12-02T16:33:31.0000000", "faxId": "IAS-N1_401d6c8c07d6b7a_0", "recipient": { "faxNumber": "200", "name": "user2" }, "status": "Completed", "username": "user2", "sender": { "faxNumber": "100", "name": null } } ] }
Product Integration API 71/75 Get Inbound Fax Details
Gets the details of an inbound fax identified by its id.
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/{id}
Resource Information
• Response Content-Type: application/json • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example id string required Fax ID null IAS-N1_401d6c8c07d6b7a_0
Response
200 OK
Fax info have been returned.
Response body
Response body is a JSON object representing outbound fax data:
Name Type Description fax Fax The inbound fax data
Fax Name Type Description faxId string The fax id username string The username of the user the fax belongs to subject string The fax subject recipient Recipient[] The fax recipients sender Sender The fax sender The status of the fax. Possible values are:
• Completed status Status • Failed • Queued • InProgress • Canceled numberOfPages int The number of fax pages detailedStatus string A more detailed version of the fax status serverName string The name of the server that sent the fax submitTime DateTime The time when the fax has been submitted to the system (ISO 8601) startTime DateTime The time when the fax sending was started (ISO 8601) endTime DateTime The time when the fax sending was concluded (ISO 8601)
Product Integration API 72/75 Get Inbound Fax Details size int Size in bytes of the fax
Sender Name Type Description name string The complete name (first and last name) of the sender faxNumber string The sender's fax number
Recipient Name Type Description name string The complete name (first and last name) of the recipient faxNumber string The recipient's fax number
Error response
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
404 Not Found
• No such inbound fax having the given id
Examples
GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/IAS-N1_401d6c8c07d6b7a_0
{ "fax": { "__type": "InboundFax:StoneFax.Faxes", "detailedStatus": null, "endTime": "2020-12-02T16:34:45.0000000", "faxId": "WIN-SM96NKMUNDO_401d6c8c07d6b7a_0", "numberOfPages": 2, "recipient": { "faxNumber": "200", "name": "user2" }, "serverName": "WIN-SM96NKMUNDO", "size": 63616, "startTime": "2020-12-02T16:33:31.0000000", "status": "Completed", "username": "user2", "sender": { "faxNumber": "100", "name": null } } }
Product Integration API 73/75 Get Inbound Fax Details Download Inbound fax document
Get the document of the fax identified by given id and format
Resource URL
GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/{id}.{format}
Resource Information
• Response Content-Type (two possible values, depending on "format"): ♦ tiff: image/tiff ♦ pdf: application/pdf • Requires authentication: Yes
URL Parameters
Name Type Required Description Default Example id string required The id of the fax which you want retrieve the document null IAS-N1_401d6c8c07d6b7a_0.pdf The format of the file to download. Must be one of the following: format string required null pdf • pdf • tiff
Response
200 OK
Fax has been downloaded.
Error response
401 Unauthorized
• No authentication provided • Wrong credentials
403 Forbidden
• Insufficient privilege level
404 NotFound
• No such inbound fax having the given id
410 Gone
• The fax exists, but related document has been removed
Product Integration API 74/75 Download Inbound fax document Examples
GET fw/Apps/StoneFax/WebAPI/Faxes/Inbound/IAS-N1_401d6c8c07d6b7a_0.pdf
Product Integration API 75/75 Download Inbound fax document