SD-WAN Branch Management

Table of Contents

• Overview
• Features
• Requirements
• Known Limitations
• How to Install
• How to Run
• Components
• Additional Information

Overview

The SD-WAN Branch Management artifact consists of a series of small modular workflows that creates a 'network' for a given organization and claims one or many access points in that network. A demonstration workflow orchestrates the process, and also indicates how to integrate with a ticketing system, such as ServiceNow.

Features

• Operation Modes: Zero Touch and Normal mode
• Onboard devices into your SDWAN environment
• Pre/Post checks for your deployment
• Notifications throughout the onboarding process

Requirements

In order to use this artifact, users will have to satisfy the following pre-requisites:

• Itential Automation Platform
  • ^2019.2.7
• App-Artifacts
  • ^2.6.2
• Meraki Adapter
  • ^0.6.0

Please refer to the documentation for the Meraki Adapter in order to install and configure the adapter.

Known Limitations

This artifact currently only supports branch management for Meraki controllers and access points. A future update may include support for Viptella, VeloCloud and SilverPeak devices.

How to Install

Please ensure that you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Requirements section in order to install the artifact. If you do not currently have App-Artifacts installed on your server, please download the installer from your Nexus repository. Please refer to the instructions included in the App-Artifacts README to install it.

The artifact can be installed from within App-Artifacts. Simply search for the name of your desired artifact 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.

How to Run

The artifact includes a demonstration for Meraki controllers which will create a network branch within an organization and claim one or more devices to that network. In order to run the demonstration, run the Meraki Network Deployment item from Automation Catalog:

You will then be presented a form with some necessary information to provide in order to run the demo:

• Organization Name: Provide the name of the organization available to the Meraki controller within which you would like to add the network branch
• Network Name: Provide a name for the network branch which will be created
• Email: Provide a valid email address in order to receive notifactions throughout the demonstration, including alerts from the device
• Devices: Provide a list of serial numbers for the devices you would like to claim to the network. You may add another device by pressing the + button in the bottom right hand corner

This demonstration may be run in verbose mode, which will display alerts in manual tasks. Additionally, the demonstration will stop at various breakpoints in this mode which require the user to work a manual task in order to progress. These breakpoints allow for an opportunity to examine the Meraki Dashboard and gain an understanding of what the Meraki workflows are doing under the hood.

When you are ready, press the Run button to begin the automation. When the demonstration has completed, the workflow will rollback any changes made, such as removing the network branch and any claimed devices.

Components

This artifact contains a set of modular workflows which are designed to be used together to create network branches and claim devices to those branches. Please see the demonstration workflow for an example of how to use these workflows, as well as how to integrate with notification and ticketing systems. The information below describes how to use each workflow, and what variables must be provided as input.

Create Network

This workflow creates a ‘network’ within a Meraki management platform. If the network already exists, the ID of that existing network is returned.

Input Variables

The following input variables are required:

• input: The input variable is a JSON object which will be used as the payload to the Create Organization Network API call. Please reference the API documentation for full details on how this payload should be formed.
• organizationName: The name of the organization within which to create the network branch.

The following JSON object provides an example for the request payload:

{
  "organization": "Acme",
  "name": "demo network",
  "type": "wireless",
  "tags": " iap demo ",
  "timeZone": "America/New_York",
  "disableMyMerakiCom": false,
  "disableRemoteStatusPage": true
}

In order to create this object, either the makeData task or the merge task may be used in your workflow before using the childJob task to call the Create Network workflow.

Validation

This workflow ensures the following:

• Check if the organization exists within the Meraki management platform
• Check if the Network already exists

Error Handling

Each error thrown is assigned a code:

• 401 – Organization not found
• 402 – An error occurred when attempting to create the network. The response from the API call is returned within the ‘errorStack’ parameter of the response. See details below.

Response

If invoked as a child job, the outgoing data payload includes all job variables defined within the workflow. The specific result of the workflow is defined within the output variable.

If successful, output will return:

• code: 200
• OrganisationId: This is the Id of the inputted organization. This is particularly useful as it is required for other API calls to Meraki
• NetworkId: The id of the network
• network: This flag will tell you whether the workflow created a new network or found an existing one in the given organization

Example Success Output

"output": {
  "code": 200,
  "status": "success",
  "description": {
    "code": 200,
    "result": "success",
    "OrganisationId": "12345",
    "NetworkId": "N_647955396388013760",
    "network": "created"
  }
}

Example Error Output

