Difference between revisions of "REST API:bulk Resource"

From AgileApps Support Wiki
imported>Aeric
 
imported>Aeric
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
Provides [[Data Import]] capabilities using the [[REST API]]. Using this API, a CSV file containing data records can be uploaded to an object.
Provides [[Data Import]] capabilities using the [[REST API]]. Using this API, a CSV file containing data records can be uploaded to an object.


:''Learn more:'' REST API [[REST API#Conventions and Considerations|Conventions and Considerations]].
:''Learn more:''
::* REST [[REST API:import Mapping Profile Resource|import Mapping Profile]] Resource
::* REST [[REST API#Conventions and Considerations|Conventions and Considerations]]
 
:''See also:''
::* REST [[REST API:bulk record Resource|bulk record]] Resource
 
 
__TOC__
__TOC__
===Requirements===
===Requirements===
:*A valid [[Login]] session.
:*A valid [[Login]] session.
:*A [[Session Identifier|sessionId]] for the request header.
:*A [[Session Identifier|sessionId]] for the request header.
:*A [[Mapping Profile]] created in the GUI, which maps CSV fields to record fields and specifies the Data Merge strategy.
:*A [[Mapping Profile]], which maps CSV fields to record fields and specifies the Data Merge strategy, created either in the GUI, or using the [[REST API:importMappingProfile Resource|import Mapping Profile Resource]]
{{Tip|To upload a record that has a raw data field (like an image), add a URL field for the path to an image. Then create an action-driven [[Data Policy]] to load the image from the URL. The bulk upload then reads URLs from the CSV data, while the data policy processes them to load the raw data.}}


===Bulk Upload Object Data===
===Bulk Upload Object Data===
Line 16: Line 22:


;Method:POST
;Method:POST
;URI:<tt><nowiki>https://{domain}/networking/rest/bulk/{objectName}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/bulk/{objectName}</tt>


:;Parameter:
:;Parameter:
:: '''objectName''': An [[Object Identifier]]. Object names are recommended, but Object IDs are supported for backward compatibility.
:: '''objectName''': An [[Object Identifier]]. Object names are recommended, but Object IDs are supported for backward compatibility.


:All {{type|}}s support bulk upload. In addition, these [[CRM Objects]] are supported:
:All {{type|}}s support bulk upload.  
::{| border="1" cellpadding="5" cellspacing="1"
| '''Name''' (shown in the GUI) || '''Object Name''' (used in the URI)
|-
| Accounts || '''Accounts'''
|-
| Contacts || '''Contacts'''
|-
| Prospect || '''Leads'''
|-
| Opportunity || '''Opportunities'''
|-
| Activity || '''Activities'''
|}
{{Note|Specify the Object Name in the URI. Case is significant.}}
{{Note|Specify the Object Name in the URI. Case is significant.}}


Line 83: Line 76:
|-
|-
| mapping || String || Yes || Name of the [[Mapping Profile]] created in the platform UI
| mapping || String || Yes || Name of the [[Mapping Profile]] created in the platform UI
|-
| leadSource || String || for import into [[Prospect]]s || Prospect source. Applies to all imported records.
|-
| ownerName || String || for import into [[Activities]] || Default owner ID or name. (This user is assigned the activity when <tt>assignedid</tt> and <tt>contactid</tt> are not mapped, or when neither field in a record has a value.)
|}
|}
<noinclude>
<noinclude>
Line 110: Line 99:


import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;
import org.apache.commons.httpclient.methods.multipart.StringPart;
import org.apache.commons.httpclient.methods.StringRequestEntity;
 
import org.w3c.dom.Document;
import org.w3c.dom.Document;
import org.xml.sax.InputSource;
import org.xml.sax.InputSource;
Line 134: Line 123:
           "<bulk>" +
           "<bulk>" +
               "<mapping>CustomerMap</mapping>" +                               
               "<mapping>CustomerMap</mapping>" +                               
              // For Prospects, add: "<leadSource>...</leadSource>" +
              // For Activities, add: "<ownerName>...</ownerName>" +
           "</bulk>" +
           "</bulk>" +
         "</platform>" ;
         "</platform>" ;
Line 166: Line 153:


       System.out.println("Use the following URL to check job status:");
       System.out.println("Use the following URL to check job status:");
       System.out.println("https://{domain}/networking/rest/status/import/"
       System.out.println("https://{{domain}}/networking/rest/status/import/"
                       + jobId);           
                       + jobId);           
     }
     }
