The following documentation provide details for the setup and configuration of the Apica Postman Check.

VERSION 1.1 2021-12-17

Note: npm Documentation Source

The latest version of the ASM Postman Check Runner documentation is found here and is authoritative:

• @apica-io/asm-pm-runner - npm (npmjs.com)

1.         Introduction

The asm-pm-runner runs Postman collections and exports results to Apica’s Check Results Service (CRS) format.

 The command-line tool is based on the standard Postman Newman utility (Newman is a command-line collection runner for Postman.)

 The primary enhancement to Newman is supporting the data decryption files and certificates. Encryption/decryption is based on the cryptify npm module.

2.       Why Use a Postman Check?

ASM users who have Postman collections can now run them, without conversion, as long-term monitoring checks from a global perspective. This allows you to expand testing from a single location to measuring and comparing multiple performance results from any Apica agent over time.

3.       The ASM Postman Check

Apica ASM can run Postman checks based on asm-pm-runner. This feature runs a Postman collection in Apica ASM and reports the results to Apica’s Check Reporting Service.

Running the Postman Runner Solution

The solution depends on Installing npm, which allows you to run your Postman Collections from the command line using the Apica Synthetic Monitoring Postman Runner (ASM PM Runner)

At a Terminal window, type the following to install npm:

npm install -g npm

Installing the ASM Postman Check Runner Solution

Solution Link: Link to the ASM Postman Check Runner Solution

At a Terminal window, type the following to install the ASM Postman Runner

npm install -g @apica-io/asm-pm-runner

ASM PM Runner Syntax

asm-pm-runner [options] <collection>

Command-line Options (as of Version 1.3.5)

To get the options available for your version of the ASM-PM-Runner, at the command line/Terminal, enter:

asm-pm-runner -h

Which will return the following help with options
Usage: asm-pm-runner [options] <collection>

Options:
-e, --environment <path> Environment JSON file
-dk, --decryptKey <decryptKey> Decrypt key
-ev, --envVars [envVars...] Environment variables. Format name=value format
-v, --verbose Print collection information on stdout (default: false)
-r, --resultDir <dir> The result directory
-dd, --dataDir <dir> The data directory for certificates and test data
-l, --logLevel <logLevel> Log level in log4js (default: "info")
--sslClientCert <path> Specify the path to a client certificate (PEM)
--sslClientKey <path> Specify the path to a client certificate private key
--sslClientPassphrase <passphrase> Specify the client certificate passphrase (for protected key)
-V, --version output the version number
-h, --help display help for command

🆕 Manage Repository Files

URL-XI, Postman, and Scripted Checks use repositories to store their scripts/collections, so the first step is to create a new Repository Profile in the ASM Portal. Please go to the Manage Repository Files page for steps in setting this up.

4. Samples

You will find some runnable examples in the installation directory under samples. See the folder structures used by npm in the npm documentation about where you can find the global npm directory.

The package.json file contains scripts for running the samples with correct parameter settings.

Example 1 - Running some http requests on http-bin

$ asm-pm-runner samples/HTTP-Bin-Requests.postman_collection.json -v -ev username=foo password=bar

Example 2 - Testing certificate on https://badssl.com

This sample uses encrypted certificates.

The command line:

$ asm-pm-runner -l debug -dk Encrypt.4.ssl --sslClientCert file.cert.pem --sslClientKey file.key.pem --dataDir samples/ec_badssl_certs -r results/ -v samples/BadSSL.postman_collection.json

Follow this npm link to see the full console output from the command above

5. Result Reports

The JSON report is stored in the results directory. The format is complaint with Check Result Service in Apica ASM.

Steps and requests in the report

The JSON report is divided into one or more steps.

• A step contains requests from the postman collection.

• The default is only one step, with all requests generated.

• Several steps will be generated if the collection contains folders.

  • One step for each folder will be generated.

  • The step name corresponds to the folder name.

• Only one level of steps is supported.

  • Folders in folders will be named folder/subfolder.

    • Example root folder/subfolder 1/subfolder 2

Returning a custom value as the result

asm-pm-runner can return a custom value as the return value when running a collection. This functionality is often used in ASM when you want to return something else than the total response time as the main result of the check run. In the collection, use two special collection parameters and assign them values in a JavaScript test.

pm.test("Status code is 200", function () { pm.response.to.have.status(200); }); let eventCount =pm.response.json().length; pm.collectionVariables.set("_Apica_ReturnValue",eventCount) pm.collectionVariables.set("_Apica_ReturnUnit","events")

Returning variables in the result

You can also return variable values in the result report. If you want to suppress a variable from being included in the result report use a name starting with the "_" character. Collection and Environment variables not changed during the run of the collection will be typed as input variables.

let json =pm.response.json(); pm.collectionVariables.set("eventName",json.name) pm.collectionVariables.set("category",json?.category?.description|| "") pm.collectionVariables.set("mediaLink",json?.mediaItem?.url|| "")

Key Links:

➡ Follow this npm link for how Variables are reported in the JSON result report

➡ Follow this npm link for the generated JSON report

6. “cryptify” Package Details

To encrypt and decrypt files in a project, you can use the NPM package cryptify, simple file-based encryption (FBE) utility for Node.js. The following file types support encryption/decryption:

• certificates

• data files

shared variables

You must supply a decryption key with the -dk option. The file must be encrypted with the key using the command-line version of cryptify.6.1.1 Install cryptify

Install cryptify

$ npm install -g cryptify

Encrypt with cryptify

$ cryptify

Usage: cryptify [options] [command]

Options:

-v, --version Display the current version

-l, --list List available ciphers

-h, --help Display help for the command

Commands

encrypt [options] <file...> Encrypt files(s)

decrypt [options] <file...> Decrypt files(s)

help <command> Display help for the command

cryptify Syntax Example

$ cryptify encrypt file.txt -p 'Secret123!'

$ cryptify decrypt file.txt -p 'Secret123!'

npm example of encrypting a file with cryptify

$ cryptify encrypt common_vars.json --password URL-XI.4.data

npm example with encrypted postman_environment

$ asm-pm-runner samples/HTTP-Bin-Requests.postman_collection.json -r results -l debug -v -e samples/ec_env/Http_bin_environment.postman_environment.json -dk Encrypt.4.ssl

PDF Version here: