PackagePushRequest

Supported Calls

create(), describeSObjects(), query(), retrieve(), update(), upsert()

Fields

Usage

Suppose that you want to push version 3.4.6 of your package to all orgs. You’ve already identified the orgs eligible for the upgrade by using MetadataPackageVersion. Now let’s write some code to create a push request, which holds a push job for each eligible org.

This code sample uses the Web Services Connector (WSC).

1// Create a new PackagePushRequest for the versionId to upgrade to
2// (for example, versionId is the "04t..." id of version 
3// 3.4.6 of the package
4PackagePushRequest ppr = new PackagePushRequest();
5ppr.setPackageVersionId(versionId);
6
7// Optionally, set the start time of the PackagePushRequest to schedule it to begin 
8// automatically; scheduledStartTime is a java.util.Calendar instance
9ppr.setScheduledStartTime(scheduledStartTime);
10
11// Save the PackagePushRequest
12SaveResult[] saveResults = conn.create(new SObject[] { ppr });
13if (saveResults[0].isSuccess()) {
14	// Add the newly generated Id to the object
15	ppr.setId(saveResults[0].getId());
16} else {
17	for (Error error : saveResults[0].getErrors()) {
18		System.out.println(error.getMessage());
19	}
20}

Or, if you’re using REST API, submit a POST request to the PackagePushRequest sObject endpoint, as in the following example. SOAP API is also supported.

1POST
2/services/data/v38.0/sobjects/packagepushrequest/
3{
4   "PackageVersionId" : "04t...",
5   "ScheduledStartTime" : "2016-08-24T21:00:00"
6}

As your next step, create a push job for each eligible subscriber you want to upgrade using PackagePushJob.

Scheduling the Push Upgrade

To signal that the push upgrade is ready to be processed, change the status of the push request to Pending. If you didn’t set a ScheduledStartTime, the push upgrade starts immediately after you change the status.

1// ppr is the PackagePushRequest instance
2ppr.setStatus("Pending");
3conn.update(new SObject[] { ppr });

If you’re using REST API, submit a PATCH request to the PackagePushRequest sObject endpoint, as in the following example. SOAP API is also supported.

1PATCH
2/services/data/v38.0/sobjects/packagepushrequest/0DV...
3{
4   "Status" : "Pending"
5}

Checking the Status of a Push Request

1// Finds the status of the PackagePushRequest for a given Id
2final String PACKAGE_PUSH_REQUEST_STATUS_QUERY = "Select status from PackagePushRequest" +
3	" where Id = '%s'";
4
5// ppr is a PackagePushRequest instance
6QueryResult queryResult = conn.query(String.format(PACKAGE_PUSH_REQUEST_STATUS_QUERY, 
7	ppr.getId()));
8
9// extract the status from the QueryResult
10String status = ((PackagePushRequest) queryResult.getRecords()[0]).getStatus();
11
12// optionally, update the PackagePushRequest instance with the latest status
13ppr.setStatus(status);

You can also check the status of a job by querying the PackagePushJob’s Status field.

Aborting a Push Request

You can abort a package push request by changing its status to Canceled.

1PATCH
2/services/data/v38.0/sobjects/packagepushrequest/0DV...
3{
4   "Status" : "Canceled"
5}

1// ppr is the PackagePushRequest instance
2ppr.setStatus("Canceled");

You can abort a package push request only if its status is Created or Pending. If the abort succeeds, all associated push jobs are also canceled. If you try to abort when the current PackagePushRequest status is Canceled, Succeeded, Failed, or In Progress, the abort doesn’t occur, and an error message is returned.