FinerEdge Publisher Support Documents

FinerEdge Publisher IDE Manual.
FinerEdge Publisher Reference Manual.
FinerEdge Publisher Demonstration Tutorial.
FinerEdge Publisher Author's Guide.
FinerEdge Publisher Programmer's Guide (this document).
FinerEdge Publisher Updates and Acknowledgments.

FinerEdge Publisher Programmer's
Guide

Version 4.5.160301.0

Programmer's Guide Introduction

General Information.
The Role of an Application.
FPUtility and FPUtilityNet.

FPServices Interface Examples

Introduction.
Setting up FPServicesApp for IIS.
Testing the Sample Service.
Creating Documents from PHP.
Creating Documents from Python.
Creating Documents from Ruby.

FPServerNet Interface Examples

Introduction.
Testing the Example.

Java Native Interface Example

Introduction.
The FPJNI Bridge.
The FPTest.java classes.
Testing the Example.

ASPX and CSHTML Setup

Common Setup Instructions.
Web Pages General Setup.
Generate Web Pages Example.


FPFileWatcher Windows Service Setup

Introduction.
Setting up FPFileWatcher.


Programmer's Guide
Introduction

General Information

Note: All FinerEdge Publisher components (in particular the main FPEngine dynamic link library) and interfaces are multi-threaded capable (i.e., thread-safe).

FinerEdge Publisher documents are XML-based entities that reside externally from the applications that use them. As such, FinerEdge Publisher documents can be created and updated independently of an organization's applications. Also, FinerEdge Publisher documents can be created and maintained by a wider range of individuals than can documents that are generated directly from within application code.

The personalization of FinerEdge Publisher documents comes from within the documents themselves. Document authors can use line-of-business data in concert with conditional processing tags and conditional formatting styles. As such, line-of-business data can be easily merged into documents in a number of ways to create custom looking paragraphs, fields, tables, etc.

This document presents a number of FinerEdge Publisher interface examples. In addition, the following table assists in determining which type of interface will best meet your needs relative to the programming environment being used:

C#, VB.NET
FPWriterWPF or FPWriterNET.
C++ (All)
FPEngine.dll (FPEngine.h).
Java,
FPJNI (Java Native Interface).
ASPX, CSHTML
FPServerNet or FPServer
Web Services
FPServices or FPServicesApp

» Back to the Table of Contents. «

FPUtility and FPUtilityNet

Either the FPUtility DLL or FPUtilityNet assembly methods should be called to locate and read certain key FinerEdge Publisher preferences and set either the 32-bit (x86) or 64-bit (x64) directory depending if the invocation is 32-bit or 64-bit.

The FinerEdge FPIDE and FPSamplesCPP applications call the FPUtility DLL functions. The FPSamples, FPSamplesWPF, FPTestBench, and FPServices/FPServicesApp components call the FOUtilityNet assembly methods.

» Back to the Table of Contents. «

The Role of an Application

The role of an application with FinerEdge Publisher is two-fold. First, the application can make use of a number of high-level properties and methods to generate entire documents in multiple different output formats.

Secondly, the application can supply either none, some, or all of the line-of-business data that will be used in the generation of documents. The line-of-business data can come from databases, XML data files, fields on a form, etc.

FinerEdge Publisher comes complete with built-in database and XML data facilities to perform most, if not all, of the data access itself. In this case, your application might elect to only supply a small amount of initial information in order to control document generation.

The common mechanism for importing external information into a document from database data sources, XML files, and applications is described in the section "Application Data Interface" within the FinerEdge Publisher Reference Manual.

» Back to the Table of Contents. «

FPServices Interface
Examples

Introduction

FPServices and FPServicesApp enable a service consumer to generate all supported cross-media outputs and are accessible using both SOAP (RPC) and REST. FPServices is a WCF service library whereas FPServicesApp is a WCF service application that utilizes the FPServices service library. The FPService must be hosted from some type of host provider whereas the FPServicesApp service application is meant to be hosted by IIS.

The following example utilizes FPServicesApp and additionally presumes a default IIS installation. If the IIS installation is other than default, the example may need to be updated according to the site's configuration.

» Back to the Table of Contents. «

Setting up FPServicesApp for IIS

Note: If IIS is being installed or services are not yet enabled, please first refer to "Post IIS Installation" in this section.

In Windows Explorer, copy the installed FPServicesApp directory to (for example):

C:\inetpub\wwwroot\FPServicesApp

In IIS, create an application pool named FPAppPool:

Right-click on the new name, and select "Advanced Settings"
Set ".NET Framework Version" to "v4.0"
When using the 32-bit version of FinerEdge Publisher on a x64 machine, set "Enable 32-bit Applications" to "True" (when using the 64-bit version of FinerEdge Publisher, this option must be "False")
If using IIS 7.5 or above, the default "Identity" of "ApplicationPoolIdentity" might be sufficent. Otherwise, set an "Identity" that has the permissions necessary to read the catalog and source documents, create output formats, and create temporary files (in the temp directory)
Close the dialog

