Object Naming Best Practices

Version 16
    Share This:

    << Other Best Practices

     

    I will be working on this document during the next couple of days (weeks), but please feel free to comment and give me feedback during this process!

    I have limited editing to a couple of co-authors at the moment, but will open the document when I get through the Alpha-phase...

    Introduction

    Naming of objects is important in any development environment, for many reasons, but doubly so in the Remedy system.

     

    Why is this so important in Remedy? It is due to the fact that all the objects in an AR System is dropped flat into the big sack of the main object type. For example Active-Links or Forms.

     

    To have any real chance of navigating a Remedy application within Developer Studio, it is extremely important to use strict naming conventions.

     

    In general, you can say that the beginning of an object name should position related objects close together, if you would sort the object list alphabetically.

     

    Scope

    This document (currently) tries to give you one style of naming objects in your AR System, which should be a very good fit for most situations.

     

    Eventually, this document may branch into several documents describing different styles in the future.

     

    If you currently have a big application in your system, such as ITMS, that you are expanding, this will limit your options. You must decide how to fit your code without introducing a contradicting naming strategy. At the same time you may want to flag your additions or modifications, to make them easy to spot.

     

    It is currently NOT the scope of this document to detail the naming convesions in ITSM.

    For ITSM customization, please consult BMC Application Customization.

    Technical Guru Summary

    This list of object types and suggested naming conversion is intended for those who need a quick summary, and already feel familiar with the rest of this document.

    • Application {Appl-name}
    • Fields [Group-prefix-in-form]{Base-form-prefix}{Del}{Field-name}
    • Filters {Appl-prefix}{Del}{Form-prefix}{Del}{Exec-order}{What does it do}
    • Active Links {Appl-prefix}{Del}{Form-prefix}{Del}{What triggers it}
    • Menus {Appl-prefix}{Del}{Form-prefix}{Del}{What does it show}
    • Guides {Appl-prefix}{Del}{Form-prefix}{Del}{Guide-name}
    • Escalations {Appl-prefix}{Del}{Form-prefix}{Del}{What does it do}

    TAG-explanation:

    • Required {}
    • Optional []

    Sample application

    To allow you to leave your usual tracks during this discussion, we will use small Food-application in all the examples, where we can store recipes including the preparation process and the required ingredients.

    FOO.pngClick on the image to maximize.

    Application or project (start from the top)

    Typically you would want to wrap your stuff into an application, and I customarily use Deployable applications, because they have many advantages. For example grouping in the home page application list, easy to move to another system, def-export can contain foundation data.

     

    You will need to decide a couple of things from the start, or if you are modifying an existing sytem, what strategy was used before you got there:

     

    What
    SampleDescription
    NameFoodYou will need a label that your users understand.
    PrefixFOO

    The prefix, or abreviation is very important, and all application objects should have this prefix.

    Typically 1-3 capital letters.

    Just make sure that it is easy to connect to the actual application, such as HPD to Incident

    Delimiter" "

    I like to use a single space " " as delimiter, as this makes things very readable.

    The most common delimiter is colon " ", as this had a special meaning for the old ARAdmin-tool, but it really makes things hard to read.

    Other common delimiters are dash "-" or underscore "_".

    Field ID Range600000000This, and some related information really belongs to another discussion: Field ID

    Forms

    Underneath the application, you have the form. I usually create a template-form for my application, that I copy (save-as) to create a new form. Set the basic layout, and permissions for the core field, and by all means add a couple of field such as a char-temp-field that you can use everywhere in your application.

     

    WhatSample 1Sample 2Sample 3Sample 4Description
    NameRecipeProcessIngredientProcess IngredientUse a descriptive name, but not too long...
    PrefixRPIPI

    Find a prefix that is unique to the application. If you have a small application, such as the example, you can use a one-letter prefix. I usually use 1-3 capital letters.

    Used for all connected filters, active-links, etc.

    I always use the form prefix, as the default value to my Request-ID field, to make it easy to connect such a Record-ID to the form involved.

    Full nameFOO RecipeFOO ProcessFOO IngredientFOO Process Ingredient

    Start with your application/project prefix, continue with the delimiter, and then add the name of your form.

    {Appl-prefix}{Delimiter}{Form-name}

    Field ID Range600001000600002000600003000600004000I usually have a form specfic field ID range for each form, used for any field that originates from that form.

    Fields

    ...

    Filters

    You will usually find many filters connected to a form, that may potentially trigger at the same time.

    From a naming standpoint, this makes it important to quickly see the execution order, and what the filter does.

     

    I would also recommend you to put related filters into guides, which usually makes it cleaner, simplifies the filter run-if clauses, and allows you to reuse temp-fields (because nothing outside the guide will touch your temporary data).

     

    Example

    Description

    FOO R 100 Check Status Assigned

    This filter just checks that the Assigned To field is not NULL when the Status is Assigned.

    {Appl-prefix}{Del}{Form-prefix}{Del}{Exec-order}{What does it do}

    FOO R 101 Call Guide CheckAssignee

    This filter just calls the Guide.

    FOO R Guide CheckAssignee 01 Exists in User

    Performs a Set-Fields to the User-form to verify that the assignee exists.

    See the Guide section for more details.

    FOO R Guide CheckAssignee 02 Error

    If the Assignee was not found in the User-form, this throws an error message telling the user about the problem.

    See the Guide section for more details.

    FOO R Guide CheckAssignee

    This is NOT a filter, it is just the Guide name included to show the complete picture.

    Note that these three filters can be replaced with a single filter, and still give the user relevant feedback using an error handler.

    FOO R Service 551 Get xxx

    Service filters can do wonders for your design.

    I suggest that you give them a special prefix befor the execution order, so that you will easily find them.

     

    Active Links

    The difference between Active Links and Filters is that Active Links are usually triggered a few at a time instead of going through all filters on a Submit or Modify.

     

    Active links are normally connected to a field or a specific action.

     

    To find an active link, in most cases, you know what triggers it, and this should be the basis of the naming.

     

    ExampleDescription
    FOO R Return Assigned To

    This filter triggers on "Return" in the "Assigned To" field.

    {Appl-prefix}{Del}{Form-prefix}{Del}{What triggers it}

    FOO R Return Assigned To Verify NameIt is often useful to add some additional explanation of what it does, if it is not obvious.
    FOO R Return Assigned To 01 Verify Name

    If you have multiple Active Links triggering on the same user action, they typically have an order in which they are processed.

    Add a number after the what-triggers-it part, and choose as many digits as you find relevant.

    In this example I have dicided that 99 execution slots is all that will ever be needed.

    FOO R Return Assigned To 99 Verify NameSee the above row.
    FOO R Display 101 Hide Customer Fields on ModifyYou might have many Active Links that fire on display, why I have decided to use 3 digits for the execution order. It is also more important with a descriptive name for the action when you have many things that fire on the same trigger.

     

    Menus

    ...

    Guides

    ...

    Escalations

    ...

    Shared Workflow

    If you have Filters or Active Links that you use across multiple forms, shared workflow, it is good practice to indicate this.

     

    Header 1Header 2
    FOO * Return Assigned To

    I have replaced the R, the Recipe form prefix, with an asterisk (*) to indicate that this Active Link is used on multiple forms.

    You can use another indicator there as well, such as shr or shared.