Hosted GET connector's allow you to expose data source rows from your own systems, for direct access by your app. An advantage of this connector is that you can control the data rows being exposed to the app. It allows you to filter rows down to the individual app user levels as desired. This is important for ERP, CRM and other enterprise systems as the security/permissions are critical. A secondary benefit is that your data does not need to be pushed to our platform, so any data sovereignty concerns are resolved by this connector. The final benefit is that data sources that run off of Hosted GET connectors are not subject to the standard 50,000 row limit as the rows are delivered directly to the device. 

Note: There are still performance limits on the app side when the rows become large. This varies across Android and IOS, and also depends heavily on the device specifications. 

As a rule of thumb, performance is affected by the overall file size of the data source more than the number of rows. For example 5,000 rows containing 100k of text data per row can be expected to run slower than 50,000 rows which have a total of 1k of data per row, e.g. columns containing say just numbers and a few short text strings.

Additionally, the use of 'heavy' data sources in screens that can be navigated sequentially by the user will result in a compounding performance decrease. Larger data sources can get progressively accumulated in device memory. You will need to test the Hosted GET on the app to find the best row count and screen mix for your specific data set. It's assumed that you have software development resources to create the web service needed by the Hosted GET connector. If not, contact our professional services team to give you a hand.


Set up a GET Connector

1. Create a data source as normal, or select an existing data source for use.

2. On the rows page of your data source, manually define and organize your data source's columns to match the output of your web service. The order of the columns must match up with what your web service returns in order for any column references to work. If you change column orders on your web service response at any stage, you will need to update the columns on the rows page to match.

3. On the settings page of your data source, set the external ID field with some value for identifying this data source. Remember this external ID value, as you will need to it when you work through the GET web service details later in this document.

4. On the settings page, add a Hosted GET connector via the 'Add Connector' button. Specify the web address of your web service endpoint in the provided URL field. You can also set a global DataSource GET url on your organization and specify that the connector use it. This allows reuse of the same service endpoint across multiple data sources.

How does it work?

When the app discovers that a data source has a Hosted GET connector, it performs a HTTP GET request against the target web service URL. The GET request contains the external IDs of the data source's being requested along with other identifying information. Included in the request is your account integration key. This is useful for authenticating the request, along with the logged in app user's email address which is useful for filtering the rows based on the user's access.

The app will issue GETs to your service whenever it attempts a data synchronization. Requests are issued by the app in a batch manner per unique target URL. For example if data source 1 and data source 2 both have the same GET connector URL, the app makes a single GET request with the request containing the external IDs of both data sources. This minimizes 'chattiness' when many data sources are being sourced from the same endpoint.

Note: We strongly recommend that you expose your web service endpoint as SSL secured HTTPS to ensure that app requests to your service are protected.

Attached to the bottom of this document is a C# file that outlines the request and response structures as simple classes. Even if you are not using C#, reviewing the properties and structure in code form can be very helpful in getting started with your own Hosted GET service.


GET Request

GET requests are issued by the app to your service, passing the values below as query string parameters. The parameters passed on the request are as follows:

GET Response

Note: Your web service MUST return a response in the following structure. Failure to comply with this format will result in failure to download rows on your app. Your response must be in JSON format. 

We also support compression on responses. This is recommended for large data sets, as text data compresses very well and thus will conserve mobile data allocations and massively reduce download time.

Rows Response (<DRowsResponse>)

Data Source (<DataSource>)

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.

If the GET is unsuccessful, your web service should return a 400 level HTTP status.


API Usage Example

Given that this connector is REST based, you can test your web service directly via your web browser using a REST plugin like the Postman Plugin for Google Chrome. For this example, we'll assume you have set the 'Target GET URL' on your Hosted GET connector to be https://yourdomain.com/xx/rowsearch. We'll also assume that the data source has an External ID of 'JOBS'

GET Request
(made by the app, with user@somewhere.com as the logged in user)

GET https://yourdomain.com/xx/rowsearch?email=user@somewhere.com&integrationkey=xxxxxxxxxxxx&providerid=1&ids=JOBS,JOBS-DISS&lastupdated=2013-02-12T14:24:09

GET Response

{
   'DataSources':[
      {
         'Id':'JOBS',
         'Rows':[
            [
               '10011',
               '10011 - Test Generic Project',
               'TEST',
               '12345AA',
               '19 Nov 2013',
               '12 Somewhere Road'
            ],
            [
               'ZDS654',
               'ZDS654 - Maintenance Costs to Excavator',
               'TEST',
               '',
               '27 Nov 2013',
               '24 Somewhere Else Road'
            ],
            [
               'ZDF662',
               'ZDF662 - Maintenance Costs for Hitachi Excavator',
               'TEST2',
               '',
               '28 Nov 2013',
               '182 Another Place, Somewhere'
            ]
         ],
         'NewRows':[
         ],
         'DeletedRows':[
         ]
      },
      {
         'Id':'JOB-DISS',
         'Rows':[
            [
               '10011-0201',
               'Project Management',
               '10011',
               'Y'
            ],
            [
               '10011-0202',
               'Quality Control',
               '10011',
               'Y'
            ],
            [
               '10011-0251',
               'Electrical Design',
               '10011',
               'Y'
            ]
         ],
         'NewRows':[
         ],
         'DeletedRows':[
         ]
      }
   ],
   'LastUpdated':'2014-03-11T15:45:50.4818098+10:00'
}

Example Code

Attached to the bottom of this document is a C# file that outlines the request and response structures as simple classes. Even if you are not using C#, reviewing the properties and structure in code form can be very helpful in getting started with your own Hosted GET service.

Troubleshooting / Testing 

Once you have set up a Hosted GET connector on your data source, the rows page for that data source will automatically attempt to pull back rows from the given GET url. The Rows page makes the same request as the app would, using your current logged in user as part of the request. This is a quick and easy way to see if your Hosted GET web service is understanding the GET request and is returning rows in the correct format.


What to do when a Hosted GET works on my IOS app, but not on Android?

This is due to the way that Android treats SSL certificates. Essentially, Android is more strict about SSL certificate chains. SSL certificate chains involve the primary SSL certificate for your web service endpoint domain, along with any intermediate certificates issued by your Certificate Authority. If you attempt to connect to a web address that features an incomplete SSL chain, then Android will fail the connection.

To test this attempt to browse to your Hosted GET service url from your default Android web browser. You will likely get a connection error with text such as 'the certificate authority is invalid'. You can further verify your SSL configuration using a testing service like SSL Labs

If your SSL installation has issues, you will see warnings such as 'chain incomplete' on the SSL Labs test results. To resolve the issue, you need to ensure that the server running the Hosted GET web service has the intermediate certificates from your Certificate Authority installed. For example if you use GoDaddy, the best place to start would be here

Once you have the correct certificate chain in place, the Hosted GET data sources will sync to your Android devices, since they can now connect to your web service. You can confirm the certificate chain by simply checking the Hosted GET url in your Android web browser - it should no longer show certificate errors when resolved.

Did this answer your question?