In IIS, establish an application named FPServicesApp:

Right-click on the FPServicesApp folder (under the Default Web Site) and select "Convert to Application"
Right-click on the FPServicesApp application and select "Manage Application" and "Advanced Settings"
Set "Application Pool" to "FPAppPool"
Close the dialog

Post IIS Installation -

You may need to update your IIS installation from a command prompt that has Administrator privileges.

To recognize the svc extension and install the service model enter:

%windir%\Microsoft.NET\Framework\v3.0\Windows Communication Foundation\ServiceModelReg.exe -r

To enable the http module enter:

%windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -iru

» Back to the Table of Contents. «

Testing the Sample Service

To start the sample web services SOAP test, run the FPTestBench application included with your installation. In the FPTestBench application, select the profile named "Sample Service" and press the Start button.

» Back to the Table of Contents. «

Creating Documents from PHP

To start the supplied PHP REST test, you must first install the free PHP for Windows environment (http://windows.php.net/download). The sample PHP test is named FPWriter.php located under the installed FPWriterLAMP folder (tested with PHP version 5.5.5).

In IIS, configure a virtual directory or application named FPWriterLAMP, and copy FPWriter.php to that directory. In your browser, browse to the url:

http://localhost/FPWriterLAMP/FPWriter.php

» Back to the Table of Contents. «

Creating Documents from Python

To start the supplied Python REST test, you must first install the free Python for Windows environment (http://www.python.org/download/releases). The sample Python test is named FPWriter.py located under the installed FPWriterLAMP folder (tested with Python version 3.3.2).

From a Python UI or command line, run the Python test named FPWriter.py located under the installed FPWriterLAMP folder.

» Back to the Table of Contents. «

Creating Documents from Ruby

To start the supplied Ruby REST test, you must first install the free Ruby for Windows environment (http://rubyinstaller.org/downloads). The sample Ruby test is named FPWriter.rb located under the installed FPWriterLAMP folder (tested with Ruby version 1.9.3).

From a Ruby UI or command line, run the Ruby test named FPWriter.rb located under the installed FPWriterLAMP folder.

» Back to the Table of Contents. «

FPServerNet Interface
Examples

Introduction

The FPServerNet interface is a standard CLR assembly that supports all FinerEdge Publisher functionality (including events) except a built-in document viewer. In addition to the database query and XML data interfaces, initial application variables can be set by calling the standard FinerEdge Publisher "SetVar..." methods prior to document creation or by responding to various events during document generation.

The FPServer interface is an Automation Server that has a dual implementation, which supports the IDispatch interface (i.e., late binding) for VBScript and JScript compatibility. The FPServer interface supports all FinerEdge Publisher functionality except the built-in document viewer and event facilities. In addition to the database query and XML data interfaces, initial application variables can be set from VBScript and JScript applications by calling the standard FinerEdge Publisher "SetVar..." methods.

Note: The IDE form definition view has the ability to automatically generate both .NET Web Pages (ASPX) and .NET Razor Pages (CSHTML) for documents and forms.

» Back to the Table of Contents. «

Testing the Example

To start the server test, run the FPTestBench application included with your installation. In the FPTestBench application, select the profile named "Sample Profile" and press the Start button.

» Back to the Table of Contents. «

Java Native
Interface

Introduction

FinerEdge Publisher includes a Java Native Interface (JNI) called "FPJava.dll". This interface was primarily developed for use with server-side Java programs or Java Server Pages (JSP). The FinerEdge Publisher JNI has been tested with the Java Development Kit from Sun Microsystems, Inc.

The FPJava DLL supports all FinerEdge Publisher functionality (including events) except the ability to directly view documents (e.g., the built-in FPWriter viewer).

» Back to the Table of Contents. «

The FPJNI Bridge

The FPJava.dll and the FPJNIDefs.java files (and FPJNIEvents.java interface) are the software pieces that comprise the bridge into the FinerEdge Publisher system. The FPJava.dll provides the JNI compatible C++ side of the bridge and also directly assists in accessing FinerEdge Publisher's built-in database facility. In turn, FPJava.dll DLL links with the FPEngine DLL (i.e., FinerEdge Publisher rendering engine).

The FPJNIDefs.java and FPJNIEvents.java files provides the Java side of the JNI bridge into FinerEdge Publisher. When this class and accompanying event interface are employed, the facilities of FinerEdge Publisher are immediately available to the Java program, to include access to database queries and XML data file sources.

The FPJava.java bean class was created as a class wrapper for FPJNIDefs.java and FPJNIEvents.java. This single point of contact allows both Java programs and JSPs to easily instanciate an FPJava object and thereby gain a consistent and easy access into the FinerEdge Publisher system. In addition, the compiled classes FPJNIDefs, FPJNIEvents, and FPJava are also packaged into a JAR file, which can be found in your FinerEdge Publisher FPJNI directory.

» Back to the Table of Contents. «

The FPTest.java program

There are three classes within the FPTest.java file. The public class "FPTest" contains the "main" entry point method. This method, in turn, creates an instance of the "FPTestFrame" class. The "FPTestFrame" class then creates an instance of the "FPTestPanel" class to perform the actual calls to the FPJNI facility. A number of comments labeled "TODO" can be seen at the beginning of "FPTestPanel" class. The lines showing the "TODO" text within a comment represent code that you'll need to change to your own environment.

The "FPTestPanel" class creates a PDF file from an example document. Creating the PDF file is accomplished entirely within the "actionPerformed" method for the btnTest button. If the FPJava instance has not been created, it will be created by the following line of code:

if (objFPJava == null) objFPJava = new FPJava();

We'll then create and initialize our external variables that are displayed by the example document. Next, we'll perform the processing and rendering of the FinerEdge Publisher document with the following JNI method calls:

objFPJava.SetCatalog(strCatalog);
SetCatalog.SetDocName(strDocName);
objFPJava.CreateDocument();

If an error occurs during processing, we'll detect it and display the pertinent information within the labels of our test panel as follows:

if (objFPJava.GetError())
  setLabels(objFPJava.GetErrorEntity(),
    objFPJava.GetErrorLine(),objFPJava.GetErrorCol(),objFPJava.GetErrorMsg());

However if no error occurs during processing, we'll generate the PDF file from the rendered document and report a successful generation within the labels of our test panel as follows:

else
{
  objFPJava.SetResult(strResultFile);
  objFPJava.GeneratePDF("");
  setLabels(strResultFile,0,0,"Successfully created file");
}

And finally, after generating the PDF file, we'll explicitly release any memory resources that are held during document processing as follows (although, this is not strictly necessary as memory resources will be automatically released when a new document is processed or your process detaches from the FPJava DLL):

objFPJava.Close();

Note: If you wanted to generate a PDF file and also an XPS file from the same document, you would call the JNI methods "GeneratePDF" followed by "GenerateXPS" prior to calling the JNI method "Close".

In most instances, calling programs should let FinerEdge Publisher handle most of the database extraction and XML input data processing. FinerEdge Publisher documents combine these inputs in a manner that document authors can easily maintain themselves. In addition, documents can easily handle embedded recordsets of data where the result of one recordset drives the data extraction of an inner recordset.

However, a Java program may want to drive the outermost recordset query or supply some initialization parameters. Also, there might be certain situations where the Java program may even want to perform all of the data extraction itself.

The data fed into FinerEdge Publisher from a Java program takes the form of "external variables". External variables can also be arrays where each element may be a different data type if desired (please refer to the FinerEdge Publisher reference manual for more information on FinerEdge Publisher arrays).

By convention, any FinerEdge Publisher variables created and populated by the Java program prior to calling the "CreateDocument" method are placed within the "Global" recordset. This is in contrast to recordset variables that are created during event calls to the "InitRecord" and "GetRecord" interface methods. The format for a FinerEdge Publisher external variable that is created prior to the call to the "CreateDocument" method is:

@Global_<name>

Where <name> can include alphanumeric characters or underscores and is case sensitive. In addition, the <name> can also be suffixed with beginning and ending brackets that enclose an array index specified as a whole number.

Five variables are created and populated from the FPTestPanel class that represent different data types. These variables are displayed in the example document output. The five variables in the FPTestPanel class are created and populated by the following FPJava methods:

objFPJava.SetVarLong("Long", 5);
objFPJava.SetVarDouble("Double", 6.7);
objFPJava.SetVarString("String", "Test String");
objFPJava.SetVarDate("Date", "12/15/2007");
objFPJava.SetVarTime("Time", "2:45pm");

» Back to the Table of Contents. «

Testing the Example

Prior to testing the FinerEdge Publisher JNI and working with the source code, you'll need to insure that you have a Java Virtual Machine (VM) and associated environment that supports Sun's Java Native Interface (JNI) installed on your Workstation.

After insuring that you have a compatible environment, you can compile FPTest.java and subsequently run the resulting FPTest.class. When the "JNI Tester" dialog appears, press the "Test" button to generate the PDF file from the example document. The resulting PDF file can then be displayed using Adobe's Acrobat Reader.

» Back to the Table of Contents. «

ASPX and CSHTML
Setup

Common Setup Instructions

In order to automatically generate FinerEdge Publisher ASPX and CSHTML processes from the IDE's form definition view, some setup is required.

As can be seen by the form tab within the IDE preferences or by the form properties dialog within the form definition view, a number of fields exist that control where the ASPX and CSHTML processes are generated as well as the location where the cross-media outputs are produced by these processes. If any form properties are set, they will override any corresponding IDE form preferences that are set. Likewise if any IDE form preferences are set, they will override any corresponding environment variable settings. The fields are as follows:

ASP url
The Active Server Pages (ASPX/CSHTML) url that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_ASP_HTTP" is used if it has been set (otherwise, a value of "http://localhost" is used).
ASP path
The Active Server Pages (ASPX/CSHTML) path prefix that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_ASP_HOME" is used if it has been set (otherwise, a value of "C:\Inetpub\wwwroot" is used).
Temp dir
The temporary path that is used to store all cross-media output files generated while running the process. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_TEMP_DIR" is used if it has been set (otherwise, the value of the temporary path name known by the system is used).
Please take a moment to consider the above information and decide if the default values are acceptable or if you should set any of the IDE form preferences or the "FP_..." environment variables described above. Environment variables are set by selecting the "System" icon in the Control Panel. Then, select the "Advanced" tab and press the "Environment Variables" button. You will normally want to set the above environment variables as "System variables".

» Back to the Table of Contents. «

Web Pages General Setup

An Active Server Pages (ASPX/CSHTML) container is required for the FinerEdge Publisher ASPX/CSHTML processes to execute. The Microsoft Internet Information Services (IIS) web server is normally utilized as the ASPX/CSHTML container.

On Windows 7, IIS7 can be setup by invoking the "Programs and Features" icon in the Classic View of the Control Panel. Click on the "Turn Windows Features On or Off" and select the "Internet Information Services" -> "World Wide Web Services" -> "Application Development Features". Insure that ASP and ASP.NET are checked and follow the installation instructions. Lastly, please insure that IIS is started on your machine.

On Windows 7 x86 and x64, IIS7 uses Application Pools to manage how applications are executed in IIS and their respective privileges. The IIS Application Pool where the FPServerNet executes will need privileges for reading and writing files (especially to the Temp directory). The Identity property of the Application Pool is one way to affect application privileges and supplies an easy way to test an initial installation.

On Window 7 x64 and II7, and when running the 32-bit version of FinerEdge Publisher, an Application Pool will need to be created that has the property "Enable 32-Bit Applications" set to True. The "Enable 32-Bit Applications" should be set to False when running the 64-bit version of FinerEdge Publisher.

» Back to the Table of Contents. «

Generate Web Pages Example

Create an IIS Application called FPAspApp under the web site root (note its physical directory subsequently refered to as PD) and set an application pool ID that allows documents to be created to the "Temp" location.

Create a virtual directory called "Temp" under the FPASPApp application. Insure the anonymous web user has just read access and no browse access to the "Temp" location.

Start the FinerEdge Publisher IDE and open the example document "FPDemoProductsDoc.fpm".

Go to the "Form" tab and select the "Form definition". Press the "Update form properties" button and enter "http://localhost/FPAspApp" into the ASP url, PD into the ASP path, and PD\Temp into the Temp dir.

Select the "Form generation" and press the Generate .NET Web Page and Generate .NET Razor Page buttons. The web pages will be generated to the location specified in the Form definition.

To test the web pages just generated, start a browser and enter the url:

http://localhost/FPAspApp/FPDemoProductsDoc.aspx (for .NET Web Pages)

http://localhost/FPAspApp/FPDemoProductsDoc.cshtml (for .NET Razor Pages)

» Back to the Table of Contents. «

FPFileWatcher Windows Service
Setup

Introduction

FPFileWatcher is a Windows service that monitors a variable number of file system directories for the creation of files. Based upon the naming patterns of the files created, specific documents can be generated and subsequently emailed to recipients along with links to the generated documents.

As a Windows Service, FPFileWatcher will write a number of messages in the Windows application event log. In addition, an event log file will also be created with the name "FPFileWatcher.txt" that resides in the same directory as the FPFileWatcher executable.

» Back to the Table of Contents. «

Setting up FPFileWatcher

The directories monitored for file creation activites are defined by a configuration file named "FPFileWatcher.xml" that resides in the same directory as the FPFileWatcher executable. For a detailed description of the configuration file structure, please refer to the FinerEdge Publisher Reference Manual section "Configuration File".

The FPFileWatcher Windows Service was installed with a Startup Type of Manual. After updating the configuration file, changes can be verified by monitoring the "FPFileWatcher.txt" log file. When the changes have been verified, one of the automatic Startup Types can be used instead.

» Back to the Table of Contents. «

Copyright © 2016 FinerEdge Software. All rights reserved.