Manage Custom Entitlements

Initial Setup

Initially you need to create a template business group using our "Create Business Group" function. Make sure you tick all the Services in the request form. Special Network or User configuration is not needed. Give it a meaningful name you can remember such as Tenantname-default-bg.

Submitting the request will create an empty business group with all the entitlements Swisscom has forseen for general customers. As the entitlement in this Business Group are created according to Swisscom standards, they will get updated with the newest content on each deployment. These entitlements will be our template for the custom entitlements we are going to create for all future business groups.

Because the template business group got created with our "Create Business Group" Blueprint and remains untouched after creation, the entitlements are getting updated on every deployment. This means that after our deployments, you can revisit the entitlements of this business group and see what has changed directly through API.

For every new Business Group

Create New Business Group
Delete unwanted entitlement(s)
Create custom entitlement(s)

Now let's see in detail what we have to do in the different steps. As this is only for advanced use cases, most of the operations need to be executed via API.

Create New Business Group

Use our "Create Business Group" function to create a new business group. A manual on how to order a new business group can be found above. Let's say you called your new business group "my-amazing-bg". This business group will have 2-3 entitlements, depending on the services you selected. They are created after the following schema:

my-amazing-bg_scs_managedServices -> This entitlement was created because you selected the "Managed Services" Service. If you did not select "Managed Services" it will not be there.
my-amazing-bg_scs_default -> This is the default entitlement for all services except "Managed Services".
my-amazing-bg_scs_default-vro -> This entitlement is used by our Orchestration solution (VMware vRealize Orchestrator).

You can always fetch information about the entitlements using the API:
(GET) https://<vra-fqdn>/catalog-service/api/entitlements?$filter=name eq 'name'

for example:
(GET) https://<vra-fqdn>/catalog-service/api/entitlements?$filter=name eq 'my-amazing-bg_scs_default'

It is worth to explain the JSON response in a bit more detail:

