Equinix Messaging Gateway
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.
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.