Subscriptions

Subscriptions

#340690

Description

The /subscriptions/<platformType> resource is used to create and manage subscription-based notifications for Densify cloud and container recommendations. This resource allows you to set up and schedule the delivery of personalized Densify recommendations to a third-party application for targeted distribution.

Personalization of the recommendation data set (returned subscription notification output) is facilitated by the following mechanisms:

  • Return only the systems you are interested in by specifying system attribute conditions with the tagReferences parameter.
  • Return only specific recommendations you are interested in by specifying recommendation property conditions with the propertyReferences parameter.
  • Suppress certain systems or recommendations in the returned output, for a period of time, with the suppressionReferences parameter.
  • Finally, the fields and attributes displayed in the returned output can be customized with the returnStructure parameter. You can specify which recommendation field to display and whether to display the field name or the field alias as the element key.

Subscription notifications are delivered to a third party application, such as Webex Teams or Slack, using the webhook definition. If you do not specify a webhook in your Subscriptions definition, the notifications are not triggered because there is no delivery location. See Subscriptions: Status for details on Subscriptions results and webhook status.

You can dynamically retrieve the current personalized Subscriptions recommendations by providing a subscription ID in the GET subscription request. See Subscriptions: Results for details on retrieving Subscriptions results on-demand.

You can also schedule the frequency of the notification distribution using the schedule definition parameter. Subscriptions without a schedule definition will typically have notifications triggered nightly after recommendation analysis and reporting database updates.

Resource

/subscriptions/cloud

/subscriptions/containers

/subscriptions

Note: If you use this resource without the <platformType> specified (i.e. without cloud or containers specified), the behavior is exactly the same as specifying the cloud-specific resource. This behavior enables backward compatibility with scripts using the Densify API prior to release 12.1.6, where the platform-specific indicator was not available.

Supported Operations

Table: Subscriptions Supported Operations

HTTP Method

Input

Output

Description

GET /subscriptions/<platformType>

Path Parameter:

Query String Parameter:

Collection of

Returns a list of existing platform-specific subscriptions in Densify.

Example: Getting a Collection of Subscriptions

Example: Getting a Collection of Subscriptions for a Specific User

POST /subscriptions/<platformType>

Path Parameter:

Collection of

Request Body Parameters:

Collection of

Creates and defines a collection of platform-specific subscriptions.

Example: Creating a New Subscription

PUT /subscriptions/<platformType>/<subscriptionId>

Path Parameters:

Request Body Parameters:

Deletes and replaces all the parameters in an existing platform-specific subscription definition.

You must specify all parameters (from the Request Body Parameters section) required for the existing subscription.

For any parameter replacement failure, an appropriate error message will be returned in the response body. See status for possible error status.

Example: Modifying a Subscription

Note: If you are not an administrative user, you can only modify your own private subscription.

DELETE /subscriptions/<platformType>

Path Parameter:

Collection of

Request Body Parameters:

Note:

  • HTTP status "204 No Content" is returned for successful deletions.
  • HTTP status "404 Not Found" is returned if the subscription does not exist or you have no privilege to access the subscription.

Deletes a collection of your private platform-specific subscriptions.

If you are an administrative user, use this method to delete any private or global platform-specific Subscriptions collections.

Each subscription delete operation is independent from the other subscription delete operations in the same request. An error with one subscription delete action does not affect the delete actions of the other subscriptions in the same request body parameter .

DELETE /subscriptions/<platformType>/<subscriptionRef>

Path Parameters:

Note:

  • HTTP status "204 No Content" is returned for successful deletions.
  • HTTP status "404 Not Found" is returned if the subscription does not exist or you have no privilege to access the subscription.

Deletes one platform-specific subscription definition from Densify.

If you are an administrative user, use this method to delete any private or global subscription. Otherwise, if you are a non-administrative user, use this method to delete one of your private subscriptions.

Example: Deleting a Subscription

Parameters

Path Parameters

Table: Subscriptions Path Parameters

Parameter Name

Type

Required (Y/N)

Description

platformType

string

Y

[cloud|containers]

Specify the technology platform for the subscription resource.

subscriptionRef

string

Y

Specify the unique subscription identifier.

