One App Cloud - Platform API

ONE APP CLOUD – MARCH 2013 RELEASE

www.oneappcloud.com

March 2013 Release

With our new release we have made it easy to extend your form data and

visualize, enhance and combine it in a number of ways including :

1. Mobile Apps - Create a mobile application using One App Cloud as a back-end

database and workflow for your forms.

2. CRM Integration – Integrate with CRM systems like salesforce.com, SAP, Zoho

and more.

3. Push alerts – Register and send push notifications for your form submissions.

4. Application to application integration – Create custom web, desktop or mobile

apps using your form data.

One App Cloud

API API API

Mobile Google/Box and

others

Your Application

www.oneappcloud.com


www.oneappcloud.com

Getting Started

The One App Cloud API allows you to submit, edit, and retrieve data contained

within your One App account. In order to use the API, you will need your unique

API Key. Do not give out this key! The key works similar to your password, and

protects your data.

Introduction

The One App Cloud API is designed to unlock the potential of the data stored

inside your One App Cloud account. We provide all the tools required to build

applications, advanced reports and visualizations.

What’s even better is that you don’t need any programming experience to at least

view the data, because if you’re reading this, you already have the tools required:

a Web Browser. We’ve added a special parameter (pretty) to the request that

makes the process of exploring the API a simple, visual experience.

This documentation will demonstrate how to fetch data using APIs with the help

of sample URLs and screenshots of results.

API URL

/apiV1/{API-Name}

API-Name here will be the name of API call. If you want to fetch forms from your

account then API-Name will be “forms”.

Helping Parameters

www.oneappcloud.com


www.oneappcloud.com

We know that debugging scripts and code in a browser is a real pain. Keeping this

in mind, we’ve added a convenient GET parameter to provide a readable in

browser view of the output.

http://app.oneappcloud.com/one-app-cloud /apiV1/users?apiKey={API-Key-Here}

&respType=xml&pretty=true

The parameter “pretty” helps you fetching the response readable in browsers

with all the indentation and new lines. We escape < and > symbols if we find

“pretty” parameter to make sure it looks readable in the browser. Because most

browsers strip your tags away and show the content concatenated. This is a

convenient feature but only for debugging. While manipulating the response

don’t use this parameter. We also show the warning message for the same when

this parameter is used.

Are there any API restrictions?

We currently restrict you’re API usage to 200 requests per day.

How can to find API key?

Using Login API you can fetch your API key. API will be required in all the API calls

except for login.

Can users other than administrators use the API?

Each user is assigned an API key. Users who are not administrators will only be

able to access resources granted to them.

www.oneappcloud.com


www.oneappcloud.com

The Login API

The Login API is used to fetch the API key. You can see a call to this API in action

here:

Request URL:

https://app.oneappcloud.com/one-app-

cloud/apiV1/login?username={username}&password={password}[&pretty=true][

&respType={xml|json}]

The expected parameters of this request are:

{username} – This must be replaced with your username in your One App

Cloud account.

{password} – Your account’s password.

{respType} – Choose your response type values can be “xml” or “json”.

Default will be “json”.

{pretty=true} - The optional pretty=true get parameter formats your output

as HTML for debugging through the browser.

Sample Response

<Users> <User> <Id>1</Id> <FirstName>Adamn</FirstName>

www.oneappcloud.com


www.oneappcloud.com

<LastName>McLaren</LastName> <Username>[email protected]</Username> <ApiKey>3321-1877-46cf-9c08</ApiKey> <MobilePhone>+91 9888988898</MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_ADMIN</Role> <ImageURL>http://sphotos-a.xx.fbcdn.net/hphotos-ash3/c0.0.403.403/p403x403/578448_291595084287634_1086470129_n.jpg</ImageURL> </User> </Users>

Here you get your API key which will be required while using other APIs.

Users API

The Users API is used to gather details about the users you have created. You can

see a call to this API in action here:

Request URL:

https://app.oneappcloud.com/ one-app-cloud/apiV1/users?apiKey={API-Key-

Here}[&pretty=true][&respType={xml|json}]


{apiKey} – This must be replaced with your API key fetched from Login API.

www.oneappcloud.com


www.oneappcloud.com

Sample Response

