Quick Start

About this Quick Start

This Quick Start provides a high-level task list that focusses on the most common and frequently used tasks and features that XPRESSO was designed for. It walks you through the steps to create, execute and view the test results of a single Job run.

To help facilitate your progression through this Quick Start, you can use several "DEFAULT" Job profiles, Group preferences and permissions, and lab/testbed locations to expedite the process.

You are required to review and customize some of these setting to take advantage of the core automation features XPRESSO provides. For any settings not touched in this Quick Start, the suggested reading path in each applicable step highlights relevant information in case you want determine what is required to configure those settings.

Quick Start Goals

This Quick start is designed for new Users who want to test-drive XPRESSO (kick-the-tires and look-under-the-hood) to get familiar with XPRESSO with minimal ramp time. The goals of this Quick Start is to:

• Show that setting up XPRESSO's working environment to create and execute a Job takes minimal effort.

• Demonstrate XPRESSO's ease-of-use, flexibility, and how XPRESSO simplifies the integration and execution of test scripts so you can quickly isolate, interpret, and analyze test results data.

• Provide a quick introduction to the XPRESSO dashboard using the most common/frequent tasks that are performed with XPRESSO. Armed with this knowledge/experience, you will be able to complete more complex tasks with XPRESSO.

• Illustrate the interaction and task flow that is required between different XPRESSO User types and Group Members.

• After you execute your first Job, introduced you to the different ways you can search your test results to quickly isolate network specific details and how you can assign Custom Tags to flag important information with keywords so you can quickly find this information again.

• Once you have mastered the basic building blocks of working with the XPRESSO dashboard and created and executed a Job, a suggested reading path is provided that will gradually introduce you to the full complement of XPRESSO's features.

Quick Start Assumptions

This Quick Start assumes you have completed the following pre-requisite tasks, read the supporting documentation, and have the necessary scripts and files in place that XPRESSO uses to execute a Job prior to starting:

• You need to register and been approved by the System Administrator to use XPRESSO. You can then login into XPRESSO as a registered user. See "Logging in for the First Time" for more information.

IMPORTANT:
You also need to be a registered user in XPRESSO in order for the Group Administrator to assign you to an appropriate working group.

NOTE:
For Cisco personnel, use your Cisco CEC credentials to login into XPRESSO for the first time or contact the XPRESSO technical support team @ xpresso-support@cisco.com.

• (Optional but recommended) You have familiarized yourself with the following:

  • The general layout of the "XPRESSO dashboard" and major graphical elements.

  • XPRESSO uses "Notifications", "Messages", "Actionable Requests" and "Webex Team Notifications" as the built-in push and pull communication/alert/messaging services and tools to assist with monitoring system events, convey/broadcast messages to/from users, and to request tasks or actions to be completed by Group Administrators or the System Administrator.

  • Since you may have to interact with other Group Members or get help as you walk through this Quick Start, you may want to review the "Help and Contact Guidelines" to determine who to contact.

  • In the event you encounter terms or acronyms on the XPRESSO dashboard you are unfamiliar with, be aware there is a specialized XPRESSO "Glossary" that provides expansions and term definitions to assist you.

• You have familiarized yourself with the different "User Types and Group Membership Roles", and reviewed the "Group, Group Membership, and Group Member" collaboration principles and Group categories that XPRESSO is designed around.

• As you advance through the latter steps in this Quick Start, XPRESSO constantly monitors all equipment and resources managed by XPRESSO in real-time to report the "Operational and Configuration States" of your test environment throughout the life-cycle of a Job Run. These states report the readiness/availability of test equipment, the transitional states as the Job executes, what happens when the Job Run completes, and if a problem occurs, the reason why. While many of these states are obvious, be aware that information is provided to help you determine what each state means.

• The assumed starting point of this Quick Start is you are a brand new User to XPRESSO therefore you only belong to the default Guest Group and have a Guest User role, or you have been invited to join an existing Group. If you already belong to a Group and have a Membership role, simply jump into this Quick Start at the appropriate step.

• You have a pyATS test script that you want to execute using XPRESSO. You can optionally acquire a sample pyATS script from these sites if required: Cisco-internal or external-source.

• You have a YAML file that is used when defining a testbed in XPRESSO (see Step 5). Alternatively, you can download a sample YAML file that will meet the requirements to complete this Quick Start.

