Skip to main content
This use case shows you how to subscribe to a set of Densify recommendation notifications using the Densify Subscription Service (DSS) API framework. The DSS is a flexible framework that offers you the ability to customize the content of your Densify recommendations for targeted distribution. DSS features include:
  • ability to filter recommendation systems based on recommendation fields (property filter);
  • ability to filter recommendation systems based on attribute tags (tag filter);
  • ability to suppress recommendation systems, for a period of time, based on recommendation fields and/or attribute tags via suppression filters;
  • ability to customize the notification output format;
  • ability to send the notification to an external webhook;
  • ability to schedule the notification;
  • ability to have private subscription definitions, as well as global subscription definitions for shared usage;
  • supports both cloud and containers system recommendations.
To use these features, you need to create an instance of the Subscription resource.

​
Creating a Subscription

The diagram below provides a high-level overview of creating an instance of the Subscription resource through the Densify API:
An instance of the Subscriptions resource is created using the POST /subscriptions/<platformType> request. You must identify the <platformType> of the subscription and use similar platform resources to define the subscription. For instance, you need to use container resources for a subscription to container recommendations. After identifying the subscription platform resources to use, define the parameter components below to customize your subscription.
  1. Define the Subscription—Specify the subscriptionName, description, and owner. The subscriptionName is used as a key identifier, so it needs to be unique for global subscriptions as well as unique within a private-scoped group of subscriptions. The description parameter is for documentation purposes, so its content should be as descriptive as possible to indicate the purpose of the subscription. See Example: Defining the Subscription.
  2. Property Filter—Specify propertyReferences to filter the recommendation systems you are interested in receiving based on recommendation fields. This feature is similar to the Recommendation Filter Menu in the Densify Console, where you can filter recommendation systems based on selected fields from the menu. In the propertyReferences filter condition, fields are selected by referencing property elements from the platform-specific Subscriptions Properties catalog. The platform of properties you reference must correspond with the platform of your subscription. Refer to Subscriptions Properties Catalogs for details on referencing properties. See Example: Specifying Property Filters for an example of a property filter condition block in a POST /subscriptions/<platformType> request.
  3. Tag Filter—Specify tagReferences to filter the recommendation systems you are interested in receiving based on attribute fields. This feature is similar to the Guest Filter from the Densify Console, but it also extends to filter platform-specific attribute tags. In the tagReferences filter condition, attributes are selected by referencing tag elements from the platform-specific Subscriptions Tags catalog. The platform of tags you reference must correspond with the platform of your subscription. Refer to Subscriptions Tags Catalogs for details.
    You must ensure that the selected Densify attributes are marked as searchable for use with DSS. Contact Densify support (Support@Densify.com) to confirm that the selected attributes are searchable in your Densify instance.
    See Example: Specifying Tag Filters for an example of a tag filter condition block in a POST /subscriptions/<platformType> request.
  4. Suppress Filter—Specify the suppressionReferences condition to suppress recommendation systems you are not interested in receiving based on recommendation or attribute fields. This feature allows you to suppress groups of recommendation systems for a period of time when the notification is actively scheduled. Suppression conditions are created by referencing suppression elements from the platform-specific Subscriptions Suppressions catalog. The platform of suppression conditions you reference must correspond with the platform of your subscription. Refer to the Subscriptions Suppressions Catalogs for an explanation of referencing the catalog. See Example: Specifying Suppression Conditions for an example of a suppression condition block in a POST /subscriptions/<platformType> request.
  5. Return Structure—Specify the returnStructure to personalize the output of the notification. If you do not specify the returnStructure parameter in your subscription, all recommendation fields applicable to the platform-specific system are returned. To return specific fields, you can specify elements from the platform-specific Subscriptions Properties Catalogs and Subscriptions Tags Catalogs that are within your scope. See Example: Specifying the Return Structure for an example of a returnStructure block in a POST /subscriptions/<platformType> request.
  6. Schedule Notification to Webhook—Specify when and where to send your notification by configuring the schedule parameter and the webhook parameter. If you do not specify the schedule parameter, the notification is triggered each night after data collection, analysis, and reporting database update processes. See Example: Specifying the Notification Schedule for an example of specifying a schedule block in a POST /subscriptions/<platformType> request. The webhook parameter is mandatory if you want notifications to be triggered. See Example: Specifying the Webhook for an example of specifying a webhook block in a POST /subscriptions/<platformType> request.
    You can test the subscription and request an on-demand results output by using the Subscriptions: Results resource, even if the webhook is not defined.
See Example: Creating a Subscription (Putting It All Together) for a complete example of the POST /subscriptions/<platformType> request with all the combined parameter components; then review the on-demand results of the subscription in Example: Getting On-Demand Results. Refer to Subscriptions for the complete subscription resource reference.

