As a Automation Service Broker administrator, you can create a content sharing policy that entitles all Automation Service Broker users in a project to shared content defined in the policy.

The following procedure shows how to use the Policies API to create a content sharing policy that defines shared content for users or groups that are part of the same project. To get the input required for the project, project users, and project groups, you use the Projects API. To get the catalog sources or catalog items to share in the policy, you use the Catalog API.

The steps to get catalog sources or items to share are optional, because a content sharing policy may not share both sources and items. However, the policy must share at least one catalog source or item.

Prerequisites

  • Verify that all general prerequisites and prerequisites for the Automation Service Broker Policies service have been satisfied. See Prerequisites for API Use Case Examples.
    Note: The Policies API and the Catalog API have the same API version. You set the API version value for both services when you satisfy the prerequisites for the Policies service.
  • Assign an API version variable for the Projects API.
    api_version_projects='2019-01-15'
    Note: The Projects APIs and Policies APIs have different API version values. You set the API version value for the Policies APIs when you satisfied the prerequisites for the Policies service.

Procedure

  1. Get a list of all projects in your organization. 
    curl -X GET "$url/project-service/api/projects?apiVersion=$api_version_projects" -H "Authorization: Bearer $access_token"  | jq "."
    Examine the response to get the ID of the project for the shared policy. The project must include the users or groups for which you want to entitle content. See Create a Project with the Project Service API.
  2. Assign the project ID variable. 
    project_id='<your_project_id>'
  3. Get a list of users in the project. 
    curl -X GET \
$url/project-service/api/projects/$project_id/principals?apiVersion=$api_version_projects&expandGroups=true& \
'$filter='"(substringof('{}',tolower(acct)))" \
-H "Authorization: Bearer $access_token"  | jq "."
    Examine the response to get the user email addresses for the project users. Users selected in the policy are entitled to items shared with the project.
  4. Get a list of groups in the project. 
    curl -X GET \
$url/project-service/api/projects/$project_id/groups?apiVersion=$api_version_projects&page=0 \
'$filter='"(substringof('{}',tolower(displayName)))" \
-H "Authorization: Bearer $access_token"  | jq "."
    Examine the response to get the group display name for the project users that are part of the group. Groups selected in the policy are entitled to items shared with the project.
  5. (Optional) Get a list of catalog sources for your project. 
    curl -X GET $url/catalog/api/admin/sources?projectId=$project_id&apiVersion=$api_version -H "Authorization: Bearer $access_token"  | jq "."
    Examine the response to find catalog sources that you want to share.
  6. (Optional) If you are sharing a catalog source, assign the catalog source ID variable. 
    catalog_source_id='<shared_catalog_source_id>'
  7. (Optional) Get a list of catalog items for your project. 
    curl -X GET $url/catalog/api/items?projectId=$project_id&apiVersion=$api_version -H "Authorization: Bearer $access_token"  | jq "."
    Examine the response to find catalog items that you want to share.
  8. (Optional) If you are sharing a catalog item, the catalog item ID variable. 
    catalog_item_id='<shared_catalog_item_id>'
  9. Create a content sharing policy with hard enforcement.
    • The value for user type is always USER.
    • The group's display name is always in the format groupDisplayName@groupDomain.
    • The typeId for the content sharing policy is always com.vmware.policy.catalog.entitlement.
    curl -X POST \
  $url/policy/api/policies?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<your_content_sharing_policy_name>",
    "projectId": "'$project_id'",
    "definition": {
        "entitledUsers": [
            {
                "userType": "USER", 
                "principals": [
                    {
                        "type": "USER",
                        "referenceId": "<user1_email_address>"
                    },
                    {
                        "type": "USER",
                        "referenceId": "<user2_email_address>"
                    },
                    {
                        "type": "PROJECT",
                        "referenceId": "$project_id'"
                    },
                    {
                        "type": "GROUP",
                        "referenceId": "<groupDisplayName1@groupDomain>" 
                    }
                ],
                "items": [
                    {
                        "id": "'$catalog_source_id'",
                        "type": "CATALOG_SOURCE_IDENTIFIER"
                    },
                    {
                        "id": "'$catalog_item_id'",
                        "type": "CATALOG_ITEM_IDENTIFIER"
                    }
                ]
            }
        ]
    },
    "enforcementType": "HARD",
    "typeId": "com.vmware.policy.catalog.entitlement" 
  }
}' | jq "."

Example: Create a content sharing policy

Create a policy named Sample Sharing Policy.

Assign variables.

Note: If your organization uses an API service that is hosted outside of the United States, your URL variable must include a country abbreviation. See Regional Endpoints for VMware Aria Automation APIs. 
$ url='https://api.mgmt.cloud.vmware.com'
$ api_version='2020-08-25'
$ api_version_projects='2019-01-15'

List the projects in your organization.

