Forms API Code Examples

The examples below use the CURL command line tool to create HTTP requests. The Python scripting language is used to store HTTP responses in variables and URL encode the HTTP requests. Virtually any language can be used and we have object oriented API Client Libraries available to simplify your development.

The command line environment used for the examples is the BASH shell (use cgywin on windows)

API Authentication

Authenticate and store the OAuth Access Token

Authenticate and store the OAuth Access Token returned from the server.

See the Authentication Overview for information on how to get the API "client_id" and "client_secret" values used in the example below.

Each example below uses the "$AccessToken" variable to populate an HTTP header named "Bearer". If the AccessToken is expired the server will respond with an unauthorized response in which case you need to request a new AccessToken.

Note: You can store the "Refresh Token" returned by the server and use the Refresh Token to request a new Access Token without re-posting the client_id and client_secret.

//Get access token and refresh token, pipe to python, extract access_token from the json response, store access_token in a variable
//The AccessToken variable will be used in all subsequent API examples            
$ AccessToken=$(curl -X POST -d "client_id=6abdcfa4-c45a-48d9-b21f-b8893c189cf9&client_secret=SqjSsY2I4bDU0E5tj9HgHYxLV0ClJJCFf75ckg3fRKU=&username=vault.config&password=p&grant_type=password" https://demo.visualvault.com/ap1/v1/customername/dbname/oauth/token | python -c 'import sys, json; print json.load(sys.stdin)["access_token"]')
$ echo $AccessToken
TAQ7K6kzcqhMFw8Sc2XXF0WUHlQ-i-IH5534_656hKwAAoccWTg4x8Zu54vbimYlRhDeDb1xhLxtyQWwsrC1HnUpfq5PUw95G3wQmDQDi7kxsTMKBQQYZ7K_UOU0IFuRgplcTHe6i8lsP2r7LD5mawU0Sw1tgmnOFd5Cg3HryCJbMvr9x9glsUu3Vd9tTFfPXfUM67w-fahhCoJDZjK8fW9nVGmBS2APX07VwNlFNuTmBYur2d5-d5-DWlCQ_nirtmBO8DfWKHpJtaDSYD0l_2u0u4xnDdUBSS1mv0FQKZaiUn2n
      

Forms APIs

VisualVault's form template designer allows you to re-create paper based forms as Web forms or design new Web forms using a familiar drag-and-drop design tool launched directly from your Web browser. For a complete description of VisualVault Forms read the Forms Documentation introduction.

Form Object Relationships and Definitions

Form Object Definitions

  • Form Templates
    Form Templates define the structure of a VisualVault Web Form. Form Templates contain 0 or more Form Data Instances created using the Template.

  • Form Data Instance
    Form Instances contain Form Fields and values. Each time a user saves a Form a new Instance or Instance Revision is created.

Forms API Examples

Get List of Form Templates

$ curl -X GET -H "Authorization: Bearer $AccessToken" "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates"
{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates"
  },
  "data": [
    {
      "href": "~/formtemplates/d7be9fc6-7abc-e411-bedc-8859ddab41cc",
      "dataType": "FormTemplate",
      "id": "d7be9fc6-7abc-e411-bedc-8859ddab41cc",
      "name": "TC3289",
      "revisionId": "acc23ac8-7abc-e411-bedc-8859ddab41cc",
      "status": 1
    },
    {
      "href": "~/formtemplates/cdadbb88-d338-e411-beaf-dfdb3596b8d0",
      "dataType": "FormTemplate",
      "id": "cdadbb88-d338-e411-beaf-dfdb3596b8d0",
      "name": "Orderform",
      "revisionId": "a9a06e31-25cc-e411-bee7-c434feb29767",
      "status": 1
    },
    {
      "href": "~/formtemplates/7302a386-50cc-e411-bee7-c434feb29767",
      "dataType": "FormTemplate",
      "id": "7302a386-50cc-e411-bee7-c434feb29767",
      "name": "Product Data Sheet",
      "revisionId": "f842847d-51cc-e411-bee7-c434feb29767",
      "status": 1
    }
  ]
}


Search for a specific Form Template

See the Query Syntax topic for assistance writing query filters.

//Get list of Form Templates using a query where the Form Template name = "OrderForm". 
 
