Tags

Export API

Comments

/groups/gisprogiskitforiphoneipad/search/index.rss?tag=hotlist/groups/gisprogiskitforiphoneipad/search/?tag=hotWhat’s HotHotListHot!?tag=hot0/groups/gisprogiskitforiphoneipad/sidebar/HotListNo items tagged with hot.hot/groups/gisprogiskitforiphoneipad/search/index.rss?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcomelist/groups/gisprogiskitforiphoneipad/search/?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcomeRecent ChangesRecentChangesListUpdates?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcome0/groups/gisprogiskitforiphoneipad/sidebar/RecentChangesListmodifiedDateallRecent ChangesRecentChangesListUpdateswiki/welcomeNo recent changes.reverse5search


Export API


GIS Pro can be customized to export data to your own server as one of the file destinations. These custom export destinations can be installed by simply following a link on your device that is provided by your company's IT staff. Once the custom destination has been installed the new export destination(s) will appear in the "Export To" dialog when users export their data (Fig. 1).

Figure 1. Custom export destinations in GIS Pro

If the link has changed, your IT professional will provide a new link which will update the custom export destination automatically. Again, simply follow the link from your iOS device.



For IT Professionals: Configuring the Server to use the Export API

The configuration of the server is done using a few basic HTTP interactions. These can be set up in any server-side language that supports HTTP POST requests (e.g. Perl, C/C++, PHP, C#, Ruby, TCL, Python, .NET, etc.).


Installation Step 1: Users Follow Installation Link from Device

The first step of the process is to create a link that installs the destination on the user's device. This is a simple way for you to distribute the configuration to your organization. The installation link uses a custom URL scheme which iOS devices (that have GIS Pro) will recognize, automatically launch the app and instruct it to add your custom export destination. The URL begins with gisupload:// and ends with the URL that will contain your server dictionary. For example: gisupload://giskit.garafa.com/gisUploader/fileUploader.php


Installation Step 2: Server Returns Installation Dictionary

When GIS Pro opens the installation link it will retrieve the contents of the specified URL and attempt to read two parameters in JSON format: "name" and "url". The name is what will appear within the app. (e.g. Sand Mountain Server in Fig. 1) and the url is the URL of the web form that will be presented to them before the upload takes place. If the app has already installed an export destination by the same name it will update the existing destination's upload URL.

An example dictionary might be:

{
   "name":"Garafa Test Uploader",
   "url":"http:\/\/giskit.garafa.com\/gisUploader\/fileUploader.php?gatherInfo=1"
}

Sample PHP code that could generate this could be:

$retArray = array();
$retArray['name'] = 'Garafa Test Uploader';
$retArray['url'] = "http://giskit.garafa.com/gisUploader/fileUploader.php?getInfo=1";
echo json_encode($retArray);


Upload Step 1: Server Returns Web Form

The web form is what the user will see when they go to upload the file. This is completely customizable and can be used to gather information such as a user id, project number, and/or login credentials. For our example, we will ask the user for a project number.

<form name='input' action='fileUploader.php' method='get'>
   Project number: <input type='text' name='proj_number' /><br />
   <input type='submit' value='Submit' />
</form>


Upload Step 2: User Submits Form and Server Returns Upload Metadata

When the web form is submitted, the server processes the response and returns the information needed for the upload in a JSON dictionary. The only required parameter it returns is "uploadURL", which is the URL that the file should be sent to. However, custom metadata can be returned as well, such as an upload ID that can help the upload script match the form data to the uploaded file. For our example we will generate a parameter called "uploadID" that will be used to identify the file once it is uploaded.

if(isset($_GET['proj_number']) ){
   $ret = array();
   $ret['uploadURL'] = "http://giskit.garafa.com/gisUploader/fileUploader.php";
   $ret['uploadID'] = generateUploadIdForProjectNumber($_GET['proj_number']);
   echo json_encode($ret);
}


Upload Step 3: File is Uploaded Along with Upload Metadata, Server Saves Uploaded File

Finally, the file is sent to the upload url along with the rest of the metadata returned in step 2. This is sent with a MIME type of multipart/form-data with two variables named "json" and "file". Example of the contents of the POST:


POST /gisUploader/fileUploader.php HTTP/1.1
Host: giskit.garafa.com 
Content-Type: multipart/form-data; boundary="stringB0undary"
Content-Length: 681651
Connection: close

--stringB0undary
Content-Type: application/json
Content-Disposition: form-data; name="json"

{
   "uploadURL":"http://giskit.garafa.com/gisUploader/fileUploader.php",
   "uploadID":1234124
}
--stringB0undary
Content-Type: text/xml
Content-Disposition: form-data; name="file"; filename="thefilename"

...............(XML DATA).............
--stringBOundary--


And the corresponding server code that handles the upload (in PHP):

if(isset($_POST['json'])){
   $metadata = json_decode($_POST['json']);
   $uploadNumber = intval( $metadata->{"uploadID"} );
   $newFileName = "uploads/$uploadNumber";
   if(   copy($_FILES['file']['tmp_name'], $newFileName) ) {
      echo "file uploaded!";
   }
   else {
      echo "upload failed. Could not upload to $newFileName";
   }
}


Upload Process Diagram

Export Process Diagram

Sample Server-Side Upload Script (PHP)

<?

if(isset($_POST['json'])){
   $metadata = json_decode($_POST['json']);
   $uploadNumber = intval( $metadata->{"uploadID"} );
   $newFileName = "uploads/$uploadNumber.kmz";
   if(   copy($_FILES['file']['tmp_name'], $newFileName) ) {
      echo "file uploaded!";
   }
   else {
      echo "upload failed. Could not upload to $newFileName";
   }
}
else if(isset($_GET['proj_number']) ){
   $ret = array();
   $ret['uploadURL'] = "http://giskit.garafa.com/gisUploader/fileUploader.php";
      // database-generated unique identifier
   $ret['uploadID'] = generateUploadIdForProjectNumber($_GET['proj_number']);
   echo json_encode($ret);
} else if (isset($_GET['getInfo'])) {
   echo"
      <html>
         <body>         <br/>       <br/>
            <form name='input' action='fileUploader.php' method='get'>
               Project number: <input type='text' name='proj_number' /><br />
               <input type='submit' value='Submit' />
            </form>
         </body>
      </html>";
} else {
   $retArray = array();
   $retArray['name']='Garafa Test Uploader';
   $retArray['url']="http://giskit.garafa.com/gisUploader/fileUploader.php?getInfo=1";
   echo json_encode($retArray);
}

function generateUploadIdForProjectNumber($number) {  
   return 1234124;  // hard-coded, would normally have database generate
}

?>

Video Demonstration:


Export API