Query String Parameters

Table: Subscriptions Query String Parameters

Parameter Name

Type

Required (Y/N)

Description

type

string

 

Specify the type of subscription to return:

  • all—(default) Return all subscriptions: global and private user-specific. If you are not an administrative user, only private subscriptions owned by you and global subscriptions are returned. This is the default behavior if "type" is not specified in the request.
  • global—Return all global subscriptions.
  • owner—Return user-specific subscriptions. If you are not an administrative user, only private subscriptions owned by you are returned. If you are an administrative user, all global and private subscriptions are returned. Typically, this option is used in conjunction with the owner query string parameter.

A subscription is considered global if the owner parameter is not populated. Global subscriptions can be used by all Densify API users.

A subscription is considered private if the owner parameter contains a Densify username. Private subscriptions can only be used by their owners or administrative users.

owner

string

 

If you are an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., you can specify a Densify username in conjunction with the type=owner query string parameter to return all of the specified user's private subscriptions.

If you are not an administrative user, you can only request for your own private subscriptions. If you use the ?type=owner&owner=<anotherusername> query string option with a username other than your own, the returned response is a 400 Bad Request -"Current login user cannot query for owner" error.

subscriptionRef

string

 

Specify the identifier of the subscription details to return.

Request Body Parameters

Table: Subscriptions Request Body Parameters

Parameter Name

Type

Required
(C-create/M-modify/D-delete)

Description

subscriptionRef

string

D

Specify the unique subscription identifier to delete.

subscriptionName

string

C M

Specify a name for this subscription.

For global subscriptions, the subscriptionName must be unique per platform. For private subscriptions, the subscriptionName must be unique per owner and across all global subscriptions for a particular platform. For example, owner A and owner B can both have a private cloud subscriptionName named "SubA", as long as "SubA" is not also a global cloud subscription.

owner

string

M1

When the owner parameter is not set, the subscription is considered global. Global subscriptions can be used by all Densify API users. Only administrative usersClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role. can create global subscriptions. When the owner parameter is set, the subscription is considered private. Private subscriptions can only be used by their owners or administrative users.

If you are an administrative user, you have the ability to assign any Densify user as the owner of the subscription in a POST request. In a PUT request, administrative users can promote the subscription from private to global by setting owner: "".

If you are not an administrative user, you can only set the owner parameter to your username. In a POST request, the owner parameter is automatically set to your username.

description

string

 

Specify a description for subscription.

outputType

string

 

application/json is the only supported type.

active

string:

[true|false]

 

Specify if the subscription is active:

  • true—The subscription is active and notifications are triggered at the scheduled times to the webhook defined.
  • false (default)—The subscription is dormant: no subscription notification is triggered, even if webhook and schedule parameters are defined.

Setting the subscription to dormant allows you to temporarily disable the subscription notification without modifying the subscription configuration. Dormant subscriptions can also be used as an example or template for future subscription creation.

Results from dormant subscriptions can be requested on-demand. See Subscriptions: Results.

propertyReferences

array of property conditions:

  • propertyID
  • operator
  • values

C M2

Specify an array of property conditions to filter the customized data set.

The following items need to be specified for each property condition:

  • propertyID—specify a global property reference or a private property reference owned by you (see propertyID | tagID | suppressionID);
  • operator—specify the comparison operator (see operator);
  • values—specify the array of comparison values (see values).

See Filter and Suppression Conditions for details on how to define property conditions.

The platform of the properties defined in property conditions must match the subscription's platform. For instance, you must only use container properties for a container subscription.

Refer to Default Cloud Properties for the list of default properties to use in your array of property conditions.

Note: You must have at least one core property in your property condition set for the purpose of filtering subscription returned results. Refer to Core and Ancillary Properties in Filter Conditions for details.

tagReferences

array of:

  • tagID
  • operator
  • values

C M3

Specify an array of attribute tag conditions to filter the customized data set.

For example, if you want to return only recommendations for systems in the ABC account, in the Marketing business unit, and running the Demo application, then you would define tagReferences conditions where account="ABC", business_unit="Marketing", and app="Demo".

The platform of the tags defined in tag conditions must match the subscription's platform. For instance, you must only use cloud tags for a cloud subscription.