• If you intend to clean your devices and load a new image as part of a Job execution, you will also need to import a clean YAML file when you register your testbed. Clean files (with examples) are detailed in the pyATS user documentation.

Step 1 - Confirm your Date and Time Settings:

Who performs this task(s)?	All new Users to XPRESSO.
Why complete this task?	After you access and log into XPRESSO for the first time, you must accurately configure your Preferred Time Zone since all content reported by XPRESSO is automatically associated with your preferred time zone. You can customize both the Coordinated Universal Time (UTC) time zone and time display format to suite your operational/preferred format.
Suggested reading	"Configuring User Preferences"
What task do I perform?	"To Confirm your Date and Time Settings"

Step 2 - Join a Group or Request a New Group:

Who performs this task(s)?	A User with no Group affiliation (Membership) other than belonging to the default Guest Group and is assigned a Guest User role.
Why complete this task?	New registered users in XPRESSO are automatically assigned to a Guest User role which is designed to be a transient (default) role before they are assigned to another Membership role by the Group Administrator. As a new user, you are also automatically assigned to a default "Guest" group. The following restrictions are imposed on Guest Members: They have minimum visibility of XPRESSO features and which actions and options users can see on the XPRESSO dashboard. They can only view details about public groups that allow guest access. The only actions they can perform in XPRESSO is submit or rerun Job Requests. You have three options to transition from a Guest User role in the Guest Group to another Group: Submit a request to join an existing Group. Submit a request to create a new Group. Switch from the Guest Group to the new Group (only available if your Group Administrator has proactively added you to their Group in advance of your request; you will be notified by email if you have been added to a Group). When a Guest member makes a request: to join an existing Group; create a new Group; or to switch Groups, the Group Admin changes their Guest role to another Membership role as part of the group enrollment process. You then need to switch from your current Group to the newly available Group (this is not done automatically).
Suggested reading	"User Types and Group Membership Roles" "Groups and Group Membership"
What task(s) do I perform?	"To Submit a Request to Join an Existing Group" "To Submit a Request to Create a New Group "To Switch from the Guest Group to a New Group"

Step 3 - Review/Change/View the Permissions for your Group:

Who performs this task(s)?	Group Administrators are required to review and/or change the default permissions for their Group. All Member roles can view their Group Default permissions.
Why complete this task?	In XPRESSO, Group Permissions: Provide the necessary background security protection. Gives Group Administrators the ability to control which actions each Membership role can perform. Also controls which action and options each Membership role can see on the XPRESSO dashboard. All Group permissions in XPRESSO have an assigned "System-default" value that are pre-set to meet most operational and security requirements. Group Administrators are required to review and/or change the default permissions to ensure: The default settings are configured appropriately for your specific testing environment to ensure the necessary security protection is maintained. The default set of actions assigned to each Membership role is appropriate for your organization and test requirement/environment. As necessary, grant or revoke the permissions for any specific actions to meet your specific needs. NOTE: When you change the permission setting associated with an action, this change affects all members within that role, not just a specific member. All Group Membership roles can view their current permissions to determine which XPRESSO actions your Membership role can perform within a Group.
Suggested reading	"Group Permissions"
What task(s) do I perform?	"To View your Group's Permissions" "To Change the Permission Settings for a Group"

Step 4 - Set up your Test Environment:

