Instances List

 Previous  Home topic  Next  Print this topic Send Feedback

Now that the form and some test instances exist you can start writing the code to get the instances list.

 

Document Icon
1.Open the project created earlier in Setting Up a Test Form.
2.Double-click the file Form1.cs in Solution Explorer. The form Form1 will open in design mode.
3.Drag and drop a DataGridView control from the Toolbox to the form (if the Toolbox is not visible you can activate it using the menu View > Toolbox).

DataGridView Control

4.Now, with the new label selected, switch to the Properties Window (if it is not visible you can activate it using the menu View > Properties Window) and then change the property Name to ‘dgViewInstances’.
5.Add a button to the form and change the property Name to ‘btnList’; property Text to ‘Get List’; and property Enabled to ‘False’.
6.Double-click on the Login button in design mode and you will be shown the event handler function for that button.
7.You will modify the code to enable the GetList button only if the login was successful. Locate the branch where the returned result (the variable name is 'res') is 0 (no errors) and add the following line in that if branch:
8.btnList.Enabled = true;
9.Your function code should now look like this:

Look of Function Code

10.In order to work with the form, you will need to add another Web reference, but this time it should be added to the form API. Follow the same steps  as were outlined in the Logging In section of the tutorial and add the Web reference to the service created at the end of the previous section (for example: http://devel.perfectforms.com/SDKFilter/mkIggQAgAAgACggE_APIDemoForm.asmx)
11.Select the project in the Solution Explorer and right-click on it (if the Solution Explorer is not visible you can activate it using the menu View > Solution Explorer).
12.In the pop-up menu, select Add Web Reference (just below Add Reference).
13.In the Add Web Reference dialog specify the Web service address (http://devel.perfectforms.com/SDKFilter/mkIggQAgAAgACggE_APIDemoForm.asmx?wsdl) and click Go.

Add Web Ref Dialog

14.Once the Web service is discovered, name the Web reference 'APIDemoForm' and click Add Reference.
15.Now go back to the design view of the form and double-click on the GetList button. This will create an empty function block that will execute once the button is clicked.

Empty Function Block

16.You will need a new global variable; a reference to the form API.
17.Using Intellisense, type the name of the Web reference you added (APIDemoForm and then ‘.’) and see the list of types exposed by the form reference.

Web Ref Addition

18.Now that you've declared the formService, it must be initialized. This will be done in the “btnList_Click” function code.

Initializing the formService

19.Using Intellisense, find out the name of the method that returns the list of instances.

Finding Method Name

20.The GetList method has the following signature: public int GetList(string tokenIn, string[] fields,string @where, out string tokenOut, out System.Data.DataTable table)
21.Pass in the following values:
•tokenIn - The previous token (the one returned by the Login method).
•fields - An array of fields that holds the field names for which you want the values returned. If left empty you will have one internal field (“ID”) that is returned. That ID will be used later to see more details about that specific instance.
•@where - A parameter used to filter the results (for example: if set to “First_Name like 'John%'” will return all form instances where the First_Name starts with John).
•tokenOut - The new token that will be used from now on to communicate with the services.
•table - A .Net table that contains the results.
22.The name of the field respects the naming conventions from the SDK and should be fully qualified names. So if the control on the form is named 'First Name' and is placed inside a page called 'Page 1' its qualified name will be 'Page 1|First Name' and the field name should be 'Page_1_First_Name'. The basic rule for converting control names to field names is replacing each character that is not a name or a letter with '_' (underscore).
23.Additional examples of controls within 'Page 1':
•Control name - 'Date of birth' -> Field name - „Page_1_Date_of_birth'
•Control name - 'Date (MM/dd/yy)' -> Field name - „Page_1_Date__MM_dd_yy_'
•Control name - 'Strange!@#$%^&*()_+{}|[]' -> Field name - „Page_1_Strange_________________'
•Control name - 'Text 1” -> Field name - 'Page_1_Text_1'
24.Some controls acts as containers so you can place more controls inside. The full name for a textbox 'Text 1' placed in a Group or Container 'Group 1' situated in 'Page 1' will be 'Page_1_Container_1_Text_1'. A peculiarity of the fields parameter is that the Form Instance ID will always be included in the resulting table.
25.You can also copy and paste the API field name for any selected field from the Properties bar in the Form Designer.
26.Your completed function should now look like this:

Look of Completed Function

27.Now you can test your application. Go to the Visual Studio menu option Debug > Start Debugging, and when your form pops up, enter the required fields (username, password and API Key) then click the Login button. You should see a pop-up that informs you that the login was successful. After that click on GetList. You should now see the list of instances for your form.

Testing the Application

28.The result does not show any real instance information, so you should add more fields to return in the list.
29.Resize the form and the DataGridView to be slightly wider.
30.Now retest the form.

Retesting the Form

Updated: 06/12/2011  Page url: http://www.perfectforms.com/Documentation/manual/html/?api_instances_list.htm
PerfectForms™ -- forms software, workflow software, and business process management