The Data Source API

allows you to update Data Sources on the platform.  This enables scenarios where data sets maintained in other systems (e.g. SAP, Salesforce) can be updated into apps automatically.

Any update to a Data Sources will be automatically synchronised to mobile devices by the platform.  Thus if a Data Source is used in a Form or other Screen type, that Data Source can be kept continuously up to date via this API.

Currently Data Sources cannot be deleted nor can they be created by this API – this is to protect existing Screens that use these Data Sources.

So, the Data Source must already exist on our platform and be referenced by its unique External Id for an API update to succeed.

On the Cloud this API is available using the REST PUT verb:

http://secure.formsfly.com/api/v1/slist?format=[xml|json]

The format query string parameter controls the desired response format.  Specify either xml or json.

PUT Request

You may use either JSON or XML formats in your PUT request.
You indicate this by setting the ContentType HTTP header as “application/json” or “application/xml”. If no ContentType is specified, XML format is assumed.

The required parameters for a PUT request to the Data Sources API are outlined below.

List (<SList>)

NOTE: XML formatted requests must specify the following xml namespace in the SList root element.
xmlns=”http://schemas.servicestack.net/types”

Input Name Data Type Required Description
ExternalId String Yes The external Id of the Data Source that this request relates to.  This value must match an existing Data Source External Id.
ProviderId Integer Yes Your unique Provider Id found on the Organisation Setup page of the secure website (under Your Account)
Integrationkey String Yes Your unique Integration Key found on the Organisation Setup page of the secure website (under Your Account)
Name String Yes The name of the Data Source.  The value specified will overwrite the existing Data Source name.
Headers Collection No A collection of Header Items. If not specified then the Headers of the Data Source will not be updated.

NOTE: The number of Headers must match the number of Val elements found in each Row (if specified).

Rows Collection No A collection of Row Items that will completely replace your current Data Source rows.
A limit of 50,000 Rows applies for replace operations.
The order of the Rows is the order that the rows will be displayed in the platform.
If you specify Rows, then any values in NewRows and DeletedRows will be ignored.
NewRows Collection No A collection of Row Items that should be added/updated onto the existing Data Source rows.
Use this field to perform incremental inserts/updates of your Data Source.
A limit of 1,000 New Rows applies per request.
DeletedRows Collection No A collection of Row Items that should be deleted from the existing Data Source rows.
Use this field to perform incremental deletes of your Data Source.
A limit of 1,000 Deleted Rows applies per request.
Each Row should contain a single Val element that is your unique identifier for the Row to delete.

Header (<Header>)

Field Name Data Type Required Description
Name String Yes Name of this Header
DisplayAt String No Specifies the desired app display position of this column’s values in each Data Source row.
Options available are:
Title – The main title area of the row
SubLeft – Appears below the Title in smaller text
Thumb – Displays the column value as an image thumbnail to the left of the Title. Only applicable if your column values are http URLs pointing at PNG or JPG files.

Row (<Row>)

Each Row is a collection of Val (<Val>) items, which are the individual column values for that Row.

Every Row must contain at least two Vals and must have as many Vals as there are Headers (columns).

The first Val should be the unique identifier or key that will be used as the answer value should this Data Source row be selected in a Form. The first Val is also critical as the key for performing incremental deletes through the DeletedRows field mentioned above.

The second Val should be the default displayable label text of the row.  You can override this default by configuring the Display Options field in the Data Source “Settings” page of the secure website.

Input Name Data Type Required Description
Val String Yes A column value for this row, can contain any string value.

If you want this column to display an icon/image in the mobile app, then specify an http url to the image in question.
The image linked to must be in PNG or JPG/JPEG format.
See the example below for this.

PUT Response

If the PUT update is successful, a 200 HTTP status is returned with an empty response.

If the PUT is unsuccessful, a 400 HTTP status is returned along with a SListResponse.

Data Source Response (<SListResponse>)

Input Name Data Type Description
ResponseStatus Collection A collection containing the errors that occurred.

Response Status (<ResponseStatus>)

Input Name Data Type Description
ErrorCode String The error code/message for the failure
Message String Description of the error
Errors Collection Any other inner errors.  For Data Sources, this is always empty and can be ignored.

API Usage Example

Given that the API is REST based, you can access the API directly via your web browser to test it using a REST plugin like the Postman plugin for Google Chrome.

PUT Request – XML

PUT http://secure.formsfly.com/api/v1/slist?format=xml 
Content-Type: application/xml
<SList xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ProviderId>1</ProviderId>
 <IntegrationKey>xxxxxxxxxxxxxxx</IntegrationKey>
  <Name>Favorite Sports</Name>
  <ExternalId>SPORTS-001</ExternalId>
  <Rows>
    <Row>
      <Val>AH</Val>
      <Val>Air Hockey</Val>
      <Val>This is some additional information about Air Hockey</Val>
      <Val>http://mywebsite.com/images/air-hockey.jpg</Val>
    </Row>
    <Row>
      <Val>FB</Val>
      <Val>Football</Val>
      <Val>This is some additional information about Football</Val>   <Val>http://mywebsite.com/images/football.jpg</Val>
    </Row>
    <Row>
      <Val>CH</Val>
      <Val>Chess (We have no additional info or images for this sport)</Val>
      <Val></Val>
      <Val></Val>
    </Row>
  </Rows>
</SList>

PUT Response – XML (Error example)

HTTP/1.1 400 Bad Request
Content-Type: application/xml
<SListResponse 
    xmlns:i="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns="http://schemas.servicestack.net/types">
    <ResponseStatus>
        <ErrorCode>ArgumentException</ErrorCode>
        <Errors />
        <Message>Missing parameters</Message>
    </ResponseStatus>
</SListResponse>

API – DELETE Task. API – PUT Data Source. API – POST Form Entry to External Web Service. API – PUT User. API – GET Users. Advanced Integration. Will it connect to our existing systems?. API – POST User. API – GET Tasks. API – DELETE User. API – Form GET Entries. API FormsFly System. Integration API Overview. API – POST Task. API – Form GET Media File. API – GET Data Source. REST Connector.