Artifact Wizard

Table of Contents

• Contribution Guidelines
• Requirements
• Installation
• Supported Components
• How To Contribute
  • Creating A New Artifact
  • Updating An Existing Artifact

Contribution Guidelines

First of all: Thank you so much for being willing to contribute! We really need the awesome workflows and use cases you have built to grow our library of pre-built automations and to make them available to anyone who might need them.

Note: The terms Artifact and Pre-built Automation are currently used to describe the same thing. We'll hopefully get some clarification on naming conventions soon and will update this document accordingly.

To make contributions easy, we've published this Artifact Wizard artifact. We'll provide more details on how it works later in this README file, but here is the summary. When you run the Artifact Wizard from our Automation Catalog app, we ask you to select the Automation Catalog item you want to contribute. As long as your Automation Catalog item has a valid form and workflow attached, we'll discover all the other objects (Command Templates, Forms, Child Workflows, Configuration Trees, etc.) and dependencies that we'll need to successfully run your automation. After you confirm that we've discovered all the things you want to contribute, Artifact Wizard will prompt you to provide a category, description, README, license information, and keywords. Then Artifact Wizard will bundle your automation, push it up to our staging folder on GitLab, and provide you a link to the newly created repository.

Let's go through all things we'd like you to provide:

Files

All files you want to contribute (workflows, forms, templates, etc.) should follow this naming schema: <Artifact Name> <title/use of file>

Examples:

• L2VPN create form
• L3VPN create form
• Banner-Management IOSXR subflow
• Banner-Management Pre-check

Workflows

Since workflows are a central part of any of our automations, we want to make sure to keep them easy to read and understand. Here are a couple of things to look out for:

• The main workflow should provide a high level view of what the entire artifact is doing. All functionality must be put into child workflows. Ideally a main workflow consists only of a couple of child workflow tasks and stub tasks. We're enforcing a 20 task maximum limit for main workflows.
• Only use IAP tasks that are shipped with our bundles as well as essential tasks from open source adapters. Example: The Meraki SDWAN artifact needs tasks from the Meraki adapter, but tasks from a ServiceNow or Slack adapter should be replaced by the stub task, which should be renamed to explain the stubbed action. Ansible modules, scripts or roles can only be used starting with IAP 2020.1.
• Re-name all titles of tasks according to what they do in your workflow. Use "Query device name" rather than "Query", or "Apply new interface config" rather than "apply template".
• Choose a task layout that helps other people understand the flow of your automation
• Try to keep the happy path on a straight line from left to right, add error handling at the bottom and loops at the top
• When using eval tasks, both success and failure transitions should be drawn at a 45 degree angle; the success transition should point up, the failure transition should point down
• Do not mix NSO and Ansible tasks in the same workflow. It will break for customers with only one of the adapters. Instead, use child workflows for each integration.
• Provide a description for each task. Like commenting your code, this is very helpful for anyone to understand your automation.

Name

Please provide a short and descriptive name of what your artifact is used for. Examples:

• Banner-Management
• Device-Health-Check
• Cisco-IOS-Upgrade

Categories

Pre-built automations are tracked in different categories. Here is a list of all of them:

• Authentication
• Cloud
• Controller / Orchestration
• DevOps
• NetOps
• Inventory
• ITSM / Testing
• Notification / Messaging
• Persistence
• SD-WAN
• Security
• Telemetry / Analytics
• Utilities

Please select the category that fits your contribution. If your artifact covers multiple categories, you can select an additional one. For examples on which artifact should be in which category, please refer to the Itential pre-built automations page

Description

This is the description of the artifact you contribute, as shown in the project/repo in GitLab, as well as in the preview of an artifact within App-Artifacts. Please describe the use case that your artifact is solving, and why people should be excited about it, within 200 characters.

Example:

Manage network banners across multiple device types and execute automations against Ansible managed network devices.

README file

Please provide a thorough README file in markdown format, including:

• Overview of the use case
• Key features/benefits
• Pre-requisites and how to install them
• How to run this artifact
  • Which form inputs are necessary?
  • Are there stubbed tasks that can be replaced?
  • What is the expected output?

Example:

Itential pre-built automations - Service Provisioning

License File

If you want to provide a specific license for your contribution, you can do so here. If you leave this field blank, Apache License Version 2 will be automatically used.

Keywords

Please provide keywords related to your artifact so that users can find it.

Examples: Configuration Management, Policy, Compliance, Audit, Device Onboarding

Note: At least one keyword is required.

Requirements

Artifact Wizard requires the following in order to run, and is compatible with the following versions:

• Itential Automation Platform
  • ^2019.2.3
  • ^2019.3.0
• App-Artifacts
  • ^2.4.2

Installation

Please ensure that you are running a supported version of Itential Automation Platform (IAP) as listed above in the Requirements section in order to install Artifact Wizard. If you do not currently have App-Artifacts installed as a service on your node, the .tgz file or "tarball" can be obtained from the Nexus repository. Please refer to the instructions included in the App-Artifacts README to install it.

Artifact Wizard can be installed from within App-Artifacts. Simply search for artifact-wizard and click the install button as shown below:

Alternatively, you may clone this repository and run npm pack to create a tarball which can then be installed via the offline installer in App-Artifacts. Please consult the documentation for App-Artifacts for further information.

Supported Components

The Itential Automation Platform components that Artifact Wizard can currently consume include:

• Automation Catalog items
• Configuration Trees
• Form Builder Forms
• JSON-Forms
• Mop-Templates
• Mop-Analytic Templates
• Workflows
• Jinja2 Templates
• TextFSM Templates

How To Contribute

Please see:

• Creating A New Artifact
• Updating An Existing Artifact

Artifact Wizard can be launched from Automation Catalog, and the job must be run as an admin user. To begin, click the Run button:

Creating A New Artifact

To create a new artifact, you must supply a name and an entry point for the automation:

Please keep in mind that the entry point to the artifact must be an Automation Catalog item. The item should supply both a workflow and a form as an entry point for the artifact. Any job variables required for the workflow to run should be supplied by the accompanying form, and will be accessible to the workflow via the formData object.

After you click the Run button, Artifact Wizard will discover all dependencies required by the workflow selected in the Automation Catalog item, as well as version information for each IAP application required to install the bundled artifact. The results of the discovery will then be available for you to confirm:

Artifact Wizard will next prompt you for metadata for the artifact, and will give you the opportunity to provide a short description, a README, license information, and a list of keywords (at least one keyword is required) relevant to the artifact. If no license is provided, Artifact Wizard will bundle Apache License Version 2 by default. Please refer to the Contribution Guidelines regarding best practices and naming conventions.

At the time of this writing, Artifact Wizard must next perform a health check to gather module information in order to properly bundle the artifact. Please note that this step will not be required to run in future versions of Artifact Wizard. You will be prompted to perform the health check as an admin user:

Artifact Wizard will then bundle all of your dependencies, create a package.json file, and push the artifact to a new repository on GitLab under our staging directory. Upon successful completion of the job, you will be provided with a link to the repository:

Click the provided link to direct your browser to the freshly created repository. You should see something similar to the following:

If you go into the bundles directory, you will be able to see all of the pieces of your automation that were bundled with the artifact:

Finally, press the Success button to complete the job

Congratulations on creating your very first artifact, and thank you for contributing! 🎉

Updating An Existing Artifact

To update and re-publish an existing artifact, simply select the automation from the dropdown menu:

Artifact Wizard will discover any new dependencies and re-bundle the automation, then create a branch from master in your repository and submit a merge request. Upon successful completion of the job, you will be provided with a link to the merge request, where you will be able to review the diffs and merge the branch back to master.

Note: At this time, only an installed artifact initially created using Artifact Wizard may be updated using Artifact Wizard.

For instance, in the example artifact above:

The workflow may be updated to view the output of the addDevicesToNode task and save this as part of the artifact. A viewData task may be added, and the workflow may then be updated:

From Automation Catalog, we can now run Artifact Wizard and choose Update Artifact, as described above. When the job completes, you will be presented with a link to review the merge request:

Click the provided link to direct your browser to the freshly created merge request:

At the bottom of the page, click Changes to review the diffs:

Finally, click Success to complete the job. If you are happy with all changes you've made, you can choose to merge this auto-generated branch back into master.

Congratulations on updating your artifact, and thank you again for contributing! 👐