Each tag condition contains the following items:

Refer to Filter and Suppression Conditions for details on how to define tag conditions.

suppressionReferences

array of suppression conditions:

  • suppressionID
  • operator
  • values
  • revokeBy (optional)

C M4

Specify an array of suppression conditions to determine systems to be excluded from the notification data set.

For example, if you want to remove all "m3" systems from the results data set for this month, then you would create a suppression list with currentType="m3*" that will expire at the end of the month.

The platform of the suppressions defined in suppression conditions must match the subscription's platform. For example, you must only use cloud suppressions for a cloud subscription.

Each suppression condition contains the following items:

  • suppressionID—specify the global or private suppression reference owned by you (see propertyID | tagID | suppressionID);
  • operator—see operator;
  • values—see values;
  • revokeBy (optional)—the time when the suppression condition expires (in Unix-time format); if revokeBy is not specified, then the suppression condition does not expire.

Refer to Filter and Suppression Conditions for details on how to define conditions.

webhook

  • uri
  • authType
  • authValue
 

Specify the webhook definition to an external application, where your personalized recommendations will be sent.

See Analysis: Webhook: Request Body Parameters for details of each parameter in the webhook definition.

If you do not specify a webhook definition, then notifications for this subscription are not triggered.

schedule

  • dayOfMonth
  • dayOfWeek
 

Specify the frequency of the subscription notifications.

If no schedule is specified, then the subscription notification is triggered after daily Densify analyses are completed and reporting database tables are updated. Typically, these processes occur at night.

The schedule parameter is defined by one or both of the following options:

  • dayOfMonth—trigger the notification on the specified day of the month (e.g. "dayOfMonth" : [10,20]);
  • dayOfWeek—trigger the notification on the specified day of the week (e.g. "dayOfWeek" : [2,3], where 7=Sunday, 1=Monday, 2=Tuesday, etc.).

If both scheduling options are defined, the scheduling options are logically AND'ed to compute the notification schedule. For example, if dayOfMonth = [1, 10, 20] and dayofWeek = [2, 4], then notifications will trigger on:

  • the 1st, 10th, and 20th of the calendar month,
  • and only if

  • the day is a Tuesday or a Thursday.

returnStructure

  • properties:
    • propertyID
    • useAlias
  • tags:
    • tagID
    • useAlias
 

Specify property and attribute tag references to be included in the output of the subscription notification.

The properties array contains the following items for each property:

  • propertyID—the property reference from the subscriptions property catalog;
  • useAlias—[true|false] indicates if the property alias is used as the element label in the subscription output.

The tags array contains the following items per tag:

  • tagID—the tagreference from the subscriptions attribute tags catalog;
  • usesAlias—[true|false] specifies if the tag alias is used as the element label in the subscription output.

If returnStructure is defined, then only the properties and tags in returnStructure are returned in the output of the subscription notification.

The platform of the tags or properties defined in the returnStructure must correspond with the platform of the subscription. For example, you must only use cloud tag or properties for a cloud subscription.

See returnStructure inside the POST request in Example: Creating a New Subscription.

If returnStructure is not defined, then the full list of possible recommendation properties are returned. The full list of recommendation properties correspond to the technology-specific Analysis recommendation response schema. For example, see Analysis: AWS Recommendations: Response for a full list of AWS recommendation properties.

For auditInfo and dataQuality property structures, you must specify the final properties to return by using the dot-walking syntax for each substructure. For example, if you want all properties of dataCollection substructure within auditInfo to be returned, you need to specify all the final properties in auditInfo.dataCollection:

  • auditInfo.dataCollection.dateFirstAudited
  • auditInfo.dataCollection.dateLastAudited
  • auditInfo.dataCollection.auditCount

Note: Resource attribute string values containing double quotes will be converted to single quotes in the subscription results output.

Filter and Suppression Conditions

Each filter or suppression condition is defined as a set of three parameters:

