{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":42029,"path":"platform-user-interface/adoption-services/onboarding-modals-reference.md","title":"Reference","bundle":null,"doc_type":null,"release":"australia","body":"\n# Reference\n\nReference information for user roles and best practices when implementing onboarding modals.\n\n## User Roles\n\nOnboarding modals require specific role assignments for configuration and usage:\n\n|Role|Capabilities|\n|----|------------|\n|admin|Full access to create, edit, and delete guidance records, guidance steps, and help content. Can configure client scripts and launch mechanisms. Access to all Adoption Services modules.|\n|help\\_content\\_admin|Edit existing guidance content without full administrative privileges. Useful for content management teams maintaining onboarding materials.|\n|User \\(any role\\)|View and interact with onboarding modals assigned to their role. Navigate through steps, answer questions, and dismiss or complete modals.|\n\n## Best Practices\n\nFollow these guidelines to create effective onboarding experiences:\n\n**Content Design**\n\n-   **Keep steps focused:** Each step should cover one concept. Limit modals to 5-7 steps maximum to avoid overwhelming users.\n-   **Use clear language:** Avoid jargon and technical terms without explanation. Write for your least experienced user persona.\n-   **Provide visual context:** Include screenshots or annotated images showing exactly where to find features. Users learn better with visual references.\n-   **Make exit clear:** Always provide a **Later** or **Skip** option. Never trap users in mandatory onboarding that blocks critical work.\n\n**Technical Implementation**\n\n-   **Test across themes:** Verify modal appearance in dark, light, and coral themes. Images and text should remain readable in all contexts.\n-   **Validate sys\\_id references:** When using programmatic triggers, ensure guidance sys\\_id is correct. Invalid references fail silently without user-facing errors.\n-   **Set appropriate roles:** Match modal role requirements to actual user populations. Over-restrictive roles mean users never see guidance; over-permissive roles show irrelevant content.\n-   **Use descriptive names:** Name guidance records and steps clearly for maintainability. Future administrators should understand purpose without reading all content.\n\n**Maintenance and Updates**\n\n-   **Review quarterly:** Product updates and UI changes can make onboarding content outdated. Schedule regular reviews to maintain accuracy.\n-   **Gather user feedback:** Add feedback mechanisms or monitor help desk tickets mentioning onboarding. Users will tell you what's confusing.\n-   **Version content:** Use the **Order** field and **Status** field to manage content versions. Keep draft versions for testing before publishing changes.\n-   **Document customizations:** Maintain external documentation of custom client scripts and launch mechanisms. Update sets may not capture all dependencies.\n\n**Parent Topic:**[Onboarding modals](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-user-interface/adoption-services/next-experience-onboarding.md)\n\n"}}