Connect Application Starter Template for Developer Training

Connector Overview

This connector includes three applications: customer-number-generator-app, email-verification-sender-app, and email-verification-receiver-app. Below is an overview and the configuration options for each app.

Applications

1. Customer Number Generator App

Type: Service App
Function: Assigns a unique customer number when a new customer account is created. It includes an API Extension.

2. Email Verification Sender App

Type: Event App
Function: Generates a new verification token after the customer account is created. It uses a Subscription to get notified.

3. Email Verification Receiver App

Type: Service App
Function: Verifies the token after the customer opens a link embedded in an email containing the verification token.

Configuration Options

1. Customer Number Generator App

The following environment variables are required for configuration:

CTP_REGION
CTP_PROJECT_KEY
CTP_CLIENT_ID
CTP_CLIENT_SECRET
CTP_SCOPES

2. Email Verification Sender App

CTP_REGION
CTP_PROJECT_KEY
CTP_CLIENT_ID
CTP_CLIENT_SECRET
CTP_SCOPES

3. Email Verification Receiver App

CTP_REGION
CTP_PROJECT_KEY
CTP_CLIENT_ID
CTP_CLIENT_SECRET
CTP_SCOPES

Getting Started

Make sure you have the copy of the source code on your local machine. Use GitHub to fork the project to your account. While creating the fork, ensure the repo is public. Otherwise you need to allow the connect-mu to access your repo. Then clone the repo onto your machine. There should be a folder created on your machine now. Go into that folder, it should contain 3 application folders.

Developing the first application: customer-number-generator-app

1. cd into customer-number-generator-app and install the dependencies

cd customer-number-generator-app
yarn

2. Implement missing part in the src/controllers.customers.controller.ts to set the customer number to a randomly generated unique value.

Add the following code to create function

// Create the UpdateActions Object to return it to the client
const updateAction: UpdateAction = {
  action: "setCustomerNumber",
  // generate a number between 1000 and 1899
  customerNumber: String(Math.floor(1000 + Math.random() * 900)),
};

updateActions.push(updateAction);

3. Build the application

yarn build

4. Configure the .env file

Before we can run this application locally we need client credentials in the .env file. Therefore first rename .env.example file to .env

mv .env.example .env

Create an API Client in Merchant Center for your Composable Commerce project under Settings->Developer Settings section. This can be an admin client, i.e has all the permissions.

Copy those values into your .env file. So at the end, your .env file should have the following environment variables set.

CTP_CLIENT_ID=
CTP_CLIENT_SECRET=
CTP_PROJECT_KEY=
CTP_SCOPES=
CTP_REGION=europe-west1.gcp

5. Run the application

Now, run the application

yarn start:dev

6. Test using the Postman Collection

To test this application locally, use the Postman collection provided.

7. Stop the application

Since every application is running on port 8080, we should stop this server before we can test the others. So please stop the server from the command line by pressing CTRL + C.

Developing the second application: email-verification-sender-app

1. cd into email-verification-sender-app and install the dependencies

cd email-verification-sender-app
yarn

2. Build the application

yarn build

3. Configure the .env file

Before we can run this application locally we need client credentials in the .env file. Therefore first rename .env.example file to .env

mv .env.example .env

You can reuse the client credentials from the previous step. Copy those values into your .env file. So at the end, your .env file should have the following environment variables set.

CTP_CLIENT_ID=
CTP_CLIENT_SECRET=
CTP_PROJECT_KEY=
CTP_SCOPES=
CTP_REGION=europe-west1.gcp

4. Run the application

Now, run the application

yarn start:dev

5. Test using the Postman Collection

To test this application locally, use the Postman collection provided. When testing this application, there will be a token generated and logged to the console. Please copy this token value for later use.

6. Stop the application

Since every application is running on port 8080, we should stop this server before we can test the others. So please stop the server from the command line by pressing CTRL + C.

Developing the third application: email-verification-receiver-app

1. cd into email-verification-receiver-app and install the dependencies

cd email-verification-receiver-app
yarn

2. Build the application

yarn build

3. Configure the .env file

Before we can run this application locally we need client credentials in the .env file. Therefore first rename .env.example file to .env

mv .env.example .env

You can reuse the client credentials from the previous step. Copy those values into your .env file. So at the end, your .env file should have the following environment variables set.

CTP_CLIENT_ID=
CTP_CLIENT_SECRET=
CTP_PROJECT_KEY=
CTP_SCOPES=
CTP_REGION=europe-west1.gcp

4. Run the application

Now, run the application

yarn start:dev

5. Test using the Postman Collection

To test this application locally, use the Postman collection provided. When testing this application, paste the token value you copied in an earlier step into Postman script.

6. Stop the application

Since every application is running on port 8080, we should stop this server before we can test the others. So please stop the server from the command line by pressing CTRL + C.

Deployment

Now that you have locally tested your connect applications successfully, it is time to deploy them onto your Composable Commerce project. For that please commit your changes and push them to your GitHub repo.

Once you have updated the GitHub repo for your project, create a release tag such as v0.0.1 and provide the following values in the Postman Collection Variables section before using the Postman collection to deploy your connector.

Variable Name	Current Value
connector-name	<a name containing your initials>
connector-staged-key	<unique key for your connector>
repo-url	HTTPS or SSH GitHub URL of the GitHub repository
repo-tag	v0.0.1
creator-email	<your email address>
deployement-key	<unique key for your deployment>

Clean Up

Once you have tested your installation, it is time to undeploy the installation. Please run the scripts in the Clean Up section of your Postman Collection.