AgileApps Support Wiki Pre Release

Java API:Data Import

From AgileApps Support Wiki

Using the data import APIs, an application developer can create an HTML page or Custom JSP Page that lets the end user browse the file system, choose a CSV data file, and import the contents of that file into an application object.

Notepad.png

Note: When the importData API is invoked, a job is submitted to the import processing queue. When that job successfully completes, the user's data will have been imported.

getMappingProfiles

Return the names and IDs of the import mapping profiles for a specified object.

Syntax
public HashMap<String,String> Functions.getMappingProfiles(objectName)
Parameters
objectName
The name of the object to query.
Returns
A HashMap containing profile IDs (keys) and their names (values).


importData

Upload a file and submit an import job for a specified object.

Syntax
String job_id = Functions.importData(String objectName, String  mappingProfile, PlatformFileBean fileBean);
Parameters
objectName
The name of the object to import data into.
mappingProfile
The name of the mapping profile. That profile (defined in the platform GUI) maps the CSV data fields to fields in the object.
fileBean
The bean that wraps a CSV data file.
Returns
A string containing the ID of the submitted job. That ID can then be used to check the status of the job using the Java getStatus resource.


Example: Import data into an Account object

In this example, a system is set up that allows the user to import CSV data into the Accounts object, and check the status of the job to find out when it has completed.

Steps

  1. Create a page that lets the user select a CSV file.
    • The mapping can be hard-coded or, since an object can have multiple import mappings, you may want to give the user a choice of mappings.
    • In this example, the user is given the choice.
  2. Create a controller page that invokes importData
    • Use the job ID returned by that API, in conjunction with the REST APIs, to set up a URL the user can visit to check the status of the job.
    • Send that URL on to the next step.
  3. Create a destination page for the user to go to after the job has been submitted.
    • In that page, display the link the user can visit to check the status of the job.

Create the Initial JSP page: AccountImport.jsp

The initial page in this example:

  1. Lets the user choose the CSV file.
  2. Gets a list of available mapping profiles for that object and give the user a list to select from (or hard code that value).
  3. Submits the job to the import queue.
  4. When done, takes the user to the "job submitted page"

To import, the data file needs to be uploaded to the server, using a multipart request. To do that a form is created that has the mediatype mutipart/form-data. 

<%@ page import = "com.platform.api.Functions"%>
<%@ page import = "com.platform.beans.*"%>
<%@ page import = "com.platform.c123456.dataImport.*" %>
<%@ page import = "java.util.*" %>

<html>

<% String mesg = (String)request.getParameter("MSG");

HashMap mapping = Functions.getMappingProfiles("ACCOUNT");
 
%>
<body>
<table width = "50%" align = "center">
<form name="dataImport"  enctype="multipart/form-data" action="https://{{domain}}/networking/multipartController/com.platform.c123456.dataImport.AccountImport" method="POST">
<br>
<br>
<br>
<br>
<input  type="hidden" name="object_id" value="ACCOUNT" >
<td >Select a File </td>
<td align="left">
   <input  type="File" name="importfile"  size="50" class="inputForm">
</td>
</tr>

<tr>
<td> Object</td>
<td align="left"> Account</td></td>
</tr>
<tr>

<tr>
<td> Select mapping profile</td>
<td align="left">
   <select  name="mapping" >     
   <% Set mappingkeys = mapping.keySet();
       Iterator it = mappingkeys.iterator();
       while (it.hasNext()) {
       String mappingId = (String) it.next();%>
           <OPTION value="<%=mapping.get(mappingId)%>"><%=mapping.get(mappingId)%>
           </option>
   <%}%>
   </select>   
</td>
</tr>
<td colspan="2" align = "center" >
  <input type="submit"  value ="Submit" name="Submit"/>
</form>
</table>
</body>
</html>

Create the Page Controller: AccountImport.java

The initial JSP page passes the data file and the name of the mapping profile to a MultiPartController that:

  • Gets the path to the data file and the name of the mapping profile from the incoming request.
  • Creates a PlatformFileBean using the uploaded file content.
  • Adds that bean as a request parameter.
  • Submits the job
  • Transitions the user to the "Job Submitted" page, passing the URL the user can visit to check job status.
import java.util.HashMap;
import java.util.Map;

import com.platform.api.Controller;
import com.platform.api.ControllerResponse;
import com.platform.api.Functions;
import com.platform.beans.PlatformFileBean;
import com.platform.beans.CustomObjectMetaDataBean;

public class AccountImport implements Controller
{
   /**
    * The controller's execute() method retrieves submitted form data  
    * and invokes the api to create the import job.
    * 
    * @param params - Contains the request parameters passed from 
    *                 the jsp page - AccountImport.jsp 
    **/
    public ControllerResponse execute(HashMap params) throws Exception
    {
      String import_job_id  = "";
  
      // object_id is a hidden variable. Here it is set to ACCOUNT.
      String objectId = (String)params.get("object_id");
      String mappingName =(String) params.get("mapping"); 
    
      // Retrieve the bean from fileparameter.
      PlatformFileBean fileBean = (PlatformFileBean) params.get("importfile");
      try
      {
        if (fileBean != null) {
          // If present, pass the bean to the import API
          // (If it isn't we'll catch the fact that import_job_id is null below.)
          import_job_id = Functions.importData(objectId, mappingName, fileBean);
        }
      }
      catch (Exception e)
      {
        e.getMessage();
        throw e;
      }
     
      // Set up to pass parameters to the next stage. 
      ControllerResponse rs = new ControllerResponse();
      rs.setData(params); 
      if (import_job_id != null && !import_job_id.equals(""))
      {        
         params.put("MSG", "File has been submitted for Import. "
                         + "Check import status by clicking the following link: ");
         params.put("URL", "https://{{domain}}/networking/rest/status/importStatus/" 
                         + import_job_id);      
         rs.setData(params);
         rs.setTargetPage("ImportScheduled.jsp");
      } else {
      rs.setTargetPage(
        "AccountImport.jsp?MSG=Error in file upload. Please check the input ...");
     } 
    return rs;
}

Create the Job Submitted Page: ImportScheduled.jsp

This page tells the user that the job has been submitted and displays the link the user can follow to query the job's status. 

<%@ page import = "java.util.*" %>
<html>

<% java.util.HashMap params = (java.util.HashMap)controllerResponse.getData();
String mesg = (String)params.get("MSG");
String url = (String)params.get("URL");
 %>

<body bgcolor="#ffff00">
  <h1 align="center">Import Status</h1>
  <table width = "80%" align = "center">
  <form name="ImportComplete" >
    <% if (mesg != null) { %>
      <tr> <td colsize="2"> <%=mesg%></tr></td>
      <tr> <td colsize="2"><a href="<%=url%>"><%=url%></a></tr></td>
     <%} %>
  </form>
  </table>
</body>
</html>
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=Java_API:Data_Import&oldid=12968"