Who performs this task(s)?	Group Admins Privilege Members can also perform most actions/tasks to register your Test environment but may need to have the Group Administrator tweak their specific permissions for certain actions. NOTE: The defaults actions you can perform on most of the components in this step are defined in the Group permissions. Group Administrator should review the Group permission settings and update them accordingly based on their organization/group mandate - see Step three in this Quick Start for more information.
Why complete this task?	Since XPRESSO actively manages the test environment associated with each test script to a finite level, you must register the correct information for the following resources and test environment: Lab/testbed Location: You need to make sure your testbed location is registered in XPRESSO. If the location where your lab is located is not part of the existing registered locations in XPRESSO, make a formal request to register the site/building. NOTE: You have the option to perform your Job Runs on a local Jenkins execution engine or use a Docker Image to run your Jobs in the Cloud. If you are using a local Jenkins engine to execute your Job Run, specify your Test Harness and the Execution engine (sub-steps 2 and 3), then continue with sub-step 5. If you use a Docker Image to execute your Job in the Cloud, skip sub-steps 2 and 3 and complete sub-steps 4 and 5. Test Harness: A test harness defines the test framework properties (name, type, path, location, supported features) for the Python script execution environment associated with your pyATS instance or Tcl-ATS tree. You need to register your test harness in XPRESSO. Execution Engines: XPRESSO uses Jenkins in the backend for Job execution. Make sure your Jenkins execution masters are registered. Docker Image: You can add (register) existing Docker Images or build new Docker images to provide a virtual equivalent of a test execution environment to execute Job Runs in the Cloud. This eliminates the need for a physical (Jenkins) execution engine or test harness. OS/Platform/Branch Metadata: OSes, Platforms and Branches are related topics as they provide a method to associate metadata (descriptor info that acts as a build/release tag, alias, or label) with devices, device images, and Job Runs. XPRESSO in turn, correlates the applied metadata allowing you to perform additional data filtration, aggregation, charting, and analytics with your test results and as a means to set a baseline. Add this information as required for this test Job Run.
Suggested reading	"Location Geo-tagging" "Test Harnesses" "Execution Engines" "Docker Images" "Branches" "Platforms" "OS"
What task(s) do I perform?	"To Manage Your Lab/testbed Location Details" "To Create a New Test Harness Instance" "To Create a New Jenkins Execution Engine Instance" "To Register a New Docker Image" "To Register a New OS" "To Register a New Platform" "To Register a New Branch"

Step 5 - Register your Testbed:

Who performs this task(s)?	Group Administrator or Privileged Members
Why complete this task?	Testbeds represent the network devices that work together as a test platform that your tests will be executed against. XPRESSO supports the following testbed types: Static testbeds: Represents the physical (pre-created) network devices in your test environment. LaaS-NG testbeds: Is a network orchestration tool (testbed) used to create on-the-fly network topologies with both physical and virtual hardware to represent or describe Cisco platforms/devices. LaaS uses the concept of Domains. LaaS-NG brings up the nodes in the topology, creates network connections among nodes and establishes console access to each node. LasS-NG is also referred to as a dynamic or logical testbed. You need to register your testbed in XPRESSO in order to execute your Job Runs; testbeds are specified in the Job Profile associated with your Job Run. Another reason you need to register your testbed is operational: testbeds and their available time-slots are considered scarce resources in your test environment since they are shared among all users to execute Job Runs. XPRESSO actively manages testbed allocations using "Testbed (priority) Queues" and "Reservations". To take advantage of these features, all testbeds need to be registered in the system. When you register your testbed in XPRESSO, the following functions are fully modeled on the XPRESSO dashboard which you can then manage: Testbed representation (the testbed YAML and optionally, the clean YAML) Testbed time allocation (priority queues and reservations)
Suggested reading	"Working with Testbeds" "Testbed (Priority) Queues"
What task(s) do I perform?	"To Register a Static Testbed and Import a Testbed YAML File" (Optional) "To Import a Clean YAML File"

Step 6 - Review/Change/View the Default Preferences for your Group:

Who performs this task(s)?	Group Administrators are required to review and set the default preferences for their Group. All Member roles can optionally view their Group Preferences.
Why complete this task?	Group Preferences are the pre-filled system default settings that are configured by the Group Administrator to help simplify and expedite the creation of configuration forms in XPRESSO. They provide a centralized registrar of all settings that are commonly used and preferred by all Members within a specific Group. Since Group Preferences "auto-fill" the fields on new configuration forms, they negate the requirement for Group members to fill every single field on the form. Group Preferences are also used for setting up external connectivity plugins and the notifications infrastructure for user operations. Most Group preferences have an assigned "System-default" value that are pre-set to meet most operational requirements. Group Administrators are required to review and/or change the default preferences each time a new Group is created to make sure the preferences meet the operational requirements for the intended Group. This ensures: They are configured appropriately for each of the components registered in XPRESSO. They are set to the optimum level required to meet the operational needs for the intended Group. This greatly reduces the overhead of having every Group member select the required field from the associate drop down menus when they are preparing and executing a Job. IMPORTANT: Although Group Administrators set the default value for Group Preferences, you can select or enter a setting on configuration forms that meets your immediate needs which overrides the default setting.
Suggested reading	"Group Preferences"
What task(s) do I perform?	"To Review or Change your Group Preferences" "To View your Group Preferences"