"output": {
  "code": 401,
  "status": "error",
  "description": "The organisation does not exist in the Meraki Network.",
  "errorStack": null,
  "errorRecommendation": "Check the value of the inputted organization exists within the Meraki platform."
}

Claim All Devices

This workflow accepts an array of devices in order for them to be claimed into a given pre-existing Network. For each element in networkDevice array, the sub-workflow Claim Device is invoked.

Input Variables

The following input variables are required:

• networkDevice: An array of serial numbers for the devices to claim. This array should be in the following format:

  [
    {
      "serial": "1234-1234-1234"
    },
    {
  
      "serial": "9876-9876-9876"
    }
  ]

• organizationId: The ID for the organization, e.g. 12345

• NetworkId: The ID for the network, e.g. N_647955396388013760

Validation

Upon completion, the status of the child Claim Device job is evaluated and depending on success or failure the job variable arrays are updated with the result.

If the output.status of the child job does not equal success then the child job is deemed to have failed.

On success, an element is added to the resultArray. The element details are:

• deviceId: serial number of the claimed device
• response: claimed
• status: success

On failure, an element is added to the resultArray and the errorArray. The element details for a failure are:

• deviceId: serial number of the claimed device
• networkId: the ID for the network
• organizationId: the ID for the organization
• response: the output variable from the child job
• status: error

Error handling

Failures/errors from the child Claim Device job are captured and added to the error array.

Response

If the count of elements in the errorArray is greater than 0, then an error response is returned.

Example Success Output

{
  "code": 200,
  "status": "success",
  "description": "All devices successfully claimed"
}

Example Error Output

In the example below, the overall status of the job is an error, and the errorStack has the result of each job.

{
  "code": 401,
  "status": "error",
  "description": "An error occurred claiming one (or more) devices.",
  "errorStack": [
    {
      "deviceId": {
        "serial": "1234-1234-1234"
      },
      "response": "claimed",
      "status": "success"
    },
    {
      "deviceId": {
        "serial": "1234-1234-TEST"
      },
      "networkId": "N_647955396388014332",
      "organizationId": "12345",
      "response": {
        "code": 402,
        "status": "error",
        "description": "An error occured whilst create the network in the Meraki Controller",
        "errorStack": {
          "icode": "AD.500",
          "IAPerror": {
            "origin": "Meraki-connectorRest-handleEndResponse",
            "displayString": "Error 400 received on request",
            "recommendation": "Verify the request is accurate via debug logs and postman",
            "code": 400,
            "raw_response": {
              "status": "success",
              "code": 400,
              "response": "{\"errors\":[\"Device with serial 1234-1234-TEST not found\"]}"
            }
          }
        },
        "errorRecommendation": "The device could not be claimed. Please check the errorStack for details. It's possible the device doesn't exist for it to be claimed."
      },
      "status": "error"
    }
  ]
}

Claim Device

This workflow claims a device into an organization's network. It does so by calling the Meraki API.

Input Variables

The following input variables are required:

• networkDevice: the serial number should be provided as a JSON object in the following format:

  {
    "serial": "1234-1234-1234"
  }

• organizationId: the ID for the organization, e.g. 812345

• NetworkId: the ID for the network, e.g. N_647955396388013760

Validation

A check is performed to ensure the device that’s being claimed has not already been assigned to any network within the organization. If it has, then the details of the network are fetched and returned, along with the status error.

Error Handling

Each error thrown is assigned a code:

• 401: The device that’s being claimed is already assigned to a network within the organization

Response

If the device has been successfully claimed, the following parameters are returned:

• Code: 200
• Status: success

Any other response can be considered a failure.

Example Success Output

{
  "code": 200,
  "status": "success",
  "description": "All is Well"
}

Example Error Output

{
  "code": 401,
  "status": "error",
  "description": "The device with Serial Number 1234-1234-1234' is already assigned to an Organizations network.",
  "errorStack": {
    "id": "N_647955396388014332",
    "organizationId": "12345",
    "type": "wireless",
    "productTypes": [
      "wireless"
    ],
    "name": "demo network",
    "timeZone": "America/New_York",
    "tags": " demo iap ",
    "disableMyMerakiCom": false,
    "disableRemoteStatusPage": true,
    "enrollmentString": null
  },
  "errorRecommendation": "Check the serial number of the device. If you believe it to be correct, try moving the device from its existing network to the new one."
}

Additional Information

Please use your Itential Customer Success account if you need support when using this artifact.