Skip to main content
Index

Overview

What is Equinix Messaging Gateway?

 

Equinix Messaging Gateway (EMG) is an event-driven messaging solution offered by Equinix to customers as a contemporary to REST API communication. EMG leverages message queuing solutions to enable customers to place orders and tickets using a simple message format. The core value proposition for the message-driven interface is its scalability, security & simplicity.

 

EMG is suitable for customers who:

  • utilize multiple colocation or network infrastructure providers.
  • have significant asset presence in Equinix and other Infrastructure Partners.
  • have their own unified central application for control of services from Infrastructure partners.
  • are a large email user for operational control.
  • believe the current methods of datacenter operation control (emails) are predicted to be an impediment to growth.

 

How does Equinix Messaging Gateway work?

 

Customer Onboarding

1. When a customer is on-boarded, they are provided with a unique customer identifier, which must be included in each message sent to Equinix. Along with the identifier, Equinix and customer will also exchange the queue details.  

 

 

2. Customer & Equinix will generate public-private key pair & exchange the public keys (pkcs8). Customer must use its private key to sign each message sent to Equinix.  Once the message is received, Equinix will use the customer’s public key to verify the message. Similarly, Equinix will sign each message sent to the customer. On receiving the message, customer will use Equinix public key to verify the message.

 

 

3. The customer must work with their CSM and Master Administrators to get access to Equinix Developer Platform and generate a Consumer Key (Client ID) and Consumer Secret (Client Secret). This Consumer Key and Secret must be generated for a user who has access to all customer assets and permission to submit tickets with Equinix. The Consumer Key and Secret must then be shared with Equinix when configuring EMG.

 

 

Message Format

All incoming and outgoing messages between Equinix and the customer will have the following components:

 

​Task

  • Header attributes
  • Body

Signature

 

Below is the EMG message structure and a sample incoming message.

 

Message skeleton

{
  "Task": {
    "Header attribute 1": "",

    "Header attribute 2": "",

    "Header attribute 3": "",

    ...

    "Body": {

      "Body attribute 1": "",
      "Body attribute 2": "",
      "Body attribute 3": "",

      ...
    }
  },
  "Signature": "Base 64 encrypted signature"
}

 

Sample incoming message 

{
  "Task": {
    "Id": "bf9f2707-d612-4d63-9958-4c8b1fcf3cc0",
    "Verb": "Create",
    "Source": "3e095d30-40ff-11e9-8959-5be078353003",
    "Version": "1.0",
    "Resource": "BreakFix",
    "ContentType": "application/json",

    "Body": {
      "CustomerContact": "demo@equinix.com",

      "Device": "MIA-96CBE-1A|Juniper MX960-PREMIUM2-AC |JN11D5FE4AFA",

      "DueDate": "2019-12-20T18:25:43.511Z",

      "Location": "LD9:0G:00Z12B:0105",

      "Severity": 3,

      "Operation": "0004/0000",

      "Description": "Create Trouble ticket",

      "RequestorId": "68efabd9-5e05-4bbf-adac-946e1573fa66",

      "RequestorIdUnique": false
    }
  },
  "Signature": "RWNobwp7CiAgIklkIjogIjM1MGFlZjcwLTc4MWIt9keSI6IHsKICAZXVlIgogIH0KfQ=="
}

 

The description of the message structure is as follows:

Message component Attribute Mandatory Type Applicable Values Description
Task Id Yes String (Guid)  

The unique identifier of the message. Customers must ensure to send a unique value for each message.

Source Yes String (Guid)  

A unique value to identify the message sender. Equinix will share this value with the customer during the onboarding process.

Verb Yes String

Create

Update

Ack

The action to be performed by Equinix. In other words, create a new order, update an existing order.

"Ack" is used by Equinix “to acknowledge" the message sent by customers.

Resource Yes String

BreakFix

Shipping

SmartHands

WorkVisit

Echo

Name of the resource. 