​
Subscriptions Properties Catalogs

The platform-specific Subscriptions Properties catalogs are resources that provides you with a list of recommendation fields to use for filtering and for personalizing the notification output. The platform of the Subscriptions Properties catalog you use for filtering must correspond with the platform of your subscription. By default, the platform-specific Subscriptions Properties catalogs already have a list of recommendation fields for you to use. You can also add additional recommendation fields to the catalogs. The list of possible recommendation fields to add corresponds to the response elements from the Densify supported cloud and container recommendations (see Analysis: AWS Recommendations: Response, Analysis: Azure Recommendations: Response, Analysis: GCP Recommendations: Response, and Analysis: Kubernetes Container Recommendations: Response).
Some recommendation elements are not common to all technologies. For example, propertyName=“minGroupRecommended” only applies to AWS Auto Scaling group recommendations.
When you create property filter conditions for your subscription, you need to reference properties from the corresponding platform Subscriptions Properties catalog (see the Subscriptions: propertyReferences parameter). Similarly, you need to reference properties from the corresponding platform Subscriptions Properties catalog to personalize the notification output (see the Subscriptions: returnStructure parameter). You can only reference properties that are accessible to the Densify username you use to authorize the API request. Property accessibility depends on the scope of the property: if the property is global, then the property is accessible to all API Densify users; if the property is private, then the property is accessible to the owner of the private property. If you are an , then you can override the property scope rule and access all properties from the catalog. See Subscriptions: Properties: owner for more property scope details. Refer to Subscriptions: Properties for the full resource definition.

​
Subscriptions Tags Catalogs

The platform-specific Subscriptions Tags catalogs are resources that provides you with a list of system attribute fields to use for filtering and for personalizing the notification output. The platform of the Subscriptions Tags catalog you use for filtering must correspond with the platform of your subscription. By default, the platform-specific Subscriptions Tags catalogs already have a list of common attributes for you to use. You can also add additional attribute fields to the catalogs. The possible attribute fields you can add comes from the set of Densify standard attributes or technology-specific attributes. When you create tag filter conditions for your subscription, you need to reference tags from the corresponding platform Subscriptions Tags catalog (see the Subscriptions: tagReferences parameter). Similarly, you need to reference tags from the corresponding platform Subscriptions Tags catalog to personalize the notification output (see the returnStructure parameter). You can only reference tags that are accessible to the Densify username you use to authorize the API request. Access to a particular tag in the catalog depends on its scope: if the tag is global, then the tag is accessible to all API Densify users; if the tag is private, then the tag is accessible to the owner of the private tag. If you are an , then you can override the tag scope rule and access all tags from the catalog. See Subscriptions: Tags: owner for additional details of tag scope. Refer to Subscriptions: Tags for the full resource definition.

​
Subscriptions Suppressions Catalogs

The platform-specific Subscriptions Suppressions catalogs are resources that provides you with a list of recommendation and system attribute fields to use for creating suppression conditions in your subscription. The platform of the Subscriptions Suppressions catalog you use for suppressing recommendations must correspond with the platform of your subscription. By default, the platform-specific Subscriptions Suppressions catalog already has a list of recommendation and attribute field suppressions for you to use. You can also add additional suppression fields. The list of possible recommendation fields correspond to the response elements from the Densify supported cloud recommendations (see Analysis: AWS Recommendations: Response, Analysis: Azure Recommendations: Response, Analysis: GCP Recommendations: Response, and Analysis: Kubernetes Container Recommendations: Response). The possible attribute fields you can add to a Subscriptions Suppressions catalog comes from the set of Densify standard attributes or technology-specific attributes. When you create suppression conditions for your subscription, you need to reference suppressions from the corresponding platform Subscriptions Suppressions catalog (see the Subscriptions: suppressionReferences parameter). You can only reference suppressions that are accessible to the Densify username you use to authorize the API request. Access to a particular suppression in the catalog depends on its scope: if the suppression is global, then it is accessible to all API Densify users; if the suppression is private, then it is accessible to the owner of the private suppression. If you are an , then you can override the suppression scope rule and access all suppressions from the catalog. See Subscriptions: Suppressions: owner for details of suppression scope.
The Subscriptions Suppressions catalogs are not used for a Subscription’s return output.
Refer to Subscriptions: Suppressions for the full resource definition.

​
Example: Defining the Subscription

