Custom Archive Name
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 within the Storages section when adding a new storage or editing an existing one.
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 theYYYY-MM-DDformat.{{ 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.
Date Formatting Function
-
date.to_string: Formats a date/time value into a string.Example:
{{ date.now | date.to_string "%Y-%m-%d" }}results in2023-10-05.
The following table explains the format modifiers:
| Format | Result | Description |
|---|---|---|
"%a" | "Thu" | Name of week day in short form of the |
"%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" | 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" | Preferred representation for the date alone, no time | |
"%X" | 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 your GitHub account.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 the Scriban Documentation.
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).
- Consider Sorting: Start archive names with dates or other sortable elements to improve organization.
- Test: Utilize 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.