Copado.yml

## Copado YML repository settings
# This file will allow users to process files within a repository
# A use case for this is to remove offending XML tags that will make a file not deployable.
# E.g. remove all ManageSandbox user permissions from a profile, since this user permission 
# only exists on production environments and will fail when trying to be deployed to sandboxes.
# E.g. remove FLS of deprecated fields, etc

## YML Considerations for application
# YML reg-ex bases and rules can be applied to ANY file in the repository, however the regular use case are profiles, permission sets and objects.
# Those rules operate on files during commit and deployment, and remove or replace references. Depending on the file type a removal can have different consequences upon deployment.
# e.g. removing the reference to a class in a profile will not change the existing access to this class upon deployment. 
# However, if a reference is removed from a permission set, the access level upon deployment will be set to false.
# Similar, if a field reference is removed from a layout, this field will disappear upon deployment from the layout.

## some details and mechanisms, which will be used in the examples
# the reg ex engine applied is Perl, please find more documentation here:https://perldoc.perl.org/perlre.html
# you can check your expressions upfront with web resources, e.g. here: http://www.regexplanet.com/advanced/perl/index.html
# wild cards should be expressed in a non-greedy way to avoid that the engine matches more than planned. an example to match any character non greedy is: .*?
# this is useful for removing managed package items, as managed packages have a prefix: e.g. packagePrefix__.*? 
# In order to not only remove, but also replace, however the functionality and therefore the application is highly limited.
# Currently it is most useful, when changing API versions in pages and classes

### regex_lib or base reg ex expressions.
# in the regex_lib sections, a base reg ex expression is defined. This is to avoid unnecessary typing and allow for easier maintenance.
# those base reg ex expressions define the scope (e.g. fields, user permissions) are referenced by rules
regex_lib:
    field: '(?s)(\n\s*<fields>(?:(?!<fields>).)*?<fullName>___REPLACEVALUE___</fullName>(?:(?!<fields>).)*?</fields>)'
    user-permission: '(?s)(\n\s*<userPermissions>(?:(?!<userPermissions>).)*?<name>___REPLACEVALUE___</name>(?:(?!<userPermissions>).)*?</userPermissions>)'
    class-permission: '(?s)(\n\s*<classAccesses>(?:(?!<classAccesses>).)*?<apexClass>___REPLACEVALUE___</apexClass>(?:(?!<classAccesses>).)*?</classAccesses>)'
    remove-simple-tag: '(?s)(\n\s*<___REPLACEVALUE___>[\s\S]*?</___REPLACEVALUE___>)'
    apiVersion-tag: '(?s)(\n\s*<apiVersion>___REPLACEVALUE___</apiVersion>)'
    validationRulesByActiveTag: '(?s)(\n\s*<validationRules>(?:(?!<validationRules>).)*?<active>___REPLACEVALUE___</active>(?:(?!<validationRules>).)*?</validationRules>)'
    validationRulesByNameTag: '(?s)(\n\s*<validationRules>(?:(?!<validationRules>).)*?<fullName>___REPLACEVALUE___</fullName>(?:(?!<validationRules>).)*?</validationRules>)'

## further useful reg ex base expressions. to use them, remove # at line start and move above this comment after the last reg ex base:
#    field-permission: '(?s)(\n\s*<fieldPermissions>(?:(?!<fieldPermissions>).)*?<field>___REPLACEVALUE___</field>(?:(?!<fieldPermissions>).)*?</fieldPermissions>)'
#    app-permission: '(?s)(\n\s*<applicationVisibilities>(?:(?!<applicationVisibilities>).)*?<application>___REPLACEVALUE___</application>(?:(?!<applicationVisibilities>).)*?</applicationVisibilities>)'
#    tab-permission: '(?s)(\n\s*<tabSettings>(?:(?!<tabSettings>).)*?<tab>___REPLACEVALUE___</tab>(?:(?!<tabSettings>).)*?</tabSettings>)'
#    page-permission: '(?s)(\n\s*<pageAccesses>(?:(?!<pageAccesses>).)*?<apexPage>___REPLACEVALUE___</apexPage>(?:(?!<pageAccesses>).)*?</pageAccesses>)'
#    object-permission: '(?s)(\n\s*<objectPermissions>(?:(?!<objectPermissions>).)*?<object>___REPLACEVALUE___</object>(?:(?!<objectPermissions>).)*?</objectPermissions>)'
#    recordtype-permission: '(?s)(\n\s*<recordTypeVisibilities>(?:(?!<recordTypeVisibilities>).)*?<recordType>___REPLACEVALUE___</recordType>(?:(?!<recordTypeVisibilities>).)*?</recordTypeVisibilities>)'
#    field-translation: '(?s)(\n\s*<fields>(?:(?!<fields>).)*?<name>___REPLACEVALUE___</name>(?:(?!<fields>).)*?</fields>)'

