Custom Application Requirements (Developer's Guide)
The custom routing application, specified by the customer, is started by the Fax Voip FSP Service when executing Custom Routing Method, after sending a fax. The individual developer is responsible for developing this application, for creating graphical user interface (GUI) to configure the rules and other settings, and for storing the configuration. The application functions can include, but are not limited to: printing faxes, storing faxes, converting fax graphic images to text files, delivering faxes in electronic mail attachments etc.
Below are the general requirements that must be taken into account by the software vendor when writing the custom application.
Command-Line Arguments
The command line passed to an application is predefined and contains all the necessary information. The developer of the custom application can parse the command line in his application to obtain the path to the fax file and other important parameters, such as Recipient Fax Number, TSID, CSID etc.
The following is an example of the command-line arguments passed to your application:
/@@@FaxFileName=C:\WINDOWS\TEMP\201d656403e9a8c_oc\FAX.pdf
/@@@RecipientFaxNumber=19012223344 /@@@RecipientName=John Smith
/@@@SenderName=Dan Black /@@@SenderFaxNumber=(631) 490-2023
/@@@SenderTSID=(631) 490-2023 FAX /@@@SenderEmail=Dan@t38faxvoip.com
/@@@SenderCompany=FaxVoip Software, LLC /@@@SenderDepartment=Sales
/@@@SenderTitle=Sales Manager /@@@SenderOfficeLocation=14
/@@@SenderHomePhone=(425) 686-1097 /@@@SenderOfficePhone=(631) 490-1288
/@@@SenderAddress=324 6th Avenue\n10014 New York\nUSA /@@@SenderBillingCode=015
/@@@DocumentName=invoice07_10_20_003.pdf;Information.txt /@@@HasCoverPage=1
/@@@Subject=This is the subject line on the cover page of the fax.
/@@@PagesTotal=4 /@@@TiffSize=132386
/@@@CSID=(901) 222-3344 /@@@TSID=Fax Voip FSP /@@@Priority=1
/@@@SubmissionTime=07.10.2020@01:28:18 /@@@OriginalScheduledTime=07.10.2020@01:28:18
/@@@StartTime=07.10.2020@01:32:49 /@@@EndTime=07.10.2020@01:36:14 /@@@Duration=00:03:25
/@@@Retries=0 /@@@PagesTransferred=4 /@@@DeviceName=Fax Voip Line 0
/@@@Status=OK /@@@JobId=201d656bff5f86f /@@@BroadcastId=2001d656bff5f75e
/@@@FaxAccount=SERVER\Administrator
Command line arguments match to the elements of the following objects: FaxOutgoingJob, FaxOutgoingMessage, FaxRecipient, FaxSender, see Fax Service Extended COM Reference documentation.
The temporary copy of the fax file (TIFF, PDF or SFF file depending on your choice) associated with outgoing fax document. This file and the temporary folder in which it is located (subfolder in the %temp% folder for Local System account) should be deleted in custom routing application after applying necessary actions. If the Create temporary copy of the sent fax in the following format option is unchecked, this argument is missing in the command line. See also in the Custom routing for outgoing faxes chapter of this user manual.
The fax number of the recipient.
The name of the recipient. Can be displayed on the cover page.
The name of the sender.
The fax number associated with the sender.
The transmitting station identifier (TSID) for the sender's device, specified in the Sender Information. Displayed at the top of each faxed page. Note that depending on the fax server settings, it may be different from the actually transmitted TSID, see also in the Configure Fax Station ID and Fax Headline chapter of this user manual. See also the description of TSID command-line argument.
E-mail address associated with the sender. If the fax is generated by the Mail to Fax function, this is the sender's e-mail address extracted from the e-mail message.
The company name associated with the sender. Usually displayed at the top of each faxed page (Fax Headline).
The department name associated with the sender.
The title associated with the sender.
The office location of the sender.
The home telephone number associated with the sender.
The office telephone number associated with the sender.
The street address associated with the sender. Usually includes the city, state, zip code (postal code) and country/region for the sender. To indicate wrap lines, the '\n' character is used.
The billing code associated with the sender.
The user-friendly name to display for the fax document. If the fax is generated by the Mail to Fax function, this is the original name of sender document including file extension. When sending multiple documents, they are separated by a semicolon. When sending a fax consisting only of a cover page, replaced with an empty string. When sending a fax in the usual way (from the Windows Fax and Scan software), can be constantly replaced by the pointless string (e. g. 'Test Fax'), due to errors in the Microsoft Fax software.
Indicates whether the fax has a cover page. Can be one of the following values: 1 - has a cover page, 0 - no cover page.
Contains the contents of the subject field on the cover page of the fax.
The total number of pages in the outbound fax.
The size, in bytes, of the Tagged Image File Format Class F (TIFF Class F) file associated with the outbound fax.
The Called Subscriber ID (CSID) received from the fax recipient. The CSID usually consists of the recipient's fax number and business name.
The transmitting station identifier (TSID) that was actually transmitted to the recipient. Depending on the fax server settings, it can be the same as SenderTSID, or it is specified by the settings of the fax device that was used for fax transmission.
Priority used when sending the fax. Can be one of the following values: 0 - low, 1 - normal, 2 - high.
The time that the outgoing fax was submitted for processing. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time that the fax was originally scheduled for transmission. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time that the outgoing fax began transmitting. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time that the outgoing fax completed transmission. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
Represents the total time that elapses between the beginning of fax transmission and the end of fax transmission. The format of this string is 'hh:mm:ss'.
In the case of a successfully sent fax, the number of times that the fax service attempted to transmit an outgoing fax after the initial transmission attempt failed. In the case of failed fax delivery, the number of times that the fax service attempted to transmit an outgoing fax. The total number of possible retries depends on the limit set.
The number of successfully sent fax pages.
Specifies the name of the device on which the fax message was transmitted.
Operation completion code. Example: OK (in the case of a successful fax sending), NO_ANSWER, BUSY.
The unique identifier for the outgoing fax.
The unique identifier assigned to the fax job during the submission process. When you submit a fax to be sent to more than one recipient, separate fax jobs will be created, but as part of the same fax broadcast, they will share the same Broadcast ID.
The name of the computer user account (fax account) who submitted the fax job.
Temporary copy of the sent fax
If the Create temporary copy of the sent fax in the following format option is checked (see in the Custom routing for outgoing faxes chapter of this user manual), the Custom Routing Method creates a temporary folder and copies the outgoing fax (TIFF, PDF or SFF file depending on your choice) into this folder. The temporary folder is created in the %temp% folder for the Local System account. The path to the temporary fax file is passed to the custom application via FaxFileName command-line argument, see above.
For example,
/@@@FaxFileName=C:\WINDOWS\TEMP\201d656403e9a8c_oc\FAX.pdf
The path to the fax file (PDF format) is:
C:\WINDOWS\TEMP\201d656403e9a8c_oc\FAX.pdf
The path to the temporary folder is:
C:\WINDOWS\TEMP\201d656403e9a8c_oc\
The temporary folder in which fax file (FAX.tif, FAX.pdf or FAX.sff) is placed can be used by your custom routing application to store temporary files that your application generates.
The custom application is responsible for deleting the temporary fax file and the temporary folder in which this file is located. You must permanently delete the temporary folder in your application after you perform all the necessary actions.
If the Create temporary copy of the sent fax in the following format option is not checked, the Custom Routing Method does not create the copy of the outgoing fax, but the custom application can still access the outgoing fax by using Fax Service API functions (based on JobId parameter that is also passed via command line).
Running under Local System account
The custom application is started in the context of the Fax Voip FSP Service using the Local System account, so the Local System account must have necessary access to files, folders and other objects with which your application works.
Terminating the application
The Custom Routing Method executes the custom routing application in the separated thread by calling the CreateProcess function. The Fax Voip FSP Service does not monitor the application after it is started and does not guarantee its correct completion. The developer of the custom routing application is responsible for the correct automatic termination of the application after execution.