Line 177: Line 164:
   /**
   /**
   * Log into the platform. After doing so, session ID is automatically
   * Log into the platform. After doing so, session ID is automatically
   * set for all future requests that use the HttpClient.
   * set for all future requests that use the HttpClient. (The server sets up
  * a cookie string for the session, and returns it in the response. The
  * HttpClient instance saves that string and adds it to subsequent requests.
  * Reusing an instance of HttpClient, in effect, defines a "session".)
   *
   *
   * @return The HttpClient object when the login succeeds.
   * @return The HttpClient object when the login succeeds.
Line 184: Line 174:
   public static HttpClient login() throws Exception
   public static HttpClient login() throws Exception
   {
   {
       String url = "http://localhost/networking/rest/login";
       String url = "https://{{domain}}/networking/rest/login";
       PostMethod postMethod = new PostMethod(url);       
       PostMethod postMethod = new PostMethod(url);       
       String loginXml =
       String loginXml =
             "<platform>" +
             "<platform>" +
               "<login>" +
               "<login>" +
                   "<userId>yourLoginID</userId>" +
                   "<userName>yourLoginName</userName>" +
                   "<password>YourPassword</password>" +
                   "<password>YourPassword</password>" +
               "</login>" +
               "</login>" +
             "</platform>" ;
             "</platform>" ;
       StringRequestEntity reqXml =  
       StringRequestEntity reqXml =  
         new StringRequestEntity(loginXml,MediaType.APPLICATION_XML, "UTF-8");
         new StringRequestEntity(loginXml, MediaType.APPLICATION_XML, "UTF-8");
       postMethod.setRequestEntity(reqXml);
       postMethod.setRequestEntity(reqXml);
        
        
Line 200: Line 190:
       HttpClient httpClient = new HttpClient();       
       HttpClient httpClient = new HttpClient();       
       int status = httpClient.executeMethod(postMethod);
       int status = httpClient.executeMethod(postMethod);
       if (status != 0) throw new Exception("Login failed with HTTP status "  
       if (status != 200) {
                                          + status);                    
        throw new Exception("Login failed with HTTP status " + status);  
      }                                                       
       return httpClient;
       return httpClient;
   }
   }

Latest revision as of 01:35, 6 December 2014

Provides Data Import capabilities using the REST API. Using this API, a CSV file containing data records can be uploaded to an object.

Learn more:
See also:


Requirements

Bulk Upload Object Data

Loads CSV data into an object.

Method
POST
URI
https://{yourDomain}/networking/rest/bulk/{objectName}
Parameter
objectName: An Object Identifier. Object names are recommended, but Object IDs are supported for backward compatibility.
All Custom Objects support bulk upload.

Notepad.png

Note: Specify the Object Name in the URI. Case is significant.

Request
A multipart request with file part for the CSV data and an XML part with information.
Here's a sample request that uploads data to a Customers object:
Content-Type: multipart/form-data; boundary=.............................103832778631715

--.............................103832778631715
Content-Disposition: form-data; name="bulk";
Content-Type: application/xml;

<platform>
    <bulk>
        <mapping>CustomerMap</mapping>
    </bulk>
</platform>

.............................103832778631715
Content-Disposition: form-data; name="Customers.csv"; filename="Customers.csv"
Content-type: application/octet-stream

{contents of file}
.............................103832778631715--
Learn more: REST API:Multipart Request
Response

Returns the id of the submitted import job, along with a message telling whether or not the job was accepted for processing. (Use the REST import Status resource to follow the progress of the job.)

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>yur456poi967</id>      <!-- import process job ID -->  
    </message>
</platform>
See also: REST API:Error Codes

Fields

Name Type Required Description
mapping String Yes Name of the Mapping Profile created in the platform UI


Sample Http Client for bulk uploads

This sample client uploads Customer data. It is contained in the Samples Zip file.
(For the JAR files it uses, see Setting Up the Development Enviroment.)
Learn more about the login process: REST login resource
package demo.rest;

import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.InputStream;

import javax.ws.rs.core.MediaType;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathExpression;
import javax.xml.xpath.XPathFactory;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

import org.w3c.dom.Document;
import org.xml.sax.InputSource;

public class BulkUploadClient {
  
  public static void main(String[] args)
  {  
    try
    {    
      // Modify the login() method to specify user name and password.
      HttpClient httpClient = login();

      String url = "http://localhost/networking/rest/bulk/Customer";      
      String importXml =
        "<platform>" +
           "<bulk>" +
              "<mapping>CustomerMap</mapping>" +                               
           "</bulk>" +
        "</platform>" ;
      
      // XML part
      StringPart sp = new StringPart("bulk", importXml);
      sp.setContentType(MediaType.APPLICATION_XML);
       
      // File part
      File file = new File("c:/document/customers.csv");     
      
      // Multipart wrapper
      Part[] part = {                        
                      new FilePart(file.getName(),file),
                      sp
                    };
                
      // Create the request          
      PostMethod postMethod = new PostMethod(url);
      MultipartRequestEntity requestEntity =
          new MultipartRequestEntity( part, postMethod.getParams() );
      postMethod.setRequestEntity(requestEntity);         

      // Send it
      int status  = httpClient.executeMethod(postMethod);   
      System.out.println("HTTP Status = " + status);            
     
      String responseXml = postMethod.getResponseBodyAsString();
      String jobId = getValue("platform/message/id", responseXml);

      System.out.println("Use the following URL to check job status:");
      System.out.println("https://{{domain}}/networking/rest/status/import/"
                       + jobId);          
    }
      catch (Exception e)
    {
      e.printStackTrace();
    }
  }
  
  /**
   * Log into the platform. After doing so, session ID is automatically
   * set for all future requests that use the HttpClient. (The server sets up
   * a cookie string for the session, and returns it in the response. The 
   * HttpClient instance saves that string and adds it to subsequent requests.
   * Reusing an instance of HttpClient, in effect, defines a "session".)
   *
   * @return The HttpClient object when the login succeeds.
   * @throws An exception if the login fails.
   */ 
  public static HttpClient login() throws Exception
  {
      String url = "https://{{domain}}/networking/rest/login";
      PostMethod postMethod = new PostMethod(url);      
      String loginXml =
            "<platform>" +
               "<login>" +
                  "<userName>yourLoginName</userName>" +
                  "<password>YourPassword</password>" +
               "</login>" +
            "</platform>" ;
      StringRequestEntity reqXml = 
        new StringRequestEntity(loginXml, MediaType.APPLICATION_XML, "UTF-8");
      postMethod.setRequestEntity(reqXml);
      
      // Log in
      HttpClient httpClient = new HttpClient();      
      int status = httpClient.executeMethod(postMethod);
      if (status != 200) {
         throw new Exception("Login failed with HTTP status " + status); 
      }                                                         
      return httpClient;
  }

  
  /**
   * Given an XPath expression and XML, parse for a specific value.
   * @param xpath_expr  An XPATH expression. 
   *                    For example: "/platform/message/description"
   * @param xml The XML string to be parsed.
   */
  public static String getValue(String xpath_expr, String xml) 
  {
    try {
      DocumentBuilderFactory docFactory =
          DocumentBuilderFactory.newInstance();
      docFactory.setNamespaceAware(true);
      DocumentBuilder docbuilder = docFactory.newDocumentBuilder();
      InputStream is = new ByteArrayInputStream(xml.getBytes());

      Document doc = docbuilder.parse(new InputSource(is));
      XPathFactory factory = XPathFactory.newInstance();
      XPath xpath = factory.newXPath();
      XPathExpression expr = xpath.compile(xpath_expr);
      Object result = expr.evaluate(doc, XPathConstants.STRING);
      return result.toString();
    }
    catch (Exception e)
    {
      e.printStackTrace();
    }
    return null;
  }
  
}