TransForm Helper Features

TransForm Utilities

The TransForm Utilities sub-menu, found in the Tools menu, contains a set of tools for working with TransForm, including a builder for generating an On-device Assets manifest and configuring onSubmit events.

TransForm Utilities sub-menu found under the Tools menu

On-device Data Builder

The On-device Data Builder is a utility for creating an On-device Assets Manifest for Alpha TransForm.

On-device data builder dialog

onSubmit Events Builder

The OnSubmit Events Builder can be used to manage onSubmit Events for your TransForm account.

onSubmit events builder dialog

The following events are available:

Action

Description

Send Email

Sends an email with the data from the Form that was submitted.

Report

Generates and emails a report for a Form when the Form is submitted.

Call webhook

Sends data submitted in a Form to a web service.

Send to SQL database

Saves the submitted Form data to a SQL database.

Send SMS Message

Sends an SMS message.

Set values in User fields

Sets the value of the submitted Form's 'User' or 'Userlabel' fields.

Dispatch or Route a form

Dispatch or route a Form to a user.

Save form in storage

Save a copy of a form to storage, e.g. AmazonS3, Google Drive, or Dropbox

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.

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 TransForm API easier. These functions are shown below:

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 [email protected].

dim formId as c = "Pictures"
dim apikey as c = "xxxxxxxxxxxxxxxxxxxxxxxxxx"
dim assignTo as c = "[email protected]"
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.