$ curl -X GET "$url/project-service/api/projects?apiVersion=$api_version_projects" -H "Authorization: Bearer $access_token"  | jq "."
Examine the response to find the project that you want to use for the shared content policy. 
{
      "id": "1d0bcd42-4d8f-4a8f-8b31-f34a4707533e",
      "name": "Example-project",
      "description": "This is an example project",
      "orgId": "f670fdfc-66d6-4689-9793-d524e7066d1e",
...

Assign the project ID. 

$ project_id='1d0bcd42-4d8f-4a8f-8b31-f34a4707533e'

List the users in the project.

$ curl -X GET \
 $url/project-service/api/projects/$project_id/principals?apiVersion=$api_version_projects&expandGroups=true& \
 '$filter='"(substringof('{}',tolower(acct)))" \ 
 -H "Authorization: Bearer $access_token"  | jq "."

A snippet of the response shows the email addresses for the users in the project.

...
    "content": [
        {
            "id": "ab373898-d29b-4e3b-8703-58023cadd140",
            "acct": "[email protected]",
            "domain": "mycompany.com"
        }
    ],
...

Get a list of groups in the project.

$ curl -X GET \
$url/project-service/api/projects/$project_id/groups?apiVersion=$api_version_projects&page=0 \
'$filter='"(substringof('{}',tolower(displayName)))" \
-H "Authorization: Bearer $access_token"  | jq "."

A snippet of the response shows the group display name for the users that are part of the group.

...
  "content": [
        {
            "id": "a9da96e7-ba19-47d4-9f38-dd1983e29424",
            "displayName": "[email protected]",
            "groupType": "USER_GROUP",
            "usersCount": 2
        },
...

Get a list of catalog sources for your project.

$ curl -X GET $url/catalog/api/admin/sources?projectId=$project_id&apiVersion=$api_version -H "Authorization: Bearer $access_token"  | jq "."

Examine the response to find the catalog sources that you want to share. 

...
    "content": [
        {
            "id": "600026c6-3155-4395-a990-580ff1159e82",
            "name": "BpContent-Quality Engineering",
            "description": "For Project-Quality Engineering",
            "typeId": "com.vmw.blueprint",
            "createdAt": "2022-10-12T10:37:01.751799Z",
            "createdBy": "[email protected]",
            "lastUpdatedAt": "2022-10-17T05:06:33.976796Z",
            "lastUpdatedBy": "system-user",
            "config": {
                "sourceProjectId": "1d0bcd42-4d8f-4a8f-8b31-f34a4707533e"
            },
      ...

Assign the ID of the catalog source to share.

$ catalog_source_id='600026c6-3155-4395-a990-580ff1159e82'

Get a list of catalog items for your project.

$ curl -X GET $url/catalog/api/admin/items?projectId=$project_id&apiVersion=$api_version -H "Authorization: Bearer $access_token"  | jq "."

Examine the response to find the catalog item. 

...
     "content": [
        {
            "id": "b2d0fba7-5f62-3c79-b1b8-a2aa7d38063b",
            "name": "CF-SQAVC67-Centos-MultiMachine",
            "description": "CF-SQAVC67-Centos-MultiMachine vsphere components, disk, networks",
            "sourceId": "600026c6-3155-4395-a990-580ff1159e82",
            "sourceName": "BpContent-Quality Engineering",
...

Assign the ID of the catalog item to share.

$ catalog_item_id='b2d0fba7-5f62-3c79-b1b8-a2aa7d38063b'

Create a content sharing policy with hard enforcement.

The following example shows the group's display name which is of the format groupDisplayName@groupDomain where: 
$ curl -X POST \
  $url/policy/api/policies?apiVersion=$api_version \
  -H "Authorization: Bearer $access_token" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sample Sharing Policy",
    "projectId": "'$project_id'",
    "definition": {
        "entitledUsers": [
            {
                "userType": "USER", 
                "principals": [
                    {
                        "type": "USER",
                        "referenceId": "[email protected]"
                    },
                    {
                        "type": "PROJECT",
                        "referenceId": "'$project_id'"
                    },
                    {
                        "type": "GROUP",
                        "referenceId": "[email protected]@mycompany.com"
                    }
                ],
                "items": [
                    {
                        "id": "'$catalog_source_id'",
                        "type": "CATALOG_SOURCE_IDENTIFIER"
                    },
                    {
                        "id": "'$catalog_item_id'",
                        "type": "CATALOG_ITEM_IDENTIFIER"
                    }
                ]
            }
        ]
    },
    "enforcementType": "HARD",
    "typeId": "com.vmware.policy.catalog.entitlement" 
}

The response shows the content sharing policy.

{
    "id": "0cecca9a-d778-47b5-acdf-c08248406052",
    "name": "Sample Sharing Policy",
    "projectId": "1d0bcd42-4d8f-4a8f-8b31-f34a4707533e",
    "definition": {
        "entitledUsers": [
            {
                "userType": "USER",
                "principals": [
                    {
                        "type": "USER",
                        "referenceId": "[email protected]"
                    },
                    {
                        "type": "PROJECT",
                        "referenceId": "1d0bcd42-4d8f-4a8f-8b31-f34a4707533e"
                    },
                    {
                        "type": "GROUP",
                        "referenceId": "[email protected]@mycompany.com"   
                    }
                ],
                "items": [
                    {
                        "id": "600026c6-3155-4395-a990-580ff1159e82",
                        "type": "CATALOG_SOURCE_IDENTIFIER"
                    },
                    {
                        "id": "b2d0fba7-5f62-3c79-b1b8-a2aa7d38063b",
                        "type": "CATALOG_ITEM_IDENTIFIER"
                    }
                ]
            }
        ]
    },
    "enforcementType": "HARD",
    "typeId": "com.vmware.policy.catalog.entitlement",
    "orgId": "10ea6be1-7723-4bf0-a221-8b4f3c7a26f7",
    "createdAt": "2022-10-24T07:52:22.731448Z",
    "createdBy": "[email protected]",
    "lastUpdatedAt": "2022-10-24T07:52:22.731448Z",
    "lastUpdatedBy": "[email protected]"
}