Lab - Postman Company Management Workflow
Lab - Postman Company Management Workflow
Lab - Postman Company Management Workflow
In this lab, you’ll construct a Postman workflow to simulate the administration of companies, company addresses, and company users. This will include implementing automation to capture and re-use values from API responses.
As a reminder, your work in previous labs should have resulted in the following Postman configuration, which will be important for the following exercise steps:
v3_token, store_hash, and storefront_channel_idAccept, Content-Type, and authTokenCreate a new HTTP request and save it to your collection with the name “Create Company.”
It’s probably helpful to group the requests in your collection into folders, such as “Companies” for all company-related requests.
Configure the request with the following details.
In the Headers tab, select the “B2B REST” preset from the Presets drop-down.
In the Body tab, check “raw” and select “JSON” from the types drop-down.
Enter the following request body. (Feel free to change the company/admin details.)
In the Scripts tab, enter the following “Post-response” test code.
The test code above will run after the API response is received and will verify that the expected data is present, indicating that the company was successfully created.
Send the request. You can observe the details in the Body tab of the response, as well as verify that all tests succeeded in the Test Results tab.
Record the companyId value from the API response for use in the next requests.
In the B2B Edition section of your BigCommerce control panel, you should be able to observe your new company and its single Admin user. Note that the API-created company is automatically in the “Approved” status. If the email address you used did not match an existing customer record, you will also see that a one was automatically created in the Customers section of the control panel.
Create a new HTTP request and save it to your collection with the name “Get Companies.”
Configure the request with the following details.
In the Scripts tab, enter the following “Post-response” test code, which will verify at least one company is returned.
Send the request and verify that all tests succeed.
You can record the ID of the company you created from this response if you didn’t already. Next, you’ll create a request for fetching the details of just this company.
Create a new HTTP request and save it to your collection with the name “Get Company.”
Configure the request with the following details.
In the Params tab, enter the ID of your newly created company as the value for the company_id Path Variable.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed.
The previous step required that you manually record the ID of the company you created and enter it into the appropriate field of a subsequent request. This can get cumbersome in a manual API workflow, especially when the number of values you must track grows.
In a real software application, capturing and using these values would be automated, and we can do the same in Postman using scripts and variables.
Open the “Create Company” request and add the following code after the previous code in the “Post-response” script.
Now, when the “Create Company” request is run, the company_id collection variable will automatically be set with the ID value from the response.
Collection variables 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, and we’re using collection variables for values relevant only to the workflow in this collection.
Open the “Get Company” request and change the company_id value in the Params tab to value {{company_id}} (including the braces).
Open the “Create Company” request, change the company/admin values in the Body tab to make sure the company name and email values don’t match existing entities, and send the request again.
Select your collection and open the Variables tab.
Verify that the collection variables include a value for company_id.
Re-send the “Get Company” request.
Now that “Get Company” is automatically fetching the information for the most recent value of the company_id variable, you should observe the details of your most recently created company.
We’ll continue using this style of automation logic for subsequent requests.
For all collection variables, you can manually change the values if necessary in order to control the automation in your requests, without needing to change the request configuration itself. Select the collection, navigate to the Variables tab, and set the “Current value” for the variable. Don’t forget to save the collection.
Next you’ll create a request for updating your existing company.
Create a new HTTP request and save it to your collection with the name “Update Company.”
Configure the request with the following details.
In the Body tab, enter the following content.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed.
In the B2B Edition section of your control panel, you can observe the updated details of your company.
Now let’s create a request to delete this company.
Create and save a new HTTP request called “Delete Company” with the following details.
In the Scripts tab, enter the following “Post-response” test code.
In addition to tests, this script also unsets the company_id collection variable now that the company no longer exists.
Send the request and verify that all tests succeed.
You can also verify in your control panel that the company has been deleted.
Next, we’ll explore using the REST API to manage company approval, practicing the filtering parameters of “Get Companies” in the process. Remember that the company you created with the API was automatically in “Approved” status so you’ll need an unapproved company before proceeding to the next API requests.
If you don’t already have unapproved companies in your store, browse to your B2B-enabled storefront, make sure you are logged out, and register a new company account.
Open the “Get Companies” request in Postman and add the following Query Param in the Params tab.
Note that this results in the query string ?companyStatus=0 being added to the URL.
In the Scripts tab, add the following “post-response” code after the previous code.
Re-send the request, which should only return unapproved companies now, and verify that the pending_company_id variable now has a value in your collection’s Variables tab.
Create and save a new HTTP request called “Approve Company” with the following details.
In the Body tab, enter the following content.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed.
You can now observe in your control panel that the identified company has been changed to “Approved.”
Try out additional “Query Params” in the Params tab of “Get Companies,” including limit, offset, sortBy, and orderBy. Test the effects of different values for these params.
Send the “Create Company” request again to create a new company and capture its company_id in the collection variable. Alternatively, you can simply select the ID of an existing company in the “Get Companies” response and manually set it as the current value of company_id in the collection’s Variables tab.
After ensuring you have a valid current company_id, let’s add an address to this company.
Create a new HTTP request and save it to your collection with the name “Create Address.”
Configure the request with the following details.
In the Body tab, enter the following content.
Make sure to include {{company_id}} exactly as it appears, including braces. This is a variable reference, exactly like when it was previously used in Path Variables.
In the Scripts tab, enter the following “Post-response” test code.
This script both runs tests and captures the ID of the newly created address as an address_id collection variable.
Send the request, verify that all tests succeed, and verify that the address_id variable was created on the collection.
In your control panel, you can observe the company’s newly created address, which should be set as both the default shipping and default billing address.
Create a new HTTP request and save it to your collection with the name “Get Company Addresses.”
Configure the request with the following details.
In the Params tab, add the following Query Param.
With this filter param in place, your “Get Address Companies” request will return only addresses for the company you’re currently working with.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed. You should observe that the results set includes the newly created address.
Try adding other filtering Query Params to the “Get Company Addresses” request, including isBilling, isShipping, limit, offset, address, city, state, country, and/or zipCode.
Lastly, let’s create a request to fetch individual details for the address you created.
Create a new HTTP request and save it to your collection with the name “Get Address.”
Configure the request with the following details.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed. You should observe your newly created address in the response.
Create a new HTTP request and save it to your collection with the name “Get Users.”
Configure the request with the following details.
In the Params tab, add the following Query Param.
As you did with “Get Company Addresses,” here you’re filtering the users request on a single company.
Try adding other filtering Query Params to the “Get Company Users” request, including limit, offset, and roles.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed.
You should have at least one user assigned to this company already: the Admin user that was specified when the company was first created.
Let’s create a new user for the company with the Junior Buyer role.
Junior Buyer is one of the pre-built roles that is assigned a hard-coded role ID (0). While you could create your Junior Buyer user using role: 0, a more forward compatible approach is to use companyRoleId. This approach will also support any custom roles you may create.
In order to specify companyRoleId, you’ll first need to fetch the available company roles and find the record ID for “Junior Buyer.”
Create a new HTTP request and save it to your collection with the name “Get Roles.”
Configure the request with the following details.
In the Scripts tab, enter the following “Post-response” test code.
In addition to tests, this script captures the ID of the role that has the exact name “Junior Buyer” in a collection variable called junior_role_id.
Send the request and verify that all tests succeed.
You should observe at least the Admin, Senior Buyer, and Junior Buyer roles in the response. If you have created any custom roles in your control panel, these should be present as well. Verify that an ID was set for junior_role_id in your collection variables.
With this role ID captured, you’re ready to create the user.
Create a new HTTP request and save it to your collection with the name “Create Junior Buyer User.”
Configure the request with the following details.
In the Body tab, enter the following content.
In the Scripts tab, enter the following “Post-response” test code.
This script captures the ID of the most recently created user in the collection variable user_id, for use in the next request.
Send the request, verify that all tests succeed, and verify that the user_id variable exists on your collection.
Re-send the “Get Company Users” request and verify that your new user now appears in the response.
Your final step will be to craft a request to fetch the most recently created user, utilizing the user id_collection variable that was auto-populated previously.
Create a new HTTP request and save it to your collection with the name “Get User.”
Configure the request with the following details.
In the Scripts tab, enter the following “Post-response” test code.
Send the request and verify that all tests succeed.
Try out finishing your user workflow by creating similar requests for updating and deleting a user. Also, consider trying fetching a user by customer ID instead of user ID.