# rules provide context to which files a reg ex should be applied, on which branch and what to do with the finding. replace or remove. 
# in addition rules sharpen the broader scope of the base reg ex towards a single or specific set of items.
# e.g. the reg ex base scopes findings to fields. A rule will define which fields in which objects should be deleted or replaced.
rules:
    ### Example for removing specific references on specific files
    ## Use Case: Delete Jigsaw and SicDesc fields in Account, Contact and Lead objects
    # choose a rule name without spaces or special characters. This is the same for all rules
    invalid_fields:
        # list exact file names of the object where those fields should be deleted
        file_names:
            - 'Account.object'
            - 'Contact.object'
            - 'Lead.object'
        # this identifies the regex base which is used. It must exist on the regex-lib section. This is the same for all rules
        regex_name: 'field' 
        # for each value in the list, Copado will will replace  __REPLACEVALUE__ in the base regex with the actual values listed. This is the same for all rules 
        replace_values:
            - Jigsaw
            - SicDesc
        # no branch means all branches. otherwise is limited to the one listed below. This is the same for all rules
        branches:
        # leave it blank to remove (replace by nothing) the matching regex, or enter a text to be replaced.
        replace_with:

    ### Example for removing specific references on all files of a certain type
    ## Use Case: Delete references for specific user permissions from all profiles or permission sets. In this case: ActivateOrder, ManageSandboxes, EditBillingInfo and ManageRealm
    invalid_user_permissions: 
        extensions: # if you want to apply the rule to types of files, list the file extension names here.
            - profile
            - permissionset
        regex_name: 'user-permission' 
        replace_values: 
            - ActivateOrder
            - ManageSandboxes
            - EditBillingInfo
            - ManageRealm
        branches:
        replace_with:

    ### Example for removing specific references, and elements where the name starts with the same characters on all files of a certain type
    ## Use Case: Remove managed package class access from profiles. 
    # It should remove all classes of copado and TH1 package as well as specific classes, such as the TestDataCreator class, which is deprecated.
    invalid_class_permissions:
        extensions: 
            - profile
            - permissionset
        regex_name: 'class-permission'
        replace_values: 
            - xx__[\w_]+ # change xx for the namespace for any managed package. Credits to Bobby White for this tip!!!
            - TH1__[\w_]+  # this will remove tags of all classes where the API name starts with TH1__ 
            - copado__.*? # removes all classes starting with copado__; a different wildcard syntax is used
            - TestDataCreator # removes references in profiles for just 1 of your own class
            - AgentOne__ManagedPackageClass # removes references in profiles for just 1 AgentOne managed Package
            - CopadoConstants
        branches: # no branch means all branches. otherwise is limited to the one listed below
        replace_with: 

    ### Example of removing references on a specific branch
    ## Use Case: Remove all tags in a file which have a certain type. e.g. all userPermission tags in a profile, in order to handle them manually
    # this will only be performed when committing from or deploying to the uat and production environment, which are linked to the master and uat branch in the repository 
    remove-all-user-permissions:
        extensions:
            - profile
        regex_name: 'remove-simple-tag'
        replace_values:
            - userPermissions
        replace_with: 
        branches:
            - master
            - uat

    ### Sample rule to use replacements 
    ## Use Case: change API versions of classes & pages from 44 to 43
    # this will be performed on the master branch only
    change_api_tag_to_current_version:
        extensions:
            - xml
        regex_name: 'apiVersion-tag' 
        replace_values:
            - 44.0
        branches:
            - master
        replace_with: '<apiVersion>43.0</apiVersion>'