<Users> <User> <Id>1</Id> <FirstName>Adamn</FirstName> <LastName>McLaren</LastName> <Username>[email protected]</Username> <ApiKey>3321-1877-46cf-9c08</ApiKey> <MobilePhone>+91 9888988898</MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_ADMIN</Role> <ImageURL>http://sphotos-a.xx.fbcdn.net/hphotos-ash3/c0.0.403.403/p403x403/578448_291595084287634_1086470129_n.jpg</ImageURL> </User> <User> <Id>2</Id> <FirstName>John</FirstName> <LastName>Kahn</LastName> <Username>[email protected]</Username> <ApiKey>a80b-818c-4024-8ec7</ApiKey> <MobilePhone></MobilePhone> <OfficePhone></OfficePhone> <Role>ROLE_HR_MANAGER</Role> <ImageURL>https://encrypted-tbn0.google.com/images?q=tbn:ANd9GcREYMDySIyzRZPZ1TmMfkBslZfSIoentMgfCAQ5f_7EYE35I1p_5Q</ImageURL> </User> </Users>

www.oneappcloud.com


www.oneappcloud.com

Forms API

The Forms API is used to gather details about the forms you have permission to

access. This API can be used to create a list of all forms belonging to a user and

dynamically generate a form embed snippet to use in your application. You can

see a call to this API in action here:

Request URL

https://app.oneappcloud.com/ one-app-cloud/apiV1/forms?apiKey={API-Key-

Here}[&formId={Form-Id}][&pretty=true][&respType={xml|json}]



{formId} – This option parameter is used to fetch the information related to

a specific form.

Sample Response

<Forms> <Form> <Id>1</Id>

www.oneappcloud.com


www.oneappcloud.com

<Name>Untitled Form</Name> <Description>Please fill out this form. Thank you!</Description> <Access>Public</Access> <RedirectMessage></RedirectMessage> <RedirectURL></RedirectURL> <StatusField></StatusField> <BlockUserChangeValues /> <ShowStatusToUser></ShowStatusToUser> <ResponseCount>6</ResponseCount> <RecentEntryTime>2013-02-13 17:00:28.0</RecentEntryTime> <RecentEntryId>2</RecentEntryId> <OpenForEdit>1</OpenForEdit> <FieldLabelAlignment>top</FieldLabelAlignment> <Font>Lucida Sans Unicode</Font> <FontSize>13</FontSize> <Heading>h2</Heading> <HeadingAlignment>left</HeadingAlignment> <HeadingFontWeight>bold</HeadingFontWeight> <HeadingFontStyle>normal</HeadingFontStyle> <HeadingTextDecoration>none</HeadingTextDecoration> <EmbededCSS></EmbededCSS> <EmbededJS></EmbededJS> <Recaptcha>0</Recaptcha> <DateCreated>2013-02-13 15:19:42.0</DateCreated> <LastUpdated>2013-02-15 18:44:33.0</LastUpdated> </Form> <Form> <Id>4</Id> <Name>Untitled Form</Name> <Description>Please fill out this form. Thank you!</Description> <Access>Public</Access> <RedirectMessage></RedirectMessage> <RedirectURL></RedirectURL> <StatusField></StatusField> <BlockUserChangeValues /> <ShowStatusToUser></ShowStatusToUser> <ResponseCount>0</ResponseCount>

www.oneappcloud.com


www.oneappcloud.com

<RecentEntryTime></RecentEntryTime> <RecentEntryId></RecentEntryId> <OpenForEdit>1</OpenForEdit> <FieldLabelAlignment>top</FieldLabelAlignment> <Font>Lucida Sans Unicode</Font> <FontSize>13</FontSize> <Heading>h2</Heading> <HeadingAlignment>left</HeadingAlignment> <HeadingFontWeight>bold</HeadingFontWeight> <HeadingFontStyle>normal</HeadingFontStyle> <HeadingTextDecoration>none</HeadingTextDecoration> <EmbededCSS></EmbededCSS> <EmbededJS></EmbededJS> <Recaptcha>0</Recaptcha> <DateCreated>2013-02-15 20:45:29.0</DateCreated> <LastUpdated>2013-02-15 20:45:29.0</LastUpdated> </Form> </Forms>

The <Form> Element

The <Form> element lives inside the parent “<Forms>. One <Form> element

exists for each form on your system. So, if you have 5 forms in your account and

