It is possible to use the Forward Enterprise API to automate integration with your change control process. 

For example, suppose you manage Change Control work using a system like ServiceNow to document the owner of a change, the devices involved, the state of the change, and the change results. You may want to trigger the creation of a workspace network and collection via the API. 

Forward Networks integrates with ServiceNow for ticket creation and CMDB management, but there is not a specific integration for Change Control. However, if your ticketing/workflow system supports running API calls, you can trigger Forward API calls to automate your workflow.

Suppose your Change Control Process is the following:

1. Create a ServiceNow ticket to track the change.
2. Add a work plan, including the devices that are part of the change, to the ticket.
3. Create a Workspace Network in Forward Enterprise with the devices in the change.
4. Define NQE queries to validate the state of the network before and after the change (for example, what is the state of all the BGP peers on the devices in the change?)
5. Run a pre-change collection on the Workspace Network.
6. Apply the changes in the maintenance window.
7. Run a post-change collection on the Workspace Network.
8. Compare the state of the network between snapshots using the Diffs feature
9. Save relevant files from the change to ServiceNow. (optional)

This article demonstrates the API calls you’ll make to verify your Change Control process.

See the following article on how to run some of these Change Control verifications manually  https://community.forwardnetworks.com/change-management-96/using-intent-checks-to-verify-a-change-control-536

Steps 3, 5, 7, and 9 above can be automated using the API, and you can insert a link into your ServiceNow ticket that will take the user directly to the Diff output for the change.

Below is a detailed description of the APIs that would be required to accomplish this task.

It is assumed here that the developer is managing the API workflow from within the ticketing/workflow system and is able to parse JSON output between API calls using something like javascript.

API Calls Required for Change Control integration

Create an API key using a service account.

The API key will have access to Forward Networks that match the user permissions of the service account. 

Note: All of the API calls mentioned below can used can be viewed and tested from https://fwd.app/api-doc

Since a workspace network is created from a parent network, you need the networkId of the parent network. You can find it in the URL when you have your main network selected. In the screenshot below, the networkId is 153030.

Create a Workspace network

Use a POST API call to generate the Workspace Network 

https://fwd.app/api/networks/{networkId}/workspaces

The networkId is the id of the main network. The body of the API call is needed here to give the workspace network a name and specify what devices are in the network. Note also that we give the workspace network a retention period of 30 days. Consult https://fwd.app/api-doc for additional fields for this or any other API call.

The screenshot below is showing an API call plug-in for VSCode. The API key and password have already been entered on the Auth page (not shown)

The response code should be 200 OK and look something like this:

{
  "creator": "forward-api-test@test.com",
  "secondsToExpiry": 604796,
  "name": "CHANGE: 101",
  "id": "300015",         <----- This is the networkId of the workspace network that was just created.
  "parentId": "153030",
  "createdAt": 1744445805385,
  "note": "For change window 2025-4-30",
  "retentionDays": 7,
  "orgId": "1234",
  "creatorId": "12345"
}

The networkId for the Workspace Network just created (300015) will be needed from the JSON output for the next step.

Trigger a collection of all devices in the Workspace Network

When the user reaches the step in the workflow to perform pre-change checks, you can trigger a collection of all the devices in the Workspace Network as follows:

POST - https://fwd.app/api/networks/300015/startcollection

Every time a collection is run, Forward Enterprise connects to all devices and cloud instances in the workspace via SSH or API and collects configuration and state data. The time required for this step depends on the number of devices, size of the files, network latency, etc.

For all of the remaining steps below, you need to know the snapshotId of each snapshot you want to perform an action on. You also need to verify that the workspace network collection and processing is complete. Many of the API calls that follow will fail if the snapshot is not finished processing.

Gets a list of all snapshots in a network

First, we get a list of all the snapshots in the network.

GET - https://fwd.app/api/networks/300015/snapshots

{
  "creator": "forward-api-test@test.com",
  "secondsToExpiry": 604787,
  "name": "CHANGE: 101",
  "id": "300015",
  "parentId": "153030",
  "createdAt": 1744896805385,
  "note": "For change window 2025-4-30",
  "retentionDays": 30,
  "orgId": "1234",
  "creatorId": "12345"
  "snapshots": 2
    {
      "id": "655104",    <-------------------- The most recent snapshot that we just triggered.
      "processingTrigger": "COLLECTION",
      "totalDevices": 2,
      "creationDateMillis": 1744897351132,
      "processedAtMillis": 1744897360153,
      "oldestCollectionMillis": 1744897302652,
      "latestCollectionMillis": 1744897350708,
      "isDraft": false,
      "state": "PROCESSED"
    },
    {
      "id": "655100",
      "note": "Initial subset of parent snapshot 153030",
      "processingTrigger": "IMPORT",
      "totalDevices": 2,
      "creationDateMillis": 1744859660200,
      "processedAtMillis": 1744896810791,
      "isDraft": false,
      "state": "PROCESSED"
    }
  ]
}

