Best practices for Jitterbit App Builder

Introduction

App Builder applications can grow in size and complexity, often involving the work of several developers over many months or years. These best practices will help you manage this complexity, make your apps easier to maintain, and keep them running at peak performance.

The app development lifecycle

Build your apps by iterating over the following tasks:

1. Discover

2. Model

3. Build and show

4. Refine and test

5. Deploy

6. Maintain

1. Discover: Gather requirements

Before you start building an app, you should have an outline of what it will do and who will use it. Here are some ideas for how you can get this information:

• Listen and learn: Organize in-person workshops and design sessions to understand who will use the app and what it should do.

• Identify key information: Gather and document the core requirements for data, user personas, business processes, and access and security.

• Avoid assumptions: Ask questions to make the app user think critically about what they are asking you to build. Challenge the rationale and logic behind your users' business processes.

• Confirm understanding: Read back your understanding of the requirements with your app users and other stakeholders. Use flow diagrams and other visual tools to better communicate technical needs with non-technical users.

2. Model: Design the foundation

A solid data model is the foundation of a successful application. Be willing to spend time on this step to avoid significant rework later.

• Create an entity-relationship diagram (ERD): An ERD documents your data model, making it easy to understand table structures and relationships. It provides a whiteboard-like experience where you can make changes easily before committing them to the database. The following is an example of a simple ERD:

  erDiagram
   Student {
       UUID student_id PK "Student ID"
       string name
   }
     Course {
       UUID course_id PK "Course ID"
       string title
   }
     Enrollment {
       UUID enrollment_id PK "Enrollment ID"
       UUID student_id FK "Student ID"
       UUID course_id FK "Course ID"
       string grade
   }
   Student ||--o{ Enrollment : "takes"
   Course ||--o{ Enrollment : "has"

• Design foundational elements: In addition to the data model, create flow charts, swimlane diagrams, wireframes, and sitemaps as needed to flesh out the application design.

3. Build and demo: Iterative development

With a solid design in place, you can begin building the application.

• Build in layers: Develop your app in distinct layers: Data, Business Logic, and User Interface. Build from the data layer up.

• Define a minimum viable product (MVP): Define and list the core elements of the app and get approval from app users before starting the main build.

• Demo early and often: Schedule regular demonstrations of the working parts of the app. This helps users understand what's possible, and adjust their expectations and requirements.

4. Refine and test: Incorporate feedback and QA

• Refine: Incorporate feedback from demo sessions to refine the application and add more granular UI/UX design features.

• Test: Thorough testing is important.

  • Internal QA: Always perform internal testing first to catch bugs.

  • End-user UAT: Let app users perform User Acceptance Testing. They know the business process best and can provide valuable feedback.

  • Use realistic data: Use realistic test data to ensure features are tested in the way end-users would use them.

  • Positive and negative tests: Test for both expected outcomes (positive tests) and unexpected behaviors (negative tests).

5. Deploy: Release management

• Package and install: Use App Builder's Release Management to promote schema changes and application updates between environments. This ensures changes are replicated in the correct order and reduces the risk of human error.

• Initial release: The MVP is live in production. Development is typically frozen for a short period to focus on production support.

• Future releases: The development process restarts for new features and future releases.

6. Document and maintain

• Document the business process: This is essential for knowledge transfer, onboarding new developers, and for future maintenance.

• Delete unused objects: Regularly delete unused tables, rules, and pages to reduce application complexity and make it easier to work with.

• Don't leave things broken: Finish features you are working on. A broken or unfinished feature creates confusion for other developers and is harder to complete later.

Data layer

Data modeling

• Naming conventions:

  • Use distinct, singular, and descriptive nouns for tables (for example, Customer, Order). Avoid abbreviating them where possible.

  • Use UUIDs for all primary and foreign keys. A good naming convention is TableNameID (for example, CustomerID).

  • Prefix boolean fields with "is" (for example, isActive).

  • Business rules tend to proliferate. Use business rule naming conventions to keep track of them.

• Keys and indexing:

  • Single-part primary keys: Use single-part UUID primary keys. This simplifies the data model and automatically supports App Builder's full audit capabilities.

  • Index columns: Index all foreign keys. Also, index any fields that are commonly used for sorting, filtering, or joining data to optimize performance.

• Relationships:

  • Use bridge or join tables to manage many-to-many relationships. Avoid flat designs (adding multiple columns for related data to a single table), as they are not scalable.

Table design

• Configurable data: Design your data model to be configurable. For example:

  • Values that might change over time (such as statuses) should be stored in separate lookup tables rather than hard-coded in business logic.

  • For time-based data (such as pricing), use a lower-level table with effective date ranges.

• Enable auditing: Enable Audit Lite or Full Audit for all tables to automatically track data changes for history and compliance.

• Define table usage: As you create tables, define their usage type (Developer, Shared, or User data). This controls how data is promoted between environments and is crucial for release management.

• Consistent values: Be consistent in how you use values such as NULL. A NULL value should have a clear and consistent meaning throughout your data model.

Lookup and parameter tables

• Lookup tables: Use lookup tables to manage lists of values. They should include the following:

  • Title: A human-readable display value. App Builder uses the Title usage type to automatically generate list controls.

  • Enum: A static, human-readable enumerated value. Using enums in business logic is much clearer than referencing a raw UUID.

  • IsActive: A boolean to control which values are available for selection in the UI.

  • Index: An integer column to control the default sort order of the list.

• Parameter table: Every application should have a parameter table. This is a unique table that contains only one record and is used to store global application settings and constants. This avoids hard-coding values and allows administrators to change them through the UI.

Data connections

• Secure connections: Configure secure connections to external data sources.

• Use App Builder connectors: When you need to use data from another application's database on the same server, use an App Builder Connector. This reduces deployment dependencies, as you do not need to push the logical and physical models of both databases simultaneously.

Business logic

Rule design

• Know the available rule types: Understand when to use business objects (for displaying data), validations (for checking data), and CRUD rules (for changing data).

• Keep rules simple: Simplify how objects and rules are built. Use reusable subqueries wherever possible to avoid duplicating logic.

• Data-driven logic:

  • Configure more, code less: Store changeable values in configuration tables, not directly in rules. This allows for easy updates via the UI without requiring a developer.

  • Enforce logic via the data model: Build logic based on table configuration rather than hard-coding values. For example, use a boolean field on a table to control a process rather than an IIF statement with a hard-coded status.

• Use functions efficiently: Use App Builder's built-in mvSQL functions for common tasks.

Business rule naming conventions

A consistent naming convention for business rules helps maintain complex apps. Use the following general pattern: Target (Purpose or Subtype) Descriptor – Optional Filter.

Query optimization

• Select only needed columns: Include only the columns you need in your rules.

• Join on keys: Join tables using their UUID keys for the best performance.

• Smart joins: Use the appropriate join type for your needs. Prefer using a single type of outer join (such as LEFT JOIN) in a query.

• Optimize WHERE clauses: Avoid using expressions on both sides of a WHERE clause operator, as this can negatively impact performance.

• Union at the highest level: When combining data sets, use UNION at the highest possible level in your query for better performance.

Events and actions

• Register events at the table level: Whenever possible, register events (such as validations and actions) at the table level. This allows other business rules to inherit that logic, providing a single place to manage it.

• Chain actions: Use success and failure actions to link multiple rules and validations for complex "if this, then that" workflows.

• Understand triggers: Know what initiates an event (a system action or a user action).

Validations

• Enforce data quality: Use validations to ensure data is correct before it is saved.

• Layered enforcement: Apply validations at the business logic or table level, not just in the UI, to ensure data integrity.

UI/UX

Good UI/UX design is critical for an application's success. A well-designed interface should be intuitive, efficient, and comfortable for the app user.

High-level principles

• Functionality first: Focus on creating a functional application before refining the visual design. Business logic and data structures may change during development, which could require redoing any premature UI work.

• Consistency is key: All elements, from buttons and fonts to colors and layout, should be consistent throughout the application. This creates a comfortable and predictable experience for users.

• Keep it clean:

  • Be generous with space: Don't squeeze elements into the UI. Proper spacing reduces clutter and cognitive load, making information easier to digest.

  • Use subtle styling: Use clean, modern styling. For example, shadows should be light and subtle, not dark and overwhelming (unless that's your corporate styling choice).

  • Delete unused objects: Remove unused pages and other objects to reduce app overhead and ease maintenance.

Layout and navigation

• Choose the right navigation:

  • Side navigation is generally the best choice, as it is responsive, scalable, and can clearly show a folder/tree structure. It is best suited for apps with many navigation items.

  • Top navigation works well for apps with very few top-level items, where screen space is a priority. It is not well-suited for responsive design or deep sub-menus.

• Establish a visual hierarchy: Use size, weight, and color to guide the app user's eye to the most important information on the page. Panel headings, sub-headings, and content should be distinct.

• Simplify actions: Give your app users a single, clear place to perform a specific action. Avoid providing multiple ways to do the same thing.

• Organize content:

  • Group content: Organize complex screens with logical groups or tabs.

  • Link panels: Connect UI panels so that selecting an item in one automatically updates related information in another.

  • Use pop-ups correctly: Use pop-up windows for details or data entry. Never show multiple pop-ups stacked on top of each other.

User input and interaction

• Design clear buttons:

  • Action-oriented text: Use action verbs on buttons (for example, "Create Report," "Save for Later") instead of generic text such as "Yes" or "No."

  • Button hierarchy: Create a clear visual distinction between primary actions (solid, bold colors) and secondary actions (outlined or less prominent).

• Provide helpful error messages: Error messages should use plain language, clearly identify the problem, and constructively suggest a solution. Don't rely solely on color to indicate an error.

• Use icons effectively:

  • Use labels with recognizable icons: Use well-known icons (such as a magnifying glass for search) in combination with meaningful text labels. Many icons are not universally understood by app users on their own.

  • Maintain consistent style: Use icons that share the same visual style (for example, fill, stroke, and size).

• Enhance data entry:

  • Mark required fields: Clearly indicate which fields are mandatory.

  • Use list controls: Offer predefined options for data entry to ensure consistency.

• Use the live designer: Make real-time UI adjustments directly in the application to quickly refine the user experience.

Typography and color

• Use legible, consistent fonts:

  • Limit font families: Use no more than two font families. One is often sufficient.

  • Consider font pairings: If using two fonts, use one for headings and another for body text.

  • Avoid all caps: Do not use all caps for body text, as it is slower to read. It should only be used for short alerts or large headings.

• Use a clear color palette:

  • Limit colors: Aim for 3 to 4 colors: one dominant, one secondary, and one or two accent colors.

  • Use semantic colors: Use commonly associated colors to provide information about state (for example, red for a warning, green for success, gray for a disabled button).

Designing for accessibility

• Ensure high color contrast: Text should have a high contrast ratio against its background (at least 4.5:1 for normal text).

• Design for keyboard navigation: Ensure that all forms and interactive elements work for app users who can only navigate by keyboard.

• Ensure clickable elements are big enough: On mobile and touch screens, make sure buttons, links, and other clickable elements are large enough to be easily used. A minimum size of 32x32 pixels is a good starting point.

• Test on real mobile devices: The best way to confirm that your application is truly responsive and usable is to test it on actual mobile devices, not just in browser emulators.

Environments and deployments

The 3-tiered approach

Develop your apps in App Builder instances on at least these three environments:

• DEV (Development): This environment lets developers work on new features without impacting users. All modifications and development efforts should take place here.

• QA (Quality Assurance): Gives app users an environment to test in without affecting developers or production data.

• PROD (Production): The live environment for app users.

Release and change management

• Never modify QA or PROD directly: Always build in DEV, promote to QA for testing, and then promote to PROD after QA sign-off. Making changes directly in higher environments can bring your systems out of sync and jeopardize future deployments.

• Use App Builder's release management: This ensures that any changes you made in DEV are replicated to QA and PROD in the same order, preventing human error.

• Backup databases: Always take a database backup of your environments before an app deployment or an App Builder version upgrade.

• Descriptive change logs: Close change management logs often and be descriptive about what changed. This makes it easier for you to review historical changes if you need to troubleshoot an issue.

• Plan deployments: Be methodical when moving apps to production, and set expectations ahead of time. Plan deployments for after business hours to minimize impact.

Application security

• Use security providers: Whenever possible, use a security provider for authentication. Do not manually assign security.

• Role-based access (RBAC): Assign roles to app users to control page access and actions. UI elements can be set to adapt according to an app user's role.

• Efficient group management: Organize app users into groups to simplify permission management.

• Row-level security: Use reach rules to show different subsets of data to different app users on the same screen.

• Integrate SSO: Use Single Sign-On (SSO) for streamlined and secure user authentication.

Notification systems

• Bidirectional notifications: Design notifications so that app users can respond with options that update application data.

• Personalized content: Use dynamic data in messages for personalized notifications.

• Link to public pages: Ensure that any application pages linked from a notification are publicly accessible.

• Consistent triggers: Register notifications at the table level for reliable triggering.

• User-configurable messages: Allow app users to modify notification text through the UI. This reduces the need for developer involvement for simple text changes.