you’re permitted to see them all, you’ll have 5 <Form> elements in the return

value from your API call.

Values for the <Form> element are defined below.

Name – The title of the form specified in the Form Settings in form

designer.

Description – The description of the form as specified in the Form Settings

in form designer.

Access – This parameter tell if the form is accessible by “logged in users” or

“public users” or “public users with a password”, specified in Form Settings.

Redirect Message – The confirmation message shown to users after they

have successfully filled out the form.

www.oneappcloud.com


www.oneappcloud.com

Redirect URL – Value of this tag is a URL where the user should be

redirected after the successful form submission. Its value is specified in

Form Settings.

StatusField – The parameter contains name of a field which is selected as a

status field in Form Settings.

BlockUserChangeValues – This parameter contains a value. If status field of

a form has this value then a user with role “ROLE_USER” should not be

allowed to update the entry.

ShowStatusToUser – This parameter tells if the status field should be

shown (Read-Only) to the user while editing an entry or not.

ResponseCount – Count of the number of entries for the form.

RecentEntryTime – Time of last entry made in the form.

RecentEntryId – ID for the most recent entry

OpenForEdit – The form’s entries are editable or not, specified in Form

Settings

FieldLabelAlignment – Alignment of the fields and their labels should be

top (one after another) or left (side by side) or right (side by side with labels

aligned in right near to the fields)

Font – Font-Family selected in Form Settings in Form Designer.

FontSize – Font-size selected in Form Settings in Form Designer.

Heading – Possible values: (h1, h2, h3, h4, h5, h6), tells how large/small the

size of heading should be, specified in Form Settings in Form Designer.

HeadingAlignment – Possible values: (left, right, center),

HeadingFontWeight – Font-weight of the Heading should be bold not.

HeadingFontStyle – Font-style of the Heading should be italic or not.

HeadingTextDecoration – Heading should be underlined or not.

EmbededCSS – This should be used if your application is a web application.

EmbededJS – This parameter also should be if your application is a web

application.

Recaptcha – Possible values: (0, 1), tells whether to add a captcha control

while user is to fill the form or not.

www.oneappcloud.com


www.oneappcloud.com

Fields API

The Fields API describes the hierarchy of your data. At the heart of this API is the

listing of Name values. Each Name corresponds to a value in the Entries API. Some

type of fields will not have Name, as those fields are not persistent, e.g. –

RichText, ImageUpload, Link and EmbedHTML.

Request URL

https://app.oneappcloud.com/ one-app-cloud/apiV1/fields?apiKey={API-Key-

Here}&formId={Form-Id}[&parentFormId={Parent-Form-

Id}][&pretty=true][&respType={xml|json}]



{formId} – This parameter is used to fetch the fields related to that form.

{parentFormId} – This optional parameter should be Parent Form’s id when

fields of a Sub-Form are to be fetched. To fetch Sub-Form’s fields this is

required.

www.oneappcloud.com


www.oneappcloud.com

The Standard Fields

Title – The Title is the friendly name you gave the field when creating your

form. For example, if you were building a table with the API, the Title would

be a column header.

Type – The Type represents a field type. A listing of these types can be

found in the Field Type section of this documentation.

Name – This is the unique reference for your field. There will be one

corresponding Name for each Entry in return value of the Entries API.

IsRequired – This value can be one or zero, representing whether or not the

field has been marked required in the Form Builder.

OtherOption – This value is one or zero and is only set if the field has

choices. Only CheckBox or Radio type fields have the option of

an Other field.

Sub-Fields

The more elaborate fields have Subfields. These include Date, Name, Checkbox,

Address, and Likert.

The example below shows a SubFields element from a Name field.

<SubFields>

<SubField>

<Name>field1360852056949pre</Name>

<Label>Prefix</Label>

</SubField>

<SubField>

<Name>field1360852056949fn</Name>

<Label>First Name</Label>

</SubField>

<SubField>

<Name>field1360852056949ln</Name>

<Label>Last Name</Label>

</SubField>

www.oneappcloud.com


www.oneappcloud.com

</SubFields>

The properties of subfields are defined here.

Name - This element works the same way a Name does for a Standard

Field. It, too, has a one-to-one relationship with the result of an Entries API

call.

Label - You need a friendly way to refer to the value of a Subfield. The Label

