MisterClipping Developer API

The MisterClipping.com Web Service (WS) offers developers a way to integrate MisterClipping into their own software package. The WS is currently being used in a diverse group of programs, ranging from simple cron job scripts to complex image managing software. The WS has the same functionality as the website: customers can set per image or per job instructions, images can be rejected, and the job status can be monitored; amongst other things.
We have various examples available in Java and C#.NET: simple proof of concept examples, as well as a multi-threaded application with GUI, embedded database, and custom FTP client. Contact us for more information.

Code samples are provided in Java throughout the manual. Depending on the import utility and the language you use, object names might slightly differ from those used in the code samples.

1. Getting Started

Before you get started you will need to contact MisterClipping.com to obtain an API key. Furthermore, it is possible to use our dedicated test environment. We advice you to do so, contact us to setup a test account.

1.1 Obtaining the WSDL

You can use a simple command-line utility, such as wsimport, to import the WSDL

# wsimport -extension -keep https://webservices.misterclipping.com/service/mrcinterface.asmx?WSDL

The URL for the test environment is https://servicesaccept.misterclipping.com/service/mrcinterface.asmx?WSDL. After you import the WSDL you will be provided with a bunch of classes containing all the methods you need to merge MisterClipping into your current workflow.

1.2 Authentication

You need to setup the user info and you'll need to obtain a reference to the MrcInterfaceSoap object before you can start talking to the WS.

// Authentication: Set vendorid, username and password.
MrcAuthentication auth = new MrcAuthentication();
auth.setUsername(username);
auth.setPassword(password);
auth.setVendorId(api_key);

// Get a reference to an instance of the soap interface object
MrcInterface iface = new MrcInterface();
MrcInterfaceSoap service = iface.getMrcInterfaceSoap12();

The member called "service" will be used to call methods for the up- and downloading process.

2. The Upload process

2.1 Creating a Job

Before you can start uploading, you'll need the actual job number. When you create a new job, you can get the job number as followed.

// Create a new job, with custom name and job description
MrcCreateJobResult jobresult = service.createJob(auth, job_name, description);

// Get the ID of the newly created job
Integer jId = jobresult.getJobId();

2.2 Obtaining FTP Information

Before you fire up your FTP client to upload your images, you have to obtain the actual FTP info.

String ftpHost = jobresult.getFtpUploadInfo().getFtpServer();
String ftpUsername = jobresult.getFtpUploadInfo().getFtpUser();
String ftpPassword = jobresult.getFtpUploadInfo().getFtpPass();
String ftpUploadDirectory = jobresult.getFtpUploadInfo().getFtpDirectory();
String ftpDownloadDirectory = jobresult.getFtpDownloadInfo().getFtpDirectory();

2.3 Submitting a Job

When you are done uploading your images, you can set per image instructions and submit the job for reviewing as followed.

CustomerFileRemark fr = new CustomerFileRemark();

// Set processing instructions for a single image
fr.setFileName(image_file_name);
fr.setRemark(image_remark);

// Add the per-image instructions to a list
List frList = new ArrayList();
frList.add(fr);

ArrayOfCustomerFileRemark remarks = new ArrayOfCustomerFileRemark();
remarks.customerFileRemark = frList;

// Submit the job for reviewing
service.submitJobForReview(auth, jId, remarks);

To submit the job without per-image instructions, you can just use null instead of the remarks argument.

3. The Download process

3.1 Checking Job Status

You can get information about your jobs with the following code.

// Reference variable for Job Information
GetJobStatusResult jInfo = service.getJobStatus(auth, jId);

// Print Job Status
System.out.println(jInfo.getStatus());

if(jInfo.isReviewed){
    // Action if job is reviewed
}
if(jInfo.needsPayment){
    // Action if job needs payment
}
if(jInfo.isClipped){
    // Fire up an FTP client and download the job
}

You can start downloading your images from the FTP path ftpDownloadDirectory once the isClipped boolean is true.

4. Finalization

4.1 Rejecting Images

The WS can be used to either reject an entire job, or to reject individual images. You can also send feedback, while still accepting the job or the image.

// Set per-job Feedback -- false = reject job
service.setJobFeedback(auth, jId, false, feedback_message);

// Feedback and/or Reject individual images
MrcFileFeedback ff = new MrcFileFeedback();
ff.setName("file.png");
List ffList = new ArrayList();
ffList.add(ff);

ArrayOfMrcFileFeedback feedback = new ArrayOfMrcFileFeedback();
feedback.mrcFileFeedback = ffList;

// Set per-image feedback -- false = reject image
service.setFileFeedback(auth, jId, feedback, file_feedback_message, false);

It is also possible to reject multiple images from the same job over multiple callouts. This can be done with the rejectFiles method. Each time you call rejectFiles a new rejected job will be created.

ArrayOfFileRemark files = new ArrayOfFileRemark();
List fileList = new ArrayList();

FileRemark remark = new FileRemark();
remark.setFileName("picture.png");
remark.setToProcessor(true);
remark.setRemark("Wrong clipping path");
fileList.add(remark);

files.fileRemark = fileList;

service.rejectFiles(auth, jId, files);

// Sleep a bit so the rejected job can be created
try{
Thread.sleep(5000);
}catch(InterruptedException e){
e.printStackTrace();
}

// Get the ID of the rejected job
Integer rejectedID = service.getRejectedJobId(auth, jId);

4.2 Closing a Job

Closing a job is straight forward, and can be done with the following method.

service.closeJob(auth, jId);

5. Important notes

Keep the number of images per job under 200
Make sure you properly close each FTP connection when you are done uploading or downloading
Do not open more than one FTP connection at once