Working with hundreds of churches over time has given us insights into the best ways to build and maintain Rock for a peak experience. While we have an extensive amount of training materials and learning, our goal is to share the most commonly needed and useful insights with the Rock community. We realize that shared success is the best success and know that by freely sharing our best practices we are all #BetterTogether.

This manual is a living document and will change over time as our team continues to learn and grow. Be sure to check back from time to time and follow along with our Resources page on our website for up-to-date training videos, handy Rock tools and more.  

Top 10 Rock Tips

There are many important tips for getting the most out of Rock. Before we dive into all the details, here is our list of the Top 10 concepts to keep in mind.

1. Make sure your digital strategy aligns leadership expectations and investment goals. Rock is the engine for your digital strategy. It is key to be sure Rock is adequately resourced.
2. Use Rock as your central data warehouse. Extend it in ways that keeps your data centralized, not splintered, for maximum personalized ministry potential.
3. Document everything. Start with your workflows, reports and data views. Don't forget your complex processes.
4. Systems increase in complexity. Invest in regularly reviewing your performance, security and configuration to prevent issues from developing.
5. Don't change the source of core files. Make core requests if needed, to fix bugs, add features or share ideas.
6. Limit changes to the approved directories on your server's filesystem. The only folders you should make changes in are: Content and Themes (and only your themes).
7. Cache is the key to performance. Use these videos for insights into how cache works in Rock:
   1. Caching within Rock
   2. La importancia del caché
8. Don't use JavaScript to change the DOM of core blocks and features or CSS to hide/move core block content.
9. Avoid hardcoding business logic in SQL and Lava.
10. Workflows are muscles, not bones. Don't over complicate them.

Infrastructure

Your servers are the foundation of your Rock experience. Making sure they are healthy and well-resourced can make all the difference in your system's performance, helping you remain prepared for both the expected and unexpected.

Initial Installation

While there are many options for hosting your Rock environment, the community tends to use Microsoft Azure for cloud hosting and in some cases on-site servers. You can find basic guides for these in the community. Our team has documented additional best practices for setting up and maintaining your infrastructure, which are outlined here.

In our experience organizations tend to under provision their Rock servers. Keep in mind, this is the engine for your church's entire digital strategy. You wouldn't put a lawnmower engine in your sports car so don't starve your Rock server of the resources it needs to amplify your ministry.  

When Setting Up Your Servers

Your initial configuration could make a big difference in your infrastructure's performance every day and during peak usage.

1. Separate your production and sandbox environments. While it may seem tempting to use one server (or VM) for both environments, your tradeoff increases risk for very little financial consideration. Putting them on different servers is a security measure to help avoid any problems that could affect your live operations.
2. Avoid using IIS bindings for multiple domains. When setting up IIS (Internet Information Services) bindings for Rock instances, it's a good idea to give each instance its own virtual machine (VM), as noted above. Also, make sure each instance has only two bindings - one for HTTP (port 80) and another for HTTPS (port 443). This way, if you add a new site with a different domain, you won't have to reconfigure IIS because Rock will handle the traffic and show the right site based on your settings. Additional bindings are not necessary and create a trip hazard.
3. Protect your system by setting up regular backups for both your web server and SQL server. This ensures that if you lose data or your system has problems, you can quickly bring everything back to how it was before. As you're considering your backup settings, make sure to keep in mind potential short-term and long-term recovery needs.
4. Consider these additional IIS settings.
   1. Enable Compression: Install the compression module on the server and enable compression within IIS. Compressing the content from your Rock server is important for quick response.
   2. Enable WebSocket Protocol (available through Microsoft Azure SignalR service): Rock's Real-time Engine will work best with WebSocket Protocol allowing you to receive real-time information from the server. If this is not enabled, you'll receive repetitive pings against the server to receive updates, which is much less efficient.

Monitoring Your Resources

Surprises are fun for parties, but not when it comes to your critical architecture.

