AppOps API

This Prodly AppOps application programming interface (API) replaces the original, deprecated API.

Overview 

This topic describes the Prodly AppOps application programming interface (API). The API helps integrate continuous delivery and release management systems to automatically perform AppOps deployments. For example, use API requests to deploy a data set or deployment plan.

The AppOps API is a RESTful API that allows you to integrate AppOps deployments into a larger continuous integration process. AppOps API requests use the Force.com REST API to invoke AppOps actions. AppOps also supports global Apex services for internal Salesforce automation.

These API services are available:

  • REST Services
  • Global Apex Services

Prodly AppOps REST Services 

Prodly AppOps REST services provide AppOps consumers and integrated systems outside of Salesforce the ability to invoke deployments and perform other actions through REST-based API requests exposed by the AppOps Salesforce package in your Prodly AppOps control environment.

Usage 

The Deployment Web Service allows you to deploy deployment plans and data sets from applications external to the Salesforce, such as a continuous delivery or release management system. For example:

  • You are running CircleCI and after deploying updated code to a QA sandbox, you need to automatically deploy the updated data to the sandbox for end-to-end testing.
  • You have a custom built solution coordinating CPQ deployments that performs automated steps to promote product catalog changes between development, QA, and UAT sandboxes.

Namespace 

PDRI

The REST Endpoints 

These APIs mimic and act as proxy for the core AppOps services REST API as documented in Swagger.

  • /apexrest/PDRI/v1/instances/{instanceId}/checkin – saves data from a Salesforce environment to a version control system (VCS) repository branch.
  • /apexrest/PDRI/v1/instances/{instanceId}/checkout – deploys data from a VCS repository branch to a Salesforce environment.
  • /apexrest/PDRI/v1/instances/{instanceId}/deploy – deploys data from one Salesforce environment to another Salesforce environment.
  • /apexrest/PDRI/v1/instances – authorizes a Salesforce environment for use by the APIs.
  • /apexrest/PDRI/v1/jobs – retrieves the history of deployments.

Refer to our Swagger page for details. Related Salesforce Documentation.

Prodly AppOps Global Apex Services  

The DeploymentServiceRequestV1 class is an Apex service specific to Prodly AppOps.

Usage 

The DeploymentServiceRequestV1 class allows you to deploy metadata, deployment plans, and data sets using the Apex API. Depending on the parameters you specify, the API request deploys data from your control environment or a source environment you specify to one or more destination environments.

Namespace 

PDRI

Global Apex Service

Service Methods

Provides wrappers to deploy data and metadata, also to list managed instances.

The DeploymentServiceRequestV1 class provides these methods:

global with sharing class AppOpsGlobalService {
  global static AppOpsWebServices.Jobs deploy(AppOpsWebServices.DeploymentServiceRequestV1 deploymentServiceRequest, 
    String destinationManagedInstanceId);
  
  global static AppOpsWebServices.ManagedInstances listInstances();
}

Sample Code

Example code which lists all environments in AppOps in order to find the source and destination environments based on org IDs. It then kicks off a deployment of a data set.

//Retrieve managed instances
PDRI.AppOpsWebServices.ManagedInstances managedInstances =
PDRI.AppOpsGlobalService.listInstances();
//Find environment ID by org ID
Id sourceOrgId = '00D4x000001989NEAQ',
destinationOrgId = '00D020000008kmIEAQ';
PDRI.AppOpsWebServices.ManagedInstance sourceInstance,
destinationInstance;
for( PDRI.AppOpsWebServices.ManagedInstance instance : managedInstances.instances ) {
if( instance.platformInstanceId == sourceOrgId ) {
sourceInstance = instance;
} else if( instance.platformInstanceId == destinationOrgId ) {
destinationInstance = instance;
}
}
//Deploy data set from control to a sandbox
Id dataSetId = 'a054x00000685c3AAA';
PDRI.AppOpsWebServices.DeploymentServiceRequestV1 deploymentServiceRequest =
new PDRI.AppOpsWebServices.DeploymentServiceRequestV1();
deploymentServiceRequest.deploymentName = 'My Deployment Name';
deploymentServiceRequest.deploymentNotes = 'Just a test deployment';
deploymentServiceRequest.source =
new PDRI.AppOpsWebServices.DeploymentSource( sourceInstance.Id );
deploymentServiceRequest.data =
new List
{ new PDRI.AppOpsWebServices.DataDeploymentRequest(dataSetId) };
deploymentServiceRequest.metadata =
new PDRI.AppOpsWebServices.MetadataDeploymentRequest();
String destinationManagedInstanceId = destinationInstance.id;
PDRI.AppOpsGlobalService.deploy(deploymentServiceRequest, destinationManagedInstanceId);

Service Model

Deployment

global with sharing class DeploymentServiceRequestV1 {
    global String deploymentName;
    global String deploymentNotes;
    global MetadataDeploymentRequest metadata;
    global List<DataDeploymentRequest> data;
    global DeploymentSource source;
} 

global with sharing class DeploymentSource {
    global String managedInstanceId;

    global DeploymentSource(String managedInstanceId) {
        this.managedInstanceId = managedInstanceId;
    }
}

