Templates for Equinix Messaging Gateway

Equinix offers an event-driven system called Equinix Messaging Gateway (EMG). The EMG system enables system-to-system integration from your in-house application to Platform Equinix. Use EMG to:

Create/update/cancel orders & receive order status notifications for subscribed Equinix Products & Services - Cross Connect, Shipments, SmartHands, Trouble Tickets, Work Visit.
Receive status notifications on provisioned Equinix Fabric Ports & Virtual Connections
Receive notifications for planned/unplanned maintenance at Equinix DataCenters
Billing Notifications when your submitted order is closed & billing is started by Equinix

Learn more about Equinix Messaging Gateway by visiting this link, or you can watch the EMG Overview video here.

To subscribe to EMG, visit the Subscriptions page in the Equinix Developer Platform to get started. Watch this video for the step-by-step guide on how to subscribe. Alternatively, you can also reach out to your Equinix Customer Success Manager.

Equinix Messaging Gateway (EMG) Templates provide reference code to seamlessly integrate with EMG. These Templates are available in three versions – Node.js, Python and Java. You can refer, use, modify & extend EMG Templates based on your architecture & security policies.

Template Details

The Templates includes:

Order Templates with sample code for order management - create, update & cancel orders with Equinix:
- /template-nodejs-v1
- /template-python-v1
- /template_java_v1
Notification Templates with sample code to receive notifications from Equinix:
- /template-nodejs-outgoing-notifications-v1
- /template-python-outgoing-notifications-v1
- /template-java-outgoing-notifications-v1
Order Templates includes individual templates with sample code to create/update/cancel Equinix orders for supported Equinix Orders & Services:
- /EquinixCrossConnectTemplate
- /EquinixSmartHandsTemplate
- /EquinixTroubleTicketTemplate
- /EquinixWorkVisitTemplate
- /EquinixShipmentsTemplate
Order Templates also includes TestClient with sample code on how to send request & receive response from EMG Templates using EMG message schemas. Visit How To Guide to know about EMG request & response schemas for supported Equinix Products & Services
- /test/TestClient
Configurations for EMG queues. These configurations will be provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in config file at below location:
- /config/config

Requirements

