Form as API  

This feature helps to host the forms in AppForms as an API in a server and can be used to execute functionalities of AppForms without a user interface. This API will be hosted as a sub site called ‘Forms’ in the AppForms site.

How to use

The API can be invoked from anywhere but for the demo purpose we will use the postman to invoke the API.

• Create a sample form.

Create a sample form in the AppForms site to run AppForms functionality without a user interface by hosting the forms in AppForms as an API on a server.

Example: Create a form to insert a value into the textbox control

Before checking in form, ensure that the “FormAsAPI” property is enabled on the property tab of the form.                       

List of controls that can be given as input in the form as API.

1. Textbox
2. Datetimepicker
3. Listbox
4. Checkbox
5. CheckBoxGroup
6. ComboBox
7. Label
8. MultiListBox
9. People picker
10. RadioButton
11. Richtextbox
12. Signature
13. Captcha
14. LookUp

• Endpoint URL 

The endpoint URL is the URL that we used in postman to get a proper response. Depending on authentication, the URL in the endpoint may change.

There are two types of authentications.

1. Basic authentication (v1)

2.     Token-based authentication (v2)

Basic authentication

Format: https://hostname/forms/api/appforms 

Sample URL: https://sys139.claysys.com:6079/forms/api/appforms

Token-based authentication

               Format: https://hostname/forms/api/v2/appforms

Sample URL: https://sys139.claysys.com:6079/forms/api/v2/appforms

Please refer page no: 16 to know more about token-based authentication.

• Method

The method to be used is POST. 

• Authorization

To connect to the API, use either “Basic Auth” in V1 (Old version) or “Bearer token” in V2 (New version)

In basic authentication, select type as ‘Basic Auth’ from the authorization tab and followed enter the username and password

In the case of token-based authentication, select type as “Bearer token” and enter the token we generated earlier.

• Request headers and Definition

The below request headers are required in addition to the default headers in postman. Request headers value can be given either in XML or JSON based on the request body that we are giving.

Request headers for the XML request body

       Accept: application/xml 

       Content-Type: application/xml 

• Request Body and Definition

Below is the sample of the Request Body that is to be used. Both XML and JSON formats are supported. Based on the request body, Accept and Content-Type must be updated in the headers.

    A sample request body in XML for inserting a value into a textbox control.

     <APIRequest xmlns=”http://schemas.datacontract.org/2004/07/ClaySys.AppForms.Model.Models” xmlns:i=”http://www.w3.org/2001/XMLSchema-    instance”>

 <APIDataList>

 <APIData>      

 <ControlName>Control name</ControlName>

 <Value>Value</Value>

 </APIData>

 <APIData>

 <ControlName></ControlName>

 <Value></Value>

 </APIData>

 </APIDataList>

 <ExecuteFormLoadRule>false</ExecuteFormLoadRule>

 <FormId>FormID</FormId>

 <FormName></FormName>

 <RuleNames>

 <RuleData>

 <RuleName>Rule Name</RuleName>

 </RuleData>

 </RuleNames>

 <TenantId>Tenant Id</TenantId>

 </APIRequest>

Output container / Field	Data Type	Description
APIDataList	List of APIData	Collection of class APIData. This class contains the input variables control name and control value
APIData .ControlName	string	Name of the control inside a form
APIData.Rows	List of RowData	Input collection that contains the data of  grid controls
APIData .Value	string	Input value of the control
ExecuteFormLoadRule	boolean	Default value is false. On value true, execute the rules created in the form load event of the form
FormId	string	GUID of the form
FormName	string	Form path of the form . Ex:  foldername.formname
RuleNames	List of RuleData	List of the rule names in the form
RuleData.RuleName	string	Name of the rule
TenantId	string	Id of the tenant

A sample request body in JSON for inserting a value into a textbox control.

{

“APIDataList”: {

“APIData”: [

            {

                “ControlName”: “Control name”,

                “Value”: “Value”

            },

            {

            “ControlName”: “”,

            “Value”: “”

             }  ]

            },

            “ExecuteFormLoadRule”: false,

           “FormId”: “Formid”,

          “RuleNames”: [

          {

         “RuleName”: “Rulename”

          }, {

         “RuleName”: “”

          }   ],

         “TenantId”: “Tenantname”

           }

• Response Body and Definition

The Response from the API will be formatted as below.

       Below is the response body for the XML request you will get after requesting the above form.

<APIResponse xmlns:i=”http://www.w3.org/2001/XMLSchema-instance” xmlns=”http://schemas.datacontract.org/2004/07/ClaySys.AppForms.Model.Models”> 

    <Controls> 

        <APIData> 

            <ControlName>Control Name</ControlName> 

            <Rows /> 

            <Value>Control Value</Value> 

        </APIData> 

    </Controls> 

    <FormName>Level 1 Form Name</FormName> 

    <Forms /> 

</APIResponse> 

       Below is the response body for the XML request you will get after requesting the above form.

{

    “FormName”: “”,

    “Controls”: [

        {

            “ControlName”: “”,

            “Value”: “”,

            “Rows”: []

        }

    ],

    “Forms”: [],

    “ErrorMessages”: []

}

Token Based Authentication

Token-based authentication is a process where the client application first sends a request to the Authentication server with valid credentials.

The Authentication server sends an Access token to the client as a response. This token contains enough data to identify a particular user and it has an expiry time. The client application then uses the token to access the restricted resources in the next requests until the token is valid. If the Access token is expired, the client application can request a new access token by using the refresh token.

The token-based authentication works as follows:

• The user enters his credentials (i.e., the username and password) into the client. (Here client means the browser or mobile devices, etc.)
• The client then sends these credentials (i.e., username and password) to the Authorization Server (here AppFormsLoginAPI works as Authorization Server).
• Then the Authorization Server (AppFormsLoginAPI ) authenticates the client credentials (i.e., username and password) and generates and returns an access  token, refresh token, and cookie. This Access Token contains enough information to identify a user and also contains the token expiry time.
• The client application then includes the Access Token in the Authorization header of the HTTP request to access the restricted resources from the Resource Server until the token is expired.

Steps to generate an authentication token.

• Endpoint URL 

      Token Endpoint URL: https://hostname/security/loginapi/token 

       Sample URL: https://sys139.claysys.com:6079/security/loginapi/token 

• Authorization

        Authorization type can be given as “No auth”.

• Request headers

      Accept: application/xml 

       Content-Type: application/xml 

• Request body

     Like in the above image, Enter three keys and values corresponding to the keys in the body tab.   

        Note: grant_type value has to be password always.

        Keys are:

1. grant_type
2. username
3. password

If TenantWise security ( IsMRMCloud: true in AppSettings ) is applied, tenantid can be passed along with the key. Refer to the below image for generating the token of Tenantwise security ‘ON ‘ site.

• Response body

Above marked item is the token where we used to give in the Authorization field of Token based authentication.