1. It should go without saying but be sure to monitor your IIS logs to see trends over time and understand if your resourcing needs are increasing or there may be a performance issue that needs to be addressed. We recommend reviewing your IIS logs at least every other month. You'll be surprised by what you learn about the traffic on your Rock server.
2. Additionally, make sure to regularly update your virtual machine and SQL database, and upgrade the SQL Server compatibility level to keep up with the latest improvements.
3. Set up proactive monitoring and alerts. We'd rather have an alert tell us something is wrong vs our pastor. We recommend Better Stack Uptime as a great option. Others in the community have also had success with Pingdom and Status Cake.
4. New in v16, Rock added an incredible new feature called Observability. This allows you to send detailed timings and metrics to observation platforms like NewRelic. Having this data available is critical to operating a well-tuned digital platform.

Beyond the Basics

Once you've mastered the basics, consider how these areas may apply to you.

1. Smart Scaling Strategies: When it comes to expanding your system, it's better to add more resources to one server (scaling up) instead of adding more servers that must work together (scaling out). This can make your setup less complicated and easier to manage.
2. Optimize API Requests with Batching: If you're using Rock's REST API for integrating services, try to group API requests together (batch them) or use a custom endpoint to prevent overusing the API. This makes your system more efficient by combining multiple requests into one, reducing extra work and improving overall performance.
3. Consider Using a Content Delivery Network (CDN): In today's digital environment a CDN is nearly a requirement. If your server is handling a lot of traffic, think about using a Content Delivery Network (CDN). CDNs spread your website content across different servers worldwide, making it load faster for visitors and reducing delays. A CDN is especially important if you're running your external website and mobile applications on Rock.

Configuración

Rock is extremely extensible, which means there are a wide range of configuration options and combinations available. While there is usually more than one right way to accomplish what you want in Rock, there are usually also many other incorrect ways.

Rather than solving just the problem at hand, consider future maintainability. This will help you avoid building a "house of cards" that becomes unstable. Work with the core product whenever possible, and even request a funded Rock core update, if needed, or add an idea to the idea board for the community to upvote. This is a much safer long-term alternative to copying core blocks and making changes to them, which is not recommended.  

The state of your data can have an impact on the performance of your Rock instance, as well. Be sure to use the included data integrity settings and reports to keep it as clean and accurate as possible.

As you're customizing Rock for your needs, keep the following configuration best practices in mind.

General

At a high level, there are several themes to consider as you tackle your Rock configuration.

Build with the Same Tools

There's an infinite number of tools and technologies you can use to extend and build off Rock. Try to use the same tools as the community whenever you can. This will provide you with several helpful benefits including:

1. Making it easier for your organization to support over time. Other community members will know it and partners will be well versed in it.
2. Allowing you to share more easily with others, which propels the entire community forward.
3. There are more resources available as a reference.

A Clean Instance is Key

And while it may seem like a small thing comparatively, keeping your Rock install clean and organized is like keeping your physical workspace tidy, especially helpful because it is shared with so many staff members.

1. Use icons consistently to help quickly differentiate between options.
2. Clear Sparklink notifications from the home page so they do not become overwhelming.

Descriptions Should Be Mandatory

When you see a description field, consider it a required field. Whether workflows, data views, helper text or more, providing context and documentation about why something exists and what it's used for will be invaluable in the future.

Hints on Specific Field Types

1. When creating a single select or multi select field type, provide keys for your values. This will allow you to rename them later without appearing to lose data. For example, instead of listing options as Apples, Lemons, Cherries, list them instead as 1^Apples, 2^Lemons, 3^Cherries.
2. Avoid using Matrix Attributes unless you've exhausted all other solutions, and they are absolutely needed. These fields are powerful, but they are less efficient, don't have reporting tools available, and take a lot of effort to get values from them.

Group

Be careful to avoid creating an infinite loop of parent-child-parent associations in group types (where a parent group type is set as a child of the child group type). We have seen this happen especially in check-in configurations.

Group Type changes should be avoided in general. Where unavoidable, special consideration should be given to the following:

1. Check to make sure the group in question is not using a Group Sync. The group sync should be deleted, if present, before making the change and added again after the group type is changed, to avoid group member mismatch exceptions.
2. Ensure Group Member role ids are updated in both Group Member and Group Member Historical tables.
3. Account for attributes that are added to group types. These attributes won't exist in the new group type. So you'll either need to migrate their values to new attributes or perhaps delete them first if they're no longer needed.

Security

