How to use Formspider Version Control

This tutorial explains the core concepts of Formspider Version Control and how developers can use them to control the revisions they make to their applications.

FS Version Control enables developers perform regular revision tasks on the source code of their applications. The FS Version Control supports following objects:

  • Every Formspider Object that can be created in a Formspider Application namely; Datasource Definitions, Datasources, Mainframe, Dialogs, Panels, Actions, Alerts, Buttons Groups, External Methods, Popup Menus, Menubars, LOV’s, Domains, Internationalization Keys and Timers.
  • Every Database Schema Object that can be created using the CREATE OR REPLACE command namely; Packages, Views, Procedures, Functions, Triggers and Synonyms.

Behind the scenes, FS Version Control seamlessly integrates with Git, the prominent distributed version control system used by millions of developers worldwide. FS supports the following Git operations on the source code it manages:

  • Reset (Called Revert to Commit Point in Formspider)
  • Create Branch
  • Change Branch
  • Merge Branch
  • Clone
  • Fetch
  • Pull

Enabling Version Control in a Formspider Application

When creating a new application simply check the box with the title “Enable Version Control” and click “OK”. In order to add an existing application to Version Control, open the Application Properties Dialog of the application, check the same box and click “OK”. Please note that, depending on the size of the application, adding it to FS Version Control may take a few minutes.

When an application is added to FS Version Control the first time,  it always has one branch named master. Formspider makes an initial automatic commit of all the FS Objects in the application to the master branch which is also the default current branch of the application.

Please note that Formspider does not automatically start managing database objects. Developers must manually add the database objects they want the application to manage to the application’s version control repository. Please see the section below called Managing Database Objects in FS Version Control for more information.

Editing an Object in Formspider IDE with Version Control Enabled

If Version Control is enabled in an application, Formspider requires a developer to check out an object before editing it. This can be achieved by;

  • clicking the “Check Out” menu item on the Pop Up Menu of an FS Object in the IDE Navigation Tree.
  • clicking the “Check Out” icon located at the top of the Object’s Edit Dialog, if the FS Object has its own Dialog,

  • clicking the “Check Out” icon located at the top of the Editor while the Object is open in the current tab of the Editor.

Once an FS Object is checked out, the Formspider IDE will allow editing of the object’s definition.

If an object is checked out by the current developer who logged in, its icon in the navigation tree will show a green lock.

If an object is checked out by another developer, its icon in the navigation tree will show a red lock.

Check-Out Mechanism

Unlike middle tier (Java, PHP etc…) or client side programming language code units (JavaScript, Objective-C etc..) PL/SQL code units do not reside in private files on a developer’s computer. They are globally available to every developer who has access to the database with the appropriate privileges. Therefore, PL/SQL developers mostly collaborate on the same PL/SQL code unit (Packages, Procedures, Functions etc…) using a check-out mechanism to prevent them from overriding each other’s modifications to the same PL/SQL code unit.

Developers of other programming languages work differently. They may edit different copies of the same file but they virtually never edit the same copy of a file. In most cases it is impractical for PL/SQL developers to set up their own private environments in which each developer has a private copy of the PL/SQL code units of the application he is working on. Therefore, FS Version Control features a check-out mechanism to better fit into the regular work routine of PL/SQL developers. This enables a team of developers to collaborate on one branch of the application without stepping on each others toes.

Whenever the developer checks out an application object for editing, Formspider automatically checks out its dependent objects that might be effected by the potential change. This enables Formspider to always keep the application in a consistent state even if multiple developers are working on it. For example, if a developer attempts to rename an Action, Formspider will attempt to check out every object (Panels, Alerts etc..) that references the action being renamed because renaming the action will cause a change in these dependent objects definitions. Formspider will not allow the rename operation if any of the dependent objects is checked out by another developer.

FS Version Control also supports a workflow in which each developer works in her own environment and with her own database objects (similar to a middle tier or client developer). Please see Cloning an Application section for more information on this subject.

Committing Changes to FS Version Control

At any time the signed in developer can view the list of objects she checked out from the “Version Control -> My Objects” menu item. Alternatively, she can use the “Commit Changes” icon in the IDE toolbar to access the same Dialog.


The “My Objects” Dialog has two tabs. The “All Objects” tab shows the list of the FS Objects in the application that are checked out by the signed-in developer or any other developer. The “My Objects” tab shows only the FS Objects signed-in developer checked out. The “Commit” button at the bottom commits the changes the signed-in developer made to an application to FS Version Control.

Clicking the “Commit” button opens a the “Commit Message” Dialog. Formspider requires a developer to enter a short description of the changes she is attempting to commit. This description comes in very handy when going over the history logs.

Once the Git commit is finished, Formspider displays the message it retrieves from the Git server. This message gives a summary of the updates made to the Git repository.

After the commit completes, FS Objects the signed-in developer checked out are automatically released.

Reverting to Commit Point

If a developer wants to cancel her changes in an application’s current branch and bring it to a state it was at a certain point back in time, she can do so by using the “Revert to Commit Point” option.

