# Archive Name Pattern ## Introduction To enhance the organization and retrieval of backup archives, Cloudback introduces the **Archive Name Pattern** feature. This feature allows you to customize the naming conventions of your backup archives using the **templating engine**, giving you greater control over how your backups are stored and identified. ## Why Customize Archive Names? Customizing your archive names offers several benefits: * **Organization**: Tailor archive names to include specific details like dates, repository names, or account identifiers. * **Easier Retrieval**: Quickly locate the backups you need without sifting through generically named files. * **Consistency**: Establish a standardized naming convention that aligns with your workflow or organizational policies. ## Accessing the Archive Name Pattern Feature You can find the **Archive Name Pattern** option when adding a new storage or editing an existing one. ![Archive name pattern](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-8fa92751c0733556a7bd2020b8bf6d5c4f865ea0%2Fstorage-settings.png?alt=media) ## How It Works The **Archive Name Pattern** feature uses the **Scriban templating engine** to dynamically generate archive names based on a template you define. By incorporating variables and functions, you can create meaningful and consistent names that make managing your backups more intuitive. > **Note:** If the generated archive name is not unique and conflicts with an existing backup, Cloudback will overwrite the existing archive. ## Scriban Template Examples Below are some templates you can use or customize: ### Account and Repository Names with Date ``` {{ date.now | date.to_string "%Y-%m-%d" }}-{{ context.AccountName }}-{{ context.RepositoryName }} ``` In this example: * `{{ date.now | date.to_string "%Y-%m-%d" }}` inserts the current date in the `YYYY-MM-DD` format. * `{{ context.AccountName }}` inserts the name of your account associated with the backup. * `{{ context.RepositoryName }}` inserts the name of the repository being backed up. *Resulting archive name: `2023-10-05-MyAccount-MyRepository`* ### Including Time in Archive Name ``` {{ date.now | date.to_string "%Y-%m-%d-%H-%M-%S" }}-{{ context.RepositoryName }} ``` *Resulting name: `2023-10-05-14-30-00-MyRepository`* ### UUID ``` {{ math.uuid }} ``` *Resulting name: `f47ac10b-58cc-4372-a567-0e02b2c3d479`* ### Short UUID ``` {{ math.uuid | string.replace "-" "" }} ``` *Resulting name: `f47ac10b58cc4372a5670e02b2c3d479`* ## Scriban Template Variables and Functions The Scriban templating engine offers a range of variables and functions for customization: ### Date and Time Variables * `date.now`: Current date and time in UTC. ### Date Formatting Function * `date.to_string`: Formats a date/time value into a string. *Example:* `{{ date.now | date.to_string "%Y-%m-%d" }}` results in `2023-10-05`. The following table explains the format modifiers: | Format | Result | Description | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | `"%a"` | `"Thu"` | Name of week day in short form of the time | | `"%A"` | `"Thursday"` | Week day in full form of the time | | `"%b"` | `"Sep"` | Month in short form of the time | | `"%B"` | `"September"` | Month in full form of the time | | `"%c"` | `"Thu Sep 12 22:49:27 2013"` | Date and time (%a %b %e %T %Y) | | `"%C"` | `"20"` | Century of the time | | `"%d"` | `"12"` | Day of the month of the time | | `"%D"` | `"09/12/13"` | Date (%m/%d/%y) | | `"%e"` | `"12"` | Day of the month, blank-padded ( 1..31) | | `"%F"` | `"2013-09-12"` | ISO 8601 date (%Y-%m-%d) | | `"%h"` | `"Sep"` | Alias for %b | | `"%H"` | `"22"` | Hour of the time in 24 hour clock format | | `"%I"` | `"10"` | Hour of the time in 12 hour clock format | | `"%j"` | `"255"` | Day of the year (001..366) (3 digits, left padded with zero) | | `"%k"` | `"22"` | Hour of the time in 24 hour clock format, blank-padded ( 0..23) | | `"%l"` | `"10"` | Hour of the time in 12 hour clock format, blank-padded ( 0..12) | | `"%L"` | `"000"` | Millisecond of the time (3 digits, left padded with zero) | | `"%m"` | `"09"` | Month of the time | | `"%M"` | `"49"` | Minutes of the time (2 digits, left padded with zero, e.g., 01, 02) | | `"%n"` | | Newline character (\n) | | `"%N"` | `"000000000"` | Nanoseconds of the time (9 digits, left padded with zero) | | `"%p"` | `"PM"` | Gives AM / PM of the time | | `"%P"` | `"pm"` | Gives am / pm of the time | | `"%r"` | `"10:49:27 PM"` | Long time in 12 hour clock format (%I:%M:%S %p) | | `"%R"` | `"22:49"` | Short time in 24 hour clock format (%H:%M) | | `"%s"` | | Number of seconds since 1970-01-01 00:00:00 +0000 | | `"%S"` | `"27"` | Seconds of the time | | `"%T"` | `"22:49:27"` | Long time in 24 hour clock format (%H:%M:%S) | | `"%u"` | `"4"` | Day of week of the time (from 1 for Monday to 7 for Sunday) | | `"%U"` | `"36"` | Week number of the current year, starting with the first Sunday as the first day of the first week (00..53) | | `"%v"` | `"12-SEP-2013"` | VMS date (%e-%b-%Y) (culture invariant) | | `"%V"` | `"37"` | Week number of the current year according to ISO 8601 (01..53) | | `"%W"` | `"36"` | Week number of the current year, starting with the first Monday as the first day of the first week (00..53) | | `"%w"` | `"4"` | Day of week of the time (from 0 for Sunday to 6 for Saturday) | | `"%x"` | `"09/12/13"` | Preferred representation for the date alone, no time | | `"%X"` | `"22:49:27"` | Preferred representation for the time alone, no date | | `"%y"` | `"13"` | Gives year without century of the time | | `"%Y"` | `"2013"` | Year of the time | ### Context Variables * `context.AccountName`: Name of the platform account associated with the backup (GitHub organization or user, Azure DevOps organization, GitLab group, or Linear workspace slug). * `context.RepositoryName`: Name of the repository being backed up. ### String Functions * `string.replace`: Replaces all occurrences of a string with a substring. *Example:* `{{ math.uuid | string.replace "-" "" }}` removes dashes from a UUID. ### Conditional Logic You can incorporate conditional statements: ``` {{ if context.AccountName == "Admin" }}AdminBackup{{ else }}UserBackup{{ end }} ``` *This will name the archive `AdminBackup` if the account name is "Admin", otherwise `UserBackup`.* ## Scriban Documentation For a complete list of variables and functions, refer to the [Scriban Documentation](https://scriban.github.io/docs/builtins). ## Best Practices When creating custom archive names, consider the following best practices: * **Keep Names Unique**: Ensure archive names are distinct to avoid conflicts and overwriting archives. * **Avoid Illegal Characters**: The name can only contain ASCII letters, digits, and the characters '.', '-', and '\_' (period, hyphen, and underscore). Any other characters in the generated name are automatically replaced with hyphens - they are not rejected. * **Do Not Include `.zip`**: Cloudback automatically appends the `.zip` extension to the evaluated archive name. You do not need to include it in your pattern. * **Consider Sorting**: Start archive names with dates or other sortable elements to improve organization. * **Test**: Use the **Test** feature to validate your templates before applying them. ## FAQ **Q: What happens if I don't specify an Archive Name Pattern?**\ **A:** Cloudback will default to its standard naming convention if no custom pattern is provided. The default naming scheme is "Short UUID" `{{ math.uuid | string.replace "-" "" }}`. **Q: Are there limitations on the length of the archive name?**\ **A:** Yes, most file systems and storage providers have a maximum file name length (often 255 characters). It's best to keep archive names concise. **Q: How do I troubleshoot if the archive name isn't generated correctly?**\ **A:** Use the **Test** button to preview the archive name. If there's an error, double-check your Scriban syntax and ensure all variables are correctly referenced. **Q: Is there a way to reset to the default naming convention?**\ **A:** Yes, simply clear the contents of the **Archive Name Pattern** field, and the system will revert to the default naming scheme. ## Learn More * [Customer Managed Storages](https://docs.cloudback.it/storage-configuration/customer-managed-storages) * [Data Deduplication](https://docs.cloudback.it/managing-backups/data-deduplication) * [Backup Details](https://docs.cloudback.it/dashboard/backup-details)