Skip to main content

Import mass usage records

Zuora

Import mass usage records

  1. Last updated
  2. Save as PDF

You can combine your mass usage records into a single file, and use the SOAP API call to create an Import object to import the file. The file is added as the attachment in the SOAP and transferred to the Zuora application server using Message Transmission Optimization Mechanism (MTOM).

You should have experience with web services client side programming and Java and XML handling to perform this task.

Prerequisites

Before you can upload mass usage records, you must prepare your development environment: 

  1. Download the Zuora`s Java sample code and make sure the file mail-1.4.jar is included in the lib directory.
    • You can download this file from the Oracle website. It is also included in the Axis package and in Zuora`s sample code package. We have tested mail-1.4.jar, but the latest version 1.4.5 should also work.
  2. Download the latest Zuora WSDL. You must be using WSDL version 37.0 or greater.
  3. Use ant clean and ant setup to generate the Zuora Web Service Axis Stub
    • Run the ant command according to the instructions in the readme.txt included with the sample code. In order to connect the server, generate the web service stub in the client side as the proxy to connect to the remote web service. 
  4. Verify that you can find the ZuoraServiceStub.Import file in ZuoraServiceStub.java.

If your programming language is not Java or if you are not using the Axis as the web service client, see the documentation for the language or tool that you are using for information about handling the SOAP message attachment with MTOM. 

Limits

Size allowed on import file

 4 MB (i.e., 4,94304 bytes or 4096 KB) is allowed on the import file size.

Upload usage files

To upload usage files through the Zuora API:

  1. Use the create() call to create an Import object. You must set the ImportType to Usage.
  2. Use the javax.activation.Datahandler to set the File Content of Import. See the sample code for an example. 
  3. Enable the MTOM in the Axis Client by setting the stub`s connection option.
  4. The create() call will return the import ID if the import is successful, or an error message if the usage import fails.

Troubleshooting usage upload errors

If the import fails, every result includes a message describing the reason the create() call failed. The following are examples of some of the error messages.

  • Validation exception: Cannot detect the file name from your Content-Type. Use the name parameter to provide the file name.
  • Validation exception: File MD5 verification error.
  • Validation exception: The import file exceeds the maximum file size of 4,194,304 bytes.
  • Validation exception: The zip file cannot contain a directory. 

API syntax

Use the following code to upload the mass usage data file through the Zuora API:

private ID createImport() throws Exception {
      Create create = new Create();
       ZuoraServiceStub.Import ip = new ZuoraServiceStub.Import();
       ip.setImportType("Usage");
       DataSource dataSource = new ByteArrayDataSource(
       new FileInputStream("<REPLACE WITH YOUR CSV FILE PATH CONTAINED THE USAGE RECORDS>")
       ,"text/plain;name=<YOUR CSV FILE NAME>");
       DataHandler dataHandler = new DataHandler(dataSource);
       ip.setFileContent(dataHandler);
       create.setZObjects(new ZObject[] { ip });
      stub._getServiceClient().getOptions()
      .setProperty(Constants.Configuration.ENABLE_MTOM, Constants.VALUE_TRUE);
      CreateResponse cResponse = stub.create(create, null, this.header);
      ZuoraServiceStub.SaveResult result = cResponse.getResult()[0];
      ID id = result.getId();
      return id;
   }