PUT Data Source

This request method 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.
Updates to a Data Source will be automatically synchronized 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.
Thus, the Data Source must already exist on our platform and be referenced by its unique ExternalId for an API update to succeed.
Data Sources have a maximum limit of 50,000 rows. If more rows are required, please contact our support team.
On the Cloud, this API is available via SSL-secured HTTPS connection using the REST PUT verb:

/api/v2/datasource?format=xml/json

The format query string parameter controls the desired response format.  Specify either XML or JSON.

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.

NOTE: All XML formatted requests must specify the following XML namespace in the data source root element: xmlns:i="http://www.w3.org/2001/XMLSchema-instance"

TABLE OF CONTENTS

• PUT Request
• Parameters
  • DataSource ()
  • Header ()
  • Row ()
  • Data Source Response ()
  • Response Status ()
• API Usage Example

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.

Parameters

DataSource (<DataSource>)

NOTE - All XML formatted requests must specify the following xml namespace in the _DataSource root element: xmlns:i="http://www.w3.org/2001/XMLSchema-instance"

Header (<Header>)

NOTE: It is CRITICALLY important that you include AlL headers for all of your columns in the Header section of your JSON body. Failure to do this will result in the omitted column header names being deleted from your Data Source. 

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.

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 DataSourceResponse.

Data Source Response (<DataSourceResponse>)

Response Status (<ResponseStatus>)

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 ADDING 1 row - JSON

{
  "ExternalId": "my_datasource_extId",
  "Headers": [
    {
      "Name": "ID",
      "DisplayAt": "SubLeft"
    },
    {
      "Name": "Title",
      "DisplayAt": "Title"
    },
    {
      "Name": "Description",
      "DisplayAt": "None"
    }
  ],
  "NewRows": [
    [
      "1",
      "MyTitle1",
      "My description1 that must be inserted"
    ]
  ],
  "CompanyId": CompIdNumber,
  "IntegrationKey": "yourCompanyIntegrationKey"
}

"NewRows": [
    [
      "1",
      "MyTitle1",
      "My description1 that must be inserted"
    ],
    [
      "2",
      "MyTitle2",
      "My description2 that must be inserted"
    ],
    [
      "3",
      "MyTitle3",
      "My description3 that must be inserted"
    ]
  ],

PUT https://secure.formsonfire.com/api/v2/DataSource?format=xml 
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<DataSource>
<CompanyId>1</CompanyId>
<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 />
</Row>
</Rows>
</DataSource>

PUT Response – XML (Error example)

HTTP/1.1 400 Bad Request
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<DataSourceResponse>
<ResponseStatus>
<ErrorCode>ArgumentException</ErrorCode>
<Errors />
<Message>Missing parameters</Message>
</ResponseStatus>
</DataSourceResponse>