eFORMz API .NET Web Service Call
eFORMz can be called as a web service. We loosely refer to eFORMz calling itself as the eFORMz API (Application Programming Interface). For a more detailed description, consult the following post: https://minisoft.com/support/index.php/eformz-api/
To carry out a web service call to the eFORMz API with output from the API, follow the instructions below.
Step 1: Setting up the eFORMz web server
After installing eFORMz locate the Minisoft > eFORMz_6 folder. Select ‘Web_Server_Control.exe’. Enter the host address followed by the port you want the API to listen on. The default port is 9998. More information on eFORMz ports can be found here: https://minisoft.com/support/index.php/eformz-ports/
The default ‘Username’ is minisoft and the default ‘Password’ is password. Once complete, select the ‘Start Web Server’ button, then select the ‘Connect’ button. Once complete, this window can be exited.
Step 2: Running the eFORMz Service Manager
Step 3: Setting up the URL and files
To call using HTTP (not secure) protocol:
http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&config=projects/WebCallExample/config.xml
localhost = The name or IP address of the server on which the eFORMz service is running
projects/WebCallExample/config.xml = The relative pathname of the XML file from the eFORMz install directory, e.g. C:\Minisoft\eFORMz_6
To call using https (secure) protocol, here is an example of the contents of the config.xml file:
<?xml version="1.0" encoding="utf-8"?> <ServiceConfiguration ServiceType="output" project="projects/WebCallExample/WebCallExample.efz" format=".xml"> <InputData format="XML" usepostdata="true"></InputData> </ServiceConfiguration>
You would replace project="projects/WebCallExample/WebCallExample.efz" in the ServiceConfiguration node with the relative pathname of the project that will be handling the web service request. The pathname is relative from the eFORMz install directory.
C#.NET Example
namespace ConsoleApp1
{
class Program
{
private static string GetTextFromXMLFile(string file)
{
string path = file;
string readText = File.ReadAllText(path);
return readText;
}
static void Main(string[] args)
{
// Create a request using a URL that can receive a post.
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&config=projects/WebCallExample/config.xml");
// Set the properties up for the request"
request.Method = "POST";
request.ContentType = "text/xml; charset=utf-8";
request.Accept = "text/xml; charset=utf-8";
string postData = "";
//Original XML Data
postData += GetTextFromXMLFile("\\minisoft\\eFORMz_6\\projects\\WebCallExample\\Example.xml");
//Create a byte array to be able to hold the request
byte[] pData = Encoding.UTF8.GetBytes(postData);
request.ContentLength = pData.Length;
//Send the request
using (Stream requestStream = request.GetRequestStream())
{
requestStream.Write(pData, 0, pData.Length);
}
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
byte[] responseData = new byte[request.ContentLength];
//Calling read on repsonse reads the data into responseData
response.GetResponseStream().Read(responseData, 0, (int)(request.ContentLength));
string yourText = Encoding.UTF8.GetString(responseData);
System.Console.WriteLine("Return from value from web service " + yourText);
}
}
}
Note: \\minisoft\\eFORMz_6\\projects\\WebCallExample\\Example.xml is the relative path name of the XML file that contains the data you want to send to the eFORMz web server.
VB.NET Example
Imports System
Imports System.Text
Imports System.Net
Imports System.IO
Module Module1
Public Function GetTextFromXMLFile(file__1 As String) As String
Dim path As String = file__1
Dim readText As String = File.ReadAllText(path)
Return readText
End Function
Public Sub Main(args As String())
' Create a request using a URL that can receive a post.
Dim request As HttpWebRequest
request = HttpWebRequest.Create("http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&config=projects/WebCallExample/config.xml")
' Set the properties up for the request"
request.Method = "POST"
request.ContentType = "text/xml; charset=utf-8"
request.Accept = "text/xml; charset=utf-8"
Dim postData As String = ""
'Original XML Data
postData += GetTextFromXMLFile("\minisoft\eFORMz_6\projects\WebCallExample\Example.xml")
'Create a byte array to be able to hold the request
Dim pData As Byte() = Encoding.UTF8.GetBytes(postData)
request.ContentLength = pData.Length
'Send the request
Using requestStream As Stream = request.GetRequestStream()
requestStream.Write(pData, 0, pData.Length)
End Using
Dim response As HttpWebResponse = DirectCast(request.GetResponse(), HttpWebResponse)
Dim responsedata As Byte() = New Byte(request.ContentLength - 1) {}
'calling read on repsonse reads the data into responsedata
response.GetResponseStream().Read(responsedata, 0, CInt(request.ContentLength))
Dim yourtext As String = Encoding.UTF8.GetString(responsedata)
System.Console.WriteLine(Convert.ToString("return from value from web service ") & yourtext)
End Sub
End Module
Note: \minisoft\eFORMz_6\projects\WebCallExample\Example.xml is the relative path name of the XML file that contains the data you want to send to the eFORMz web server.
In order to carry out a web service call to the eFORMz API without output from the API, first, follow steps 1 and 2 from up above.
Getting ready:
There are a few things we must set-up first before we get started. First, we need to open up the director toolkit. Then go to file, new configuration, click the add button for the name and directory put: accessible. Click on the accessible directory and click the add button, put *.[file type] that you will be sending to the web server and click ok. Click on the File Selection and hit add, hover over Add output process then click on file output. This makes it so that the files that you load will be outputted to the accessible directory. Go to the Director tab, click on the + button and click on the … button and click your accessible.cfg file. Click the checkbox below to Make configuration accessible from eFORMz Web Services and hit the start button. Save your changes by clicking file and save the configuration and close the window. Now open up the director configure. Go to configure startup parameters and make sure it has: LocalPM.cfg -ac accessible.cfg in the startup parameters box and hit OK. Hit the Exit button and save your changes.
Setting up the URL:
To call using http (not secure) protocol:
http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&director&Host=localhost&Port=9996&User=minisoft&Password=password&ConfigurationName=accessible.cfg&QueueName=accessible&NameTemplate=data_.xml&ProcessData=true
To call using https protocol:
https://localhost:8000/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&director&Host=localhost&Port=9996&User=minisoft&Password=password&ConfigurationName=accessible.cfg&QueueName=accessible&NameTemplate=data_.xml&ProcessData=true
If you add on “&ProcessData=true”, the web service will wake up the queue monitor (if it is sleeping) to process anything in the queue immediately.
C#.NET example
public static void CallEformzWebService(string strXML){
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://localhost:8001/servlet/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&director&Host=localhost&Port=9996&User=minisoft&Password=password&ConfigurationName=accessible.cfg&QueueName=accessible&NameTemplate=data_.xml&ProcessData=true");
// Set the properties up for the request
request.Method = "POST";
request.ContentType = "text/xml; charset=utf-8";
request.Accept = "text/xml; charset=utf-8";
request.KeepAlive = false;
request.Timeout = -1;
string postData = "";
postData += strXML;
//Create a byte array to be able to hold the request
byte[] pData = Encoding.UTF8.GetBytes(postData);
request.ContentLength = pData.Length;
//Send the request
using (Stream requestStream = request.GetRequestStream()){
requestStream.Write(pData, 0, pData.Length);
requestStream.Close();
}
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
}
TroubleShooting
If you don’t have the request.GetResponse(); then the file won’t be loaded into the accessible folder.
If you want to be able to give the file a specific name so that eFORMz can differentiate the files then give &NameTemplate a special name. Make sure that the name follows the correct naming convention for file names, such as a special character, otherwise it will cause an error.