diff --git a/Catalog Items - Flow.md b/Catalog Items - Flow.md index 5bfe54b..f500e12 100644 --- a/Catalog Items - Flow.md +++ b/Catalog Items - Flow.md @@ -1,19 +1,19 @@ # Creating a complete catalog item Objective: learn about catalog items, the request catalog, request items, business rules, variables, variable sets, UI policies, client scripts, and workflows. -Login to the sandbox +Login to your personal developer instance. ### Create the catalog item 1. Go to the Catalog Items table (Look for Request Catalog Configuration > Catalog Defnitions > Maintain Items) 2. Create new 3. Fill out these values: 1. Name: [your name]'s Test Catalog Item - 2. Catalogs: IT Services Request Catalog - 3. Category: Student Practice + 2. Catalogs: Pick an existing catalog in the picker + 3. Category: Student Practice (you might have to make this if someone hasn't already made it for you) 4. Short Description: A catalog item designed for practicing servicenow admin fundamental skills 5. Portal Settings, Request method: Submit 4. Right click the header and select save -5. See if your catalog item shows up here +5. See if your catalog item shows up in your service portal (go to `your_instance_name`.service-now.com/sp) ### Add variables/variable sets 1. Scroll down to the related lists section (the tabs at the bottom not to be confused with Related Links) @@ -137,7 +137,7 @@ Note: Flows are powerful, and with great power comes great responsibility. It is 14. In the flow field, add your flow and save/update your item Your catalog item now has this functionality: -* Upon submission, the user is emailed letting them know that we received their request (this happens automatically without your configuration). (note that emails are disabled in sandbox so you won't actually see the email) +* Upon submission, the user is emailed letting them know that we received their request (this happens automatically without your configuration). * If the user did not mark the checkbox question as true, then it will create a task for you to complete and the task will remain open until that task is completed before the flow continues. * If the user marked the checkbox question as true/checked, then it will send an approval request to you first, and upon approval the flow will continues * If the task is completed, then a "completed" email is sent to the user @@ -145,7 +145,7 @@ Your catalog item now has this functionality: A lot more functionality just from a simple flow! Go and actually test these scenarios by submitting your form several times. You can see "approvals" and "tasks" show up on the request item record after you submit the form. -* To approve or reject an approval you can either go here: +* To approve or reject an approval you can either impersonate the approver and check the service portal, or type Approvals in the app nav. * To complete a Catalog Task, go to the newly created request item and scroll down to the "Catalog Tasks" related list Did everything happen that you expected? **If this is not working for you, double check your Catalog Item to see if your Process Engine > Flow has your Flow there.** diff --git a/Catalog Items - Workflow.md b/Catalog Items - Workflow.md index dae6d3b..6beecfd 100644 --- a/Catalog Items - Workflow.md +++ b/Catalog Items - Workflow.md @@ -1,7 +1,7 @@ # Creating a complete catalog item Objective: learn about catalog items, the request catalog, request items, business rules, variables, variable sets, UI policies, client scripts, and workflows. -Login to the sandbox with your admin credentials via the side door https://ucdavisietsand.service-now.com/side_door.do +Login to your personal developer instance. #### Create the catalog item 1. Go to the Catalog Items table (Look for Service Catalog > Open Records > Maintain Items) @@ -13,7 +13,7 @@ c. Catalogs: IT Campus Services d. Category: Student Practice e. Short Description: A catalog item designed for practicing servicenow admin fundamental skills 4. Right click the header and select save -5. See if your catalog item shows up here https://ucdavisietsand.service-now.com/servicehub/?id=ucd_view_service2&sys_id=47fe399513e1df00d26f5e7f3244b028&ucd_catalog=5ec4eed5134143003527bd122244b0af&parent=93056219134143003527bd122244b024 +5. See if your catalog item shows up in your service portal (go to `your_instance_name`.service-now.com/sp) #### Add variables/variable sets 1. Scroll down to the related lists section (the tabs at the bottom not to be confused with Related Links) @@ -164,7 +164,7 @@ Your catalog item now has this functionality: A lot more functionality just from a simple workflow! Go and actually test these scenarios by submitting your form several times. You can see "approvals" and "tasks" show up on the request item recordafter you submit the form. -* To approve or reject an approval you can either go here: https://ucdavisietsand.service-now.com/servicehub/?id=ucd_my_stuffand click on "My approvals" or go to the newly created request item and scroll down to the "Approvers" related list +* To approve or reject an approval you can either impersonate the approver and check the service portal, or type Approvals in the app nav. * To complete a Catalog Task, go to the newly created request item and scroll down to the "Catalog Tasks" related list Did everything happen that you expected? diff --git a/Record Producers.md b/Record Producers.md index bdf3cd8..2ee97bd 100644 --- a/Record Producers.md +++ b/Record Producers.md @@ -1,9 +1,7 @@ # Creating a Complete Record Producer Objective: learn about record producers, and server-side scripts. -Login to the [sandbox]() - -
+Login to your Personal Developer Instance ### Create the Record Producer 1. Go to the Catalog Items table (Look for Request Catalog Configuration > Catalog Defnitions > Maintain Items) @@ -15,8 +13,6 @@ Login to the [sandbox]() 4. Click Submit at the bottom left 5. You've now created a record producer. Find your record producer on the Record Producers table, and select it. -
- ### Editing the Server-Side Script 1. In your record producer, find the "What it will contain" tab (should be just below the Record Producer's fields) and make sure it's selected 2. In that tab, scroll down to the "Script" section. This is where the server-side script is (i.e. run by the backend, not the frontend)1 @@ -41,8 +37,6 @@ current.u_variables.display = true; Server-side scripts can get much more in-depth. You can use [ServiceNow's Glide class](https://docs.servicenow.com/bundle/paris-application-development/page/script/general-scripting/reference/r_GlideClassOverview.html) to edit databases at scale, execute server-side code directly from the client, create custom forms, etc. It is very powerful! But with great power comes with great responsibility! **Even so much as one messed up capitalization in a server-side script could ruin the whole UCSD database! Be careful, and always contact your supervisor if you're not sure a script will run as intended!** -
- ### Mapping Variables to Case Fields This section will introduce the creation of variables, using the GlideSystem (or ```gs```) to get logged-in user information, and mapping a variable to a field in a generated case. 1. Go to your record producer and create a new Variable @@ -61,8 +55,6 @@ Now what have you done so far? You've created a variable that will map to a fiel In the future, you'll be messing with even cooler scripts that will be able to automate many more things (you can even make a form that will send text messages to people, or make a robot send messages to your slack channel)! -
- ### Server-Side Print-Debugging 1. For server-side print-debugging, you will have to use ```gs.info()``` and then look in System Logs > Application Logs for the information that is logged 2. A rule of thumb for ```gs.info()``` calls is to format it as ```gs.info([your name] - , ...)```. This is because, in the SNOW-Development environment, there are tons of forms printing info at the same time, so it will be impossible to find your own if you do not prepend your name to your console output. Example: @@ -70,8 +62,6 @@ In the future, you'll be messing with even cooler scripts that will be able to a gs.info('rickesh - ' + gs.getUser()); ``` -
- ### Record Producer Accessibility This section is mainly meant as a heads-up (you are not changing values on your record producer). Right now, your record producer is considered 'Unlisted'. That means that no one can access your form unless you give them the direct link to access it. Well that's kind of annoying, so let's change that: 1. Go to your Record Producer and find the "Accessibility" tab. @@ -80,8 +70,6 @@ This section is mainly meant as a heads-up (you are not changing values on your * Category is a sub-category that belongs to the department. 3. Although, we won't be changing these, keep in mind that this is how forms are listed and unlisted for UCSD. -
- ### Footnotes 1. This is different from client-side scripts. Client-side scripts run in the frontend and any ```alert()``` calls for client-side print-debugging will actually be visible on the form itself. Client-side scripts will run _as an action is performed or when the form loads_. This is not true for server-side scripting. For record producers, scripts will run _after_ you submit the form. For debugging details, see Server-Side Print-Debugging 2. Variable Explanations diff --git a/Standards/API Usage.md b/Standards/API Usage.md index 3735396..06c18b2 100644 --- a/Standards/API Usage.md +++ b/Standards/API Usage.md @@ -3,7 +3,7 @@ ## Outbound - Outbound calls to external APIs via REST, SOAP, or other methods are allowed. -- Do not store API keys in plain-text on scriptstable records, instead put them in system properties. +- Do not store API keys in plain-text on scriptable records, instead put them in system properties. - Intentionally rate limit outbound calls that occur rapidly (several per second). Make sure these calls are condition-based for when they occur instead of timer based. - Do not use ServiceNow to call an external API to check for updates rapidly. If you need live updates, attempt to create an inbound integration that is triggered by the external system, instead of polling for updates. - Prefer creating outbound service records that are called in script rather than creating an entire outbound call in individual scripts. diff --git a/Standards/Catalog Items.md b/Standards/Catalog Items.md index d39231f..b2f6691 100644 --- a/Standards/Catalog Items.md +++ b/Standards/Catalog Items.md @@ -3,31 +3,30 @@ Request catalogs and their catalog items (forms) are used to describe, support, and request services from service providers. ### Catalog Item Style Guide -- Use the standard style guide to design catalog items. -- The catalog request item style guide is maintained on the ServiceNow in knowledge article KB0000991. Printed copies are considered drafts. + +- Use your company provided style guide to design catalog items. ### Request Catalog Style Guide This style guide is a set of standards to help the information technology community develop ServiceNow Request Catalog items. This style guide follows: -- Guidelines provided by Strategic Communication which can be found at http://marketingtoolbox.ucdavis.edu - The Associated Press (AP) style guide and The Chicago Manual of Style, which UC Davis Strategic Communication follows - ServiceNow product documentation - -In addition to the standards listed above, the Information Educational Technology web development team has guidelines that can be referenced on their service page at http://itcatalog.ucdavis.edu/service/web-development. #### Audience + - Staff who have oversight and content management responsibilities for ServiceNow - IT community developers who work on ServiceNow modules, applications, and system components utilizing the Item Designer #### Purpose + The Request Catalog is for service offerings. Services offerings may include both products and services. #### Request Item Writing Tips - **Avoid capitalizing every word in a header, question or phrase**. The first letter of the first word of variables in a catalog item should be capitalized (i.e. Phone number). Capitalize professional titles, organizations, and other proper nouns, but in general, avoid the use of caps. -- **Avoid the use of acronyms**. If an acronym is required, the full name should be written out the first time it is used with its corresponding acronym in parenthesis (i.e. Information and Educational Technology (IET)). +- **Avoid the use of acronyms**. If an acronym is required, the full name should be written out the first time it is used with its corresponding acronym in parenthesis (i.e. Associated Press (AP)). - **Use clear and concise language**. For variable questions, typically verbs are not necessary. (i.e. “Requestor’s job title” rather than “Enter the requestor’s job title.”) #### General Formatting @@ -64,6 +63,7 @@ A cascading style sheet (CSS) has been created that adheres to University guidel 6. **Multi line vs Single line** Question dependent, but multi lines should only be used for lengthy questions such as asking for additional detail. #### Guide to Usability + - **Tooltips** (rollover or hover functionality) are the primary method used for "help text." The majority of variables in a form will require a tooltip; the exception to this standard is when the variable name is its definition. - **More information** should be used sparingly in support of more complicated content within the variable. This is a secondary solution to the tooltip. More information appears in grey under the input field. Do not include information directed to an individual or group, requirements, or terms and conditions. - **Common variables** used in form design: diff --git a/Standards/Complete 20200122.md b/Standards/Complete 20200122.md deleted file mode 100644 index cb42652..0000000 --- a/Standards/Complete 20200122.md +++ /dev/null @@ -1,382 +0,0 @@ -# Developer Mindset Standards - -+ Do debugging and research when something in your application or program is not working, and if debugging assistance is still needed, contact IET SM for help - + Take advantage of ServiceNow's debugging tools such as User Criteria Diagnostics, Debug Security Rules, JavaScript debugger - + Research your issue using sites like ServiceNow community forms or ServicePortal.io -+ Be wary of directly copy-pasting code found online into your programs. Read through it first and understand what you are copying -+ Try new coding ideas or concepts in Sand first, before implementing it in Dev -+ Reference good documentation -+ Do not write hundreds of lines of code in one sitting. Instead, write a few lines of code at at time, and test as you go to ensure it works as expected -+ Reference https://stackoverflow.com/help/how-to-ask when asking other development teams for assistance, rather than asking "this doesn't work, why?" -+ Write/provide good documentation for the things you make - -# Script Include Standards - -- Generally speaking, create new script includes for individual applications, catalogs items, or functions. - - As opposed to one script include for several catalog items, which may cause problems with delegated develpment. -- Only return information that the calling script will need -- Use JSON.stringify and JSON.parse instead of JSON.encode and JSON.decode -- Use Script Includes instead of Global Business Rules -- Use existing script includes when possible -- Avoid hardcoding values by using System Properties and Messages -- Remove logging and temporary comments before moving to production. -- Copy out-of-box script includes and edit the copy instead of editing the original. -# Workflow Standards - -A ServiceNow workflow is used to automate processes. A workflow is a sequence of activities, such as generating records, notifying users of pending approvals, or running scripts. Workflows contain activities that are a set of instructions, including but not limited to approvals, scripting, timers, and email notifications. - -### General -- Include the Workflow: Standard Open Message at the beginning of the item workflow. -- Include the Workflow: Standard Close Message at the end of the item workflow. -- When possible, notifications should be created via the Create Event activity which then triggers a notification. Notification activities are also acceptable but Create Event is preferred. Do not send notifications via a Run Script activity. -- All activities should lead to the End activity. -- Any workflow section that is repeatable should be made into its own workflow so that it can be used as a sub-workflow in other workflows. - -### Good Practices for Workflow Design -- Use the workflow validation tool provided by ServiceNow. -- Use the workflow scratchpad. Pass data between workflow activities. -- Use else/catch-all logic to handle exceptions -- It is preferred that approval requirements are handled at the start of a workflow. -- Tasks that the user cancels or skips should avoid canceling the entire Request or downstream tasks in separate and independent request items. -- Split large or complex workflows into smaller sub-flows. -- Using sub-flows enables unit testing and reuse. -- Data can be passed between sub-flows using workflow inputs and return values - -### Workflow States -- All RITM (Request Item) workflows should have a beginning state and an end state even if completely automated. -- Set the RITM state to “Work in Progress” at the beginning of the workflow. -- Set the RITM assignment group to the relevant group at the beginning of the workflow. -- At the end of a workflow, set the RITM state to “Closed Complete.” -- At the end of the workflow's failure path (if there is one), set the RITM state to “Closed Incomplete.” -- “Closed Skipped” is rarely used in RITM workflows, as it means there is no work to be done. The standard is to set the RITM state to “Closed Incomplete” instead. -- Failure paths should never cause a RITM state of “Closed Complete.” - -### Workflow Stages -- If there is an Approval request, set the stage title to “Waiting for Approval.” at a minimum, it is preferred that you customize this stage to say “Waiting for approval from [group]” -- If there is a Catalog Task, set stage names to “Fulfillment.” Use “Fulfillment” instead of “Delivery” unless both are being used. As with Approval, it is preferred that you make the stage name more descriptive. -- Do not use the "Request Approved" stage (this pertains to the Request Item (RITM), not the approval request. -- Completion Paths -- Set the last activity before End activity to “Completed” stage - -### Failure Paths -- When a Catalog Task completion path exists, set the failure path to the “Request Cancelled” stage. -- Only use the “Request Cancelled” stage for a path with no Catalog Tasks or Approvals (e.g., checking to see if the submitter of the item is authorized to submit the item). -- Do not set additional stages for more than one failure path. - -### Render stages from a workflow-driven method. -- The Stage order should be Computed. -- Stage values and their corresponding display values must be the same. -- Ensure that the “End” activity can never be reached earlier than any other intended activity on the workflow, as this will cause the workflow to end regardless of anything else still in progress on the workflow. -- Ensure workflows that are completed have been published -- In approval activities that have group approvals, utilize the “Approval - User” activity instead of the “Approval - Group” activity unless you understand the differences and need the exact functionality of the latter. -- Wait for condition activities should wait for changes to the exact record being watched -- It is preferred that workflows eventually reach the end activity. - -### Workflow Notifications -- Minimize the number of notifications sent to users. -- Do not send redundant or duplicate notifications. - - Example: Approvals generate notifications automatically from notifications configured on the approval table. Your workflow does not need to send a notification letting a user know if it has been approved or rejected. -- Avoid hardcoding notifications. Use independent notifications. -# Update Sets - -### Update Set Naming Conventions - -Use a consistent naming convention for update sets. - -- **NEVER COMPLETE THE DEFAULT UPDATE SET FOR GLOBAL** -- Create at least one local update set and switch from the Global update set to the local one before beginning work. -- At a minimum, update sets must have a unique name that identifies the originating campus organization, concise description, and implementation sequence. A reference to the project requirement is also recommended to ensure traceability to customer requirements such as: -org_reference_desc_seq/date - - org: Primary developer organizational acronym - - reference: External reference number - - desc: Short description - - seq/date: (optional) Sequence number or version or date - - Example: IET STRY0001234 Incident Hotfix 3 2020.01.12 -- The standard date format is YYYY.MM.DD. -- Do not use the word “default” anywhere in your update set name - -### Good Practices for Update Sets - -- Never delete an Update Set. -- Never re-open previously completed update sets. Create new ones instead. -- Never manually merge update sets. Utilize batch functionality instead. -- Before completing an update set, review the update set to ensure that the only updates included pertain to the desired work. -- Preview update sets before committing them. -- Identify dependencies between update sets. Follow naming conventions standards to specify the correct order for migrating them to the next instance. -- Remove all debugging scripts and system properties before marking an update set as Complete. -- In the dev instance, completed update sets should never be placed into a batch after it has been completed -- Do not transfer updates between update sets manually. Seek administrative assistance when update sets contain incorrect updates. -- Test your work before you complete your update set. - -### Instance Administrators - -- When preparing for production release, batch all updates for that release together -- When pulling to production, delete all irrelevant update sets from the loaded table -# UI Policies Standards - -+ When possible, use a UI Policy to set field attributes to mandatory, read-only, or visible rather than a Client Script -+ Avoid adding the same variable to multiple UI Policies -+ Do not make a hidden variable mandatory - -# UI Actions Standards - -+ Use a distinctive name to distinguish from other UI Actions -+ Use buttons, menus, and links appropriately in forms and lists. For example, do not clutter a form with too many buttons. -+ Avoid putting all necessary logic in the UI Action, it is preferred to leverage Business Rules or Script Includes instead -+ Do not modify commonly used UI Actions such as Save or Delete -+ Add role restrictions to buttons you do not want accidentally pressed -# Scripting Standards - -### GlideRecords - -- Do not name your GlideRecord instantiations as simply `gr` as this may conflict with other running GlideRecords. -- Instead, name them something like `table_gr` or `function_gr` -- Remove logging and unnecessary comments prior to promoting toward production -- Do not use client-side GlideRecords, instead use GlideAjax -- For complex GlideRecord queries, it is preferred to generate encoded query strings through the list filter and using that with `addEncodedQuery`, rather than using a series of `addQuery` and `addOrCondition`. - -### GlideAjax - -- Only return information that is going to be used by the client. - -### General - -- Avoid naming globally used variables as `i` as that may conflict with other scripts running. -- Make code easy to read with appropriate white-space, indentation, and comments -- When appropriate, verify that variables and fields have a value before using them -- Avoid using hard-coded values - -# Roles Standards - -- Roles should never be assigned directly to users - - Assign roles to groups then assign members to that group - - If needed for deployment, utilize the `Add to update set` tool installed in development to add any record relevant to group/role membership: - - sys_user_group - - sys_user_grmember - - sys_group_has_role - - sys_user_has_role - - sys_user - - sys_user_role -- Do not use application roles as a way to be able to edit configurations in production. Files typically included in update sets should follow a developement process (dev to test to production). -- Do not assign roles that would grant configuration access in the production environment unless it is agreed upon that the receiving group and users should have the access. -- Do not add new role inclusions to existing out-of-box roles if those roles are already being utilized elsewhere. -- It is preferred that new roles are created within scoped applications (not Global). -- Do not ever include the admin or security admin role in a group -- Do not grant admin access to other users. A rule is in place for IET Service Management to be notified every time this happens. -- New ROLE groups for granting access to new roles should be requested from IET Service Management. -# Service Portal Standards - -Aka Widgets, Pages, and the front-end. - -### Portals -- New portals should be vetted by the TAG or IET Service Management as they may be granting access or read access to items/records that are not intended for the public -- Follow campus design standards (eg. common footer, color schemes, font-families, etc.) - -### Widgets - -- Do not display restricted information unless the user is logged in and is supposed to be able to see such information. -- Design widgets to be re-usable -- Do not edit other application widgets without permission -- Copy out-of-box widgets and edit the copy instead of editing the original. -- Be aware of how many libraries you import as it can impact performance. - -### Pages - -- If using role restrictions, evoke CAS for users not logged in first. -# Plugins, ServiceNow Store, and External Update Sets Standards - -### Plugins - -- Generally speaking, since some plugins affect other parts of the instance and some plugins will completely change the architecture of the instance, IET Service Management should be contacted to activate plugins in the Development, Test, and Production instances. -- Plugins are typically not reversable once installed, so use caution and review the dependencies before activating. -- Plugin activations in sub-production instances can be requested here https://ucdavisit.service-now.com/servicehub/?id=ucd_cat_item&sys_id=296c901d134b6b003527bd122244b087 - -### ServiceNow Store - -- Only users with ServiceNow HI accounts are able to request entitlements from the ServiceNow Store. -- If your department does not have a HI representive, contact IET Service Management for assistance. - -### External Update Sets - -- The UC Davis ServiceNow instances contain sensitive information and therefore external update sets should be implemented with caution. -- Fully review every update within the update set to ensure that the intended functionality and only the intended functionality is part of the update. -- Do not implement external update sets if they look like they may affect other developers work negatively or if they would turn off functionality that is currently in-use in some way by another area in the instance. -- Do not implement update sets that requires outside connections to unknown sources. -# Glide Method usages - -### GlideRecord -- Use when attempting to get information from specific records -- Don't use for attempting to do calculations on groups of records, use GlideAggregate instead -- Only use on server scripts (usable in client scripts but do not do this, opt for GlideAjax instead) - -### GlideAggregate -- Use when doing calculations on groups of records -- Only use on server scripts - -### GlideAjax -- Use when you need information from the server after the client has finished loading the page -- Only use on client scripts - -### GlideElement -- Used to operate on fields of the currently selected GlideRecord -- Only use on server scripts - -### GlideSystem -- Use to get information from the system -- Only use on server scripts - -### GlideDateTime -- Use to perform date-time operations -- Only use on server scripts - -### GlideUser -- Use when getting session infromation about the current logged-in user -- Only use on client scripts -# General instance restrictions - -- Do not promote update sets, install plugins, install applications, update applications, or change system properties during business hours as it automatically evokes a cache flush. -- Do not edit functionality for an application owned by another group without express permission from the TAG or IET Service Management. -- Do not export restricted information to external systems or instances. -- Do not impersonate other admin accounts to create updates. -- ***Do not grant admin access to other users***. A rule is in place for IET Service Management to be notified every time this happens. -- Do not share admin credentials -- Do not use admin accounts to look at restricted records. All record views are recorded in the database. -- Report vulnerabilities found to IET Service Management. -# Flow Designer Standards - -- Since flows are not tied to tables/records like workflows are, they can be easily configured to run in any situation. That being said, always approach flow triggers with the perspective of "do not allow this to run unless absolutely needed" or else many flow contexts will accidentally be created. -- Do not edit base system actions and flows. Editing these will cause them to not immediately receive future updates from ServiceNow. -- Flows should be within scoped applications whenever possible (not Global). -- When possible use IntegrationHub to handle authentications instead of recreating your own -- Never test flows in a production environment -- Never develop flows in a production environment -- Do not create conflicting logic with already active business rules and workflows -# Documentation Standards - -+ For scripts - + Comment code as if the original author will not be around anymore - + Comment on functions with full parameter and return descriptions -+ For others - + Determine if a KB article is necessary - + Otherwise provide a good description in the description field -+ Keep comments/documentation as accurate and updated as possible -+ Ensure documentation is well-written, clear, and meaningful -+ Do not be verbose and unnecessary with your comments. For example, commenting about initializing a `GlideRecord` or variable. - -# Client Script Standards - -+ Use Client Scripts to validate user input -+ When possible, use a UI Policy to set field attributes to mandatory, read-only, or visible rather than a Client Script -+ Do not create Global Client Scripts, instead create them on Base Tables that can be inherited for all child/extending tables -+ If possible, avoid DOM Manipulation -+ Do not use `GlideRecord` in Client Scripts, use `GlideAjax` instead -+ Always remove console logging and alerts prior to completion -+ If creating Client Scripts for Catalog Items, ensure that it works in the Service Portal - -# Catalog Item Standards - -Request catalogs and their catalog items (forms) are used to describe, support, and request services from service providers. - -### Catalog Item Style Guide -- Use the standard style guide to design catalog items. -- The catalog request item style guide is maintained on the ServiceNow in knowledge article KB0000991. Printed copies are considered drafts. - -### Request Catalog Style Guide - -This style guide is a set of standards to help the information technology community develop ServiceNow Request Catalog items. - -This style guide follows: -- Guidelines provided by Strategic Communication which can be found at http://marketingtoolbox.ucdavis.edu -- The Associated Press (AP) style guide and The Chicago Manual of Style, which UC Davis Strategic Communication follows -- ServiceNow product documentation - -In addition to the standards listed above, the Information Educational Technology web development team has guidelines that can be referenced on their service page at http://itcatalog.ucdavis.edu/service/web-development. - -#### Audience -- Staff who have oversight and content management responsibilities for ServiceNow -- IT community developers who work on ServiceNow modules, applications, and system components utilizing the Item Designer - -#### Purpose -The Request Catalog is for service offerings. Services offerings may include both products and services. - -#### Request Item Writing Tips - -- **Avoid capitalizing every word in a header, question or phrase**. The first letter of the first word of variables in a catalog item should be capitalized (i.e. Phone number). Capitalize professional titles, organizations, and other proper nouns, but in general, avoid the use of caps. -- **Avoid the use of acronyms**. If an acronym is required, the full name should be written out the first time it is used with its corresponding acronym in parenthesis (i.e. Information and Educational Technology (IET)). -- **Use clear and concise language**. For variable questions, typically verbs are not necessary. (i.e. “Requestor’s job title” rather than “Enter the requestor’s job title.”) - -#### General Formatting - -A cascading style sheet (CSS) has been created that adheres to University guidelines. This style sheet applies standard formatting to all aspects of the Service Hub, including the public-facing Knowledge Base. -- Font Tags - Do not change or insert Font Tags into any allowable HTML field. This erroneous code diminishes the set standards. Bold or italic may be used for impact on the content it references. -- Phone numbers - Use the traditional formatting convention for phone numbers: - - Area code followed by 7 digits; (NPA) NXX-XXXX where NPA is the area code and NXX-XXXX is the subscriber number - - Area code wrapped in parentheses "( )" - - The subscriber number is separated by a hyphen ("-") -- Dates - Use International Organization for Standardization (ISO) format: - - Four-digit year first, followed by month, then day: YYYY-MM-DD - - With each separated by a hyphen ("-") - - Numbers less than 10 preceded by a leading zero - - Years expressed as "0" prior to year 1 and as "-1" for the year prior to year 0 (and so forth) - - #### Form Design Guidelines - -1. **Standard content blocks**. All request forms should maintain the three content block standard. - 1. Customer Information – This section captures the customer's details including contact method, department, and any relevant authorization information. This serves as validation of who is entering information into the form. There are two variable sets available for this block, one with Request on behalf of, and one without. This section includes the following standard fields. - 1. Primary Contact - UI policy to auto-populate with CAS authentication - 2. Email – auto-populates - 3. Telephone – auto-populates - 4. Request on behalf of – optional field - 2. Request Information – This is the body of the form. The variables in this block must be held in containers. The number of questions in this block is determined by the requirements of the request. - 3. Additional Information – This content block is for supplemental information such as attachments or additional information that are not captured in the body of the form. There are two variable sets available, Include Billing and Exclude Billing. Do not use the Additional Information variable set if the RITM workflow is completely automated. The customer may assume that information entered will be reviewed. -2. **Variable sets**. Variable sets are standard sets of fields that can be used across multiple forms. Using variable sets keep forms standardized and make for a consistent user experience. They should be used whenever possible. -3. **Agreement checkbox**. Include this checkbox on impactful items that deal with matters such as account cancellation or finances. A script has been developed and is available which inactivates the "Submit" button unless the agreement is checked/acknowledged. -4. **Columns**. Column usage will be up to the form designer's discretion, but here are some general guidelines: - 1. Fields that trigger/reveal other fields should generally be two columns, revealing the other field either below or to the right of the first field. - 2. Most multi line text fields should be one column spanning the width of the page. - 3. Single line text fields will generally be one column, spanning half the page. -5. **Drop downs**. If a drop down field is mandatory, it should default to "None" so the requester must choose one of the options before submission is allowed. If a drop down field is not mandatory, a "None" option is not needed. -6. **Multi line vs Single line** Question dependent, but multi lines should only be used for lengthy questions such as asking for additional detail. - -#### Guide to Usability -- **Tooltips** (rollover or hover functionality) are the primary method used for "help text." The majority of variables in a form will require a tooltip; the exception to this standard is when the variable name is its definition. -- **More information** should be used sparingly in support of more complicated content within the variable. This is a secondary solution to the tooltip. More information appears in grey under the input field. Do not include information directed to an individual or group, requirements, or terms and conditions. -- **Common variables** used in form design: - - Select Box - drop down menu item to be used in cases of a single item needing to be selected from a list of items. - - Yes / No - a select box variable type used for questions with a Yes or No answer. - - Check Boxes - individual options that are true or false. These should be used in a vertical alignment. - - Radio buttons - should be used in cases where one of four options, or less, need to be selected. Best practice is to use this when all options need to visible on the form. - - Submit button - located in the lower left corner for web submission forms. - -A complete list of variable types can found [here](https://docs.servicenow.com/bundle/jakarta-servicenow-platform/page/administer/wizards/task/t_DefineAVariable.html). -# Business Rules Standards - -+ If possible, use conditions in Business Rules -+ Do not use `current.update()` in a Business Rule script -+ Just like `current.update()`, do not script a Business Rule that may accidentally activate itself again upon running -+ Do not create Global Business Rules, it is preferred to use Script Includes instead. -+ Understand if you intend for other Business Rules to run due to the running of this Business Rule. If not, ensure that you set .setWorkflow to false -+ Use Business Rules to validate input on top of Client Scripts/UI Policies since fields can be editable outside of fields. -# API Usage Standards - -## Outbound - -- Outbound calls to external APIs via REST, SOAP, or other methods are allowed. -- Do not store API keys in plain-text on scriptstable records, instead put them in system properties. -- Intentionally rate limit outbound calls that occur rapidly (several per second). Make sure these calls are condition-based for when they occur instead of timer based. -- Do not use ServiceNow to call an external API to check for updates rapidly. If you need live updates, attempt to create an inbound integration that is triggered by the external system, instead of polling for updates. -- Prefer creating outbound service records that are called in script rather than creating an entire outbound call in individual scripts. - -## Inbound - -- Do NOT create an unauthenticated API for inbound calls -- Always prefer to use a more secure authentication method like OAuth 2.0 over a simple username/password authentication -- Do not store API keys in plain-text on scripts or table records, instead put them in system properties. -- Do not create or configure table APIs for campus-used tables unless approved by the campus TAG or IET Service Management (eg. the incident table). -- Some tables have ACLs or Business Rules that intend to restrict some information that is accessible (eg. incident, sc_req_item, sysapproval_approver, sc_task, x_uocd2_business_m_case, etc.). Always use discretion when divulging information on these tables for an API. Always program to satisfy that these ACLs and rules are not broken. -# ACL standards - -- __Understand how ACLs are evaluated and in what order they are run before attempting to configure ACLs__ -- Never leave anything in the script field if the ACL's advanced field is false. -- Understand that ACLs impact instance performance, the more complex the query and the more that are running, the slower the interaction will be. -- **Whenever possible**, a matching Before Business Rule Query should be created for every ACL that is designed to remove records from a person's view. \ No newline at end of file diff --git a/Standards/Developer Mindset.md b/Standards/Developer Mindset.md index b38ebab..f6b7e8d 100644 --- a/Standards/Developer Mindset.md +++ b/Standards/Developer Mindset.md @@ -1,6 +1,6 @@ # Developer Mindset Standards -+ Do debugging and research when something in your application or program is not working, and if debugging assistance is still needed, contact IET SM for help ++ Do debugging and research when something in your application or program is not working, and if debugging assistance is still needed, contact another developer for help + Take advantage of ServiceNow's debugging tools such as User Criteria Diagnostics, Debug Security Rules, JavaScript debugger + Research your issue using sites like ServiceNow community forms or ServicePortal.io + Be wary of directly copy-pasting code found online into your programs. Read through it first and understand what you are copying diff --git a/Standards/General instance restrictions.md b/Standards/General instance restrictions.md index 12f67d8..e5adb4a 100644 --- a/Standards/General instance restrictions.md +++ b/Standards/General instance restrictions.md @@ -1,10 +1,10 @@ # General instance restrictions - Do not promote update sets, install plugins, install applications, update applications, or change system properties during business hours as it automatically evokes a cache flush. -- Do not edit functionality for an application owned by another group without express permission from the TAG or IET Service Management. +- Do not edit functionality for an application owned by another group without express permission from them. - Do not export restricted information to external systems or instances. - Do not impersonate other admin accounts to create updates. -- ***Do not grant admin access to other users***. A rule is in place for IET Service Management to be notified every time this happens. +- ***Do not grant admin access to other users*** - Do not share admin credentials - Do not use admin accounts to look at restricted records. All record views are recorded in the database. -- Report vulnerabilities found to IET Service Management. \ No newline at end of file +- Report vulnerabilities found \ No newline at end of file diff --git a/Standards/Plugins, Store, External Update Sets.md b/Standards/Plugins, Store, External Update Sets.md index 6a42751..2c136c3 100644 --- a/Standards/Plugins, Store, External Update Sets.md +++ b/Standards/Plugins, Store, External Update Sets.md @@ -2,18 +2,16 @@ ### Plugins -- Generally speaking, since some plugins affect other parts of the instance and some plugins will completely change the architecture of the instance, IET Service Management should be contacted to activate plugins in the Development, Test, and Production instances. - Plugins are typically not reversable once installed, so use caution and review the dependencies before activating. -- Plugin activations in sub-production instances can be requested here https://ucdavisit.service-now.com/servicehub/?id=ucd_cat_item&sys_id=296c901d134b6b003527bd122244b087 ### ServiceNow Store - Only users with ServiceNow HI accounts are able to request entitlements from the ServiceNow Store. -- If your department does not have a HI representive, contact IET Service Management for assistance. +- If your department does not have a HI representive, contact the product owner. ### External Update Sets -- The UC Davis ServiceNow instances contain sensitive information and therefore external update sets should be implemented with caution. +- If your instance contains sensitive information, external update sets should be implemented with caution. - Fully review every update within the update set to ensure that the intended functionality and only the intended functionality is part of the update. - Do not implement external update sets if they look like they may affect other developers work negatively or if they would turn off functionality that is currently in-use in some way by another area in the instance. - Do not implement update sets that requires outside connections to unknown sources. \ No newline at end of file diff --git a/Standards/Portal.md b/Standards/Portal.md index 80dac55..ff5675b 100644 --- a/Standards/Portal.md +++ b/Standards/Portal.md @@ -3,7 +3,7 @@ Aka Widgets, Pages, and the front-end. ### Portals -- New portals should be vetted by the TAG or IET Service Management as they may be granting access or read access to items/records that are not intended for the public + - Follow campus design standards (eg. common footer, color schemes, font-families, etc.) ### Widgets @@ -12,8 +12,4 @@ Aka Widgets, Pages, and the front-end. - Design widgets to be re-usable - Do not edit other application widgets without permission - Copy out-of-box widgets and edit the copy instead of editing the original. -- Be aware of how many libraries you import as it can impact performance. - -### Pages - -- If using role restrictions, evoke CAS for users not logged in first. \ No newline at end of file +- Be aware of how many libraries you import as it can impact performance. \ No newline at end of file diff --git a/Standards/Role usage and creating new roles.md b/Standards/Role usage and creating new roles.md index 9e501f1..bf265ed 100644 --- a/Standards/Role usage and creating new roles.md +++ b/Standards/Role usage and creating new roles.md @@ -14,5 +14,4 @@ - Do not add new role inclusions to existing out-of-box roles if those roles are already being utilized elsewhere. - It is preferred that new roles are created within scoped applications (not Global). - Do not ever include the admin or security admin role in a group -- Do not grant admin access to other users. A rule is in place for IET Service Management to be notified every time this happens. -- New ROLE groups for granting access to new roles should be requested from IET Service Management. \ No newline at end of file +- Do not grant admin access to other users. \ No newline at end of file diff --git a/Standards/Script Includes.md b/Standards/Script Includes.md index 2a535d8..2b4d1f8 100644 --- a/Standards/Script Includes.md +++ b/Standards/Script Includes.md @@ -1,7 +1,7 @@ # Script Include Standards - Generally speaking, create new script includes for individual applications, catalogs items, or functions. - - As opposed to one script include for several catalog items, which may cause problems with delegated develpment. + - As opposed to one script include for several catalog items, which may cause problems with delegated development. - Only return information that the calling script will need - Use JSON.stringify and JSON.parse instead of JSON.encode and JSON.decode - Use Script Includes instead of Global Business Rules diff --git a/Standards/Update Sets.md b/Standards/Update Sets.md index feac9c3..b13d82f 100644 --- a/Standards/Update Sets.md +++ b/Standards/Update Sets.md @@ -1,10 +1,12 @@ # Update Sets +Remember: different companies do things differently! The below doesn't necessarily apply to every dev team. + ### Update Set Naming Conventions Use a consistent naming convention for update sets. -- **NEVER COMPLETE THE DEFAULT UPDATE SET FOR GLOBAL** +- Never set the update set for Global Default to complete - Create at least one local update set and switch from the Global update set to the local one before beginning work. - At a minimum, update sets must have a unique name that identifies the originating campus organization, concise description, and implementation sequence. A reference to the project requirement is also recommended to ensure traceability to customer requirements such as: org_reference_desc_seq/date @@ -12,15 +14,15 @@ org_reference_desc_seq/date - reference: External reference number - desc: Short description - seq/date: (optional) Sequence number or version or date - - Example: IET STRY0001234 Incident Hotfix 3 2020.01.12 + - Example: DA STRY0001234 Incident Hotfix 3 2020.01.12 - The standard date format is YYYY.MM.DD. - Do not use the word “default” anywhere in your update set name - ### Good Practices for Update Sets -- Never delete an Update Set. +- Never delete an Update Set. (Some companies delete them in production though, YMMV) - Never re-open previously completed update sets. Create new ones instead. + - Why? If another instance has retrieved your update set already then it will never try to retrieve your newly "updated" update set, resulting in desynced update sets. - Never manually merge update sets. Utilize batch functionality instead. - Before completing an update set, review the update set to ensure that the only updates included pertain to the desired work. - Preview update sets before committing them. @@ -33,4 +35,4 @@ org_reference_desc_seq/date ### Instance Administrators - When preparing for production release, batch all updates for that release together -- When pulling to production, delete all irrelevant update sets from the loaded table \ No newline at end of file +- When pulling to production, delete all irrelevant update sets from the loaded table diff --git a/Training Zero to One above.md b/Training Zero to One above.md new file mode 100644 index 0000000..c67580b --- /dev/null +++ b/Training Zero to One above.md @@ -0,0 +1,86 @@ +## Session topics + +* An introduction to the platform +* Introduction to DB theory and platform +* Make sure to sign up for a personal developers instance at https://developer.servicenow.com/ +* Make sure to have a github account +* Tour a PDI +* Training: ServiceNow Foundations eLearning [link](\ServiceNow Foundation Videos.md) +* Update Set Instructions +* Catalog Items +* Catalog Items - Flow Designer +* Catalog Items - Worflow +* Catalog Items - Personal Instance w/Workflow +* Record Producers +* UI Policies +* Client Scripts +* GlideRecord +* GlideAjax +* GlideAggregate +* Business Rules +* CSS +* Bootstrap +* Regular Expressions +* Aria Best Practices +* Performance Analytics +* Cheat Sheet & Quick Reference + +## ServiceNow as a platform of products +* ITSM +* ITBM +* ITOM +* HR +* CSM +* SecOps/GRC +* Creator + +## ServiceNow as a platform of tools +* Case/Incident +* Knowledge +* Service Request +* Service Portal +* Change Management +* Reporting +* Visual Task Boards +* Survey +* Integrations +* Performance Analytics +* ATF +* SLA + +## ServiceNow as a platform of industry technologies +* JavaScript (Programming Language) +* HyperText Markup Language (HTML) +* IT Service Management +* Web Components (Web Framework) +* Cascading Style Sheets (CSS) +* Web Services +* Configuration Management Databases +* Information Technology Infrastructure Library (ITIL) Processes +* Workflows and Automation +* User Interface +* Application Programming Interface (API) +* Agile Methodology +* Application Development +* Business Process +* Business Requirements +* Change Management +* Debugging +* System Administration +* Governance Risk Management And Compliance +* Single Sign-On (SSO) +* Test Automation +* CI (Continuous Integration) Practices and Tools - Conceptual +* Github, Jira, code repositories +* Regex +* Relational Databases: What they are; Data Modeling; Database querying criteria/best practices +* Reporting/Analytics +* Web Accessibility + +## To be scheduled/determined + +* Tools: Explain the agile development/scrum/sprint process +* Visual Task Board for Developers +* Reporting and Dashboards +* Tools: Slack +* Exercise: Creating catalog items \ No newline at end of file diff --git a/Update Set Instructions.md b/Update Set Instructions.md index 8324cc1..369218b 100644 --- a/Update Set Instructions.md +++ b/Update Set Instructions.md @@ -25,7 +25,7 @@ Update sets take all the changes you did and puts them together. It records all ![picture3](https://user-images.githubusercontent.com/6828733/51413781-e1a57380-1b24-11e9-848f-60f1bb5c22cc.png) -### 4. Name of your update set should be: IET related record (usually a story number), short description (story name) +### 4. Name of your update set should be: `Your organization/department abbreviation` `related record (usually a story number)` - `short description (story name)`