Staging Concept for Time Cockpit Customizations

One of the unique possibilities of time cockpit is its extensibility. You can adapt the data model, lists, forms, export and import formats, reports, etc. to you needs. A question that we often get is how to test customizations before putting them into production. In this blog post I would like to show you some options you have.

Categories of Extensions and Customizations

You can extend and customize time cockpit on various levels. The deeper you want to change time cockpit's default behavior, the more technical skills you need have. However, even if you have no programming skills at all, you can still adapt time cockpit to a large extent. Let's examine the different customization options.

Customizing Time Sheet Calendar Entries

Customizing the appearance of time sheet records in time cockpit's graphical calendar can be done without any programming skills. The tool to use for this purpose are Formatting Profiles. Typically formatting profiles are defined by time cockpit power users (e.g. backoffice team, the team's project manager) directly in the production system. With time cockpit's scripting capabilities you could theoretically prepare formatting profiles in a development environment and move it to production in a second step. However, we have not heard from users who want to do that.

Customizing Time Cockpit's Data Model

If you want to customize time cockpit's data model, you still don't need to write a program. You can use time cockpit's administration module to interactively add e.g. tables, columns, relations, valiation rules, etc.

Some of our customers make heavy use of this feature. They extend time cockpit with lots of additional features important for their business. At the beginning of a project, changing time cockpit's data model interactively is not a problem. However, when you have many people working with and depending on the system, you cannot risk breaking it by applying further changes. You need a way to test your customizations first. For this purpose time cockpit offers its scripting capabilities.

All configuration changes that you can make using time cockpit's UI can be made through a script, too. In fact there are some customizations which are only available via scripting (e.g. binary and file properties) - but this is not in the scope of this article. Time cockpit's online help contains a chapter with some sample scripts for model manipulation. Additionally you find the entire SDK documented there.

If you are not perfectly familiar with writing Python scripts and reading SDK documentation, you can even generate scripts from changes you made interactively. Just right-click on the item (e.g. entity, list, form, etc.) and select View Script. Time cockpit will generate a script for creating the selected item for you.

Customizing Lists and Forms

Time cockpit lists and forms actions are defined using an XML-based domain specific language. You can read more about it in the time cockpit online help:

• Customizing Lists
• Customizing Forms

I contrast to entities, you cannot add e.g. columns or fields directly to the lists and forms that we ship. The reason for this is time cockpit's update logic. Whenever we change or add something to the lists and forms we ship, we replace the entire definition in your subscription during update.

If you want to change lists and forms, you have to make your own copy of it and change this copy. Again you can use time cockpit's administration module to interactively design lists and forms and create a script for moving the change from test to prod later (see descriptions above).

Once you have successfully created a new list or a new form, you have to make it available to your users. You have multiple options for this:

• If you created an entirely new list, you might want to add it to time cockpit's menu. Use the Modules section to create a new link to your list:
  
  
• If you want to replace an existing list, you can also use the Modules section mentioned above. However, if your list should become the default list for an entity, you can replace our default list with your implementation in the entity definition:
  
  
• If you want to change the form for an entity, you can also replace our default form with your form in the entity definition (see previous item).

Best Practices

Here are some important best practices for making larger changes to existing time cockpit deployments:

1. Develop you customization or extension in a dedicated test environment first.
   Contact us if you want to have a copy of your production environment for development or testing purposes.
2. Write your customization or extension as a script.
   You can use time cockpit's visual editor, let time cockpit create a script afterwards and adapt it to your needs.
3. Never reuse existing GUIDs inside a single deployment. 
   Time cockpit uses GUIDs to uniquely identify each element of its data model. Either don't specify a GUID (time cockpit will generate one for you) or generate new GUIDs. However, you can reuse GUIDs in different deployments (e.g. use the same GUIDs in your test and your production environment).
4. Be very carefully when deleting parts of the data model.
   Users might become unable to synchronize their data if they have offline changes for model elements that you are about to delete.
5. Write scripts so that they can be executed multiple times.
   To achieve this you should add checks that only e.g. create a new entity if it does not already exist. See time cockpit's online help for examples.
6. If you build larger extensions to time cockpit, cosider using a source control system like TFS or Git to manage your scripts.
7. If your scripts become really large, consider using a dedicated development environment like Visual Studio with its Python Tools.
   This will give you things like a debugger, syntax highlighting, etc. See also this blog article of my colleague Simon about developing time cockpit scripts in Visual Studio.
   
8. All your changes are prefixed with USR_, don't try to change that.
   Never create customizations with prefix APP_ (Application Specific) or SYS_ (System). Theoretically this would be possible with time cockpit's SDK. However, if you do this, we might not be able to update your subscription anymore.