The “Revert to Commit Point” operation needs a valid Commit ID to function. The Git Repository gives a unique ID to each commit issued by a developer. The developer can browse the Git repository using the “Version Control” tab in the Formspider IDE. Using the “Version Control” tab she can determine the Commit ID she wants the application to revert back to.

To move back the application to a commit point, click the “Version Control -> Revert to Commit Point” menu item from the IDE menu bar.  The “Revert” Dialog shows up.

Paste the commit ID obtained from the “Version Control” tab to the Commit ID field and click the “Revert” button. The application will go back to the state it was at that commit ID and the Formspider IDE will display the message it received from the Git Server.

As a shortcut, you can revert to the previous state of the application by entering HEAD@{1} as the Commit ID.

Creating a Branch

Branching is a very powerful feature of version control systems that enables developers to work on multiple versions of an application easily. For example, a developer can work on the master branch of an application to fix bugs that are reported from the production environment and release maintenance versions while developing a new feature in the dev branch. The deployed new maintenance versions from the master branch never include the code written in the dev branch.

To create a new Branch click the “Version Control -> Create Branch” menu item. A Dialog show up.

Enter a name for the new branch. Enter the name of another branch or a Commit ID. This is the starting point of the new branch. Click the “Create Branch” button to create the new Branch. Once it is created, the application automatically switches over to the newly created branch. Formspider shows the current branch of the application open in the IDE.

Please note that there must not be any checked out objects in the application for Formspider to be able to create a new branch.

Changing Branches

In order to change the current Branch of the application open in the IDE, select the “Version Control -> Change Branch” menu item. A Dialog shows up.

Select the Branch to switch to and click the “Change Branch” button.

Please note that there must not be any checked out objects in the application for Formspider to be able to switch to another branch.

Merging a Branch to another Branch

Creating and switching between branches would not be as meaningful unless the FS Version Control also enabled merging of a branch to another. For example, once the development on the dev branch is finished developers should be able to move the changes to the master branch of the application. This is called a Merge.

To start a Merge click the “Version Control -> Merge Branch” menu item. A Dialog shows ups asking the source branch for the merge operation. The destination branch is always the current branch the application is on.

Click the “Merge” button to start the merge operation.

During the merge operation, FS Version Control carries over the changes made in the Source Branch to the Destination Branch. In some cases FS Version Control may not be able to figure out the right operation to perform to bring over a particular change. These cases are called Conflicts.

A Conflict may occur if;

  • An object deleted in the Source Branch is modified in the Destination Branch.
  • An object is modified in the Source Branch and in the Destination Branch, and Git Server cannot consolidate these modifications. (For example, in both branches the backgroundColor of the same panel object is changed to different values. There is no way a Version Control System can figure out the right way to consolidate these two changes.)
  • An object modified in the Source Branch is deleted in the Destination Branch.
  • A newly created object in Source branch and a newly created object in Destination branch have the same name.

Moreover, even if there is not a Conflict, after the merge, an FS Object’s definition may violate the Formspider Object Rules (For example, a button cannot have two buttonPress events). This happens because all Git does is merging text files. It does not understand the semantic meaning of the Formspider metadata and cannot validate its rules.

FS Merge Wizard provides an easy to use interface to the developer so that he/she can resolve these issues.

If there is a conflict in a database object after a merge, Formspider does the following in the destination schema:

  • It creates the database object in an uncompiled form with changes from both source and destination in it.
  • It creates the database object with “MINE” suffix in its name which represents the object in the destination repository.
  • It creates the database object with “THEIRS” suffix in its name which represent the object in the source repository.

The developer is responsible to resolve the conflicts and compilation errors in the database objects.

Until the merge conflicts for FS Objects are resolved, Formspider IDE does not allow developers to modify the application subject to the merge operation. Please see How to do a Merge in Formspider for more information on this topic.

Cloning an Application

If  it is feasible in the development environment,  Formspider allows each developer to work on its own private copy of an application (including both FS Objects and Database Objects). This way of working is similar to how middle tier and client side developers build applications where everyone has its own private copy of the application objects.

To clone an application, click the “Version Control -> Clone” menu item. A dialog shows up.

Enter a name for the new application which is going to be created as part of the cloning and a datasource schema name for this new application.

Cloning creates a new copy of an application based on the last commit its current branch is on.

Since Clone operation copies every Database Object being managed by the original application to the clone application, it must know the schema names it needs to use to create the new Database Objects. Therefore, it lists the schema names of the Database Objects in the original application’s version control repository and asks the developer to provide a destination schema for each one of them.

For example, assume that the developer is cloning an application named AppOne with datasource schema SchemaOne. Further assume that the new name for the clone application is CloneOne and the new datasource schema for CloneOne is TargetSchemaOne. If AppOne is managing Database Objects in SchemaOne and SchemaTwo, the Clone dialog asks for two destination schema names, one for SchemaOne and one for SchemaTwo such as TargetSchemaOne and TargetSchemaTwo. The clone operation copies all the Database Objects in SchemaOne to TargetSchemaOne and  the ones in SchemaTwo to TargetSchemaTwo. Further, Clone operation ensures that the copied Database Objects are being managed by CloneOne application. This way it creates a completely new copy of AppOne named CloneOne that does not share any dependencies with AppOne.