Parameter	Description
name	The name of the entitlement. Every custom entitlement should start with `<businessgroupname>\_entitlement-'` followed by a short word specifying the purpose.
organization	This contains information about the tenant you are operating and the business group you want to assign.
organization.tenantRef	The tenant ID
organization.tenantLabel	The tenant name (label)
organization.subtenantRef	The business group ID
organization.subtenantLabel	The business group name (label)
principals	This contain information about the users included in this entitlement. If you set the parameter "allUsers" to true this will be null.
principals.tenantName	The tenant ID
principals.ref	The username in format `<username>@<domain>` (johndoe@mydomain.net)
principals.type	USER
principals.value	The "readable" name (John Doe)
entitledResourceOperations	Needed to entitle resource actions. Is an array of resourceOperationRef elements. Every element has to be specified with id and label of the action.
entitledServices	Needed to entitle services. Is an array of serviceRef elements. Every element has to be specified with id and label of the service
allusers	Will be true if it is a Swisscom created entitlement, can be false if it is an entitlement you created. (See principals)
localScopeForActions	Can be true or false. If you are using Managed Services in our Cloud, this can never be false (Only exception is Swisscom's vRO entitlement). This setting decides whether a user can execute actions set in this entitlement only on machines within the scope of the entitlement or on all machines he is entitled (also in other business groups).

Now that you know everything about your new business group, we can start creating your own entitlements by deleting ours first.

Delete unwanted entitlement(s)

We learned already that when a business group is created with our "Create New Business Group" Blueprint, it automatically creates 2-3 entitlements. We can separate those entitlements in three categories.

Do not touch:

Our orchestration entitlement goes into this category (my-amazing-bg_scs_default-vro). Please do not delete this entitlement. We need it to run our cloud smoothly.

Careful:

The entitlement created when using the "Managed Services" Service goes into this category. You can theoretically delete this entitlement, however if you create a custom entitlement, you cannot mix an entitlement created for the "Managed Services" Service with other services and you can only delete Actions and not add additional actions to this entitlement. If you create a new entitlement for "Managed Services", all the Actions must have the same configuration as in the Swisscom given entitlement. Especially in respect to approval policies.

More or less safe:

All other (default) entitlements go into this category. You are more or less safe to delete it. Some restrictions may apply (see Create custom entitlement(s))
In order to delete an entitlement, we need to disable it first. Copy the Body of the entitlement you want to delete:
(GET) https://<vra-fqdn>/catalog-service/api/entitlements?$filter=name eq 'name'

Set the payload as body of the new put request an change the following two attributes:

"status": "INACTIVE",
"statusName": "Inactive",

Now send the put request:
(PUT) https://<vra-fqdn>/catalog-service/api/entitlements/<entitlements_id>
(you can receive the entitlements_id from the id field of the body you received using the get operation)

Your entitlement should now be Inactive and you can delete it
(DELETE) https://<vra-fqdn>/catalog-service/api/entitlements/<entitlements_id>

Now we can start creating the you custom entitlements

Create custom entitlement(s)

First of all let's create a new entitlement. This is the JSON payload you have to use:

{
  "@type": "entitlement",
  "description": "",
  "entitledCatalogItems": [],
  "entitledResourceOperations": [
    {
      "resourceOperationRef": {
        "id": add_value_here,
        "label": add_value_here
      }
    }
  ],
  "entitledServices": [
    {
      "serviceRef": {
        "id": add_value_here,
        "label": add_value_here
      }
    }
  ],
  "expiryDate": add_value_here,
  "id": add_value_here,
  "name": add_value_here,
  "organization": {
    "tenantRef": add_value_here,
    "tenantLabel": add_value_here,
    "subtenantRef": add_value_here,
    "subtenantLabel": add_value_here
  },
  "principals": [
    {
      "tenantName": add_value_here,
      "ref": add_value_here,
      "type": "USER",
      "value": add_value_here
    }
  ],
  "priorityOrder": add_value_here,
  "status": "ACTIVE",
  "statusName": "Active",
  "localScopeForActions": false,
  "allUsers": false,
  "version": add_value_here
}

The (most important) parameters that you should provide are, more parameters are described in the table above:

Parameter	Description
name	The name of the new entitlement. Every custom entitlement must start with `<businessgroupname>\_entitlement-` followed by a short word specifying the purpose.
organization	This contains information about the tenant you are operating and the business group you want to assign.
organization.tenantRef	The tenant ID
organization.tenantLabel	The tenant name (label)
organization.subtenantRef	The business group ID
organization.subtenantLabel	The business group name (label)
principals	This contain information about the users included in this entitlement. If you set the parameter "allUsers" to true this has to be null.
principals.tenantName	The tenant ID
principals.ref	The username in format `<username>@<domain>` (johndoe@mydomain.net)
principals.type	USER
principals.value	The "readable" name (John Doe)
entitledResourceOperations	Needed to entitle resource actions. Is an array of resourceOperationRef elements. Every element has to be specified with id and label of the action.
entitledServices	Needed to entitle services. Is an array of serviceRef elements. Every element has to be specified with id and label of the service.
localScopeForActions	Can be true or false. Usually you need to set this to true, see description above and special case below.

The rest of the parameters can be skipped and not included in the payload.

Since you have a template Business Group with default Swisscom entitlements, you can use this business group (and its entitlements) as a template for your new entitlements. There are more sources with information which maybe helpful building your entitlements:

Get information about a resource action:
(GET) https://<vra-fqdn>/catalog-service/api/provider/resourceActions?limit=1000&$filter=name eq 'name'
Get information about a business group:
(GET) https://<vra-fqdn>/identity/api/tenants/<tenant>/subtenants?$filter=name eq 'name'
Get Information of your template entitlements: (GET) https://<vra-fqdn>/catalog-service/api/entitlements?$filter=name eq 'name'

Correlating information from all those endpoints will give you the body of your new entitlement. Now let's talk about exceptions:

Managed Services:
As soon as Managed Services are involved, there are certain boundaries you need to respect:

Never mix the "Managed Services" Service with other Services in an entitlement
- Create a separate entitlement only for Managed Services
Only the Resource Actions from the scs_ManagedServices entitlement of your template entitlement can be used
- Copy the Resource Action including the approval Policy configuration from the template entitlement
Only remove, do not add additional Actions
- It is allowed to remove actions compared to the template entitlement, but never add additional ones
localScopeForActions must be set to "true" on all entitlements
- To ensure that it is not feasible to execute day-2 outside of the scope of the entitlement, the localScopeForActions option must be set to true on all entitlements on all business groups!

Reconfigure Resource Action:
The Reconfigure Resource Action must be created with an approval policy attached. Use the template entitlement (scs_default) to copy the exact configuration of this resource action. If you plan to add it to your entitlement, use it exactly as configured in scs_default or in scs_managedServices, if you are creating an entitlement for Managed Services!

Now with all the special cases discussed we can create your new entitlement:
(POST) https://<vra-fqdn>/catalog-service/api/entitlements/ (set the payload as body)

If you want to update an existing entitlement you can first get the one you want using:
(GET) https://<vra-fqdn>/catalog-service/api/entitlements?$filter=name eq 'name'

update the desired field and put the payload back using:
(PUT) https://<vra-fqdn>/catalog-service/api/entitlements/<entitlements_id> (set the payload as body)

# Manage Custom Entitlements

# Initial Setup

# For every new Business Group

# Create New Business Group