Skip to main content

Create a Web Service

Learning Objectives

After completing this unit, you’ll be able to:

  • List the steps you can take to create a new web service.
  • Describe B2C Commerce Web Service framework best practices (timeout, circuit breaker, rate limit).
  • List the Business Manager configurations you must create for each web service.
  • Explain why web service names are important.
  • Explain the purpose of the service type.

Create a New Web Service

You learned about the Salesforce B2C Commerce Web Services framework in the previous unit. Now it’s time to learn about web services and how to create them.

You can take these steps to create a new web service for B2C Commerce third-party integrations.

Step

Task

1

Configure a web service in Business Manager.

2

Code a web service.

3

Set up logging and troubleshoot a web service.

4

Get it ready to go live.

Configure a Web Service

To integrate a third-party application via a web service, specify these credentials and web service profiles in Business Manager.

Configuration

Description

Web service

Specifies the credentials and web service profile that B2C Commerce uses when calling a web service. It generates a ServiceConfig object.

Web service credential

Is used for basic authentication.

Web service profile

Determines how B2C Commerce manages timeouts and rate limits for the web service. It defines how B2C Commerce detects and manages high numbers of requests to and responses from the service, as well as its availability. Different services with similar requirements can all use the same service profile.

When you configure a web service, you must create the credentials and profiles first. Then create the web service.

Names Are Important

When naming a service, it’s important to use an identifiable pattern, such as this: cartridge.protocol.service.operation

Here are some examples.

  • mycartridge.http.payment.get
  • mycartridge.ftp.partner.getPriceList

When service names contain periods, the period-delimited name segments become part of the logging hierarchy. Always include the cartridge in the name. This helps when you have multiple web service integrations, because it groups logging information and ensures unique service names.

You also need to take care when naming the prefix for the log file for your service. All logs are written in the shared log directory to a file named service-prefix-internalID-date.log.

If you don’t enter a prefix, the prefix name defaults to main, and the file is named service-main-serviceID-date.

Note

These are examples. You can use your own naming convention.

Create Web Service Credentials

To access Business Manager, you must have a B2C Commerce implementation. In this module, we assume you have the proper permissions to perform these tasks. If you don’t, that’s OK. Read along to learn how you would take these steps in a staging instance. Don't try to follow our steps in your Trailhead Playground. B2C Commerce isn't available in the Trailhead Playground. If you have a staging instance of B2C Commerce, you can try out these steps in your instance. If you don't have a staging instance, ask the site administrator if there is one that you can use.

B2C Commerce uses web service credentials for basic authentication. Here’s how to specify credentials.

  1. Open Business Manager.
  2. Select Administration > Operations > Services.
  3. Click the Credentials tab.
  4. Click New.
    Create new service credentials in Business Manager.
  5. Enter a name for the credential: test.mycartridge.http.partnerDon’t include spaces or user/password details.
  6. Enter the URL to the service, including the protocol. For example: http://51.134.145.10To use one service configuration for several URIs, you can extend or alter the URL using getURL callback in the service registry definition.
  7. Enter the username for the credential: s-architect
  8. Enter the password: StringliGhtd1The password is masked after you type it and can't be retrieved from Business Manager. Store the value securely elsewhere.
  9. Click Apply.
Note

You can skip the operation part of the service name. This lets you use the same credential for multiple operations that are executed through the same service.

Configure a Web Service Profile

The web service profile defines how B2C Commerce detects and manages high numbers of requests to and responses from the service and its availability. Different services with similar requirements can use the same service profile. The following Business Manager web service profile settings are considered Web Services framework best practices.

Timeout

Specify the timeout in milliseconds. This value is used for both the connection and socket timeout of any internal connection. If B2C Commerce receives no response within this time, it throws an error.

The total run time of a service can be longer than the timeout, as long as individual responses don't exceed it. For example, consider a 5000-ms timeout. A 4-second connection attempt, followed by reading two chunks of data at 4 seconds apiece, takes about 13 seconds total. Because none of the individual communications exceeded 5 seconds, the process does not time out.

Service Type

When you create a web service configuration in Business Manager, you must select a service type. The service type determines the underlying class used to call your web service and adds methods to those inherited from the Service class.

Type

Class

HTTP

dw.net.HTTPClient

HTTP Form

dw.net.HTTPClient

FTP

dw.net.FTPClient

SFTP

dw.net.SFTPClient

SOAP

dw.ws.webReference2

Generic

Does not wrap any class.

Circuit Breaker

Circuit breakers provide an extra level of protection on top of the default behavior. They identify when a service is unavailable and stop making calls to the web service. The best practice is to enable the circuit breaker and configure it according to the service call rate. Here’s what you can specify in Business Manager.

  • The number of calls that must fail to trigger the circuit breaker. You must also set a value for the Circuit Breaker Interval (ms). Otherwise, leave both fields empty.
  • The number of milliseconds in which the maximum number of calls can fail. You must also set a value for the Max Circuit Breaker Calls field. Otherwise, leave both fields empty.

Rate Limit

This setting limits the number of outgoing calls within a specific interval. You can specify:

  • The maximum number of calls that B2C Commerce makes for the interval.
  • The number of milliseconds in which B2C Commerce can make the maximum number of calls to the web service.

Configure a Profile

Here’s how to configure a web service profile.

  1. Open Business Manager.
  2. Select Administration > Operations > Services.
  3. Click the Profiles tab.
  4. Click New.
    Create new service profile in Business Manager.
  5. Enter the profile name: synchronous.storefront.profile
  6. Enter the number of milliseconds for the client connection timeout: 1,000
  7. Select Enable Circuit Breaker and enter the number of calls that must fail to trigger the circuit breaker.
  8. Select Enable Rate Limit and enter the maximum number of calls that B2C Commerce makes for the rate limit interval.

Create a Web Service

Here’s how to configure a web service.

  1. Open Business Manager.
  2. Select Administration > Operations > Services.
  3. Click New.
    Create a new service in Business Manager.
  4. Enter a name for the service using the naming pattern: mycartridge.http.payment.get
  5. Select the service type: HTTP
    The type determines the underlying class used to call the web service and adds methods to the methods inherited from the service class.
  6. Select Enabled if the web service is available and you want to make calls to it. It isn't enabled by default.
  7. In the Service Mode list, select one:
    • Select Live to make calls to a live web service.
    • Select Mocked to use the mocked call configured in your service registry to simulate the expected response from the web service.
  1. Enter a prefix for the log file for this service: paymentThis must be at least 3 characters long.
  2. Select Communication Log Enabled to log the data in the request and response of the web service call. If you select this, Salesforce strongly recommends using the log filtering callback methods to remove private or sensitive data from the log messages.
  3. Select Force PRD behavior in non-production environments to prevent unfiltered communication logs from being written on non-production instances.
    • If you enable this on a non-production instance, communication logs are disallowed unless you configure a filter.
    • If you disable this on a non-production instance, communication logs are allowed regardless of whether a filter is configured.
    • This setting has no effect on production instances.
  1. Select a service profile: profile-123
  2. Select a service credential: credential-123

Next Steps

In this module, you learned how to configure a web service in Business Manager. Next, learn how to code and customize a web service for a B2C Commerce integration.

Resources

Partagez vos commentaires sur Trailhead dans l'aide Salesforce.

Nous aimerions connaître votre expérience avec Trailhead. Vous pouvez désormais accéder au nouveau formulaire de commentaires à tout moment depuis le site d'aide Salesforce.

En savoir plus Continuer à partager vos commentaires