//query syntax used is "?q=[name] eq OrderForm"
//Note the query "[name] eq 'OrderForm'" must be URL encoded with the field name in square brackets and the search predicate surrounded by single quotes.
//The python library urllib.quote_plus is used to URL encode the query string, use your language specific library to URL encode.
$ query=$(python -c 'import sys,urllib; print urllib.quote_plus("[name] eq '" + OrderForm + "'")')
$ echo $query
%5Bname%5D+eq++%2B+OrderForm+%2B+
$ FormTemplateID=$(curl -X GET -H "Authorization: Bearer $AccessToken" "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates?$query" | python -c 'import sys, json; print json.load(sys.stdin)["data"][0]["id"]')
 
$ echo $FormTemplateID
d7be9fc6-7abc-e411-bedc-8859ddab41cc
      


Get List of Form Fields for a Specific Template

Note: Form Field names prefixed with double underscore represent deleted fields. Deleted fields are hidden from the Form HTML markup but the field definition and data is not deleted. You can access deleted fields using the API or using the Form Dashboard editor.

$ curl -X GET -H "Authorization: Bearer $AccessToken" "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates/${FormTemplateID}/fields"
{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates/cdadbb88-d338-e411-beaf-dfdb3596b8d0/fields"
  },
  "data": {
    "fields": {
      "__customername": "__CustomerName",
      "__checkbox1": "__Checkbox1",
      "__checkbox2": "__Checkbox2",
      "column1": "Column1",
      "column3": "Column3",
      "datafield5": "DataField5",
      "column2": "Column2",
      "invoice no": "Invoice No",
      "signature1": "Signature1",
      "comments": "Comments",
      "productimage": "ProductImage",
      "revisionid": "DhID",
      "instancename": "DhDocID",
      "modifydate": "VVModifyDate",
      "modifyby": "VVModifyBy",
      "modifybyid": "VVModifyByUsID",
      "createdate": "VVCreateDate",
      "createby": "VVCreateBy",
      "createbyid": "VVCreateByUsID"
    },
    "baseFields": [
      "RevisionId",
      "InstanceName",
      "ModifyDate",
      "ModifyById",
      "ModifyBy",
      "CreateDate",
      "CreateById",
      "CreateBy"
    ]
  }
}


Search for a specific Form Template

See the Query Syntax topic for assistance writing query filters.

//Get list of Form Templates using a query where the Form Template name = "OrderForm". 
 
//query syntax used is "?q=[name] eq OrderForm"
//Note the query "[name] eq 'OrderForm'" must be URL encoded with the field name in square brackets and the search predicate surrounded by single quotes.
//The python library urllib.quote_plus is used to URL encode the query string, use your language specific library to URL encode.
$ query=$(python -c 'import sys,urllib; print urllib.quote_plus("[name] eq '" + OrderForm + "'")')
$ echo $query
%5Bname%5D+eq++%2B+OrderForm+%2B+
$ FormTemplateID=$(curl -X GET -H "Authorization: Bearer $AccessToken" "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates?$query" | python -c 'import sys, json; print json.load(sys.stdin)["data"][0]["id"]')
 
$ echo $FormTemplateID
d7be9fc6-7abc-e411-bedc-8859ddab41cc
      


Search for specific Forms and Return their Field Values

Search invoice forms where the Invoice Number='12345' and return a specific list of fields. A similar search would be Patient Intake Forms where PatientId={some value}. In each case we are searching the Form Data associated with a specific type of Form Template.

$ curl -X GET -H "Authorization: Bearer $AccessToken" "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates/${FormTemplateID}/forms?q=%5Binvoice%20no%5D%20eq%20'12345'&fields=invoice%20no,instancename,comments"
{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "https://demo.visualvault.com/api/v1/{customer}/{database}/formtemplates/cdadbb88-d338-e411-beaf-dfdb3596b8d0/forms?q=[invoice no] eq '12345'&fields=invoice no,instancename,comments"
  },
  "data": [
    {
      "href": "~/formtemplates/cdadbb88-d338-e411-beaf-dfdb3596b8d0/forms/d80863c1-e20d-e511-be7d-1040f3b0ab95",
      "dataType": "FormInstance",
      "invoice No": "12345",
      "instanceName": "Orderfor-000014",
      "comments": "2",
      "revisionId": "d80863c1-e20d-e511-be7d-1040f3b0ab95"
    }
  ]
}