Skip to main content

Scripting

  • Updated

Introduction

Scripts are used in OC Reporter to automatically assign users and/or servers to customers or to exclude objects from the SPLA usage reports.

Scripting Levels

There are two scripting levels:

  1. Global level: The global scripting level is located in Data Import > Automation > Scripts to be executed section. Scripts executed there apply to all scanned data in OC Reporter.
  2. Customer level: The customer scripting level is located in each detailed view of a customer in Customers > Customers > Specific customer > Scripts to be executed section. Scripts executed there apply only to data related to that specific customer. Scripts executed at the customer level overwrite scripts executed on the global level.

The Execution Time Of Scripts

Scripts are automatically executed on each new automatic data import. The scripts can be manually executed, once the scripts are entered and saved. This is done by clicking on the “Execute scripts” button, located in the respective global or customer scripting section. This allows you to see the scripting results immediately, without waiting for the next automatic data import.

Scripting Scopes

Scripts can be used:

  • to exclude users, servers, or software licenses from the SPLA usage reports.
  • to assign users or servers to customers. Assignments can only be executed on the customer level.
  • to modifying specific attributes of objects.

Anatomy Of Scripts

In the scripting section, you can add on each line one script. Scripts are executed from up to down, which means scripts added more down could overwrite scripts added more up in the scripting section. A script has two or three parts:

  1. The first part defines which object type is affected
  2. The second part defines the conditions in which the script is executed
  3. The third part defines what to execute on the specified objects

The script parts are separated by a “@” sign. An example script:

user@username=%admin%@exclude_spla=yes,exclude_spla_reason=admin

In this example script, all three parts are separated by the “@” sign. The first part defines for which object type you want to execute the script. In the example above, it is the “user” object type. You could also use “server” as the object type to execute scripting on servers. The second part defines the condition. In the case above, we want to execute our script to all users which contains in their username the word “admin”. You could define multiple conditions by chaining them with “&&”. The third and last part defines what attributes we want to modify. In the example above, you want to exclude all users who contain “admin” in their username from SPLA.

Object Types

You can use the following object types in your script:

  • user: Executes scripts on user objects.
  • server: Executes scripts on server objects.
  • user-software: Executes scripts on user-related software licenses.
  • server-software: executes scripts on server-related software licenses.

Conditions

Conditions vary between the object types. In the conditions part of the script you can use the “%” (percent sign) as a placeholder to define if the value in the condition should start with (putting the percent sign in the end), end with (putting the percent sign in the beginning) or contain the given value (putting the percent sign in the beginning and end). If you don’t use the percent sign, then the script will search for the exact string given as the value of the attribute.

Condition attributes are always an attribute-value pair with a “=” (equal sign) between them. The opposite sign of “=” is the “!=” (not equal) sign. For instance, if you want to execute a script, where all users should be affected, except users with a starting username of “abc”, you would add in the condition part of the script the following: username!=abc%

You can also chain multiple condition attribute-value pairs together in the condition part of a script with “&&”. For instance, if you want to execute a script where all servers which are in a specific OU and containing “abc” in their names should be affected, we could add in the condition part the following: ou=%/Test Server%&&label=%abc%

The following are the most used condition attributes:

For user object types

  • ou
  • domain
  • username
  • full_name
  • email
  • ad_groups
  • description
  • is_local_admin
  • is_only_local_admin

For server object types

  • ou
  • domain
  • dns_suffix
  • vlanid
  • label
  • ad_groups
  • description
  • resource_pool
  • is_dc
  • is_ts
  • hkey
  • hypervisor_datastores
  • hypervisor_folder
  • hypervisor_domain

Updated attributes

In the third part of the script, we are defining the attributes to update or modify. You can update multiple attributes with a “,” (comma). Most of the time you want to exclude specific objects from the SPLA usage:

  • exclude_spla: This attribute accepts the following values: “yes” or “no”. If it is set to “yes”, that particular object will not be counted in the SPLA usage report anymore.
  • exclude_spla_reason: With this attribute, you can define a reason for your exclusion. This attribute accepts the following values: “admin”, “nh” (for service accounts or non-human accounts), “demouser” (for demo user accounts), “vl” (for volume licenses), “dr” (for disaster recovery) or “azurevm” (for Azure VMs) or “other”.
  • exclude_spla_description: If you define “other” in “exclude_spla_reason”, you can enter a descriptive text with this attribute.

Examples

Assign a user to a customer

As mentioned above assignments can only be executed on customer scripting levels. Assignments have only two parts in the scripting. The object type and condition part, the updating part of the attributes not entered.

Let’s assume you want to assign all users within a particular OU to a customer. The OU of the users is: “mydomain.intern/Customers/Customer A/Users”. The script would look like this:

user@ou=%/Customer A/%

You could instead of the attribute “ou” also use the other condition attributes listed above. For instance, we could assign all users of a specific domain to a customer:

user@domain=mydomain.intern

If you want to combine attributes, you could define the following script:

user@domain=mydomain.intern&&ou=%/Customer A/%

This script will assign all users which are in the domain “mydomain.intern” AND contain in their OU “/Customer A/”.

Assign a server to a customer

The assignment of servers follows the exact same rules as the assignment of users. The only difference will be to change the object type name from “user” to “server”:

server@ou=%/Customer A/%

You can also use the other attributes listed above for the condition part, for instance:

server@label=CustomerA_% or server@ip_address=10.10.20.%

This script would assign all servers which start in their names with “CustomerA_” but end with something else. The second script would assign all servers in the subnet of “10.10.20.x”

Exclusion or object attribute update

Exclusion scripts can be executed on a global or customer level and contain always the three parts of a script. if a script is executed, and a mistake was made in the script, in order to revert the changes you need to reverse the values in the third part and execute the script again.

Example

You executed the following script to exclude all service accounts from the SPLA usage calculation:

user@username=svc%@exclude_spla=yes,exclude_spla_reason=nh

After the execution, you figured out that actually, you excluded more users than you expected because there were users whose username starting with “svc” but were no service accounts. To correct the mistake, you need to execute the above script one time again but like the following:

user@username=svc%@exclude_spla=no,exclude_spla_reason=

After the users are again not excluded from SPLA, you can correct your script and execute it again and keep it in the scripting section. To stay in your example, you could see that all service accounts start with “svc_” and correct your script to the following:

user@username=svc_%@exclude_spla=yes,exclude_spla_reason=nh

Assigning licensing context to object

If the module for Flexible Virtualization and CSP-Hoster is activated, you can set for the following objects the licensing context:

  • Datacenters
  • Clusters
  • Hosts
  • Virtual Machines
  • Users

The following licensing contexts are available:

  • Microsoft SPLA: ms_spla
  • Microsoft CSP-Hoster: msd_csp_hoster
  • Bring Your Own License (BYOL): mse_byol
  • Microsoft CSP subscription: msf_csp_subscription
cluster@label=Cluster 1@license_context=msd_csp_hoster
server@domain=abc@license_context=ms_spla
user@ou=%byol-users%@license_context=mse_byol
server-software@server.ad_groups=%csp%@license_context=msf_csp_subscription

Exclude admin users

Depending on how you defined your admin users, you could use the username, ad_groups or other condition attributes in your script.

user@username=%Admin%@exclude_spla=yes,exclude_spla_reason=admin
user@username=%Admin%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=ABC

Exclude local administrator accounts

user@is_local_admin=1@exclude_spla=yes,exclude_spla_reason=admin
user@is_local_admin=1&&domain=sh11.lan@exclude_spla=yes,exclude_spla_reason=admin
user@is_only_local_admin=1@exclude_spla=yes,exclude_spla_reason=admin

Note: Beware, the above scripting with “is_local_admin” also excludes any AD groups/AD user accounts that may have been added to the Local Administrators groups on the Windows servers. If by mistake, someone adds the Domain Users group to the Local administrators' group on a Windows server, this would exclude all AD Domain users. If you only want to exclude local admin users, then it is better to use the “is_only_local_admin” attribute.

Exclude users based on their full name

user@full_name=%support%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Support Accounts

Exclude users based on OU membership

user@ou=%/OU_NAME/%@exclude_spla=yes,exclude_spla_reason=nh
user@ou=%/OU_NAME/%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Admin or Service Accounts

Exclude users based on AD group membership

user@ad_groups=%Domain Admins%@exclude_spla=yes,exclude_spla_reason=admin

Exclude users based on custom AD user attributes

user@extra_fields=%extensionAttribute1:Service Account%@exclude_spla=yes,exclude_spla_reason=nh

Reverse/Negate all user exclusions

user@@exclude_spla=no

Note: If the condition part of a script is kept empty, all objects will be affected by that script.

Exclude users who never logged into the environment (users with last login time being blank in AD)

user@last_login=NULL@exclude_spla=yes

Note: Beware that as per SPLA rules, a license is required for these users as well if they have the technical ability to access the environment.

Exclude hypervisor nodes/physical servers by their name/label

server@type_id=host&&label=XXX@exclude_spla=yes

Exclude hypervisor nodes/physical servers by their domain

server@type_id=host&&domain=XXX@exclude_spla=yes

Exclude hypervisor nodes in a specific cluster

server@type_id=host&&cluster_label=%XXX%@exclude_spla=yes

Exclude all VMs in a specific cluster

server@type_id=vm&&cluster_label=%XXX%@exclude_spla=yes

Exclude all VMs located on specific Hypervisor nodes

server@host_label=xxx@exclude_spla=yes

Exclude all servers (VMs, and hypervisor nodes) in a specific cluster

server@cluster_label=%xxx%@exclude_spla=yes

Exclude servers by their IP address/subnet

