Lab - Postman Registration/Login Workflow

Introduction

In this lab, you’ll create a workflow in Postman to simulate the common storefront tasks of registering a company and logging in.

This will include building in automation to capture and re-use values from API responses, much in the same way that the storefront application would track a user’s session.

Prerequisites

• A BigCommerce sandbox store or trial store, or a full production store
• B2B Edition enabled in your store
• Postman or a similar API client

In this lab, you will:

• Create API requests to handle customer registration and login
• Implement Postman scripts to automate values used in API requests

Step 1: Configure a Postman Environment and Collection

1. Log in to your BigCommerce store control panel and recordthe store hash for your BigCommerce store. You can find this in the URL of your control panel, which is in the format https://store-{store hash}.mybigcommerce.com.
2. Create a new Postman environment with the following variables. (Be sure to save the environment after adding the variables.)

3. Create a new collection and give it an appropriate name, such as “B2B GraphQL.”
4. Select your new environment from the environment drop-down at the top of the Postman interface.

The correct value must be selected from the environment drop-down whenever you send a request, in order to ensure the appropriate variables are used.

Step 2: Register a Company

Registering a brand new company account is a two-step process, as a BigCommerce customer must first be registered with the standard BigCommerce GraphQL API, and the company can then be created with the B2B GraphQL API. (These two steps are performed together in the default Buyer Portal registration.)

Your first step, therefore, will be the customer registration request. This will be the only request in these labs to use the BigCommerce GraphQL API.

This request will require several fields, but two that will be reused in future requests (such as the Login request) are the email address and password of the Admin user you intend to register. That being the case, let’s once again make use of Postman variables to reduce duplicate copy/pasting and potential mismatched values.

For these values, you’ll use collection variables. These are similar to environment variables and referenced in the same way. We’ve used an environment variable for connection information that would be common to any requests being sent to a specific environment, while we’re using collection variables for values relevant only to the workflow in this collection.

1. Open the collection and navigate to the Variables tab.
2. Add the following variables.

3. Save the collection. (Note that the “initial value” set for any new variable will automatically be set as the “current value” as well.)
4. Create a new HTTP request and save it to your collection with the name “Create Customer.”
5. Configure the request with the following details.

These details will be identical for all B2B GraphQL Storefront API requests.

6. In the Headers tab, use the Presets drop-down to Manage Presets, then add a header preset with the following values, saving it with a name like “BC REST.”

7. Select your newly created header preset to populate headers.
8. In the Authorization tab, set Auth Type to “No Auth.”

Recall that all B2B GraphQL requests are either anonymous, requiring no authentication token, or are authenticated with a token obtained from customer login. You’ll be setting the proper authorization config on the collection itself after you’ve configured the login workflow, which all requests will inherit by default. For any requests that are anonymous, like this customer registration request, you must explicitly configure authorization not to inherit from the collection.

9. In the Body tab, enter the following query.

mutation CreateCustomer(
    $storeHash: String!,
    $email: String!,
    $password: String,
    $firstName: String!,
    $lastName: String!,
    $phone: String,
    $channelId: Int
) {
    customerCreate(
        customerData: {
            storeHash: $storeHash,
            email: $email,
            firstName: $firstName,
            lastName: $lastName,
            phone: $phone,
            originChannelId: $channelId,
            channelIds: [$channelId],
            authentication: {
                forcePasswordReset: false,
                newPassword: $password
            }
        }
    ) {
        customer {
            id
            email
        }
    }
}

10. Enter the following in the GraphQL Variables panel.

{
    "storeHash": "{{store_hash}}",
    "email": "{{admin_email}}",
    "password": "{{admin_password}}",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "111-222-3333",
    "channelId": {{storefront_channel_id}}
}

Feel free to change the customer details.

11. In the Scripts tab, enter the following “Post-response” code.

