Custom action cheat sheet

This article provides a series of tips to help you maximize the effectiveness of your PowerShell script when creating a custom action in CoreView:

• Get-DomainFromSid: it extracts the domain from a SID value.

Example:

Get-DomainFromSid -Sid S-1-5-21-1454471165-1004335555-1606986666-6666

• Get-ServerFromDn: it extracts the domain from a distinguished name.

Example:

Get-ServerFromDn -dn "CN=user_1,DC=child,DC=server,DC=local"

• Get-ListDomains: this function provides the domains of a forest.

Example:

Get-ListDomains

• Get-ReverseOrganizationUnit: if the value starts with DC=, the function reverts the path.

Example:

Get-ReverseOrganizationUnit -ou "DC=local,DC=contoso,OU=folder"

• unicode: it transforms a string into UTF-8. 

Example:

unicode -str "value"

• Get-CountriesLookup: it contains a lookup of countries

• Get-CountryCodeFromDisplayName: This function returns the iso-code from the display name of a country. 

Example:

Get-CountryCodeFromDisplayName -displayName "Italy"

• Get-CountryDisplayNameFromCode: This function returns the display name from the iso-code of a country. 

Example:

Get-CountryDisplayNameFromCode -countryCode "IT"

• Get-CvOnpremExchangeCredential: this function retrieves the On-Premises Exchange credential object. However, this function is limited to a single forest context.
• Get-CvADCredential: this function retrieves the credential information from an opened Active Directory (AD) session. It's limited to a single forest context.
• Get-CvEmailAddresses: Given a string as input with one or more email addresses separated by a comma, this function returns a list of email addresses even if some elements contain a comma in their name.

Example:

Get-CvEmailAddresses -emailAddresses "fake@domain.com,x500:/o=ExchangeLabs/ou=Exchange Administrative Group (test)/cn=Recipients/cn=1511b2015ac3521f8355f08ca5be1af0-my, test"

• Get-CvGroupCategoryFromValue: given a group type value (an integer) and an email, this function returns the type, so we can understand if that group is a security or a distribution group.

Example:

Get-CvGroupCategoryFromValue -groupTypeValue 8 -mail "fake_distribution@domain.com"

• Replace-Upn: This function replaces a single character ' with a double ''.

Example:

Replace-Upn -upn "user'c.example@contoso.com"

• Refresh-CVGraphToken: this function is designed to refresh the token for the Microsoft Graph session. It's particularly useful when you need to ensure that your session token is valid and up-to-date.
   
• Get-InfrastructureMasterByDomain: This function gets the value of a domain-level role called Infrastructure Master.

Example:

Get-InfrastructureMasterByDomain -domain "contoso.local"

• ConvertFrom-CVCanonicalObject: this function converts a Canonical Name (CN) into a Distinguished Name (DN).

Example:

ConvertFrom-CVCanonicalObject -CanonicalName "Constoso.local/OU Users/myUser"

• Retry-CvCommand: this function is designed to retry a script block multiple times. That is useful when an operation might fail intermittently or the data is not available immediately. 

The function accepts six parameters:

1. $scriptBlock: this is the command that you want to execute. It should be passed as a script block.
2. $params: these are the parameters for the command in the script block.
3. $retryCount: this is an optional parameter that specifies the number of times the command should be retried if it fails. The default value is 10.
4. $sleepTime: this is an optional parameter that specifies the amount of time (in seconds) the function should wait before retrying the command. The default value is 3 seconds.
5. $throwException: this is an optional parameter that specifies whether an exception should be thrown if the command fails after all retries.
6. $stopOnNull: when set to $true, the function will stop the retry pattern if the result of the script block is null, even if the maximum retry count has not been reached.

Examples:

# Use Case 1: Retry with Exception Thrown
# Description: The Retry-CvCommand function attempts to execute the provided script block 'get-aduser' three times for the given 'fake@contoso.com' identity. The function is configured to throw an exception (ErrorAction Stop) if the user does not exist. In this scenario, after three attempts, the function throws an exception indicating that the user doesn't exist.
    $sbUseCase1 ={
        param ($identity)
        get-aduser -Identity $identity -ErrorAction Stop
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase1 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $true

# Use Case 2: Retry without Exception Handling
# Description: The Retry-CvCommand function retries executing the script block 'get-aduser' three times for the given 'fake@contoso.com' identity. However, this time, the function is not configured to throw exceptions (ErrorAction not set to Stop) so the Retry-CvCommand can't catch the exception, and the function will fail three times.
    $sbUseCase2 ={
        param ($identity)
        get-aduser -Identity $identity
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase2 -params "fake@contoso.com" -retryCount 3 -sleepTime 1 -throwException $false

# Use Case 3: Stop Retry on Null Result
# Description: The Retry-CvCommand function retrieves the 'Office' property of an Active Directory user with the provided identity. In this case the user exist but the office property is null so we can will stop immediately the execution (stopOnNull is set to $true). This behavior is useful when you don't want to continue retrying if a certain condition (null result) is met.
    $sbUseCase3 ={
        param ($identity)
        $office = get-aduser -Identity $identity -Properties Office | Select-Object Office
        return $office.Office
    }
    $result = Retry-CvCommand -scriptBlock $sbUseCase3 -params "CN=joker j,OU=OU_test,DC=contoso,DC=local" -retryCount 3 -sleepTime 1 -stopOnNull $true

• Get-CvCustomAttributes: this function provides some information, such as the type and the omSyntax attribute of an Active Directory attribute. The function needs two parameters:

1. className: Active Directory includes a default Schema with many object classes such as users, groups, computers, organizational units and so on. Those objects are known as "Classes"; for example, we could set the value "User".
2. ldapCustomAttributesName: this is the name used by LDAP clients to read and write the attribute, so for example, “costCenter”

Example:

Get-CvCustomAttributes -className 'User' -ldapCustomAttributesName 'CostCenter'