TransForm Helper Features

Description

Alpha Anywhere includes built-in tools that make it easy to create applications that interact with Alpha TransForm.

Discussion

TransForm is a service for building mobile data collection forms. For more information on TransForm, click here

The TransForm service has no dependence on Alpha Anywhere. You can use TransForm without having to also use Alpha Anywhere and without having to have an Alpha Anywhere license. However, there are several helper functions and features in Alpha Anywhere that are designed to make working with TransForm easier.

TransForm API Explorer

The TransForm API explorer allows you to experiment with the TransForm API.

The TransForm API allows you to perform tasks in the TransForm service. Almost all tasks that can be performed in the TransForm service through the various TransForm user interfaces (i.e. Form Designer, Permissions, Management Console, Form Filler) can also be performed using the API.

The TransForm API is a REST API.

To open the TransForm API Explorer, select the Tools > Open TransForm API explorer command when the Web Control Panel has focus.

The dialog shows all of the API methods.

In order to test any of the methods, you will first need to get an API key. To get an API key log into your account at https://transform.alphasoftware.com and from the Home tab, select the Developer Options, Get TransForm API key options or follow the instructions in How to Generate an Alpha TransForm API Key below.

Once you have your API key, click the Enter API Key button to enter your API Key. Alpha Anywhere will remember the key so you will not need to enter the key again.

When you create an API key you select the 'scopes' associated with the key. In the list of available API method shown in the image below, each method shows the required scopes for that method. For example, in order to call the CreateNewFormInstance method, your API key must grant either the ALL or CFI scope.

The API Explorer also shows help for each method. To see the help, select the Help pane shown in the image below.

When you have the Explore tab selected, if you select a method, the right hand part of the dialog will prompt for the method's parameters:

The required parameters are indicated with an * after the name.

After you fill in the required parameters, click on the Test button. Alpha Anywhere will make the REST API call and show you the result in the API Result pane. The dialog also has tabs called CURL, Node and Xbasic.

These tabs show code showing how to make the API call using either CURL, Node.js, or Xbasic.

Xbasic Helper Functions

There are several Xbasic functions that make working the the TransForm API easier. These functions are shown below:

The A5TransForm_CreateFormInstance() and A5TransForm_GetData() functions are merely convenient ways to use the TransForm API from Xbasic. They do not add any additional functionality to the API and you could also have used the API in your Xbasic code to achieve the same results.

 A5TransForm_CreateFormInstance() Function

Create a New TransForm Form Instance - This function is a wrapper on the TransForm CreateNewFormInstance API method. It allows you to create a new form instance and assign the instance to a particular user.

Creating a new form instance programmatically is typically done is "dispatch applications". When the user to whom the new form instance was assigned opens TransForm on their device and performs a refresh action, the new form instances assigned to that user will appear in the list of existing forms. This is called a "dispatch application" because a new task has been "dispatched" to a user.

Syntax:

P result = A5TransForm_CreateFromInstance(C apiKey, C formId,C formDataJSON,C assignTo)

Where:

  • result - An object that contains the result of the function. The object will have these properties:
    • error - true/false
    • errorText - if error is true, a description of the error
    • result - a property with the formInstanceId of the new form. (The formInstanceId is the primary key of the new record that was created.)
  • apiKey - Your TransFrom API key. (You can get an API key from the Developer Options section at TransForm Central (transform.alphasoftware.com).
  • formId - This is the ID of the TransForm form definition for which you are creating a new form instance.
  • formDataJson - This is the data for the new form instance. It is in the form of a JSON string

 Example

Assume you have a form called "Pictures" and you want to create a new form instance with the data shown below, and you want to assign this new form instance to a user called user1@mycompany.com.

dim formId as c = "Pictures"
dim apikey as c = "xxxxxxxxxxxxxxxxxxxxxxxxxx"
dim assignTo as c = "user1@mycompany.com"
dim formDataJSON as c
formDataJSON = <<%txt%
{
    "field1": "value1",
    "field2": "value2",
    "photos": [
        {"photo": "https://mys3bucket.s3.amazonaws.com/image1.jpg"},
        {"photo": "https://mys3bucket.s3.amazonaws.com/image4.jpg"}
    ]
}
%txt%
 
dim pResult as p
pResult = a5TransForm_CreateFromInstance(apikey,formid,formdataJson,assignTo)

 A5TransForm_GetData() Function

Gets the data for a TransForm form. The result can be paginated so as not to return too much data at once.

If you request paginated data you must specify the page size and page number. For example, you might specify a page size of 10 and page number of 2. This will return 10 records, starting with the 11th record.

Syntax:

c JSONData = A5TransForm_GetData(C apikey, C formid [,L paginated [,N pageSize [,N pageNumber [,P Obj [,L flagDisplayWaitMessage]}}}})

Where:

  • JSONData - a JSON array of data showing the date for the form instances
  • apiKey - Your TransFrom API key. (You can get an API key from the Developer Options section at TransForm Central (transform.alphasoftware.com).
  • formId - This is the ID of the TransForm form definition for which you want to get data.
  • paginated - .t./.f. - defaults to .f. - Specifies if all of the forms should be returned at once, or just a single "page" of data
  • pageSize - the number of records in a page of data. Defaults to 10. Only used if paginated is .t.
  • pageNumber - the page number of data to return. Defaults to 1. Only used if paginated is .t.
  • Obj - An object (Xbasic dot variable) that will be filled in with information when the function executes. The object will contain these properties:
    • error - .t. or .f.
    • errorText - a description of the error if there was an error
    • recordCount - the number of form instances that were found.
  • flagDisplayWaitMessage - specifies if a "wait" message should be displayed while the function is executing. Defaults to .t.

 Example

Assume you have a form called "Pictures" and you want to retrieve the data for form

dim formId as c = "Pictures"
dim apikey as c = "xxxxxxxxxxxxxxxxxxxxxxxxxx"
dim jsonData as c
dim flagPaginated as l = .t.
dim pageSize as n = 10
dim pageNumber as n = 1
dim pResult as p
jsonData = a5TransForm_GetData(apikey, formid, flagPaginated, pageSize, pageNumber, pResult)

List Control

The List control can display data from a TransForm form. When you create a new List, the list of available options for the List's data source includes TransForm.

If you select the TransForm option, the List builder will display the following prompts where you can specify your TransForm API key, the ID for the form for which you want to display data and whether the data should be paginated (recommended if there are many form instances).

How to Generate an Alpha TransForm API Key

An Alpha TransForm API key is required in order to use the TransForm API. Follow the instructions below to generate an API key.

  1. Go to TransForm Central. Log in with your TransForm username and password if prompted.

  2. On the Home Tab, click on Developer Options.

  3. Click on Get TransForm API Key

  4. Select the scope(s) for the key. Use Shift-Click or Ctrl-Click to select multiple options.

  5. Click Get API Key to generate the key. Copy the key and store it in a safe place.

    If you generate a key by mistake or no longer have a need for an API key, use the Revoke TransForm API Key tool to revoke the API key.

See Also