Platform SDK

The Platform SDK is a command line tool for developing frontend and backend extensions and themes. The Platform SDK is available for Windows, Mac, and Linux. You can find the source code on GitHub and download releases from npm.

Prerequisites

Before using the Shopgate CONNECT Platform SDK, you should have a basic understanding of the following topics: Extensions, Pipelines, and Steps.

How To Install the Platform SDK

The Shopgate CONNECT Platform SDK is based on Node.js and requires Node.js version 8.4 or later installed on your development machine.

To install the Platform SDK, open a terminal (as a user with permission to install software) and type:

npm install -g @shopgate/platform-sdk

For any installation issues, refer to the npm troubleshooting page.

After installation, the sgconnect command should appear within the terminal that allows you to perform all actions required to develop on the Shopgate CONNECT Platform.

To check the version of the installed SDK, type:

sgconnect --version

Releases

Shopgate releases the Platform SDK in Semantic Versioning style. The latest version of the Platform SDK is mandatory. When you start the Platform SDK, it checks for the latest version. If a newer version is available, you will see an update message.

You can find releases of the Platform SDK on the GitHub releases page.

Use the Platform SDK

The Platform SDK enables you to develop backend extensions, frontend extensions, and themes. You can test all of these application components within a sandbox app. The following sections explains how to develop these components with the Platform SDK.

Log In with Your Account

Before you can use the Platform SDK for developing extensions or themes, you need to authenticate against the Shopgate CONNECT Platform. A Shopgate Developer Account is required.

Log in to the Shopgate CONNECT Platform:

  1. Type sgconnect login.
  2. Enter your Shopgate Developer account username and password.

After initially logging in, a session file is created and stored in your user directory for later Platform SDK requests so you do not have to log in again.

Refer to sgconnect login in the reference documentation for more information.

Initialize a New Project

A new projects is bound to a Sandbox App. You must be a member of the organization which owns the Sandbox App so that you have access rights to the Sandbox App. Access rights are required to initialize a new project.

A project is bound to a Sandbox App, but a Sandbox App is not bound to a project. You can use one Sandbox App for multiple projects. For example, if you create a project for the development of two extensions for application A, you can use the same Sandbox App for the development of extensions or themes for application B, as long as you create a new project folder for application B. The only restriction is that you cannot work on the same Sandbox App with application A and B at the same time.

To initialize a new project:

  1. Create a new folder for a project
  2. Within the project folder, type: sgconnect init
  3. When the command prompts you, enter the Sandbox App associated with the project.

File Structure

Executing sgconnect init will create a project file/folder structure with the following:

File/Folder Description
.sgcloud/ Folder that contains project-related files
attachedExtensions.json File which stores information of all currently attached extensions, see attach extensions
storage.json Storage file for pipelines and extension steps
frontend.json Support file for the frontend process
app.json Storage file for the Sandbox App id associated with the project
extensions/ Folder for extensions
pipelines/trustedPipelines Read-only directory that contains copies of pipelines which are currently available for the Sandbox App. Changes to files in these directories do not affect the execution of pipelines.
themes/ Folder that contains themes such as Shopgate’s GMD or iOS theme

Do not execute this command in your user directory since there is already a .sgcloud/ folder that stores log in data in your user directory.

Re-initializing a Project

If you call the sgconnect init command inside of an initialized project (on any level) the command will cause a project reset. But don’t worry: it will ask if you really want to do this. In case you confirm the reinit, the command will delete all project related files like extension configs and everything in .sgcloud/ and sets the project up just like a fresh project.

Also the command asks you for the Sandbox App you want this project to connect to. This way you can switch the Sandbox App without setting up a new project.

Refer to sgconnect init in the reference documentation for more information.

Create a New Extension

After initializing the project, you can create a new extension.

  1. Type sgconnect extension create.
  2. Enter the extension name and type.

For backend extensions, you also enter whether the extension runs in a trusted environment.

Here are the steps the Platform SDK executes when you create a new extension:

  1. Downloads the Shopgate extension boilerplate from Github into the projects extensions/ directory.
  2. Renames boilerplate to the name you provided (<organization name>-<extension name> like: @shopgate-user).
  3. Removes unused dirs and files (frontend-related items if only backend was selected as type and vice versa).
    1. removed frontend items:
      • directory: frontend/
    2. removed backend items:
      • directory: extension/
      • directory: pipelines/
  4. Removes placeholders and updates files according to your changes. For example, the Platform SDK updates the organization name and the extension name. All occurences of @awesomeOrganization/awesomeExtensions will be named <organization name>/<extension name>.
  5. Installs dependencies necessary for frontend development for all frontend extensions.