1. File types can have security on them. Make sure that sensitive file types have correct security AND don't have URLs that would allow file access without going through Rock (for example, don't store secured files in the FileSystem).
2. People can belong to lots of security roles. So, try to keep your custom security roles very focused: only allowing or denying access for a small number of related pages, blocks, or processes. If someone needs multiple roles, just add them to both security roles. Document and maintain your security roles well so that they are understandable in the future when onboarding and offboarding staff and volunteers.
3. When creating a new security role, start by choosing a security role that is closest to your intended use-case. Your new security role should allow or deny additional roles from the foundation of the existing security role. Then add the people to BOTH of these security roles so that the new role is "stacked" on top of the existing role.
4. When editing security at the page or block level, use security roles rather than adding specific individuals whenever possible.

Jobs

1. Don't ignore jobs that are taking longer to run than they should. As an absolute minimum, make sure that a job doesn't take so long to complete that it is not finished by the time it is supposed to start again (even though Rock won't let multiple instances of the same job run at a time). Jobs should not take hours to complete.
2. Review your job history at least once a week to look for jobs that are having issues.

Finance

1. Rock batches are intended to be tied out to the batches in your bookkeeping system of record. Each month, as your books are reconciled and closed, the matching Rock batches should be closed. The only open batches in Rock should be associated with transactions during a month that has not yet been reconciled.

Data Views and Reports

1. Consider persistence for your data views. While not every data view should be persisted, be sure to approach this topic smartly, and set persistence frequency with careful consideration. Persistence allows your data views to load more quickly and be more performant. Don't forget, however, that if you are viewing a report or stacked data view, the persistence of each data view will impact the refresh rate for the data shown. Persistence is preferred and should be tailored for each use case.
2. While reusing basic data views is recommended, avoid multiple levels of nested data views that use similar filters where possible. This can cause performance issues. Your reporting strategy should be reviewed from time to time and duplicate or overlapping data views cleaned up, especially if data views and reports are built by many members of your staff.
3. When building reports, avoid creating custom Lava columns that use entity commands or get properties from other related entity types. These can affect performance quickly, especially for reports with large data sets.

Flujos de trabajo

Think of workflows like the dynamic muscles that make processes flexible. They help connect different features and make things happen, rather than being the fundamental building blocks like bones. This means that they are best used for action, and to move data into the right locations in Rock. They are not intended to store data. It also means that it is generally better to have many small workflows that work together instead of one big, complicated one. This makes things easier to manage and fix if something goes wrong. 

Workflows Can Impact Performance

Workflows are very powerful, but they can easily have an outsized impact on your server if not configured correctly. Here are some of our top tips for managing your workflows efficiently. 

1. When dealing with workflows, try not to persist them if it's not necessary. There are quicker ways to note when something occurs. If you must persist in a workflow, think about how infrequently you can process it to lessen the impact on your server. For example, workflows waiting for someone to fill out a form don't need to be processed every ten minutes. Adjusting the timing helps your system work better.
2. And always mark workflows as complete when they finish their tasks. Be careful with skipped actions, as they can keep processes running and may slow down your system. When setting up a workflow make a thoughtful decision on the best timeframe (in days) for completion, keeping the workflows, and holding onto logs. This helps keep your system clean by getting rid of older or finished workflows.
3. Workflow logging is a handy tool for identifying issues in your workflow, however it is best used as a temporary support. Keep workflow logging turned on only for as long as you need it for fixing problems. Turning it off when you're not actively troubleshooting can save resources.
4. Be sure to set a well-considered "Processing Interval" for each of your workflows. This setting tells Rock how often it should wake up a workflow to ensure there are no updates needed. In most cases, your workflow will only be changed by interaction with a person. When this is the case the processing interval can be set to a very high number (like once a day or even longer).
5. The "Maximum Workflow Age" setting can also be a critical setting in ensuring that your Rock instance isn't repeatedly processing workflows that are no longer needed. If a workflow is still active after this configured time period, Rock will automatically inactivate it.

General Configuration Tips

Workflows have many settings and options. Here are some considerations that may be helpful.

1. Be cautious with workflow triggers. They can be tricky to find later and might accidentally make things loop forever, causing problems for your system. They can also be a performance issue for your server if not configured correctly or if they are placed on entities that are often changing. When you do need to make a trigger be sure to use a "Post-Save" trigger as they do not slow down the UI.
2. When sending a text message through a workflow, avoid using an SMSResponse attribute in combination with the SMS Send workflow action. If you do, the recipient would get the message twice.
3. Don't default to using SQL workflow actions. Try not to use workflows that involve SQL unless you really need to. If there's no other solution, think carefully about whether a core enhancement may be needed instead.
4. Remember, workflows don't have built-in security when you create them. Especially when using external, public forms, make sure to set up the first steps of your workflow carefully to only allow one type of workflow, adding extra security.

Think of Your Future Self

It would be hard to over-document a process. Write down all the details about your workflows in the description and changelog. This not only helps your organization understand what's going on but also gives you a helpful guide for future improvements. We call this a love letter to our future self.

Check-in

Check-in is one of the more complex parts of Rock. Here are some tips to make Check-in work the best for you and your families.

Security Codes

1. The pool of security codes is shared by all check-ins for a day (even ones that don't print a code on the label). Because of the way Rock generates the codes, it's better for check-in performance to use four characters (instead of three) if you check in more than a few thousand people a day.

Labels

1. Don't modify core Rock labels. Instead, make copies of the core labels that ship with Rock and modify those copies, since core labels can be overwritten on Rock updates.
2. Keep in mind that attractive, well-designed labels present your church in a good light and make you stand out! Labels are formatted in ZPL. You can find everything you need to get started in Rock's label documentation.
3. As you're testing your labels, don't forget to test using the shortest and longest possible character counts in your text fields to understand how they will handle edge cases.

Configuración

1. Don't duplicate configurations, groups, or schedules unnecessarily. Whenever possible, use the same check-in configuration, groups and schedules for different campuses. Simple is best!
2. The check-in experience for parents should be a prime consideration in configuring check-in. Avoid asking them to make decisions they won't understand ("How would I know to choose group A over group B, when both are options?", for example).
3. Don't edit the stock check-in workflow.
4. Watch out for circular group type references. They can cause Check-in Manager to crash Rock. See this community Recipe for more info.

Hardware

1. For "bulletproof" check-in, a hardwired network is ideal, followed by Wi-Fi, then Bluetooth in order of robustness.
2. Rock requires ZPL-compatible printers (see our recommendations in the Printers section of our Checking Out Check-In manual). A word to the wise: printers with cutters will make your life easier! They become virtually jam-proof if you don't require folks to tear off labels.
3. Watch out when you order printers – labels are designed for a specific resolution (the core labels are designed for 203 dot-per-inch printers). Printer orders can sometimes take awhile to be fulfilled. Make sure you order them with as much advance notice as possible.
4. We highly recommend ordering your printers and labels from iT1 Source. Not only will you get the best price, you'll also get the best service.
5. To prevent jamming and to speed up lines we highly recommend getting cutters for your Zebra printers.

SQL

SQL is a powerful option for your Rock tool kit. Here are some guidelines that will help you understand when and how to use SQL for the best results.

Formatting Standards

1. Using standard conventions is important for writing quality SQL. The core team has provided a basic SQL Style Guide for the Rock Community. Be sure your SQL formatting follows these standards. You can find assistance in formatting your SQL with this free online tool.
2. Additionally, our team has put together a video on SQL Best Practices, offering valuable insights into formatting guidelines and tips to enhance your query construction.

When to Use SQL

1. In the realm of Rock, think of SQL as outside of the castle walls - a powerful but external tool. Although SQL may be the right answer in the end, you should avoid making it your initial choice. Explore Rock's internal configuration options first, as they offer more robust solutions that are dynamically tied to Rock's underlying structure.

How to Use SQL

1. If SQL is the right answer to your problem after all, be sure to construct your statements with the future in mind. Rather than embedding configuration or business logic into your SQL (such as WHERE [Id] IN (23,24,25) ), instead avoid referencing specific Ids that have to be maintained over time. Opt for a more future-proof approach. For insights into writing dynamic SQL, check out this video.
2. The videos linked above provide a deeper understanding of how SQL operates beyond Rock's protective barriers, offering valuable tips for those times when SQL is the ideal choice for your project.
3. Want to go deeper with SQL? We highly recommend you take the Rock SQL Class.
4. Want to go even deeper? We highly recommend this book: T-SQL Fundamentals.

And More

As our team delves deeper into SQL, we continually share our insights on our website - ranging from introductory to advanced topics. Here is a sample of what you will find. Check back periodically to explore new content, including:

1. Trucos con dátiles
2. Orden de ejecución de SQL
3. Patrón de pivote

Lava

Lava is an incredible tool in the belts of Rock Administrators! It gives you the ability to easily get information out of your database and display it on a page without having to do any programming. With very few exceptions (such as the {% sql %} command and the {% interactionwrite %} command), Lava is also read-only so you don't need to worry about potentially causing data to be deleted or edited incorrectly.

However, we recommend that you are intentional with your approach to Lava - it can cause performance slowdowns if you don't design your templates carefully, and your future self will thank you if you keep your work as clear and readable as possible.

Formatting Standards

1. As with SQL, formatting and documentation standards are important for readability and future updates and troubleshooting. Please follow the guidelines provided in the Lava Style Guide. And here are the differences in syntax to keep in mind between DotLiquid and Fluid.
2. Additionally, keep configuration and variable declarations at the top of your lava sections / scripts rather than embedding them inline. This helps with updates and keep scripts more maintainable.
3. Don't use the {% comment %} tag but prefer the //- and /- -/ syntax.
4. For readability don't add hyphens to your tags (e.g. {%- assign ... -%} unless the existence of whitespace will break what you're doing. In most cases additional whitespace does not matter.

Performance Considerations

1. A single entity command can trigger several thousand database calls if you're not careful. Consider using advanced filters like expressions, select and prefetch attributes when using entity commands to limit the amount of data being brought back from the database. You can also set 'securityenabled' to false where applicable to improve performance.
2. Using caching strategies like Conjuntos de datos persistentes also helps improve real time performance. You can use {[benchmark]} shortcode from the free Lava Tools Plugin to get a lot of information about the performance of a lava template, while creating templates to help make decisions between using different strategies.
3. Use the Fluid Lava Engine as soon as possible.

Design Considerations

Like any other tool, there are a few considerations to keep in mind to get the most out of lava. We have listed a few key ones here.

1. Be aware of the field type of data you are handling and account for the existence of data in Lava with null and empty.
2. Refrain from using {% unless %}, except as a check for the last run of a {% for %} loop.
3. Use shortcodes to extend the functionality of lava tags, and {% include %} tags to reuse templates across multiple pages.
4. Avoid nesting shortcodes and includes. Keeping track of the scope of variables can get complicated real fast.
5. The free Lava Tester plug-in can save you a lot of time in quickly testing your Lava against your real-world entities.

Web

At its core, Rock is a website - or really, it's probably a series of websites. There are a lot of powerful things you can do with web sites, pages, and blocks in Rock, but here are some guidelines to make sure you're not laying traps for yourself, and to keep your website as responsive as possible.

Magnus

Triumph has invested heavily in the development of Magnus, a plugin that deeply integrates into VS Code and Azure Data Studio. Using Magnus allows you to easily edit content and data in Rock directly from these amazing tools. Look for Magnus in the Rock Shop inside your Rock instance.

External Website

1. When you install Rock, there is a default external site available to show you some of the capabilities of Rock. But this site is designed to be a demonstration, not the starting point of your own website.
2. During version updates, we will occasionally add or edit pages and functionality on this site, to allow you to keep up to date on some recommended functionality for your external site. You don't want us to be making these changes on your actual external site, especially if it's a new feature you're not ready to start using yet! So, when you're ready to start using Rock as your external website (or a partial website with functionality like Event Registration, Group Finder, and online Giving, we recommend you create a brand-new site for your visitors to view, instead of using the pages on the default External Website.
3. And of course, you'll want to use a different theme than the default Stark theme for your new external site- we designed that to be basic intentionally, so you're not tempted to use it. We don't want every church to end up using the same theme and looking the same as each other.

Centralized Templates

1. Rock has several ways for you to store templates in one place and use them in multiple blocks. The most common ones use Lava; these are Include files and Lava Shortcodes.
2. Include files are nice if you are using source control to deploy or track changes as you make them. But they're more difficult to quickly load and examine when you're troubleshooting or editing something in Rock, and it's important to note that variables can't be passed to and from include files when you're using the recommended Fluid Lava engine.
3. Generally, we recommend centralizing your templates in Lava Shortcodes instead. These have built-in fields to allow you to provide documentation on how and where they're intended to be used, they can be dynamic based on parameters you pass into them, and they're easy to load in the Rock UI and examine or edit when necessary.

Fast Page Loads

All of the data that lives in your Rock system has to be stored somewhere. For the most part, your data lives in your database. But data can also be cached in RAM which is much faster for the server to retrieve. And fast data retrieval means more than just fast pages- it also means more capacity for more people using your system at the same time. Here's what you need to know about caching. 

1. Generally anything that's cached has to be retrieved once from the database, but the point of caching is that once we've gotten that data out of the database, we don't want to send the server back to the database over and over to get the same information each time.
2. Some blocks such as the Content Channel Item/View blocks or the HTML Content block have settings that allow you to control how long the data shown by the block is stored in cache. Generally speaking, unless there is Lava that personalizes the content dynamically (such as according to who is loading the page), you should always cache these blocks' content.
3. But anywhere you can use Lava, you can also specify that certain content should be cached using the {% cache %} tag. And these tags are super powerful because they're stored and looked up again later by a specific key - a key that you get to specify. So, when you're using a cache tag, even if you have content that does get personalized, you can include an indication of what personalizes the content in the key. For example, if you personalize content based on the time of day, you could have cache key that dynamically includes the time of day, such as front-page-greeting-morning versus front-page-greeting-afternoon. That way as long as the factor that customizes the content doesn't change, Rock can keep using the cached content. But as soon as the factor changes, Rock will go get the latest content and cache it with the new tag. You can use this concept with other factors as well, such as what parameter value is provided in the page URL.

Maintainable and Accessible HTML

When you are adding HTML to any of your templates or blocks, it's good to be aware of (and use) semantic markup wherever possible. 

1. This is important for accessibility reasons; for example, using an <article> element is semantic HTML and makes it very easy for technology like a screen reader to identify the main content that a page is designed to show. It's much harder for a screen reader to figure this out if we use non-semantic markup like <div class="article">.
2. It also makes the markup more maintainable and readable for others on your team (or even yourself in six months!). And applying theming to semantic markup makes more sense too; a <b> tag (which is not considered semantic) is just supposed to make text bold. And even though you can specify that all <b> tags should also be colored red for emphasis, it's not likely that anybody reading your markup would assume that there's any styles except bold applied to these elements, so it's confusing. On the other hand, the semantic <strong> tag doesn't have any pre-conceptions attached to it except that text in this tag will stand out strongly on the page. It makes a lot more sense to apply color specifications as well as weight specifications (and maybe other styles too!) to these semantic tags.

CSS

Rock has a powerful set of CSS utility classes. Use these whenever possible to simplify and reduce the amount of custom CSS you write.  

JavaScript

Since Rock is viewed as a series of web pages using a browser, of course the browser is capable of running any JavaScript that you might include on the page. However, we recommend that you never use JavaScript to modify the look, layout, or functionality of core blocks. This is because core blocks are always changing and being improved, and customizations that you try to make this way are likely to break in the future. If you need a block to work a different way than it currently does, we recommend that you work with a Rock partner to get updates made in core - this also benefits other churches who now have access to the functionality you requested. 

Choosing Your Integrations and Extensions

Now that you've read through our team's most popular Rock best practices, be sure to apply the same thoughtful consideration to the ways that you're extending your core platform and the organizations you're partnering with.

Just as not all applications on your phone's app store are of the same quality (think architecture, design, maintenance and responsiveness), not all Rock extensions and integrations are created equally as well. Be sure to do your homework and choose with care.

1. We recommend only installing plugins that have been tested on a sandbox server and are confirmed as needed for your ministries. Additionally, be sure to update them to the latest versions as they are made available, and you have tested them.
2. Apply the advice of those you trust and stay up to date on community feedback regarding available integrations by reading this community survey on integrations.
3. Consider the pros and cons of building out your Rock experience vs. adding an integration that pulls data out of Rock in order to manipulate it or communicate with your members. There is a loss of valuable data in interactions and insights when you use integrations that "splinter" your data into different databases, rather than keeping Rock as your data warehouse, which allows for deep, rich personalization.
4. Finally, when choosing a partner for consulting and development of your Rock instance, be sure to ask the questions recommended by the Spark team. And don't forget to review each partner's output as an indication of their expertise, training and processes, to be sure you're making the best selection for your long-term Rock experience.