server@ip_address=10.10.20.%@exclude_spla=yes
server@ip_address=%10.10.20.5%@exclude_spla=yes (required when the server has multiple IP addresses)

Exclude servers (VMs) based on their vSphere Hypervisor folder ID

server@hypervisor_folder=%XXX%@exclude_spla=yes

Force OS license on host

server@label=XXX@forced_spla_os_license=9EA-00039

Exclude all VM’s on a specific host from SPLA, because of volume licensing

server@host_label=hybrid-10g-blade3.vmware.domain.de@exclude_spla=yes,exclude_spla_reason=vl

Exclude all VM licenses on a specific host from SPLA, except the Windows OS license

In this case, we need to execute two scripts:

server-software@server.host_label=XXX@exclude_spla=yes,exclude_spla_reason=vl
server-software@server.host_label=XXX&&software_level=%Windows Server%@exclude_spla=no,exclude_spla_reason=

Instead of executing two scripts, we can also use the “!=” sign in the condition part and reduce the above script to just one script:

server-software@server.host_label=XXX&&software_label!=%Windows Server%@exclude_spla=yes,exclude_spla_reason=vl

Exclude Windows Server OS licensing for a specific AD Domain

server-software@server.domain=customer-fqdn.com&&software_label=%Windows Server%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Not licensed through SPLA

Exclude Microsoft Office from SPLA for a specific user domain

user-software@user.domain=customer-fqdn.com&&software_label=%Microsoft Office%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Licensed by Customer Owned licenses on dedicated cluster

Exclude specific Office Access version

user-software@full_label=%Office Access 2007%@exclude_spla=yes

Exclude all Office licensing for members of a specific AD group

user-software@user.ad_groups=O365_%&&software_label=%Office%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Licensed over CSP

Exclude RDS licenses for Local Administrator accounts

user-software@user.is_only_local_admin=1&&software_label=%Remote Desktop Services%@exclude_spla=yes,exclude_spla_reason=admin

Exclude RDS licenses for a specific server

user-software@software_label=%Remote Desktop Services%&&access_device_labels=%DCSE321%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=No RDS installed

Exclude all RDS licenses, except for users in a specific OU

user-software@software_label=%Remote Desktop Services%&&user.canonical_name!=%/NL/%@exclude_spla=yes

Exclude RDS licenses for all users who have access to Windows servers without a TS/RDS role installed

user-software@software_label=%Remote Desktop Services%&&access_device_terminal_servers!=%yes%@exclude_spla=yes

Exclude SQL Developer edition from SPLA report

server-software@server.domain=customer-fqdn.com&&software_label=SQL Server%&&label=%Developer Edition%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=SQL Server Developer Edition

Note: Be aware that SQL Developer edition is not allowed to be installed in an SPLA environment. Exclusions of SQL Developer editions are only allowed in specific situations. Please consult with your reseller or SAM consultant.

Exclude SQL Express if it's installed on an on-premise ESXi cluster at a customer site, and dedicated to this customer

server-software@server.datacenter_label=%Datacenter-Client1%&&software_label=%SQL Server%&&label=%Express Edition%@exclude_spla=yes

Exclude specific DATEV SQL licenses

server-software@sql_instances=DATEV_%&&software_label=%SQL Server Standard%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=DATEV

Assign Exchange Plus license to specific users, based on AD group membership

user-software@user.ad_groups=%XenDesktop-Enterprise%&&software_label=%Exchange Standard%@plus_edition=1

user-software@user.domain=sh11.lan&&user.extra_fields=%customAttribute15:outlook%&&software_label=%Exchange Server Hosted%@plus_edition=1

Exclude Exchange license by recipient type

user-software@software_label=%Exchange Server%&&exchange_recipient_type=%RemoteUserMailbox%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Remote Mailbox

user-software@software_label=%Exchange Server%&&exchange_recipient_type=%RemoteSharedMailbox%@exclude_spla=yes,exclude_spla_reason=other,exclude_spla_description=Remote Shared Mailbox

Force SQL Enterprise license for all clusters with the given name

server@cluster_label=%spla-sql%@forced_spla_sql_license=7JQ-00341

Force SQL Enterprise license for all hypervisor nodes in a specific cluster

server@type_id=host&&cluster_label=%XXX%@forced_spla_sql_license=7JQ-00341

Force SPLA Windows Server Datacenter OS license on VMware hypervisor hosts

server@hypervisor_id=vmwarevsphere@forced_spla_os_license=9EA-00039

Force SPLA Windows Server Datacenter OS License for all Hypervisor nodes in a specific cluster

server@type_id=host&&cluster_label=%XXX%@forced_spla_os_license=9EA-00039

Force SQL per core licensing on all SQL servers

server-software@software_label=SQL Server%@preferred_licensing_type=core

Assign all customers to a single customer group

customer@@customer_group_id=XXX

Related articles