Use the POST /subscriptions/cloud request to create a cloud subscription. The first set of parameters to specify are the subscriptionName and description, which are free-form strings. The owner parameter is automatically set to your Densify username if you are not an . You can also set the active parameter to indicate if the subscription is dormant or active (the default is active). Remember to specify your active authorization key for each token-based authentication request (see Authorize for details).
Headers:
Accept: application/json
Authorization: Bearer <apiToken>
Request:
POST /subscriptions/cloud
{
    "subscriptionName": "My Subscription",
    "description": "A subscription for my Use Case",
    "active": true,
    ...

​
Example: Specifying Property Filters

To specify property filter conditions in the POST /subscriptions/<platformType> request, use the propertyReferences parameter. In this example, the property condition filters all AWS EC2s with predicted uptime between 50 -100%. The cloud subscription propertyReferences condition references the propertyID of “serviceType” and “predictedUptime” from the Cloud Subscriptions Properties catalog.
Request Parameter - Property Filter Condition Section:
   ...
    "propertyReferences": [
       {
           "values": ["EC2"],
           "propertyID": "b4e7260f-1aae-4150-b75d-1b1234075500",
           "operator": "="
       },
       {
           "propertyID": "f2a38773-db60-478a-9982-1a2d1ba7d380",
           "operator": "[]",
           "values": [50,100]
       }
     ],
    ...

​
Example: Specifying Tag Filters

To specify tag filter conditions in the POST /subscriptions/<platformType> request, use the tagReferences parameter. In this example, the tag condition filters all systems belonging to the “Sales” department. The cloud subscription tagReferences condition references the tagID of “Department” from the Cloud Subscriptions Tags catalog.
Request Parameter - Tag Filter Condition Section:
    ...
    "tagReferences": [
       {
           "values": ["Sales"],
           "tagID": "9879308e-3162-499b-8fe5-7fd67e627079",
           "operator": "="
       }
     ],
    ...

​
Example: Specifying Suppression Conditions

To specify suppression conditions in the POST /subscriptions/<platformType> request, use the suppressionReferences parameter. In this example, the cloud suppression condition removes all terminate recommendations until April 20, 2020. After April 20, 2020 (the revokeBy date), the suppression condition is deprecated. The cloud subscription suppressionReferences condition references the suppressionID of “recommendationType” from the Cloud Subscriptions Suppressions catalog.
Request Parameter - Suppression Filter Condition Section:
    ...
    "suppressionReferences": [
       {
           "values": ["Terminate"],
           "suppressionID": "a6827ae4-fa2b-405e-a564-d70f2dad45c2",
           "operator": "=",
           "revokeBy": 1587415413000
       }
     ],
    ...

​
Example: Specifying the Return Structure

To specify a customized return structure in the POST /subscriptions/<platformType> request, use the returnStructure parameter. In this example, the return output will contain the following cloud fields: effortEstimate, entityId, name, recommendationType, savingsEstimate, serviceType, Department (attribute), Virtual Domain (“account”). These fields reference the propertyID and “tagID” from the Cloud Subscriptions Properties catalog and the Cloud Subscriptions Tags catalog, respectively. Some of these property or tag fields have the "useAlias" flag set to true, which returns the alias names instead of the property or tag names.
Request Parameter - Return Structure Section:
    ...
    "returnStructure": {
        "properties": [
            {
                "propertyID": "b4e7260f-1aae-4150-b75d-1b1234075500"
            },
            {
                "useAlias": true,
                "propertyID": "e2ae92c5-91c7-4ff5-a29f-99aa92d65178"
            },
            {
                "propertyID": "08d84679-1816-4cd7-b766-e4ad441b9a6c"
            },
            {
                "propertyID": "b20b2499-e901-4d79-873c-5e953ae8be33"
            },
            {
                "useAlias": true,
                "propertyID": "cebcd841-89d8-4007-a4c6-1f0b06723db4"
            },
            {
                "propertyID": "88695e33-19c4-4813-819a-31e59322da6e"
            }
        ],
        "tags": [
            {
                "useAlias": true,
                "tagID": "be3cdc69-962e-4461-b8c3-07cec8e712be"
            },
            {
                "tagID": "9879308e-3162-499b-8fe5-7fd67e627079"
            }
        ]
    },
    ...

​
Example: Specifying the Webhook

For the destination of the notification, specify the webhook parameter in the POST /subscriptions/<platformType> request. If you do not specify a webhook, no subscription notifications are triggered; the subscription is considered dormant since there is no destination for the notification. You can test the subscription and request an on-demand results output by using the Subscriptions: Results resource, even if the subscription is dormant or if the webhook is not defined.
Request Parameter - Webhook Section:
    ...
    "webhook": {
        "uri": "https://testsystem.com/webhook/receiver",
        "authType": "basic",
        "authValue": "test:test"
    },
    ...

​
Example: Specifying the Notification Schedule

To specify a notification schedule in the POST /subscriptions/<platformType> request, use the schedule parameter. In the example below, the cloud subscription is scheduled to be triggered on Mondays and Fridays of each week (dayofWeek 1 = Monday). If you do not specify the schedule parameter, the subscription notifications are triggered nightly by default.
Request Parameter - Schedule Section:
    ...
    "schedule": {
        "dayofWeek": [
            1,
            5
        ]
    },
    ...

​
Example: Creating a Subscription (Putting It All Together)

This example puts all the subscription components (from the previous examples) together to create a cloud subscription.
Request:
POST /subscriptions/cloud
Parameters:
[
       {
        "subscriptionName": "My Subscription",
        "description": "A subscription for my Use Case",
        "active": true,
        "webhook": {
               "uri": "https://testsystem.com/webhook/receiver",
            "authType": "basic",
            "authValue": "test:test"
        },
        "propertyReferences": [
            {
                "values": ["EC2"],
                "propertyID": "b4e7260f-1aae-4150-b75d-1b1234075500",
                "operator": "="
            },
            {
                "propertyID": "f2a38773-db60-478a-9982-1a2d1ba7d380",
                "operator": "[]",
                "values": [50,100]
            }
        ],
        "tagReferences": [
            {
                "values": ["Sales"],
                "tagID": "9879308e-3162-499b-8fe5-7fd67e627079",
                "operator": "="
            }
        ],
        "suppressionReferences": [
            {
                "values": ["Terminate"],
                "suppressionID": "a6827ae4-fa2b-405e-a564-d70f2dad45c2",
                "operator": "=",
                "revokeBy": 1587415413000
            }
        ],
        "returnStructure": {
            "properties": [
                {
                    "propertyID": "b4e7260f-1aae-4150-b75d-1b1234075500"
                },
                {
                    "useAlias": true,
                    "propertyID": "e2ae92c5-91c7-4ff5-a29f-99aa92d65178"
                },
                {
                    "propertyID": "08d84679-1816-4cd7-b766-e4ad441b9a6c"
                },
                {
                    "propertyID": "b20b2499-e901-4d79-873c-5e953ae8be33"
                },
                {
                    "useAlias": true,
                    "propertyID": "cebcd841-89d8-4007-a4c6-1f0b06723db4"
                },
                {
                    "propertyID": "88695e33-19c4-4813-819a-31e59322da6e"
                }
            ],
            "tags": [
                {
                    "useAlias": true,
                    "tagID": "be3cdc69-962e-4461-b8c3-07cec8e712be"
                },
                {
                    "tagID": "9879308e-3162-499b-8fe5-7fd67e627079"
                }
            ]
        },
        "schedule": {
            "dayofWeek": [
                1,
                5
            ]
        }
    }
]
Response:
[
    {
        "subscriptionRef": "7f2b2f50-3988-4275-a1ac-34a9b45408b9",
        "subscriptionName": "My Subscription"
    }
]

​
Example: Getting On-Demand Results

This example retrieves the cloud subscription (created from the previous example) results on-demand. This request returns the cloud subscription results regardless of what is configured in the webhook, schedule, or active parameters.
Request:
GET /subscriptions/cloud/7f2b2f50-3988-4275-a1ac-34a9b45408b9
Response:
{
       "subscription": {
           "name": "My Subscription",
        "description": "A subscription for my Use Case",
        "created": "Mon Apr 13 13:50:15 EST 2020",
        "createdBy": "saas",
        "lastRefreshed": "Fri Apr 17 1:00:10 EST 2020",
        "owner": "saas"
    },
    "count": 98,
    "results": [
           {
               "effortEstimate": "Low",
            "entityId": "c0ebf351-9b6c-4d57-b3d0-23c7861f9db4",
            "name": "ex-pro-asop-896",
            "recommendationType": "Downsize - Optimal Family",
            "savingsEstimate": "49.39808",
            "serviceType": "EC2",
            "divider": "------------------------",
            "Department": "Sales",
            "awsAccount": "229132289155"
        },
        {
               "effortEstimate": "Low",
            "entityId": "234ca9b6-3def-4ace-87c5-466c2e41f1d1",
            "name": "ex-pro-kotl-966",
            "recommendationType": "Downsize - Optimal Family",
            "savingsEstimate": "163.6333",
            "serviceType": "EC2",
            "divider": "------------------------",
            "Department": "Sales",
            "awsAccount": "229132289155"
        },
        {
        // ... *SNIP* additional 96 system recommendations not displayed *SNIP* ...
        }
    ]
}

​
Postman Collection

Densify provides a Postman collection of sample API requests for working with your public cloud environments. See Postman Collection