Node.js Templates
- Node.js v10.16.2+
- Visual Code (https://code.visualstudio.com/)
Python Templates:
- Python - v3.8.5+
- Azure SDK for Python - v0.50.3+
- pytest - v6.0.1+
- pytest-asyncio - v0.14.0+
Java Templates
- Java 8 & above
- IntelliJ IDEA or Eclipse IDE

Prerequisites

An existing subscription with EMG is required in order to use our Templates. Visit the Subscriptions page in the Equinix Developer Platform to get started. Alternatively, you can also reach out to your Equinix Customer Success Manager.
Visit Equinix Developer Platform & follow the steps to generate Equinix Client ID and Client Secret keys.
You must have authorized permissions by your Master Administrator to order and receive notifications for Equinix Products & Services.

How to Run EMG Templates

Node.js Templates:
1. SDK Setup:
  - Download & import the Node.JS EMG Template project to Visual Code.
  - Run npm install from the root directory to install azure-bus package and other dependent libraries as per “package.json”.
  - Search & Install “Mocha Test Explorer” plugin from Visual Code Marketplace.
  - Select the EMG template project in Visual Code & click on Debug icon.
  - When promoted, click on “create a launch.json file” and select “Node.js”. This will create “.vscode” folder.
  - Right click on “.vscode” folder, create a new file call “settings.json” & insert below lines into the newly created file.
```
{
  "mochaExplorer.files": [
      "test/*.js"
  ],
  "mochaExplorer.logpanel": true
}
```
  - Update /config/config.js with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in the config file.
  - Save all the files & restart Visual Code editor
2. Create/Update/Cancel Orders through EMG for supported Equinix Product & Services.
  - Update values of CLIENT_ID and CLIENT_SECRET with Consumer Key & Consumer Secret generated by you while subscribing to EMG through Equinix Developer Platform.
  - Navigate to test/TestClient and run intended test for intended order operation for supported Equinix Product & Services.
  - You would need to update the request packet for each test with applicable values based on your Assets & presence within Equinix. Visit How To Guide to know about EMG request & response schemas for supported Equinix Products & Services
  - On successful processing of the of the Equinix order, output will be displayed on the Visual Code console. (Toggle to Test Explorer view)
  - After creating an order, take note of the ServicerId displayed in the console, and replace the ORDER_NUMBER constant in TestClient to successfully run the test for update & cancel order operations.
3. Receive Notifications from EMG:
  - Download & import the Node.JS EMG Template project (/template-nodejs-outgoing-notifications-v1) to Visual Code.
  - Update /config/config.js with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in the config file.
  - Save all the files & restart Visual Code editor
  - Run npm install from the root directory to install azure-bus package and other dependent libraries as per “package.json”.
  - Now open the Terminal window of Visual Code and execute the below command on the root location:
    - node EquinixNotificationListener.js
  - Above command would spin an indefinite listener on customer’s queue where messages would be received instantly whenever any new notification message pushed to the queue from Equinix.
Python Templates:
1. SDK Setup:
  - Download & import the Python EMG Template project to Visual Code.
  - Setting up environment
  - Execute below command on the terminal to create a new virtual environment.
    - py -3 -m venv .venv
  - Activate the new virtual environment using the below command
    - .venv\scripts\activate
  - Install Azure Service Bus Package
```
pip install azure-servicebus
```
  - Install pytest framework to run Test Client:
```
pip install pytest

pip install pytest-asyncio
```
  - Update /config/config.py with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in the config file.
2. Create/Update/Cancel Orders through EMG for supported Equinix Product & Services.
  - (Refer to the same section in Node.js Templates)
3. Receive Notifications from EMG:
  - Download & import the Python EMG Template project (template-python-outgoing-notifications-v1) to Visual Code.
  - Install Azure Service Bus Package
```
pip install azure-servicebus
```
  - Install pytest framework to run Test Client:
```
pip install pytest

pip install pytest-asyncio
```
  - Update /config/config.py with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in the config file.
  - Now open the Terminal window of Visual Code and execute the below command on the root location
    - python equinix_notification_listener.py
  - Above command would spin an indefinite listener on customer’s queue where messages would be received instantly whenever any new notification message pushed to the queue from Equinix
Java Templates
1. SDK Setup:
  - Download and import the Java Template project into the Java IDE of your choice - Intellij IDEA or Eclipse IDE
  - Run the below script from with the parent folder \template_java_v1
    - mvn install
  - Ensure all the dependent libraries are successful installed under ‘External Libraries’ of your project.
  - Update /config/config.java with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the placeholders provide in the config file.
2. Create/Update/Cancel Orders through EMG for supported Equinix Product & Services.
  - (Refer to the same section in Node.js Templates)
3. Receive Notifications from EMG:
  - Download and import the Java Template project (template-java-outgoing-notifications-v1) into the Java IDE of your choice - Intellij IDEA or Eclipse IDE
  - Run the below script from with the parent folder \template-java-outgoing-notifications-v1
    - mvn install
  - Ensure all the dependent libraries are successfully installed under ‘External Libraries’ of your project.
  - Update /config/config.java with EMG configurations (queues connection string etc.) provided by Equinix when you subscribe to EMG. Copy the YAML from your EMG subscription details on Equinix Developer Platform & override the place holders provide in the config file.
  - Now click on the Debug icon next to “EquinixNotificationListener” drop down.
  - This would open a new terminal and spin an indefinite listener on customer’s queue where messages would be received instantly whenever any new notification message pushed to the queue from Equinix.

Tutorials

See the links below for the tutorials on how to use our EMG Templates for different scenarios:

equinix / messaging-gateway-templates