Import mass usage records
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:
- Download the Zuora`s Java sample code and make sure the file
mail-1.4.jar
is included in thelib
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.
- 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
- Download the latest Zuora WSDL. You must be using WSDL version 37.0 or greater.
- Use
ant clean
andant setup
to generate the Zuora Web Service Axis Stub- Run the
ant
command according to the instructions in thereadme.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.
- Run the
- Verify that you can find the
ZuoraServiceStub.Import
file inZuoraServiceStub.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:
- Use the create() call to create an Import object. You must set the
ImportType
toUsage
. - Use the
javax.activation.Datahandler
to set the File Content of Import. See the sample code for an example. - Enable the MTOM in the Axis Client by setting the stub`s connection option.
- 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; }