pm.test('Response is not an error', () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test('Response is JSON with data', () => {
    pm.response.to.have.jsonBody("data");
});
const customer = pm.response.json().data?.customerCreate?.customer;
pm.test('Response includes a customer ID', () => {
    pm.expect(
        customer?.id
    ).to.be.a('number');
});
pm.collectionVariables.unset('admin_customer_id');
pm.collectionVariables.set('admin_customer_id', customer?.id);

In addition to tests, this script also captures the ID of the newly created customer in the collection variable admin_customer_id for use in the next request.

12. Send the request and verify that all tests succeed. You should see the details of your newly created customer in the response. Verify that the admin_customer_id variable has been set on your collection.

Now that your new Admin customer has been created, you’re ready to register a company.

13. Create a new HTTP request and save it to your collection with the name “Create Company.”

14. Set the same configuration that was used for the previous request, including the HTTP method, URL, Headers (using your previously created “GraphQL” preset), and Body type.

15. In the Authorization tab, set Auth Type to “No Auth.”

16. Enter the following query in the Body tab.

mutation CreateCompany(
    $storeHash: String!,
    $customerId: String!,
    $companyName: String!,
    $companyEmail: String,
    $addressLine1: String!,
    $city: String!,
    $country: String!,
    $state: String!,
    $zipCode: String!
) {
    companyCreate(
        companyData: {
            storeHash: $storeHash,
            customerId: $customerId,
            companyName: $companyName,
            companyEmail: $companyEmail,
            addressLine1: $addressLine1,
            city: $city,
            country: $country,
            state: $state,
            zipCode: $zipCode
        }
    ) {
        company {
            id
            companyName
        }
    }
}

17. Enter the following in the GraphQL Variables panel.

{
    "storeHash": "{{store_hash}}",
    "customerId": "{{admin_customer_id}}",
    "companyName": "John's Widgets",
    "companyEmail": "johndoe@example.com",
    "addressLine1": "987 Park Central East",
    "city": "Austin",
    "country": "United States",
    "state": "Texas",
    "zipCode": "78726"
}

18. In the Scripts tab, enter the following “Post-response” code.

pm.test('Response is not an error', () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test('Response is JSON with data', () => {
    pm.response.to.have.jsonBody("data");
});
const company = pm.response.json().data?.companyCreate?.company;
pm.test('Response includes a company ID', () => {
    pm.expect(
        company?.id
    ).to.be.a('string');
});

19. Send the request and verify that all tests succeed.

With the full company registration process complete, you should be able to observe the new company, with its assigned Admin user and initial address, in the B2B Edition section of your control panel.

Note that the company is in the “Pending” status, exactly as you’d expect with a company registered from the storefront context.

20. In the B2B Edition admin, select your new company and approve it.

Step 3: Log In as a Company User

Your next request will simulate a front-end user’s login, using the credentials you initially set up in collection variables.

1. Create a new HTTP request and save it to your collection with the name “Admin Login.”
2. Set the same configuration that was used for the previous request, including the HTTP method, URL, Headers (using your previously created “GraphQL” preset), and Body type.
3. In the Authorization tab, set Auth Type to “No Auth.”
4. Enter the following query.

mutation LogIn(
    $storeHash: String!,
    $email: String!,
    $password: String!
) {
    login(
        loginData: {
            storeHash: $storeHash,
            email: $email,
            password: $password
        }
    ) {
        result {
            token
            user {
                id
                bcId
                firstName
                lastName
                email
            }
        }
    }
}

5. Enter the following in the GraphQL Variables panel.

{
    "storeHash": "{{store_hash}}",
    "email": "{{admin_email}}",
    "password": "{{admin_password}}"
}

6. In the Scripts tab, enter the following “Post-response” code.

pm.test('Response is not an error', () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test('Response is JSON with data', () => {
    pm.response.to.have.jsonBody("data");
});
const result = pm.response.json().data?.login?.result;
pm.test('Response includes a token', () => {
    pm.expect(
        result?.token
    ).to.be.a('string');
});
pm.test('Response includes a user ID', () => {
    pm.expect(
        result?.user?.id
    ).to.be.a('string');
});
pm.test('Response includes a BC customer ID', () => {
    pm.expect(
        result?.user?.bcId
    ).to.be.a('number');
});
pm.test('Response includes a user email', () => {
    pm.expect(
        result?.user?.email
    ).to.be.a('string');
});
pm.environment.unset('b2b_storefront_token');
pm.environment.unset('b2b_logged_in_email');
pm.environment.unset('b2b_logged_in_id');
pm.environment.unset('bc_logged_in_id');
pm.environment.set('b2b_storefront_token', result?.token);
pm.environment.set('b2b_logged_in_email', result?.user?.email);
pm.environment.set('b2b_logged_in_id', parseInt(result?.user?.id));
pm.environment.set('bc_logged_in_id', result?.user?.bcId);

There are a number of values that need to be captured from the login response, and this script tests for each of them before storing them. In this case, you’re using environment variables to store these details for the “currently logged-in” user, simulating the way a front-end application might track a user’s session. You’ll create a separate user with a different role later and will be able to execute a login as either, making it appropriate to store the current “logged-in” email address separately from your admin_email variable.

• The token in the response is the main authentication credential you will need for most requests.
• Both the user’s email and B2B id will be required for certain requests.
• In rarer cases, the user’s bcId - the ID of the BigCommerce customer - will be needed.

7. Send the request, verify that all tests succeed, and verify that all four variables are set on your environment.

Finally, you’ll now configure the default Authorization configuration on your collection, ensuring that the captured GraphQL token will be used for other requests.

8. Open your collection and navigate to the Authorization tab.
9. Set”Bearer Token” as the Auth Type and the following value as the Token. (Don’t forget to save the collection.)

{{b2b_storefront_token}}

Step 4: Fetch User Company Info

In your final request, you’ll use the userCompany query to fetch basic company information for the user matching the Bearer token. This request will use a new environment variable to track the company ID of the latest authenticated user, similar to the variables from the login request.

1. Create a new HTTP request and save it to your collection with the name “User Company.”
2. Set the same configuration that was used for the previous requests, including the HTTP method, URL, Headers (using your previously created “GraphQL” preset), and Body type.
3. In the Authorization tab, verify that Auth Type is set to “Inherit auth from parent.”
4. Enter the following query.

query GetUserCompany(
    $userId: Int!
) {
    userCompany(
        userId: $userId
    ) {
        id
        companyName
        companyStatus
        addressLine1
        addressLine2
        city
        state
        zipCode
        country
    }
}

5. Enter the following in the GraphQL Variables panel.

{
    "userId": {{b2b_logged_in_id}}
}

6. In the Scripts tab, enter the following “Post-response” code.

pm.test('Response is not an error', () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test('Response is JSON with data', () => {
    pm.response.to.have.jsonBody("data");
});
const userCompany = pm.response.json().data?.userCompany;
pm.test('Response includes a company ID', () => {
    pm.expect(
        userCompany?.id
    ).to.be.a('string');
});
pm.environment.unset('b2b_logged_in_company_id');
pm.environment.set('b2b_logged_in_company_id', parseInt(userCompany?.id));

7. Send the request, verify that all tests succeed, and verify that the b2b_logged_in_company_id variable is set on your collection.

You now have a completely automated Postman workflow for both registering a new customer and company, as well as “logging in” as your new Admin user. This will facilitate simple a authentication procedure for all requests in the subsequent labs, as you craft more workflows to simulate the storefront experience.