global with sharing class DataDeploymentRequest {
    global String dataSetId;
    global String deploymentPlanId;
    global Boolean simulation;
    global EventControlOptions eventControlOptions;
    global QueryFilter queryFilter;

    global DataDeploymentRequest(String dataSetId) {
        this.dataSetId = dataSetId;
    }
}

global with sharing class EventControlOptions {
    global Boolean deactivateAll;

    global EventControlOptions(Boolean deactivateAll) {
        this.deactivateAll = deactivateAll;
    }
}

global with sharing class QueryFilter {
    global String filter;

    global QueryFilter(String filter) {
        this.filter = filter;
    }
}

global with sharing class MetadataTypeDeploymentRequest {
    global String type;
    global List<MetadataComponentDeploymentRequest> metadataComponents;

    global MetadataTypeDeploymentRequest(String type) {
        this.type = type;
    }
}

global with sharing class MetadataDeploymentRequest {
    global Boolean validation;
    global String testLevel;
    global List<MetadataTypeDeploymentRequest> metadataTypes;

    global MetadataDeploymentRequest(String metadataType) {
        this.metadataType = metadataType;
    }

    global MetadataDeploymentRequest(List<MetadataTypeDeploymentRequest> metadataTypes) {
        this.metadataTypes = metadataTypes;
    }

    global MetadataDeploymentRequest() {
    }
}

global with sharing class MetadataComponentDeploymentRequest {
    global String componentName;

    global MetadataComponentDeploymentRequest(String componentName) {
        this.componentName = componentName;
    }
}

Jobs

global with sharing class Jobs {
global List jobs;
}
global with sharing class Job {
global String id;
}

Managed Instances

global with sharing class ManagedInstances {
    global List<AppOpsWebServices.ManagedInstance> instances;
}

global with sharing class ManagedInstance {
    global String id;
    global String platformInstanceId;
    global String instanceType;
    global String connectionId;
    global Boolean controlInstance;
}

Apex REST Services

These APIs mimic and act as proxy for the the core AppOps services REST API as documented in Swagger. They just add the API key header when invoking the AppOps API.

/apexrest/PDRI/v1/instances/{instanceId}/checkin

/apexrest/PDRI/v1/instances/{instanceId}/checkout

/apexrest/PDRI/v1/instances/{instanceId}/deploy

/apexrest/PDRI/v1/instances

/apexrest/PDRI/v1/jobs

Parameters 

The DeploymentServiceRequestV1 method accepts these parameters:

  • String deploymentName – A name to distinguish this deployment from other deployments on the Deployment History page.
  • String deploymentNotes – Notes that become part of the deployment results.
  • MetadataDeploymentRequest metadata – A method describing the metadata to deploy.
  • List<DataDeploymentRequest> data – A method describing the data to deploy.
  • DeploymentSource source – A method describing the source environment to deploy from.

The DeploymentSource method accepts these parameters:

  • String managedInstanceId – The ID of the AppOps connection to the source environment from which to deploy data.

The DataDeploymentRequest method accepts these parameters:

  • String dataSetId – The ID of the data set to deploy. Do not specify if specifying a deployment plan.
  • String deploymentPlanId – The ID of the deployment plan to deploy. Do not specify if specifying a data set.
  • Boolean simulation – A flag to indicate only preview the data to deploy (don’t actually deploy).
  • EventControlOptions eventControlOptions – A method describing how to control events.
  • QueryFilter queryFilter – A method describing how to filter the source data. 

The EventControlOptions method accepts these parameters:

  • Boolean deactivateAll – A flag to automatically deactivate and reactivate all available platform automation during deployment. 

The QueryFilter method accepts these parameters:

The MetadataDeploymentRequest method accepts these parameters:

  • Boolean validation – A flag to indicate only validate metadata to deploy (don’t actually deploy).
  • String testLevel – The Validation Tests Option to use to instruct AppOps Release to call the exact same Validate Change Set routines that Salesforce calls.
  • List<MetadataTypeDeploymentRequest> metadataTypes – A list of methods describing the metadata Comparison Views to deploy. 

The MetadataTypeDeploymentRequest method accepts these parameters:

  • String type – The metadata comparison view to deploy.
  • List<MetadataComponentDeploymentRequest> metadataComponents – A list of methods describing the metadata components to deploy.  

The MetadataComponentDeploymentRequest method accepts these parameters:

  • String componentName – The name of the metadata component to deploy.  

Return Value 

Depending on the parameters you pass in, the DeploymentServiceRequestV1 method returns one of these values:

  • ID – The ID of the result record.
  • List<ID> – A list of result record IDs, one for each destination environment.

Sample Code 

ID deploymentResultId = PDRI.DeploymentServiceRequestV1(deploymentName, deploymentNotes, metadataMethod, dataMethod, sourceID);

API Error Messages 

This table lists errors the API can return.

Error CodeError KeyError Message
209INVALID_DEPLOYMENT_PLAN_IDInvalid deployment plan id <deploymentPlanId> in API request.
210INVALID_DATA_SET_IDInvalid data set id <dataSetId> in API request.
211INVALID_SOURCE_CONNECTIONInvalid source org connection id <sourceConnectionId> in API request.
212INVALID_DESTINATION_CONNECTIONInvalid destination org connection id <destinationConnectionId> in API request.
213TOO_MANY_DESTINATION_ORG_IDSToo many destination orgs. Please limit the number of destination orgs to five per deployment.