ContentType Yes String application/json  
Version Yes String 1.0 The version of the request and response schema.
Body Yes Object   An object containing the details of the order. The attributes within the object will vary based on the resource and verb. Refer to the How to guide section for more details.
Signature     String  

Base64 encoded signature of the "Task's" value.

 

Sample outgoing message  

{
  "Task": {
    "Id": "4f6ec8d0-902f-4892-aa31-8bfed1edc075",
    "Source": "3e095d30-40ff-11e9-8959-5be078353003",
    "Version": "1.0",
    "Resource": "SmartHands",
    "Verb": "Update",     
    "ContentType": "application/json",
    "CreationTimeUTC": "2020-05-21T02:08:11.471Z",
    "Body": {
      "RequestorId": "123456789",
      "ServicerId": "1-199912345789",
      "State": “InProgress",
      "Description": "Ticket 1-199912345789 has been updated to InProgress state."
    }
  },
  "Signature": "RWNobwp7CiAgIklkIjogIjM1MGFlZjcwLTc4MWIt9keSI6IHsKICAZXVlIgogIH0KfQ=="
}

 

The description of the outgoing message is as follows:

Name Type Description
Task Object The task object comprises a common set of header attributes and a unique set of body attributes. The header attributes are applicable to all order types, whereas the body attributes vary for each order.
ID String (Guid)

The unique identifier of the message. Equinix will send a unique value for each message.

Source String (Guid) A unique value to identify the message sender. This value will be shared with the customer during the onboarding process.
Verb String

Indicates the action type. Applicable values are "Ack" and "Update". 

 

The value "Ack" is “to acknowledge" the message sent by customers.

 

The value "Update" is to provide update on the latest status of the submitted order.

Resource String

Indicates the order type. 

 

Supported Values - BreakFix, SmartHands, WorkVisit, Shipping

ContentType String  
CreateTimeUTC String Indicates the date and time at which the Trouble Ticket order was created at Equinix's end.
Version String The version of the request and response schema.
Body Object

An object containing the details of the order. The attributes within the object will vary based on the resource and verb.

RequestorId String

The customer's reference number for this Trouble Ticket order. 

ServicerId String

Indicates the Trouble Ticket order ID generated by Equinix after the order was submitted.

StatusCode String

The HTTP status code of the request.

 

This attribute is returned if "Verb" = "Ack"

State String

The current state of the submitted order.

 

This attribute is returned if  "Verb" = "Update"

 

Supported values:

 

Open - Customer order has been successfully submitted into Equinix IT systems.

 

InProgress - Customer order is being worked on by Equinix Datacenter Technician.

 

Closed - Customer order has been successfully completed by Equinix Datacenter Technician.

 

Cancelled - Customer order has been cancelled in Equinix IT systems based on customer request.

 

Pending Customer Input - Equinix Datacenter Technician has requested for additional information while working on customer order.

Description String

Additional details of the order created

 

Ex: "Ticket 1-199912345789 has been updated to InProgress  state."

Attachments Array [{ String,  String }]

Includes all attachments for this request.


Supported Value: [{"Name":<Attachment_Name>, "Url":<Attachment_URL>}]

 

5 files with 5MB size each

 

Supported filetypes: .bmp,.jpeg,.jpg,.gif,.png,.tif,.txt,.doc,.docx,.xls,.tiff,.xlsx,.ppt,.pptx,.pdf,.vsd,.pps,.ppsx

Signature String Base64 encoded signature.

 

EMG Workflow

 

The following diagram illustrates a high-level workflow of how EMG works using Microsoft Azure Service Bus messaging. 

 

 

 

Step 1  - Customers places an order to Equinix by creating a message based on a pre-agreed format.

 

Step 2  - The message is pushed into an Equinix owned queue.

 

Step 3  - Equinix reads the queue and processes the request.

 

Step 4  - Once the message is processed. Equinix creates a response message. 

 

Step 5  - The response message will be pushed into a customer outgoing queue.

 

Step 6  - The customer processes the incoming message.