Step 7 - Create a Job/Job Profile:

Who performs this task(s)?	All Member roles can perform this task.
Why complete this task?	A "Job" defines the common entry point for one or more pyATS test scripts that can be aggregated together to prepare a Job Run in advance of execution within the same runtime environment. Shared attributes include which Execution Engine and Test harness to use, any Job/Environment/pyATS arguments that need to be applied, and which testbeds or LaaS-NG topologies to use. A "Job Profile" contains the metadata information that defines how to run your Job such as which arguments, test harness, execution engine, testbeds, or LaaS-NG topologies that apply to a particular test run. It allows you to create multiple variation of the job based on settings defined in the metadata. At a minimum, a Job when initially registered is always associated with its DEFAULT Job profile. You can create or clone additional Job profiles for other required variations. Each Job in XPRESSO, can have one or more associated Profiles. A Job and a Profile together define an executable suite to run.
Suggested reading	"Creating XPRESSO Jobs" "Creating Job Profiles"
What task(s) do I perform?	"To Create a New Job" "To Create a New Job Profile"

Step 8 - Execute your Job Request:

Who performs this task(s)?	All Member roles can perform this task.
Why complete this task?	When you save a Job in XPRESSO and the Job is submitted for execution and queued (therefore, the job is set to “Run DEFAULT” on the Registered Jobs page), the Job is now considered to be a "Job Request" (also known as a Run Request and is truncated to just "Request" on the XPRESSO dashboard). You can provide additional settings, or overwrite the configured settings when initiating a Job Run Request to further define/refine your test requirements. For example, you can select/de-select which testbeds to use, specify your clean file requirements and Job/Environment/Harness arguments, and configure optional parameters such as establishing a baseline test run or running your tests on multiple testbeds. A Job/profile can be executed as a single Job Request, as a group run with other Jobs/Profile(s) or as a Group Bundle Run. The Job Request will execute when the testbed resources become available or when the Job is scheduled to run.
Suggested reading	"Configuring and Executing Job Requests"
What task(s) do I perform?	"To Configure and Execute a Single Job Request"

Step 9 - View your Job Test Results:

Who performs this task(s)?	All Member roles.
Why complete this task?	Once a Job Request completes the Job Run, it contains your Job test results. You can then: View the executed run request and/or the results of the Job Request. View a quick-look Results Summary that provides a Pass/Fail breakdown for all test cases in your Job Request. View Job test result details that displays a line-by-line log of all test cases in your Job Request broken down to each section, sub-section, and each discrete executed device command.
Suggested reading	"Viewing Job Test Results" "Searching in XPRESSO
What task(s) do I perform?	"Viewing XPRESSO Job Test Results" (both summary and detailed information) "System-wide Searching using the Global Search Tool" "Searching Local Registered Objects" "Using Custom Tags for Searching" "Using XPRESSO's Advance Key Word Search"

Step 10 - Suggested Next Steps:

Who performs this task(s)?	All Member roles; note that some of the suggested tasks may limited to specific Member roles.
Why complete this task?	Now that you understand the basic building blocks of working with the XPRESSO dashboard and creating and executing a job run, you might ask... "What's Next?" Follow the suggested reading path below that will gradually introduce you to the full complement of XPRESSO's features.
Next tasks to try	"Create a Job Profile" "Create a Job Bundle" "Reserve a Testbed" "Schedule a Job Run" "Manage your Scheduled Events in the Calendar" "Run a Group Job Request" "Run a Bundle Job Request" "Compare and Analyze your Test Results" "Baseline your Job Test Results"
Optional tasks to try	"Request a LaaS Instance" "Create/Edit a LaaS Topology" "Reserving a Topology" (includes how to take and reuse a snapshot of a topology) "Manage the Configuration Status of a Resource" "Viewing Test Results Posted to Cisco TRADe"
Advanced tasks to try	"Register a New Docker Image" "Register a New Webhook "Configure Lab VPN Preference Settings" "Troubleshoot Operational Failures using History Tracking" "Working with REST and CLI APIs"