works similarly to the Title element. In most cases, however, this text is

determined by us. For example, the First Name and Last Name Text values

are predetermined.

Choices

Some fields, like the radio, dropdown and likert, represent a choice from several

available choices. These are represented in the <Choices> element, which in turn

has a series of <Choice> elements. The example below shows the choices for

a likert field.

<Choices>

<Choice>

<Score>1</Score>

<Label>Strongly Disagree</Text>

</Choice>

<Choice>

<Score>2</Score>

<Label>Disagree</Text>

</Choice>

<Choice>

<Score>3</Score>

<Label>Agree</Text>

</Choice>

<Choice>

<Score>4</Score>

www.oneappcloud.com


www.oneappcloud.com

<Label>Strongly Agree</Text>

</Choice>

</Choices>

A Choice element has the following elements:

Label - Is easy to picture if you think of a Drop Down. Each choice in the

DropDown is represented by a<Label> element.

Score - This is a text/number representing a choice’s value relative to the

other choices. For example, if there are four choices, the score ranges from

0 to 3 in case of likert type fields.

Putting it all together

The following is an example of the most complicated field type, the likert. Let’s

discuss what we’re seeing.

The Field Type is likert, which is like a combination of a checkbox and a select

type. The <Name> is field1357157506890. The subfields each have a Name as

well, because each represents a possible field value. So,

field1357157506890__0_, field1357157506890__1_, and

field1357157506890__2_ will all result in a corresponding entry value when the

Entries API is called. This is useful on the client side if you’re using standard like

XPath to navigate your DOM. The <Field> element also has a <Choices> element,

which represents the possible values for each of the <Subfield> elements.

<Field>

<Field>

<Name>field1357157506890</Name>

<DefaultValue></DefaultValue>

<IsRequired>0</IsRequired>

www.oneappcloud.com


www.oneappcloud.com

<IsHideFromUser>0</IsHideFromUser>

<Title>Likert 1</Title>

<Description></Description>

<Type>Likert</Type>

<Font>default</Font>

<FontSize>default</FontSize>

<FontWeight>bold</FontWeight>

<FontStyle>normal</FontStyle>

<TextDecoration>none</TextDecoration>

<SwitchRowCol>0</SwitchRowCol>

<SubFields>

<SubField>

<Name>field1357157506890__0_</Name>

<Label>Usability</Label>

</SubField>

<SubField>

<Name>field1357157506890__1_</Name>

<Label>Interface Look</Label>

</SubField>

<SubField>

<Name>field1357157506890__2_</Name>

<Label>Colors</Label>

</SubField>

</SubFields>

<Choices>

<Choice>

<Score>0</Score>

<Label>Very Satisfied</Label>

</Choice>

<Choice>

<Score>1</Score>

<Label>Satisfied</Label>

</Choice>

www.oneappcloud.com


www.oneappcloud.com

<Choice>

<Score>2</Score>

<Label>Neutral</Label>

</Choice>

<Choice>

<Score>3</Score>

<Label>Dissatisfied</Label>

</Choice>

</Choices>

<Page>1</Page>

</Field>

www.oneappcloud.com


www.oneappcloud.com

Entries API

The Entries API is used to gather the data that users have submitted to your form.

In this section we’ll describe the hierarchy of the entries element as well as

describe the syntax for filtering this data.

Request URL

https://app.oneappcloud.com/ one-app-cloud/apiV1/entries?apiKey={API-Key-

Here}&formId={Form-Id}[&parentFormId={Parent-Form-

Id}][&parentFormEntryId={Parent-Form-Entry-

Id}][&parentFormFieldName={Parent-Form-Field-Name-

Id}][&pretty=true][&respType={xml|json}]

www.oneappcloud.com


www.oneappcloud.com



{formId} – This parameter is used to fetch the entries related to that form.

{parentFormId} (Only required for Sub-Form’s entries) – This optional

parameter should be Parent Form’s id when entries of a Sub-Form are to be

fetched.

{parentFormEntryId} (Only required for Sub-Form’s entries) – This optional

parameter should be Parent Form’s Entry Id.

{parentFormFieldName} (Only required for Sub-Form’s entries) – This

optional parameter should be Parent Form’s Field’s Name in which the Sub-

Form is mapped.

The <Entry> Element

