Table of Contents

  1. Introduction
  2. Integrating
  3. USPS Bulk Shipping Fields

1. Introduction

The following information provides guidance for integrating the Zenkraft Bulk Shipping Platform into your org. The Bulk Shipping Platform allows for the processing of bulk/high-volume shipments. As it is a platform, some custom integrating is necessary to accommodate your company’s specific shipping needs. The Bulk Shipping Platform was built to provide flexibility, to ensure your company’s specific shipping needs are met. Through the use of Apex and Visualforce, the Bulk Shipping Platform can be extended to provide a custom shipping experience.

2. Integrating

The Zenkraft Bulk Shipping Platform allows you to processes a high volume of shipments in batches. It allows you to define every aspect of the shipment(s) and then validate the shipments in bulk, and also allows you to process the shipment(s) in bulk. Both domestic and international shipment validation and processing are supported.

Also, bulk printing is supported. You must first have Zenkraft Shipmate setup to print successfully with a thermal printer.

There are several objects you will be using. USPS Queued Shipment and USPS Queued Package are the objects you use to define each individual shipment. Then, to combine them into a bulk shipment queue, associate the Queued Shipment records to a USPS Bulk Shipment. The USPS Bulk Shipment object acts as your shipping queue. All commands to validate and to process queued shipments are operations on the USPS Bulk Shipment record. Once you insert all those records to define your shipments, you use the Apex class BulkShipmentInterface to validate or process the shipments, passing the class the ID of the USPS Bulk Shipment record.

The zkusps.BulkShipmentInterface.validateBulkShipment() method takes the ID of the Bulk Shipment record as parameters and performs basic app validation on each Queued Shipment associated to that Bulk Shipment record.

The zkusps.BulkShipmentInterface.processBulkShipment() method takes the ID of the Bulk Shipment record as a parameter and generates the labels for each Queued Shipment associated to that Bulk Shipment record.

Both zkusps.BulkShipmentInterface.validateBulkShipment() and zkusps.BulkShipmentInterface.processBulkShipment() return a String value representing the Batch ID. as each Queued Shipment gets processed, a Queued Shipment Status record gets inserted that will show the results (see the Status__c field) and also contain the Batch ID. After all Queued Shipments are processed, a Bulk Shipment Status record is inserted associated to the Bulk Shipment also with the Batch ID, just so you know the processing is complete. The Queued Shipment Status object and the Bulk Shipment Status object are useful for writing triggers. You can write triggers that execute logic as each Queued Shipment is processed for a given Batch ID, or you can write triggers that execute logic once an entire Bulk Shipment Status indicates that processing is done for all the queued shipments.

A key thing to note is that the master lookup field on the USPS Queued Shipment object is re-parentable. This is so you can build different ways of handling failed validations or processing of a Bulk Shipment queue. For example, you can decide to perform the validation on a Bulk Shipment record, and if any Queued Shipment validations fail, those can be re-parented to a new Bulk Shipment record that can be a collection of Queued Shipments that need to be adjusted to pass validation. Also, the same can be done during the processing of the Queued Shipment records, where any Queued shipments that have an error can be re-parented to a new Bulk Shipment record that can be a collection of Queued Shipments that need to be evaluated by the users.

To test without building any of your own Apex code to integrate, you can use the Salesforce Developer Console. Note, you must first insert in valid data for Queued Shipments and Queued Packages. In the Salesforce Developer Console, simply execute the following once you have inserted in valid data (will perform actions on the Bulk Shipment record with the name ‘Bulk-Shipment-00000001’, adjust accordingly):

zkusps__BulkShipment__c[] bulkShipments = [select Name,Id from zkusps__BulkShipment__c];
zkusps__BulkShipment__c bulkShipment = null;
for (zkusps__BulkShipment__c bs : bulkShipments) {
  if (bs.Name == 'Bulk-Shipment-00000001') {
    bulkShipment = bs;
  }
}

if (bulkShipment != null) {
  zkusps.BulkShipmentInterface.validateBulkShipment(bulkShipment.Id);
}

Some important things to note when integrating:

Please read all the field specific documentation of the Custom Objects before using them, to understand how the fields should be used.

Once a validate or processes bulk is kicked off, do not do any operations on the Bulk Shipment or Queued Shipment/Packages until the batch is done. You will know it is done for the entire batch once a Bulk Shipment Status record is inserted with the corresponding Batch ID