Refer to sgconnect extension create in the reference documentation for more information.

Attach / Detach an Extension

Attaching

Attaching an extension will mark the extension as active or in use for the Platform SDK. The backend- and frontend process require these designations.

An active or in use mark for backend extensions means steps of attached extensions are being redirected to your local SDK. For frontend extensions this mark means components of attached extensions are getting inserted into the installed theme.

To attach all extensions in the extensions folder, type:

sgconnect extension attach

To attach specific extensions, type:

sgconnect extension attach extensionsId1 extensionsId2 ...

Refer to sgconnect extension attach in the reference documentation for more information.

Detaching

Detaching causes the extension to be “inactive” or “disabled”. Just as the attach command, the detach command can be used to detach all extensions or only specific ones.

To detach all extensions in the extension folder, type:

sgconnect extension detach 

To detach specific extensions, type:

sgconnect extension detach extensionsId1 extensionsId2 ...

Refer to sgconnect extension detach in the reference documentation for more information.

When detaching a potential broken extension, you can restore the Sandbox App to its previous state. Restoring the Sandbox help enables you to test if there is an error within the former attached extension. For extensions that were only attached and not installed on your Sandbox App, the extension’s pipelines, steps, and any frontend components will not be available after detaching.

Refer to pipeline requestsfor testing for more information.

Backend Extension Development

You start the backend process to develop your backend extensions and test them on your Sandbox App. Starting the backend process connects your current project with your Sandbox App within the Shopgate CONNECT Platform.

CAUTION

You must attach any extension you want to test before you start the backend process. If you attach extensions while the process is running, those extensions will not connect with your Sandbox App. You must restart the backend process to connect them.

To start the backend process, type:

sgconnect backend start

When you enter this command, the backend process completes the following actions:

  1. Resets the Sandbox App on the Shopgate CONNECT Platform. Resetting provides a clean state of the application. Former attached extensions will get detached and uploaded pipelines which were in development will be removed. Overwritten pipelines will get restored. Note that these actions only occur in your Sandbox App. Your local project stays untouched.
  2. Uploads the pipelines of all attached extensions.
  3. Connects all attached extensions to your Sandbox App. If a step of these extensions gets called within a pipeline, the step gets executed on your local machine.
  4. Copies currently used pipelines of your Sandbox App into the general pipelines/trustedPipelines folders. You can view this folder to see the current state of your Sandbox App.
  5. Creates a proxy server on port 8090 on your local machine. You can use the proxy server to send direct pipeline calls to it.

Refer to sgconnect backend start in the reference documentation for more information.

Developing Pipelines

You can develop pipelines in two ways:

  • Create a new pipeline within the pipelines folder of your attached extension, OR
  • Copy an existing pipeline from your general/trusted pipelines folders into the pipelines folder of your attached extension. Copying an existing pipeline will overwrite the pipeline that is currently used by the Sandbox App with the one you copied.

Every time you alter a pipeline in extensions/<attachedExtension>/pipelines, the SDK validates and uploads it to your Sandbox App. If the validation and upload are successful, the pipeline is ready for use. If the validation and upload are not successful, the SDK displays an error message such as the following message:

6/25/2018, 4:56:04 PM ERROR: Pipeline invalid: Missing required property: steps (field=body.pipeline)

After uploading the pipeline is downloaded again into your your general/trusted pipelines folders to indicate it is in use by the Sandbox App.

Developing Steps

Steps of attached extensions are executed on your local machine. The following graphic displays the execution of a pipeline which uses local steps. Extension A is unattached (deployed) while Extension B is attached via the SDK.

When a step gets executed locally such as by calling a pipeline which uses the step, you can print logs directly to your console. Therefore you have to use the logger provided by the step context. The logger is aware of the step that logs the data. For example, a debug log like the following:

context.log.debug(responseBody, `Got ${type} status`)

would look like this:

15/03/2018, 11:43:36 DEBUG: [@shopgate/testExtension/testStep.js]: { status: 'OK' } Got request status

See logger reference.

Debugging Step Code

You can also use a debugger to debug steps by running the SDK with the inspect flag (--inspect). The debugger is currently supported for VS Code and Php- / Webstorm.

VS Code

To use the debugger in VS Code, you alter the .vscode/launch.json file in your project directory. Add the following launch configuration to the file:

{
  "type": "node",
  "request": "attach",
  "name": "Attach to remote process (Platform SDK)",
  "address": "localhost",
  "port": 9229,
  “localRoot": "${workspaceFolder}",
  "remoteRoot": "${workspaceFolder}",
  "restart": true
}

The screenshot shows a launch.json file with the launch configuration added (only one launch configuration):

After you altered the file, you can start the backend process with the inspection flag by typing:

sgconnect backend start --inspect

The following log should appear during start:

Debugger listening on ws://127.0.0.1:9229/4157ea69-993d-4f9f-9722-2d4d10fe4db6
For help see https://nodejs.org/en/docs/inspector

While the process is running, you can start the debugger of VS Code by pressing the debugger play button with the configuration “Attach to remote process (Platform SDK)” selected.

The console then shows the following message:

Debugger attached.

Set breakpoints in step code will now be inspectable and pause the execution.

Php- / Webstorm

To use the debugger in PHPStorm, you add a new run configuration by selecting the plus sign.

  1. Select the Node.js preset for the configuration.
  2. Configure the settings of the Node.js preset with the following:
    • working directory: leave the default
    • javascript file: enter the absolute path to the sgconnect executable
    • Parameters: enter backend start --inspect
  3. Save the run configuration.
  4. Select the bug button to start the debug mode.

Besides the default console logs of the backend process, your terminal also displays a message indicating the debugger is running:

Debugger listening on ws://127.0.0.1:9229/4157ea69-993d-4f9f-9722-2d4d10fe4db6
For help see https://nodejs.org/en/docs/inspector

Set breakpoints in step code will now be inspectable and pause the execution.

Using the Proxy Server

The purpose of the proxy server is to simplify pipeline calls to the Sandbox App. Follow these guidelines for calling a pipeline:

  • Use http://localhost:8090/pipelines/<pipelineName> for regular pipelines and http://localhost:8090/trustedPipelines/<pipelineName> for trusted pipelines
  • Send an HTTP POST request with the content-type: application/json
  • Send the input of the pipeline as a JSON object. If the pipeline does not require any input, send an empty JSON object.
  • If a local step takes longer than eight seconds, it will time out. If the pipeline request itself takes longer than 20 seconds, it will also time out.

Theme / Frontend Extension Development

To develop and test frontend extensions, the Platform SDK enables you to run the frontend locally. The served frontend watches for changes in your code and updates the view seamlessly.

Set Up the Frontend

Typically the frontend start command implicitly starts the set up. However, you can manually execute the set up. For example, you can re-execute the step if your ip changes.

To set up the frontend:

  1. Type sgconnect frontend setup.
  2. Check your local ip address is displayed correctly or type in the correct ip.
  3. Enter the port where the local frontend gets served (webpack-dev-server).
  4. Enter the port for the Shopgate CONNECT API proxy. The locally running frontend will request data on this port. The proxy will translate the requests to this port to requests that a real app would do.
  5. Review the default settings for the following items:
    1. Hot Module Replacement port: Hot Module Replacement (HMR) exchanges, adds, or removes modules while an application is running, without a full reload. Refer to Webpack hot module replacement for more information.
    2. Remote dev server port: Port of bridge for communicating remotely via Redux DevTools extension, Remote Redux DevTools, or RemoteDev.
    3. Source map type: Describes the kind of source maps. Refer to Webpack devTool for more information.

Start the Local Frontend Server

To start the local for frontend server, type:

sgconnect frontend start

This command starts everything according to your set up. The start command uses an installed theme by default. If you have multiple themes installed, the command prompts you to select one.

During start, it will do the following:

  • Create the app.json file from the extension-config.json
  • Start a proxy server to call the Shopgate CONNECT service
  • Start the webpack development server which compiles the frontend and also recompiles on file changes

When requesting http://<local ip address>:<port you entered during setup> (e.g. http://localhost:8080) the selected theme should be displayed in your browser.

Automations

There are several automations that you have to be aware of when using the SDK.

When the extension-config.json file changes, certain files that depend on the extension-config.json file are recreated.

file when what
extension/config.json (of current extension) backend-, frontend process: on start; current extension-config.json file was altered frontend / backend configs get resolved
config/components.json (of all themes) frontend process: on start, any extension-config.json file was altered components are gathered and updated in the components.json files

Also pipelines in extensions/<extension>/pipelines are watched. When a pipeline of an attached extension is altered, it gets uploaded to the Sandbox App. If the pipeline was successfully uploaded, it gets downloaded to the projects (trusted)pipelines folder, which indicates the pipeline is in use by the Sandbox App.