The <Entry> element lives inside the <Entries> parent. One <Entry> element exists

for each submission to your form. So, if you have 5 submissions to your form,

you’ll have 5 <Entry> elements in the return value from your API call.

Sample Response

Here’s an example of a call to the Entries API.

<Entries>

<Entry>

<Id>1</Id>

<field1357157498058>Sid</field1357157498058>

<field1357157498556>(610) 590-4444</field1357157498556>

<field1357157499090>2013-01-02 00:00:00.0</field1357157499090>

<field1357157499688>[email protected]</field1357157499688>

www.oneappcloud.com


www.oneappcloud.com

<field1357157500170>12.00</field1357157500170>

<field1357157501951>First Choice</field1357157501951>

<field1357157506890__0_>2</field1357157506890__0_>

<field1357157506890__1_>1</field1357157506890__1_>

<field1357157506890__2_>0</field1357157506890__2_>

<field1357157506890__3_>3</field1357157506890__3_>

<field1357157507791line1>123, ABC</field1357157507791line1>

<field1357157507791line2></field1357157507791line2>

<field1357157507791city>XYZ</field1357157507791city>

<field1357157507791state>PA</field1357157507791state>

<field1357157507791zip>28118</field1357157507791zip>

<field1357157507791country>US</field1357157507791country>

</Entry>

</Entries>

Paging

You can also request pages of data. This is useful because the maximum page size

for the Entries Api is 100. So if you wanted to page through your data 25 entries

at a time, you’d write paging arguments which looked like the example below.

pageStart=0&pageSize=25

Let’s look at the different parts of the example above.

pageStart - The page number you’d like to start from.

pageSize - The number of entries returned in your page.

Example

This concept is best explained with an example: So, if you’re filtering for all entries

whereField1 Contains Bob and the filter returned 1000 entries, and you

set pageStart=0 and pageSize=25you’d end up with the first 25 entries which fit

the filter. If you up the pageStart to 25 and left the pageSize the same, you’d get

the next 25 entries.

www.oneappcloud.com


www.oneappcloud.com

Some things to note about pageStart and pageSize:

pageStart defaults to 0

pageSize defaults to 25 and the maxim is 100

Entry Save API

To submit data to a form, you use the EntrySave API. This page will describe the

details of “POSTing” to your form.

Request URL

This API accepts POST requests in the following formats:

https://app.oneappcloud.com/ one-app-cloud/apiV1/entrySave


{apiKey} –API key fetched from Login API.

{formId} – Id of the form in which you want the entry response to be

added.

{parentFormId} (Only required for Sub-Form’s entries) – This optional

parameter should be Parent Form’s id when entries of a Sub-Form are to be

created.

{parentFormEntryId} (Only required for Sub-Form’s entries) – This optional

parameter should be Parent Form’s Entry Id.

{parentFormFieldName} (Only required for Sub-Form’s entries) – This

optional parameter should be Parent Form’s Field’s Name in which the Sub-

Form is mapped.

www.oneappcloud.com


www.oneappcloud.com

The <Entry> Element

After a successful POST to the EntrySave API, the system will send you

a <Entry> in the appropriate format as shown here:

<Entry>

<Saved>true</Saved>

<EntryId>8</EntryId>

</Entry>

Let’s review what these mean

Saved – This boolean value represents success or failure. So, the value true

means success, the value false means “no success”.

EntryId – The Entry ID created by this submission.

Dealing with failure

If the entry is not saved there could be some validation errors to show. The result

format in case of failure is shown below:

<Entry>

<Saved>false</Saved>

<EntryId></EntryId>

<Errors>

<Error>

<FieldName>field1362147308853</FieldName>

<ErrorMessage>Field Numeric Text 1 must be a valid number</ErrorMessage>

</Error>

</Errors>

</Entry>

Let’s see what these resulting elements mean

www.oneappcloud.com


www.oneappcloud.com

FieldErrors – The <Errors> element contains a collection

of <Error> elements.

FieldName – The unique identifier for the field. This corresponds to a Name

returned by the Fields API.

ErrorMessage – If contained within a <Error> element, this text describes

what went wrong when validating the field. Error Message contains

escaped HTML entities, so it may be displayed directly on a web page.

www.oneappcloud.com

One App Cloud - Platform API

Documents

Transcript of One App Cloud - Platform API