Getting Started

Getting Started with SFCC Web Service Library

This section will guide you through the installation and initial setup of the SFCC Web Service Library. By following these steps, you'll be able to integrate the library into your Salesforce Commerce Cloud project and start utilizing its powerful features.

Installation

1. Clone or Download the Repository

Begin by cloning the repository or downloading the ZIP file to your local machine.

git clone https://github.com/dkatashev/sfcc-web-services.git

Alternatively, you can download the ZIP file directly from the GitHub repository releases and extract it to your project directory.

2. Integrate into Your Project

Add the lib_webservice cartridge folder to your project's source code.

1. Copy the Cartridge:

   • Navigate to the cartridges/lib_webservice/ directory in the cloned repository.
   • Copy the entire lib_webservice folder to your Salesforce Commerce Cloud project.

2. Include in Cartridge Path:

   • Go to the Business Manager in your SFCC instance.

   • Navigate to Administration > Sites > Manage Sites > [Your Site] > Settings.

   • Update the cartridge path to include lib_webservice (this framework has no dependencies and can be placed at the end):

     your_existing_path:lib_webservice
     

   • Why Last?: By placing lib_webservice at the end of your cartridge path, you ensure that it doesn’t override any of your project’s custom code, unless explicitly intended.

3. Deploy to SFCC Instance

Deploy the lib_webservice cartridge to your SFCC instance:

1. Using WebDAV:

   • Upload the lib_webservice cartridge to the {version} directory on your SFCC instance via WebDAV.

2. Using Business Manager:

   • Go to Administration > Site Development > Code Deployment in Business Manager.
   • Upload the cartridge ZIP file through the Business Manager interface.

3. Using IDE:

   • Use your IDE’s deployment tools to upload the cartridge directly to your sandbox instance.

4. Verify Installation

To ensure that the installation was successful:

• Test the Setup:
  • Run a basic service to confirm that the library is functioning as expected. You can use the provided "Hello World" example to verify the integration.

---

Example: Hello World

Here’s a quick example to verify that everything is set up correctly.

Step 1: Create a Simple Service Script

Create a new script in your project:

// cartridges/app_custom/cartridge/scripts/services/HelloWorldService.js

var RestService = require('*/cartridge/scripts/webservice/RestService');

var HelloWorldService = RestService.extend({
    SERVICE_CONFIGURATIONS: {
        default: 'example.rest',
    },
});

module.exports = HelloWorldService;

Step 2: Configure the Service in Business Manager

1. Navigate to Administration > Operations > Services.
2. Create a new service profile named example.rest.profile.
3. Set up a new service credential called example.rest.credentials:
   • Enter the service URL to a valid endpoint for testing, such as https://jsonplaceholder.typicode.com/posts.
   • Configure any required authentication settings as needed.
4. Finally, create a new service named example.rest, and assign the previously created profile and credential to this service.

Step 3: Execute the Service

Add a controller or job to execute the service and log the output:

// cartridges/app_custom/cartridge/controllers/HelloWorld.js

var server = require('server');

server.get('Show', function(req, res, next) {
    var HelloWorldService = require('*/cartridge/scripts/HelloWorldService');
    var result = HelloWorldService.fetch({
        method: 'GET',
    });

    res.json({ result: result.object });
    next();
});

module.exports = server.exports();

Navigate to https://[your-site]/HelloWorld-Show to see the output from the service.

---

Next Steps

Now that you've successfully installed and verified the SFCC Web Service Library, you can explore the following sections to learn more:

1. Architecture Overview: Understand the core components and structure of the library.
2. Usage: Detailed documentation on using the library with different web services (REST, SOAP, SFTP, WebDAV, Email).
3. Contributing: Learn how you can contribute to the project.