vRealize Automation Notification Service API

Notification Service API Specification

What Is the Notification Service REST API?

The notification service supports configuring and sending notifications for several types of events, such as the successful completion of a catalog request or issuance of a catalog request that requires approval.

Typical Use Cases

By using the notification service:

• System administrators can configure global email servers that process email notifications using the NotificationProvider resource.

• Tenant administrators can override the system default servers, or add their own servers if no global servers are specified.

Tenant administrators select which events will cause notifications to be sent to users in their tenants using the NotificationScenarioConfiguration resource. Each component, such as the service catalog or IaaS, can define events that can trigger notifications. Notifications for all event are enabled by default.

Each user can choose whether to receive notifications using the UserNotificationPreference resource. Users either receive all notifications configured by the tenant administrator or no notifications, they do not have fine-grained control over which notifications to receive.

Some emails have links that users can use to respond to the notification. For example, a notification about a request that requires approval can have one link for approving the request and one for rejecting it. When a user clicks one of the links, a new email opens an automatically generated subject line. The user can send the email to complete the approval.

See the documentation for each REST resource for more details.

Key Concepts

Tenant Id

Because vRA supports multitenancy, some notification URIs must reference the tenantId that you are interested in. Exceptions include the system admin APIs,` which can be shared across tenants.

Use the URL attribute of your tenant for all URIs requiring a tenantId. For example, if your "Development" tenant accesses vRA via the URL https://vcac.server/vcac/org/dev, then dev is what you should use when the API calls for a tenantId.

Notification Preferences

Each user can choose whether to receive notifications using the UserNotificationPreference resource. Users either receive all notifications configured by the tenant administrator or no notifications, they do not have fine-grained control over which notifications to receive.

In addition to specifying a preference whether to receive email or not, users can specify the locale in which email should be sent to the user.

API Usage Examples

This section gives usage examples for requesting data for all tenant notification providers and for creating a notification provider.

Requesting Data for All Notification Providers

Example Request

Be sure to replace ${tenantId} appropriately:

GET /api/notifications/tenants/{tenantId}/providers?offset=0&limit=10
Accept: application/json

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "links": [],
  "content": [{
    "@type": "EmailNotificationProvider",
    "id": "4bd085ca-09b1-47d5-8fce-695163e6cc08",
    "version": 0,
    "name": "vRA global, outbound email notification provider",
    "description": null,
    "type": "EMAIL_PROVIDER",
    "providerDirection": "OUTBOUND",
    "providerMode": {
      "role": "GLOBAL",
      "overriddenGlobalProviderId": null
    },
    "serverName": "smtp.example.com",
    "protocol": "SMTP",
    "port": 25,
    "sslEnabled": false,
    "username": "vcac",
    "password": null,
    "authenticationRequired": true,
    "emailAddress": "vcac@example.com",
    "deleteMessagesAfterRead": false,
    "folder": "INBOX",
    "selfSignedCertificateAccepted": true
  }],
  "metadata": {
    "size": 10,
    "totalElements": 1,
    "totalPages": 1,
    "number": 1,
    "offset": 0
  }
}

Creating a Notification Provider

Example Request

Be sure to replace ${tenantId} appropriately:

POST /api/notifications/tenants/{tenantId}/providers
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "@type": "EmailNotificationProvider",
  "name": "vRA global, outbound email notification provider",
  "type": "EMAIL_PROVIDER",
  "providerDirection": "OUTBOUND",
  "providerMode": {
    "role": "GLOBAL"
  },
  "serverName": "smtp.example.com",
  "protocol": "SMTP",
  "port": 25,
  "sslEnabled": false,
  "emailAddress": "vcac@example.com",
  "selfSignedCertificateAccepted": true,
  "username": "vcac",
  "password": "password"
}

Example Response

Response Headers
{
HTTP/1.1 201 Created
           Date = Fri, 04 Apr 2014 17:04:10 GMT
           ETag = "0"
       Location = https://vcac.server.com/notification-service/api/notifications/global/providers/df29347f-6795-41c0-aab7-a1ca9f317ad9
   Content-Type = application/json;charset=UTF-8
 Content-Length = 0
           Vary = Accept-Encoding,User-Agent
     Keep-Alive = timeout=15, max=100
     Connection = Keep-Alive
}