Fetching Branches from Another Application

Cloning an application only makes sense if it can later be merged to the original application. The Fetch operation is the first step to achieve this goal. Fetch retrieves the branches from another application to the current application. These new branches can be used in a Merge operation.

To fetch from another application, click “Version Control -> Fetch” menu item. The Fetch Dialog shows up. Select the application to retrieve the branches from and click “OK”.

Pulling from another Application

Performing a Pull is identical to performing a Fetch and a Merge. In other words, Pull retrieves branches from another application and merges the selected branch to the current branch of the application open in the IDE. Click the “Version Control -> Pull” menu item in the IDE menubar. The Pull Dialog shows up. Select the application and the branch to pull from and click “OK”.

Managing Database Objects in FS Version Control

A Formspider application consists of both FS Objects and Database Objects. FS Version Control enables developers manage both the FS and Database Objects of an application in the same version control repository. Every FS Object a developer creates in an application with Version Control enabled, is automatically added to the application’s version control repository and managed by the system. For Database Objects however, the developer must manually register the object to the application’s version control repository.

To add database objects to an applications version control repository click the “Open” icon in the Database Objects Navigator toolbar.

The “Database Objects” Dialog shows up.

To add Database Objects to the application’s repository, select the schema the database objects reside. Next, select the type of the objects. FS Version Control supports the following object types: Procedure, Function, Package, View, Trigger and Synonym.

Finally, select one or more objects from the list of available objects and add them to the list of managed objects. The Dialog supports registration of multiple types of objects in one step. Click “OK” to complete save the changes.

A Formspider application’s version control repository can manage database objects in multiple schemas. To add database objects from another schema simply change the schema name selected in the dialog’s combo box and continue as described above. Please note that the dialog will ask to save the modifications prior to changing the schema name.

Editing a Database Object Managed by FS Version Control

Developers may continue using their favorite PL/SQL editor to edit database objects managed by FS Version Control. Since FS Version Control is implemented at the database level, it works with any editor.

Once a database object is part of an FS application version control repository, FS Version Control will only allow changes to it if there is a signed in Formspider User in the current database session the update is being executed in and if the database object is not check out by another user.

Formspider has a new API package called api_versioncontrol to help developers interact with FS Version Control.

The API’s in api_versioncontrol are as follows:

login(in_user_cd varchar2, in_password_tx varchar2) :
signs in to Formspider with a valid Formspider User Name and Password

logout;
signs out of Formspider

checkOutDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2);
Locks the specified Database Object for the signed in user to edit.

releaseDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2);
Releases the lock on the specified Database Object which belongs to the signed in user.

addDBObject(in_schema_cd varchar2, in_type_cd varchar2, in_name_tx varchar2, in_repoName_tx varchar2);
Adds a database object to an applications version control repository. Use the managing Formspider application's name as the value for the in_repoName_tx parameter.

Use the TYPE_FUNCTION, TYPE_PACKAGE, TYPE_PROCEDURE, TYPE_SYNONYM, TYPE_TRIGGER, TYPE_VIEW constants in the api_versioncontrol package as input values to the in_type_cd parameter used in the API’s.

There are 4 more API’s in api_versioncontrol that are used by Formspider internally to manage database objects.

Use the checkOutDbObject API to check out a database object. During a save, Formspider automatically checks out a database object in her name if the Oracle session has a signed-in Formspider User.  If the object the developer is attempting to edit is already checked out by another developer, Formspider prevents the save with an appropriate error message. Developers may also use the Formspider IDE and check out a database object from the navigation tree by right clicking to it and selecting the Check Out menu item from the Pop Up menu.

The Formspider IDE presents a green lock icon on database objects checked out by the signed-in developer and a red lock icon on database objects checked out by other developers.

Committing Database Object Modifications

Commits are issued the same way commits are issued for FS Objects. To issue a Git commit go to “Version Control -> My Objects” or click the “Commit Changes” icon in the Formspider IDE Toolbar.

The “My Objects” Dialog shows up.

Database objects checked out by the signed-in developer show up in the “My Objects” Tab along with the FS Objects. Clicking the “Commit” button commits signed-in developer’s changes to the application’s version control repository.

Please note that there is no API in the api_versioncontrol package to issue a Git commit. Commits can only be issued via the Formspider IDE.

Releasing an Object

If the developer wants to remove the edit lock on an object she checked out, she can do so by attempting to release the object. For an object to be released, it must not have been edited by the developer. If an object is edited, the only way to remove the lock is to issue a commit.

To release an object, click “Version Control -> My Objects” menu item or the “Commit Changes” button on the toolbar. Next, click the “Release” hyperlink next to the object. This causes Formspider to attempt to release the edit lock on the object. If the current definition of the object is the same as the last committed version then the Release succeeds.

Note that Database Objects can be released either from the Dialog above or using the API api_versioncontrol.releaseDbObject.