Salesforce and Application Integration > Customizing Salesforce > Implementing Service Steps and Search Services

Implementing Service Steps and Search Services

This topic describes how to create service steps and search services from Salesforce Apex classes.

Note: You can download an archive file that contains a sample automated step and a sample search service.

Creating an Apex-based Service Call Step

You can create new Service Call step services using an Apex Class that implements the IAeAutomatedStepService interface.

IAeAutomatedStepService Interface

To create the new services, you first implement two interface methods:

•describe()
•invoke()

describe(): Returns AeServiceDescription, which contains metadata for services.xml.

invoke(): Invoked at runtime.

For example:

global class icrtStep_EchoService implements
IAeAutomatedStepService {
global AeServiceDescription describe() {
// called during synchronization
}

global AeServiceResponse
invoke(AeServiceRequest aRequest) {
// called at runtime
}
}

Service Discovery with Apex Automated Steps

When you synchronize your Salesforce organization, Apex services are discovered based on their class name. If a class name starts with "icrtStep", it is recognized as a Service step (an "Apex automated step"). For example, the Apex class named "icrtStep_EchoService" is a service.

Process objects or object lists are serialized to a JSON payload format, similar to the process object input or output in other processes. They are sent to Apex where the System.JSON class in Apex can parse the JSON.

To return a process object, define the outputs as either 'reference' or 'objectlist' and serialize the objects to JSON so Process Designer converts them back to a process object.

For example, for output parameters:

global AeServiceDescription.AeServiceParameterDesc
output = sDescription.addOutputParameterDesc('objOutput', 'reference');
output.addParameterOption('referenceTo','Account');

Service Interface

Apex services must implement two methods:

•describe()
•invoke()

describe(): Provides information discovered for use by the cloud service.; Returns an instance of AeServiceDescription, which has the following fields:

Field	Description
serviceType	Type of service , either a service step or a search.
namespaceQualifier	Organization-specific namespace.
name	Service class name.
displayName	Name displayed to the user.
description	Text describing the service.
inputParameter (0..n)	List of input parameter descriptions. (AeServiceDescription.AeParameterDesc)
outputParameter (0..n)	List of output parameter descriptions. (AeServiceDescription.AeParameterDesc)

invoke(): Implements the runtime behavior of the service.; Takes an instance of AeServiceRequest as input.; Returns AeServiceResponse, which has the following fields:

Parameter	Description
objectId	ID of the Applies To object from the host's context.
objectType	Type of the Applies To object from the host's context.
parameter (0..n)	List of AeServiceParameter name/value pairs.

Field	Description
parameter (0..n)	List of AeServiceParameter name/value pairs.
errorInfo.AeErrorInfo	Conveys error information. Use this to relay error information instead of throwing an uncaught fault within your service
errorInfo.errorMessage	Error message.
errorInfo.invalidData	Field-level error details.

Custom Search Services

You can implement search services as Apex classes. Search services use the same interface and discovery mechanisms as step services, with the following differences:

•Set the service type to search in AeServiceDescription:

AeServiceDescription.serviceType = 'search';

•There should be one output parameter, Search Results, that returns the data.
•To return a valuelist, the invoke() method should return name/value pairs representing the name/id of the objects returned.

The following example returns a valuelist of account references filtered by OwnerId:

List<Account> accountList =
[SELECT Name, id FROM Account WHERE OwnerId =:userRef LIMIT 20];
for (Account account: accountList)
{
// For a search service, return name/id as parameters
response.addParameter(account.Name, account.Id);
}

Republish the Salesforce Connection

To make custom automated step and search services visible, you need to republish the Salesforce connection from Application Integration.

Note: You need to republish the Salesforce connection only when you make a change to the class interface, not when you make a change to the class.