From the above the JSON output, you can obtain the snapshotId. The most recent snapshot collected is listed first. If the state does not show “processed”, you need to wait before performing other actions.

Verify that your Workspace network snapshot has completed and is processed

To check that a single snapshot has completed and is processed, use the following API call. (You could re-run the call every 5 minutes until processing is complete).

GET - https://fwd.app/api/snapshots/655104/metrics

{
  "snapshotId": "655104",
  "needsReprocessing": false, 
...
...
}

The false response here tells us that the snapshot has been processed. It does NOT need reprocessing.

Once the pre-change snapshot is confirmed, the user can proceed with their maintenance work.

After applying your Change Window modifications, trigger the API to create another snapshot of your Workspace network

POST - https://fwd.app/api/networks/300015/startcollection

Get the snapshotId of your post-change snapshot

Run the list snapshots API again to get the latest snapshotId and verify that processing is complete once again.

GET - https://fwd.app/api/networks/300015/snapshots

Now you will have two snapshotIds to compare, say 655104 and 655105.

Send other users a link to the Workspace Network

The format of the link will be:

https://fwd.app/?/search?networkId=300015

This will take the user straight to the workspace network 300015.

Send other users directly to the Diff in Forward

You could also direct the user straight to the diff between the two snapshots

https://fwd.app/?/diffs?networkId=300015&snapshotId=655104&baseSnapshotId=655105   

You can construct the above URL from the network and snapshot IDs obtained from the previous API calls.

The Diff feature page is the easiest way for the user to compare pre and post change config and state files, as well as the results of NQE queries in the inventory.

Use API to extract before and after files / NQE check results

You can also using API calls to extract the before and after files or the results of an NQE check before and after the change. Remember that this output will be less readable than in the platform, but can be saved indefinitely in ticketing/workflow system.

Example: NQE query to list state of BGP neighbors before and after a change. 

Suppose you have an NQE query that lists the state of BGP neighbors on all the devices in the network. The user can view these change from Diffs page. You can also export the table of differences in BGP state using an API call to the NQE query.

For example, this NQE query lists the BGP neighbors and their state.

/*
 * @intent Verifies that enabled BGP peerings are established
 */

foreach device in network.devices
foreach networkInstance in device.networkInstances
foreach protocol in networkInstance.protocols
where isPresent(protocol.bgp)
let bgp = protocol.bgp
foreach neighbor in bgp.neighbors
where isPresent(neighbor.sessionState)
where neighbor.enabled
select {
  violation: neighbor.sessionState != BgpSessionState.ESTABLISHED,
  deviceName: device.name,
  protocolIdentifier: protocol.identifier,
  neighborNeighborAddress: neighbor.neighborAddress,
  sessionState: neighbor.sessionState,
  neighborDevice: neighbor.peerDeviceName

}

Obtain the NQE query by find the Qid from the (i) next to the query name in the NQE Library.

Call your BGP NQE from the API

Then use the following API call to run the NQE query and see the diffs between two snapshots:

POST - https://fwd.app/api/nqe-diffs/655104/655105

BODY:

{
  "queryId": "Q_e59d897e165e45e7249f91c35ac9d74f6cd534e6"
}

The JSON output from this query will provide a table which includes BGP neighbors that were added, changed, or modified during the change.

{
  "totalNumRows": 3,
  "rows": d
    {
      "type": "ADDED",
      "after": {
        "violation": false,
        "deviceName": "router-1",
        "protocolIdentifier": "BGP",
        "neighborNeighborAddress": "10.1.1.2",
        "sessionState": "ESTABLISHED",
        "neighborDevice": null
      }
       {
      "type": "MODIFIED",
      "before": {
        "violation": false,
        "deviceName": "router-1",
        "protocolIdentifier": "BGP",
        "neighborNeighborAddress": "169.254.2.2",
        "sessionState": "ESTABLISHED",
        "neighborDevice": null
      },
      "after": {
        "violation": true,
        "deviceName": "router-1",
        "protocolIdentifier": "BGP",
        "neighborNeighborAddress": "169.254.2.2",
        "sessionState": "IDLE",
        "neighborDevice": null
      }
    }
  ]
}

Some final thoughts.

We did not show how to list the files for each device and download them. This can be done and will require multiple API calls depending on which files you want to pull, but all the API calls needed are listed in this section of the documentation.

https://fwd.app/api-doc#network-snapshots

Briefly, you would need to run an API to list the files collected for each device, then an API call to download each file to the ticket/workflow system.