The Bulk Shipment Status record’s Status__c field simply indicates that the validate or process batch completed, but does not indicate whether the individual Queued Shipment‘s were validated/processed successfully. Check the Bulk Shipment Status object’s Status__c picklist field for possible values.

Each Queued Shipment record’s Queued Shipment Status record (of the same Batch ID) should be checked to identify errors or ensure success. Check the Queued Shipment Status object’s Status__c picklist field for possible values.

It is recommended that you first run the validateBulkShipment() method on the Bulk Shipment and verify the resulting Queued Shipment Status records before you attempt the processBulkShipment(). If the validation was successful, the Status__c field of all Queued Shipment Status records (for that Batch ID) should be set to VALIDATED

It is recommended that after a processBulkShipment(), that you verify the resulting Queued Shipment Status records. If the processing was successful, the Status__c field of all Queued Shipment Status records (for that Batch ID) should be set to SUCCESS

If the Status__c field for a Queued Shipment Status record is ever set to ERROR, the StatusMessage__c field on that Queued Shipment Status record will contain a message describing the error.

At a minimum, the following fields on the Queued Shipment record must have a value for a Domestic Shipments:

  1. Label Image Type – should be set to a Thermal printer option if you would like to use the bulk printing feature
  2. Service Type
  3. Packaging Type
  4. Weight/Dimension Units – Set to LB / IN for US domestic shipments
  5. Sender Details (Sender Name, Sender Company, Sender Phone, Sender Email, Sender Street, Sender City, Sender State/Province, Sender Zip/Postal Code)
  6. Recipient Details (Recipient Name, Recipient Phone, Recipient Street, Recipient City, Recipient State/Province, Recipient Zip/Postal Code, Recipient Country)
  7. The minimum fields for the Queued Package are determined by the selected Packaging Type on the Queued Shipment record. First, there can only be one Queued Package record associated to a Queued Shipment record. Multi-package shipments are not allowed.
  8. If the Packaging Type is one of the USPS Flat Rate packaging types, none of the fields on the Queued Package record are required. Note that even if none of the fields are specified, a blank Queued Package record must be associated.

If the Packaging Type is not a USPS Flat Rate packaging type, the following are the required fields on the Queued Package record:

  1. Weight (Weight Pounds and/or Weight Ounces)
  2. If the Packaging Type is specifically set to ‘Large Parcel – any dimension over 12 inches’, the following are the required fields on the Queued Package record:
  3. Weight (Weight Pounds and/or Weight Ounces)
  4. Length
  5. Width
  6. Height

It is recommended you set the fields that associate the shipment to other objects. For example, if you want the Shipment record generated to have the lookup set to an Account object, ensure the field Account__c has a value set on the Queued Shipment record. If you want the Shipment record generated to have the lookup set to a Contact record, ensure the field Contact__c has a value set on the Queued Shipment record. If you want the Shipment record generated to have the lookup set to a Lead record, ensure the field Lead__c has a value set on the Queued Shipment record. If you want the Shipment record generated to have the lookup set to an Opportunity, ensure the field CustomAddressSource__c and CustomAddressSourceRecordId__c on the Queued Shipment record. Note, to use those relating to Custom Address Source, a valid Custom Address Source must be setup already. Please see field level documentation for more details.

Bulk Printing works for all Printers. Setup the Printer through the Shipmate Preference, as done with our existing released app. Ensure that the printing works by creating a standard shipment through the main shipping wizard and printing it. Once that is verified, you can print from the Bulk Shipment record, using the Print Thermal Labels button. It will print the labels for the latest completed processed shipment.

It is recommended that once you process a Bulk Shipment and created all the labels, that you do not add more Queued Shipments to the Bulk Shipment and process it again, as that will re-processes Queued Shipments that were already part of the Bulk Shipment. The goal is to treat the Bulk Shipment as your queue, and validate it and update the Queued Shipment until all validations pass, and then process the Bulk Shipment once to generate labels just once.

It is recommended that if any Queued Shipments fail as part of the processing of a Bulk Shipment, that those Queued Shipments be re-parented to a new Bulk Shipment and updated and processed as part of the new Bulk Shipment.

Once a successful processing of a Bulk Shipment occurs, the individual Queued Shipment Status records will have a lookup to the Shipment record that was generated.

3. USPS Bulk Shipping Fields

USPS Bulk Shipment

USPS Bulk Shipment Status

USPS Queued Package

USPS Queued Shipment

USPS Queued Shipment Special Services

USPS Queued Shipment Status

Did this answer your question?