Copy
{
    "propertyID | tagID | suppressionID": "<GUID>",
    "operator": "<supported logical operator>",
    "values": [<array of values>]

The propertyID | tagID | suppressionID are the unique identifiers to the property, tag or suppression in your Subscriptions catalogs. You can only reference identifiers that are global or privately owned by you. The system property or tag values are compared to the values array provided, based on the logical operator.

For example, if you want to filter cloud systems where "predictedUptime" is between 50-100%:

  1. First, find the propertyRef for the "predictedUptime" property in your Cloud Subscriptions Property catalog:
  2. Copy
    {
        "propertyRef": "f2a38773-db60-478a-9982-1a2d1ba7d380",
        "propertyName": "predictedUptime",
        "aliasName": "propertyPredictedUptime",
        "owner": ""
    }
  3. Use the propertyRef identifier (in the previous step) for the propertyReference condition in your subscription:
  4. Copy
    "propertyReferences": [
        {
        "propertyID": "f2a38773-db60-478a-9982-1a2d1ba7d380",
        "operator": "[]",
        "values": [50,100]
        }
    ]

A subscription can have multiple filter conditions to customize the resulting data set. Each condition referencing an individual property, tag, or operator is logically AND'ed together during evaluation. Conditions referencing the same property or tag with the same logical operator are OR'ed together during evaluation. Systems matching the suppression conditions are removed from the resulting data set.

Note: You cannot compare entire multi-structure recommendation elements, such as auditInfo and dataQuality. You can only use their final substructure properties in the subscription filter condition, such as auditInfo.dataCollection.dateFirstAudited or dataQuality.completedDays.

Table: Logical Evaluation of Multiple Conditions

Logical Evaluation

Property/Tag/Suppression

Operator

AND

  • different property/tag/suppression
  • different or same operator

OR

  • same property/tag/suppression
  • same operator

Note: Suppression conditions are evaluated after property and tag conditions.

Table: Subscriptions Filter and Suppression Condition Parameters

Parameter Name

Type

Required

(Y/N)

Description

propertyID | tagID | suppressionID

string

Y

Specify the reference ID of the property, tag, or suppression from the corresponding catalog:

  • See Subscriptions: Properties to retrieve propertyIDs available in the platform-specific Subscriptions Properties catalog.

  • See Subscriptions: Tags to retrieve tagIDs available in the platform-specific Subscriptions Tags catalog.

  • See Subscriptions: Suppressions to retrieve suppressionIDs available in the platform-specific Subscriptions Suppressions catalog.

You can only use global reference IDs or reference IDs that are owned by you.

operator

one of

  • =
  • <
  • >
  • <=
  • >=
  • like
  • []
  • ()
  • (]
  • [)

Y

Specify a logical operator for the property or tag comparison. The following operators are supported:

  • "=" —equal to;
  • "<" —lesser than;
  • ">" —greater than;
  • "<=" —less than or equal to;
  • ">=" —greater than or equal to;
  • "like" —matches to the provided substring; the "*" wildcard character can be used to anchor substring searches;
  • "[]" —matches to values contained in the provided inclusive range, e.g. "values" : [1,3] matches to {1, 2, 3};
  • "()" —matches to values in the provided exclusive range, e.g. "values": [3-8] matches to {4, 5, 6, 7};
  • "(]" —matches to values in the provided exclusive beginning and inclusive ending range, e.g. "values": [2,5] matches to {3,4,5};
  • "[)" —matches to values in the provided inclusive beginning and exclusive ending range, e.g. "values": [1, 3] matches to {1,2};

values

an array or range of

  • string
  • integer
  • float

Y

Specify an array of values for the logical comparison.

For numeric ranges, specify the beginning and the end range values, e.g. "values": [1,10] implies from 1 to 10.

For multiple values, the filter condition considers the list as a series of OR clauses. For example, if you are comparing serviceType = ["EC2", "RDS", "Spot"], then the condition is evaluated as [serviceType = "EC2" OR serviceType = "RDS" OR serviceType = "Spot"].

For the "like" operator, use the "*" wildcard character to match zero, one or multiple characters to one end of the substring, e.g. "values": ["t2*"] matches to "t2", "t2.5", or "t2.micro", but not to "rds-t2.large".

Using the "like" operator without "*" wildcard will match the substring to any part of the property or tag value, e.g. "values": ["size"] matches to "Resize", "Upsize-Family", or "size-right".

Refer to the various cloud recommendation resource elements for valid values: Analysis: AWS Recommendations: Response, Analysis: Azure Recommendations: Response, and Analysis: GCP Recommendations: Response.

Note: To filter "Just Right" recommendations or "Not Analyzed" systems, you must use the exact recommendationType property string, "Not Analyzed" or "Just Right", when you use the "=" or "like" operator.

Core and Ancillary Properties in Filter Conditions

The concept of core and ancillary properties is taken into consideration only for filtering purposes. Ancillary properties cannot stand alone in a Subscriptions property condition set; they must be used in conjunction with a core property for the purpose of filtering subscription returned results.

In any Subscriptions property condition set, you must have at least one core property condition. If you want to only filter subscription data based on an ancillary property, you can add an always-true condition with a core property.

Refer to Default Cloud Properties for the list of core and ancillary properties.

For example:

If you want to create a subscription to only review systems with the same recommendation for over 30 days, you would create a property filter condition with recommSeenCount > 30. Since recommSeenCount is an ancillary property, you would also need to add another always-true condition with a core property, such as savingsEstimate > -10000. This will couple an ancillary property with a core property in your condition set. Therefore, your resulting subscription property condition set for this example would be:

propertyReferences =

  • (recommSeenCount > 30)
  • (savingsEstimate > -10000)

After finding the propertyID for recommSeenCount and savingsEstimate in your Subscriptions Properties catalog, you can form the propertyReferences filter:

Copy
"propertyReferences": [
    {
    "propertyID": "1dd76248-a503-40b1-9303-e990bbad7818",
    "operator": ">",
    "values": [30]
    },
    {
    "propertyID": "cebcd841-89d8-4007-a4c6-1f0b06723db4",
    "operator": ">",
    "values": [-10000]
    }
]

Response

The following is a complete list of possible response elements returned for the /subscriptions/<platformType> resource.

Table: Subscriptions Response Schema

Element

Type

Filter/Sort

Description

Subscription Identification

subscriptionRef

string

F

The unique referenced ID of the Densify subscription.

subscriptionName

string

 

The subscription name.

description

string

 

The subscription description.

owner

string

F

The designated owner of the subscription.

The subscription is considered global if this element is empty and private otherwise.

Subscription Configuration

outputType

string

 

application/json is the only supported output type.

active

string:

[true|false]

 

Indicates if the subscription is active or dormant:

  • true (default)—The subscription is active and notification will trigger at the scheduled time to the webhook defined.
  • false—The subscription is dormant: no subscription notification will trigger, even if webhook and schedule parameters are defined.

webhook

  • uri
  • authType
  • authValue

 

The webhook definition to an external application, where your personalized recommendations will be sent.

See Analysis: Webhook: Request Body Parameters for details of each parameter in the webhook definition.

If a webhook definition is not specified, then no notifications are triggered for this subscription.

propertyReferences

array of

  • propertyID
  • operator
  • values

 

An array of property conditions to be evaluated on the set of system recommendations before including them in the returned data set.

For details of the propertyID listed in the condition, see Subscriptions: Properties to retrieve property definitions available in the platform-specific Subscriptions Properties catalog.

See Filter and Suppression Conditions for details on how property conditions are defined.

tagReferences

array of

  • tagID
  • operator
  • values

 

An array of tag conditions to be evaluated on system attributes before including the system in the returned subscription data set.

For details of the tagID listed in the condition, see Subscriptions: Tags to retrieve tag definitions available in the platform-specific Subscriptions Tags catalog.

See Filter and Suppression Conditions for details on how tag conditions are defined.

suppressionReferences

array of

  • suppressionID
  • operator
  • values
  • revokeBy (optional)

 

An array of suppression conditions to determine system recommendations excluded from the returned subscription data set.

Revoked suppression conditions (i.e. when revokeBy datetime has passed) are not taken into consideration during the results data set generation.

For details of the suppressionID listed in the condition, see Subscriptions: Suppressions to retrieve suppression definitions available in the platform-specific Subscriptions Suppressions catalog.

See Filter and Suppression Conditions for details on how suppression conditions are defined.

schedule

  • dayOfMonth
  • dayOfWeek

 

The scheduled frequency of the subscription notification.

If no schedule is specified, then the subscription notification is triggered after daily Densify analyses are completed and reporting database tables are updated. Typically, these processes occur at night.

The schedule parameter is defined by one or both of the following options:

  • dayOfMonth—trigger the notification on the specified day of the month (e.g. "dayOfMonth" : [10,20]);
  • dayOfWeek—trigger the notification on the specified day of the week (e.g. "dayOfWeek" : [2,3], where 7=Sunday, 1=Monday, 2=Tuesday, etc.).

If both scheduling options are defined, the scheduling options are logical AND'ed to compute the notification schedule.

returnStructure

array of property references and an array of attribute tag references:

  • properties
    • propertyID
    • useAlias
  • tags
    • tagID
    • useAlias

 

Arrays of property and attribute tag references to be included in the output of the subscription notification.

The following items are listed for each property in the properties array:

  • propertyID—the property reference from /subscriptions/<platformType>/properties;
  • useAlias—[true|false] indicates if the property alias is used as the title in the recommendation output.

The following items are listed for each attribute tag in the tags array:

  • tagID—the tag reference from /subscriptions/<platformType>/tags;
  • useAlias—[true|false] indicates if the tag alias is used as the title in the recommendation output.

If returnStructure is defined, then only the properties and tags in returnStructure are returned in the output of the subscription notification.

If returnStructure is not defined, then the full list of possible recommendation properties are returned. The full list of recommendation properties correspond to the technology-specific Analysis recommendation response schema. For example, see Analysis: AWS Recommendations: Response for a full list of AWS recommendation properties.

Note: You must have at least one core property in your property condition set for the purpose of filtering subscription returned results. Refer to Core and Ancillary Properties in Filter Conditions for details.

webhookStatus

string

 

The status, date, and time of the last subscription results pushed to the webhook location:

  • Success—subscription results sent to the webhook successfully;
  • Failure—transmission of subscription results to the webhook failed.

lastTriggered

string

 

The status, date, and time of the last subscription results request:

  • On-Demand Success—the last request was on-demand and it was successful;
  • On-Demand Failure—the last request was on-demand and it failed to produce results;
  • Scheduled Success—the last request was a successful scheduled subscription event posted to a webhook;
  • Scheduled-Failure—the last request was a failed webhook post of the scheduled subscription event.

Returned Error Message

message

string

 

The message for the status response is returned.

status

number

 

The HTTP response code of the request. Possible status values include:

  • 200—success with request (usually with content in response body);
  • 204—success with request, no content returned;
  • 400—bad request (invalid parameters, logical errors);
  • 401—authentication failed;
  • 404—resource not found (or no privileges);
  • 415—unsupported media type;
  • 500—internal server error.

Examples

Example: Getting a Collection of Subscriptions

The following example shows you how to retrieve your collection of cloud subscriptions. Assuming that your username is "saas", the returned collection is a set of global subscriptions and subscriptions that belong to the "saas" user. You are not able to see private subscriptions belonging to other Densify users.

Note: If you are an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., then the returned collection will be all global cloud subscriptions and private cloud subscriptions for all Densify users.

Example: Getting a Collection of Subscriptions for a Specific User

If you are an administrative userClosedAn administrative user is a Densify user in the Administrator user group or with the Analysis Admin role., you can use the owner query string parameter to get a collection of subscriptions for a particular user. The following example shows you how to retrieve a collection of cloud subscriptions for the "saas" user.

Example: Creating a New Subscription

This example shows you how to create and define a new cloud subscription. In this sample subscription, we filter for systems where predicted uptime is between 50-100% and suppress systems that have a "Terminate" recommendation.

Example: Modifying a Subscription

This example shows you modify an existing cloud subscription and assumes that you are the "saas" user. You have to specify all the required parameters (including the owner parameter) for the subscription since previous parameters are deleted or reset to default in a PUT request. In the example below, the subscription name, description and returned elements are updated from the original subscription (in the previous Example: Creating a New Subscription).

Example: Deleting a Subscription

This example shows you how to delete a subscription. An HTTP "204 No Content" response is returned for a successful deletion.