Metadata Repository

Settings > Administration > Global Resources > Metadata Repository

DEPRECATED: This functionality has been deprecated. Sandboxes are the preferred mechanism for shared development in the cloud.

Metadata is the data that defines platform elements. Objects, classes, and roles are all examples of platform elements that are defined by metadata. Every element in the platform is defined by metadata, and all of the metadata is stored in a central repository in the platform.

The metadata repository is an externalized version of the central repository that can be shared by multiple developers, creating a robust, nimble development environment for distributed development teams.

Prerequisites

In order to set up the development environment and use it effectively, you need a working knowledge of:

• XML
• Software development environments
• Version control software
• Development instance of the LongJump Platform

How it Works

As shown in the following diagram, the metadata repository is an externalized copy of platform metadata that can be shared by multiple developers, generally by way of a version control system.

In this shared development environment, applications can be 'built' using the metadata stored in the repository (similar to building an executable using source code).

In a local version of the LongJump Platform instance, users (developers) can:

• Keep multiple project spaces (Tenants), each pointing to different repository on the file system
• As the application development progresses, the LongJump Platform automatically represents the metadata in XML format in the repository path on the file system
• Check out the files and build an entire application in the local LongJump Platform instance (via Read from Repository)
• Extract the platform elements into XML files (via Write to Repository)
• Check in/check out XML files to/from the central repository

Note: Version control for the source code is managed by the Service Provider, and is outside the scope of the Metadata Repository. Learn more: Version Control.

Configure the Local Repository Path

A Develop Instance of the LongJump Platform is required in order to use this feature.

1. Click Settings > Administration > Global Resources > Metadata Repository
2. Click the [Edit] button
3. Click the checkbox icon to Enable Developer Configuration
4. Enter an absolute path to the Metadata Repository directory
5. Click [Save]

• The Metadata Repository Path is validated as follows, and triggers an error message if any of the validations fail:

• Is this a valid absolute path?
• Does the path exist in the server file system? If not, create the path/directory.
• Is write permission enabled for the path/directory?

After the Metadata Repository is enabled and configured successfully, developers can initiate development by reading from or writing to this path.

About the Metadata Repository Path

• This is an absolute path to directory on the local file system where the XML representation of your database resides, in the form of XML files.
• Validations are done to ensure that each tenant in a given instance has a unique path for storing those files.

About the Read / Write Actions

About the Read from Repository Action

A Read action transforms/interprets the metadata files (XML) that reside in the Metadata Repository Path into Platform Elements.

• All files in the Metadata Repository Path are read
• No option is provided to read specific files
• Before the read occurs, the Recycle Bin is emptied

Best Practice - Read from Repository

Follow this process to manage files in the Metadata Repository and support a healthy development environment.

1. Perform an Update from Version Control
2. Make any required create/update/delete actions on the working copy (Metadata Repository)
3. Perform a Read action from the Metadata Repository

• This assures that the timestamp is correct, and version control is supported correctly

After a Read action

• The platform elements in the development instance of the LongJump Platform match the platform elements defined in the metadata files

About the Write to Repository Action

A Write action transforms/interprets Platform Elements into metadata files (XML).

• Generates XML files from the metadata definitions of Platform Elements
• XML files are stored in the Metadata Repository Path

• In a Write action, files in the Metadata Repository Path are deleted, then the new files are written

Developers may use the Write to Repository action initially, construct XML files from a working platform instance.

Automatic Write to Repository

After the Developer Configuration is enabled and the Metadata Repository Path is configured, the Write to Repository action happens automatically, whenever a a Platform Element is modified in the working copy.

• If any metadata item is Added/Updated/Deleted, then the XML file is generated in the Metadata Repository Path; a timestamp for each metadata item is also stored in the working database, which matches the timestamp of the generated files
• If any metadata item is updated, then the timestamp of the item in the database is validated against the timestamp in the file system; if there is a mismatch, an error message is triggered, instructing the user to perform a Read action (Read from repository) before proceeding
• If an item is deleted, the corresponding XML file is also deleted
• If a deleted item is restored from the Recycle Bin, then the XML file is recreated

Golden Rule for Successful Development

Do not modify XML files manually

The Metadata Repository is designed to manage collaborative development environments by tracking check in/check out actions via timestamps embedded in the files.

If an XML file is modified (or deleted) outside of the Metadata Repository, then Save/Update/Delete actions on Platform Elements will fail, because the timestamp will be out of sync with the metadata repository.

Version Control

A Subversion-based Version Control system is required. Version Control systems create a central, accessible, uniform version of file assets. This is a key foundation in multi-developer environments, and a good idea, even in small shops.

As with all version control systems, it is critical that all files are updated before the developer attempts any modification. Version control clients like SyncroSVN are recommended, however any version control client that supports XML merging can be used. As always, any conflicts must be carefully resolved and merged.

Note: Hidden files/folders or SVN properties (.svn) are not affected by [Read from Respository]/[Write to Repository] actions

Learn more:

• SynchroSVN User Manual

• Video demos:

• Basic Functionality
• Check Differences
• Resolving Conflicts

Working with Syncro SVN Client

1. What happens if I delete an item?

   • When an item is deleted from the LongJump Platform, the corresponding metadata xml file is also deleted from the Platform Instance
   • The deleted item(s) are marked with an exclamation mark icon (!) in SyncroSVN
   • To reconcile this situation:

   • Note the folder name that is marked as missing (!)
   • Update the Platform Instance (local working copy) and use the Syncro Client delete command to mark it as deleted, then commit the changes

2. What happens if I rename an item?

   When an item is renamed, the corresponding metadata file is deleted from that platform instance and a new metadata directory is created

   • To reconcile this situation:

   • Note the folder name that is marked as missing (!)
   • Update the Platform Instance (local working copy) and use the Syncro Client delete command to mark it as deleted, then commit the changes

   The new directory will be updated to the Platform Instance (local working copy)

3. What is the XML metadata file naming convention?

   The XML filename is created as follows: {itemname}{underscore}{underscore}{itemId}.xml

   And appears as: [item_name]__[item_id].xml

   For example, an Invoice object might have this XML metadata filename:

   Invoice__3254avf8324jdm39424m5s9392.xml

   If the item name contains multi-byte characters, the term resource is used instead:

   resource__3254avf8324jdm39424m5s9392.xml