From TeleForm 10.5 onwards, it has become possible to integrate .NET (either C# or VB) script via TeleForm's COM Scripting API.
This section gives an overview of the concepts and provides examples of simple scripts. The following are required:
- At least TeleForm 10.5
- A copy of Microsoft Visual Studio. A free "Community" version is available here
- Local administrative rights to your PC
Overview
A Scripting API configuration screen is available (Utilities menu / Configuration / Global System / Scripting API) which allows you to configure custom Add-Ins with TeleForm. These add-ins can perform a multitude of tasks within the TeleForm application environment, such as:
- Custom scripted business rules that check fields and forms are filled in correctly
- Database lookups for forms and fields
- Custom exports and data integration with other back-end systems
- New recognition engines for custom tasks
- Custom batch scanning configuration screens
With previous versions of TeleForm, many of these functions were possible through Microsoft VBA integration (and more historically through BasicScript). Now, TeleForm's API has been opened up, allowing you to create more advanced custom functionality. Greater customisation is a good thing, however creating .NET scripts that link into TeleForm's API requires a greater knowledge of programming than previous scripting options. Knowledge and experience of Visual Studio is a definite advantage. The process is as follows:
- Create a new class library in Visual Studio (choosing VB or C#). Ensure it is COM-visible
- Add a reference to the TeleForm Scripting API Library
- Implement the tfscript.ITFScriptAddIn interface and other required interfaces (such as tfscript.ITFFormEntryPoints to gain access to the form processing entry points)
- Add your custom business rules in the relevant functions or subroutines
- Build your DLL (dynamic link library) file, giving it a COM GUID
- Open up the TeleForm Scripting API configuration screen and add your new add-in DLL name and GUID
- Choose how workstations are to register new versions of the add-in and save your configuration
This FAQ section describes each of the above steps and provides a small example script.
Create a new class library in Visual Studio or Visual Basic Express
If you do not have a full copy of Visual Studio available, a free "Express" version is available here.
We recommend using C# as there are more on-line examples available, however, the steps in the FAQ will still work in either language.
Firstly, create a new Class Library project. In the example below, we use the project name "VBExample"
Once this has been created, choose Properties from the Project menu. Next, tick 'Make assembly COM-visible' from the Application tab:
Adding a reference to the TeleForm Scripting API Library
The next step is to add the TeleForm Scripting API reference to the project.
- Click on the Reference tab in the Properties window
- Click Add... button. A new window will open
- From the COM tab, find and select 'TeleForm 10.5 Scripting API Library'. Please note: TeleForm v10.5 and above will include the latest 'scripting API library' versions to select. Furthermore, if the 'TeleForm Scripting API Library' is not available, you will need to install a workstation copy of TeleForm on your PC
- Once selected, click OK.
Customise
We're now ready to add custom code to apply your business rules to the Add In.
The following script is added in the FormEntry subroutine.
It simply takes 3 fields: Day (values 1-31), Month ("JAN" to "DEC") and Year (as a 4-digit year) and concatenates them together into a proper date in the format DD/MM/YYYY to be placed into a field called simply Date.
Public Sub FormEntry(ByVal nContext As tfscript.TFFormEntryContext, ByVal nSubContext As_
tfscript.TFFormEntrySubContext) Implements tfscript.ITFFormEntryPoints.FormEntry
If nContext = tfscript.TFFormEntryContext.TFFormEntry_PreExport Then 'Runs before export
Try 'Using Try in case Date, Day, Month or Year fields do not exist on form
Dim ExportDate As tfscript.ITfField
ExportDate = Form.Fields("Date") 'The ITfField object is read/write
ExportDate.Text = Format(Val(Form.Fields("Day").Text), "00") & "/"
'Line above sets Date field to the day (with leading 0 if required) followed by / (e.g. 23/)
Select Case Form.Fields("Month").Text
'Line above, depending on the Month value, appends the numerical form (e.g. 23/04/)
Case "JAN"
ExportDate.Text = ExportDate.Text & "01/"
Case "FEB"
ExportDate.Text = ExportDate.Text & "02/"
Case "MAR"
ExportDate.Text = ExportDate.Text & "03/"
Case "APR"
ExportDate.Text = ExportDate.Text & "04/"
Case "MAY"
ExportDate.Text = ExportDate.Text & "05/"
Case "JUN"
ExportDate.Text = ExportDate.Text & "06/"
Case "JUL"
ExportDate.Text = ExportDate.Text & "07/"
Case "AUG"
ExportDate.Text = ExportDate.Text & "08/"
Case "SEP"
ExportDate.Text = ExportDate.Text & "09/"
Case "OCT"
ExportDate.Text = ExportDate.Text & "10/"
Case "NOV"
ExportDate.Text = ExportDate.Text & "11/"
Case "DEC"
ExportDate.Text = ExportDate.Text & "12/"
End Select
ExportDate.Text = ExportDate.Text & Form.Fields("Year").Text
'Line above appends the year (e.g. 23/04/2012)
Catch ex As Exception
MsgBox("Error:" & Err.Description) 'Display a message if an error occurs
Exit Sub
End Try
End If
End Sub
Building the class library and adding a COM GUID
In order for a TeleForm application to be able to communicate with the new .NET script (a class library), a GUID must be associated with it and visible in the COM. Visual Studio offers a tool to generate a new GUID but websites such as Guid Generator offer the same service.
GUID (or UUID) is an acronym for 'Globally Unique Identifier' (or 'Universally Unique Identifier'). It is a 128-bit integer number used to identify resources. 128-bits is big enough and the generation algorithm is unique enough that if 1,000,000,000 GUIDs per second were generated for one year the probability of a duplicate would be only 50%.
This GUID is used to associate with our new library (DLL).
To instruct Visual Studio to use a new GUID, use the code below in the Class definition:
<Guid ("B5F4EE9E-9064-4B6D-A672-329C38853B0B"), ClassInterface (ClassInterfaceType.None), ProgId
("VBExample.VBExampleAddIn")> -
Public Class VBExampleAddIn
Your own unique GUID will appear in the quotes.
You are now ready to Save and Build your Add In. To do this, right click on VBExample project in the Solution Explorer and select Build VBExample.
The resulting DLL will be visible in your project directory, for example:
C:\Users\<yourlogin>\Documents\Visual Studio 2010\Projects\VBExample\VBExample\bin\Release
This file location will be used in the next step.
Configuring TeleForm Scripting API to use your new class library
We have successfully created a new Add In and TeleForm needs to upload the required DLL when needed.
Open up any TeleForm module and select Configuration from the Utility menu. On the configuration screen, choose the Global System tab followed by the Scripting API tab. A set of pre-installed Add-Ins will appear. Click New to configure the VBExample Add-In.
The following screen should appear:
The following settings have been adjusted:
- Component Installation: copy and register. The VBExample.dll will automatically be copied and registered using the Registration Command (configured below) on workstations
- Component: click the Load button to browse to the VBExample project directory (from the last step)
- Name: this has been manually set to VBExample
- GUID: The GUID from the last step has been pasted manually
- Registration command: this command will register the DLL with the current PC's COM. Please note: the path of Regasm is dependant on the version of .NET that the project was compiled in. In TeleForm 10.5.2 (build 10555) and above, the path of the RegAsm command can be simplified using the notation <.NET 4.0>\regasm
- Enabled option: this has been ticked.
Upon clicking OK, you will immediately check the setting and receive a message in the event of an error.
If the Add-In has not been previously installed, it will automatically copy and register locally on workstations. Updated versions of your Add-In DLL must be placed in <TeleForm Mapped Drive>:\TeleForm\Scripts\AddIns to be automatically distributed across workstations.
Final configuration notes
Following the steps outlined in this FAQ section will ensure your Add-In runs for every TeleForm application (i.e. every form / batch) when enabled.
Some business rules may be required for individual forms. If so, please check the FormID value before applying business rules logic.
Further documentation on all API objects, methods and properties are found in:
<TeleForm Mapped Drive>:\TeleForm\Doc\SDK\COM
Note to editors: Please feel free to reproduce FAQ information in whole or part but we do request that you credit ePC and place a link back to our website whenever information is reproduced.
The FAQ's are compiled on the basis of questions received by ePC. If you have a question, please contact us.