Deltek Maconomy Extender Handbook for Using the Maconomy Extender IDE

July 31, 2014

While Deltek has attempted to verify that the information in this document is accurate and complete, some typographical or technical errors may exist. The recipient of this document is solely responsible for all decisions relating to or use of the information provided herein. The information contained in this publication is effective as of the publication date below and is subject to change without notice. This publication contains proprietary information that is protected by copyright. All rights are reserved. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, or translated into another language, without the prior written consent of Deltek, Inc. This edition published July 2014. © 2014 Deltek, Inc. Deltek’s software is also protected by copyright law and constitutes valuable confidential and proprietary information of Deltek, Inc. and its licensors. The Deltek software, and all related documentation, is provided for use only in accordance with the terms of the license agreement. Unauthorized reproduction or distribution of the program or any portion thereof could result in severe civil or criminal penalties. All trademarks are the property of their respective owners.

Handbook for Using the Maconomy Extender IDE ii

Contents

Terminology and Concepts ...... 1 Installation ...... 2 Installing in Eclipse ...... 2 Updating Maconomy Extender ...... 3 Alternative Update Method ...... 5 Starting Maconomy Extender ...... 6 Setting Up a Server Repository ...... 7 Extending a Maconomy Installation ...... 10 Creating a MaconomyExtender Project ...... 10 Automatic Check of the Maconomy Version ...... 13 Find, Open, and Copy Standard and Solution files ...... 14 Inspecting Container Definitions ...... 16 Server-Specific Files ...... 17 Validating Changes ...... 17 Impact Analysis ...... 18 Testing Changes on a Local Maconomy Installation ...... 18 Comparing Files on the Sandbox Server with Files in the Active Project ...... 19 Comparing Files from the Standard Layers with Files in the Active Project ...... 20 Inspecting Installed Files on a Server ...... 20 Pushing Changes to the Server Repository ...... 20 Deploying Changes ...... 22 Development Workflow and Git ...... 24 Introduction to Git ...... 24 Work Process and Server Setup ...... 25 Server Setup and Relation to Branches ...... 27 Deployment Diagram...... 27 Rules Imposed by Maconomy Extender ...... 28 Workflow Examples ...... 29 Maconomy Classic Support ...... 32 Creating Maconomy Classic Folders ...... 32 Specifying Customer Numbers and Building and Stamping Options ...... 32 Need a Special License File? ...... 34 Deploying Reports ...... 34 Working with Servers ...... 35 Deploying to a Server ...... 36

Handbook for Using the Maconomy Extender IDE iii

Promoting to a Server ...... 36 Forced Deploy (Deploy to Server) ...... 37 Viewing Installation History ...... 37 Changing the Server Configuration ...... 37 Using the Editors ...... 40 Working with the Source ...... 40 Working with the MMSL Preview ...... 42 Working with the MWSL Preview ...... 42 Working with the MDML Preview ...... 46 Authentication and Authorization Support ...... 49 Access Roles ...... 49 Login Dialog ...... 50 Extension Framework Development...... 51 Prerequisite ...... 51 Creating a Bundle ...... 51 Extending a Container ...... 52 Creating a Root Container ...... 52 Setting the Target Platform ...... 54 Whitelist ...... 55 Download a Coupling Service ...... 55 Starting the Coupling Service for Testing...... 55 Deploying Changes ...... 55 Uninstalling Extensions ...... 56 Custom Dictionaries ...... 57 Add and Modify Dictionary Files ...... 57 Deploying Dictionaries...... 57 Working with the Git Version Control System ...... 59 Scenarios ...... 59 Tips and Tricks ...... 67 Writing Release Notes ...... 69 Adding Release Notes...... 69 Viewing, Modifying, and Deleting Release Notes ...... 69 Generate Release Note Report ...... 69 References ...... 70 Online Resources ...... 70 Books ...... 70 Appendix A: Using GitHub ...... 71

Handbook for Using the Maconomy Extender IDE iv

Appendix B: SSH Access to a Git Server ...... 73 Generating Public/Private Keys ...... 73 Adding a Public Key to the Server ...... 74 Preparing a Repository Server with SSH Access ...... 74 Appendix C: Troubleshooting ...... 75 Coupling Service Commands Do not Seem to Work ...... 76 Appendix D: Set Up SSH Access to a Windows Server...... 77

Handbook for Using the Maconomy Extender IDE v

Terminology and Concepts

Before you read this document, you should be familiar with terminology related to servers and server processes.

Term Description

Sandbox Server A Maconomy server used to test changes without any repository control. It can be a local installation or a shared server.

Development Server A Maconomy server under repository control. Used for development testing, this server can be used by several people.

Release Test Server A Maconomy server used to test extensions by end users.

Pre Live Server A Maconomy server with a setup exactly like a live server. Changes are verified on this server before they are deployed/promoted to a live server.

Live Server A Maconomy server running live (in production).

Local Repository A local clone of the server repository. The local repository is used during development. Committed changes can then be pushed to the server repository.

Server Repository A remote repository on a server or GitHub, where all source code is shared among developers. Users can fetch and merge changes from the server repository and push changes to it. The server repository can be accessed through file or SSH.

VCS Version Control System. The Maconomy Extender uses Git as the VCS.

Deploy To deploy means to install a specific revision from the repository on a server. Source files are installed on a server through a deployment mechanism.

Promote To promote an installation from server A to server B means that the revision installed on A will be installed on B.

Handbook for Using the Maconomy Extender IDE 1

Installation

Maconomy Extender is based on Eclipse and comes as a separate product for Microsoft Windows. It is shipped as a zip file and can be downloaded from the following site: https://dl.maconomy.com/partner/Applications/Released/MaconomyExtender/Products/Released/ Unzip the content to a folder on your hard drive and double-click the MaconomyExtender.exe file in the directory /MaconomyExtender/. Because of restrictions on path lengths on Windows, you should unzip to a directory near the drive root, for example, c:/Applications/. Download the 64-bit version if you have a 64-bit Windows installation. You can also install Maconomy Extender in an existing Eclipse development environment through an update site. For more information, see Installing in Eclipse.

Macintosh and Linux platforms are not currently supported. You must use Windows to install.

Installing in Eclipse If you have an existing Eclipse 4.3.1 (Kepler) installation with features similar to the Eclipse for RCP Developers edition, you can install Maconomy Extender through an update site.

To install or update Maconomy Extender, complete the following steps: 1. From the Maconomy menu, click Help » Install New Software. 2. Click the Add button. 3. On the Add Repository page, make the following entries: . For Name, enter ME. . For Location, enter the following: https://dl.maconomy.com/partner/Applications/Released/MaconomyExtender/Update Sites/Released/ . Click OK. The Maconomy Extender features available for installation display onscreen.

Handbook for Using the Maconomy Extender IDE 2

Installation

4. Select both features—Maconomy Extender and Maconomy Extender Dependencies.

5. Clear the Contact all update sites during install to find required software option. 6. Click Finish and then click OK on the dialog boxes that open. 7. If you are not logged in to Deltek’s domain, enter a user ID and password when you are prompted: . Enter the partner site user ID: maconomy/PartnerFTP. . Enter the password: #The2011Journey#. . Click OK. 8. Restart Eclipse when you are prompted.

Updating Maconomy Extender Maconomy Extender is configured to update itself. When Maconomy Extender starts, it contacts an update site to check for updates. If an update is available, you see a notification in the lower- right corner after Maconomy Extender starts.

Handbook for Using the Maconomy Extender IDE 3

Installation

If you are outside Deltek’s domain, you are prompted for a user ID and password. Enter the user ID and password provided above.

To update Maconomy Extender, complete the following steps: 1. Click the notification on the Updates Available message box. Maconomy Extender is listed in the Name field on the Available Updates page.

2. Press Next, press Next again, accept the license agreement, and click Finish.

Handbook for Using the Maconomy Extender IDE 4

Installation

3. When the installation completes, click Restart Now.

Alternative Update Method You can also check for updates manually by following the steps in Installing in Eclipse. If you are outside Deltek’s domain, you are prompted for a user ID and password.

Handbook for Using the Maconomy Extender IDE 5

Starting Maconomy Extender

To start Maconomy Extender, execute the MaconomyExtender.exe file under the MaconomyExtender folder in the installation directory. Like many Eclipse-based tools, Maconomy Extender uses a workspace where source files are located. Maconomy Extender and Eclipse also store runtime data related to the tooling in the workspace. You may be asked to select a workspace when Eclipse starts. You can accept the default location, which is a directory in the installation directory, or you can select another location.

Handbook for Using the Maconomy Extender IDE 6

Setting Up a Server Repository

Before you extend a Maconomy installation for the first time, you must set up a server repository with the custom files from the Maconomy installation. This is a one-time-only operation—it is only needed when a specific customer starts using Maconomy Extender for the first time. The repository is used to share files among team members, and it tracks the changes made to each file. The repository is usually set up by a technical consultant when installing or upgrading a Maconomy installation. Initially, you set up the repository with files from the Custom folder under the CustomizationDir directory from the Maconomy installation directory. You set up the repository as empty if there are no custom files. Maconomy Extender uses the repository to get custom files. Changes or new files are pushed back to the repository from the user’s machine. You can set up the server repository on one of the following: . A server with direct file access . A server with SSH access that has the Git version control system installed . GitHub — a cloud service for hosting Git repositories The recommended option is to use GitHub. Then customers, partners, and Deltek consultants can collaborate using the same repository in the cloud, and Deltek has access to the source files in support cases. To set up a GitHub repository you can either use Deltek’s GitHub account, or the customer or partner can create an account. If you use Deltek’s GitHub account, you must contact Deltek Engineering ([email protected]) to get the repository created and set up with access by your users. Please make the request at least one day before it is needed. The direct file access approach is the easiest to set up because it does not require any software installation or initial setup at GitHub. This option is most often recommended for test and demonstration purposes. The direct file access requires that all consultants who work on a customer project have read/write access to the shared network drive. Maconomy Extender provides a wizard to help set up a server repository from a Maconomy installation.

To launch the setup wizard, complete the following steps: 1. In Maconomy Extender, click File » New » Other » Maconomy » Maconomy Server Repository. 2. Click Next. The Access to the Maconomy Server page and the Repository page are displayed.

Handbook for Using the Maconomy Extender IDE 7

Setting Up a Server Repository

3. To set up how to access the Maconomy development server, perform one of the following actions: . You can access the Maconomy installation through the file system if you have direct file access to the server. Enter the Maconomy directory if you use file access. . You can access the server through an SSH connection if the server supports it. Select the SSH access option and define the connection parameters. The Maconomy install path on the server must be an absolute path to the Maconomy server installation on the server. Information about access to the server is stored in the repository and is used by Maconomy Extender when you deploy extensions to the server. 4. Click Next and set up coupling service. For the Maconomy server, select where the coupling service is installed. 5. Set up the server repository. Use one of the following options: . You can set up the server repository on GitHub. Enter the name of the repository on GitHub. The repository must already exist on GitHub. Contact Deltek Engineering to get one created. If you use an account other than Deltek’s GitHub account

Handbook for Using the Maconomy Extender IDE 8

Setting Up a Server Repository

(DeltekEngineeringOperations), you must change the GitHub preferences to use the other account in Window » Preferences » Maconomy Extender » Github. See Appendix A: Using Github for further details. . You can set up the server repository as a file directory on a network drive; all users must be able to access that directory on that drive. . You can set up the server repository on an SSH-based server. SSH access requires an SSH-enabled server with Git installed. Furthermore, the server must have a bash console. A Windows server must have Cygwin installed. Appendix A: Using Github describes how to set up such a server. In the preceding figure, we selected Github and entered the repository name as defined on GitHub. 6. Provide a name for the repository link file and a project name. These are used to generate a repository link file that is placed on the server. You can import this link file into Maconomy Extender; the connection to the repository is set up automatically. 7. Click Next and establish security settings for the repository. You can choose a basic security option that uses a simple user database to set up and assign individual roles to a number of team members. For example, you can specify who can deploy to a server and who can only develop extensions. See Authentication and Authorization Support for information on how to use security in Maconomy Extender. Or, you can opt not to set up any security for the repository. You can then enter a namespace for the customer. The namespace must be a valid directory name and is used for placing custom files. For example, the namespace can be the name of the customer. This is a default namespace for the customer, and other namespaces can be used while developing extensions. If the customer is a DMFE customer and uses a shared Maconomy cloud server, the customer’s short name should also be defined. 8. Click Finish. The wizard accesses the server for to retrieve custom files and then creates the repository at the selected location. Standard files are also extracted from the server and put into the server repository. Because this includes more than 4,000 files, the operation might take a while, from a couple of minutes to hours, depending on network speed and access to the server. This completes the initiation of the server repository. Users can start to make extensions to the Maconomy installation through this repository and deploy files from the repository to the Maconomy server.

Handbook for Using the Maconomy Extender IDE 9

Extending a Maconomy Installation

This section introduces how to create a Maconomy Extender project for a customer and how to start extending the Maconomy installation. Maconomy Extender has a built-in development workflow and rules for how to deploy changes to servers. This is explained in Development Workflow and Git. You can extend several Maconomy installations in a single workspace at the same time. Each Maconomy installation is extended in one MaconomyExtender project. A MaconomyExtender project contains all of the custom files for a Maconomy installation and is connected to a server repository and a Maconomy installation. This is set up automatically when you create the project.

Creating a MaconomyExtender Project

To create a MaconomyExtender project, complete the following steps: 1. In Maconomy Extender, click File » New » MaconomyExtender project. Maconomy creates a project named DemoExtension in the workspace and imports custom files from the server repository into a local repository. The following figure shows the first page of the New Maconomy Extender Project wizard.

2. Set the location of the server repository. You can set the location manually or you can select a Server Repository link from the drop-down list. This action sets the project name and the server repository location. Alternatively, you can browse to a server repository link file. A link file was created and placed on the Maconomy server when the server repository was created. Or, you can enter a project name and set the location of the server repository. If you use GitHub, enter the name of the GitHub repository. If you do not use Deltek’s GitHub account, you must set the account name in the preferences.

Handbook for Using the Maconomy Extender IDE 10

Extending a Maconomy Installation

3. Configure the Server Repository link field to list repository link files in a specific folder. To do this, click Window » Preferences » MaconomyExtender under the “Folder with link files” preference. This step is optional. 4. Click Next. 5. If you see a dialog box about authenticity as illustrated in the following figure, click Yes.

6. If asked for a keyphrase, enter the keyphrase for your private key used for Github.

7. A local clone of the server repository is created, and the server mappings wizard page displays. This page lists all of the Maconomy servers that are defined in the server repository for this customer. In the following figure, four servers are defined, with three based on file access and one that is not accessible.

8. For each server that has file access and does not have a UNC path defined, enter a path to the installation directory on a network drive. This information is necessary to deploy extensions to the servers. You specify a server mapping if a server was defined with file access without using an UNC path.

Handbook for Using the Maconomy Extender IDE 11

Extending a Maconomy Installation

9. Set the sandbox Maconomy installation directory. If you set the sandbox installation directory, you can test changes on the sandbox server before you commit them to the repository and deploy them to the Maconomy server. A sandbox server can be a local Maconomy installation or a shared server that can be used for testing. This step is optional. 10. Click Next, and use the Standard and Solution layer options to access extensions from these layers.

. Use the Use files from Server Repository option when it is available. Standard files are taken from the server repository. This is the default option when files are available in the repository. . The Don’t use files option specifies that no files are used. Hence, you cannot copy files from these layers to the custom layer or to validate the extensions. . The Use files from sandbox Maconomy installation option uses the standard files from the sandbox installation as the base for copying them to the extension layer, and for executing validations. . The Extract and use files from default server option extracts the standard and solution layer from the server to the local machine and uses these files. Be aware that this can be a long operation that can take minutes or hours, depending on network speed and access to the customer. . The Use files from directory option uses standard files from the specified directory as the base for copying them to the extension layer, and for executing validations. 11. Click Finish. A project is created. It contains the custom files imported from the server repository, and the project itself is set up as a local repository. The editors for the workspace client file types are automatically configured, and the available standard and solution files are updated to reflect the Maconomy version for the project.

Handbook for Using the Maconomy Extender IDE 12

Extending a Maconomy Installation

You can now change, add, or delete custom files in the project; test the changes on the sandbox Maconomy installation; push them to the server repository; and deploy them to the Maconomy servers. These actions are described in the following sections.

Automatic Check of the Maconomy Version When a project is created, and each time it is set as active, the Maconomy version of the default server is compared to the Maconomy version registered in the repository. If the versions do not match, a warning is shown as illustrated in the following figure.

The Maconomy version of the standard files used for the project is also compared to the Maconomy version registered in the repository, and a similar warning is shown if they do not match. If any of these warnings are shown, you should update the repository with information about the new version as well as the updated standard files. You can do this from the Project Properties page. Right-click the project, then select Properties » MaconomyExtender » Version, and click the “Check server for upgrades” button.

Handbook for Using the Maconomy Extender IDE 13

Extending a Maconomy Installation

When the versions do not match, you can select a server to update from. Versions, schema files, and standard files are then updated to the same version as the server, and the information is pushed to the server repository so others automatically get it. If the Maconomy versions of standard files are wrong, and the repository has been updated for the new Maconomy version, you can update the standard files for the project from the project properties page under Properties » MaconomyExtender by clicking the “Update” button. Creating another project for the same customer also uses the updated standard files from the repository.

Find, Open, and Copy Standard and Solution files Files from the standard and solution layers are located in a dedicated view called Standard and Solution Layers. This view is configured to show standard and solution files for the active Maconomy Extender project. The active project is the one that was most recently created. You can change the active project at any time by selecting a Maconomy Extender project. Right-click the project and select MaconomyExtender » Set as active from the context menu. This action updates the Standard and Solution Layers view. The view displays files related to the Maconomy version that the project extends (see the following example).

Handbook for Using the Maconomy Extender IDE 14

Extending a Maconomy Installation

The Standard and Solution Layers view provides the following functionality: 1. The view lists Workspace Client files for all layers. This includes the custom layer, where files are located in the workspace and shown in the Project Explorer view. A yellow color on a file indicates that this file is shadowed by another layer. 2. The view contains an interactive filter. The list of files that match the filter is automatically updated when the filter changes. For each file, you can see the file type and the layer from which it originates. 3. Double-click a file to open it. It opens in read-only mode if it is from the Standard, Solution or Extension layer. You can change the yellow background of the editor in the Maconomy Extender preferences. 4. To copy a file from the standard or solution layer to the extension layer, right-click and select Copy as extension in the view (or in a read-only editor). Alternatively, click the corresponding action on the view. This action opens the file for editing and closes the editor with the read-only version, if it was previously opened. This action also removes the stamp. 5. When the Link with editor action is enabled, the view selects the standard file that is currently open in the editor. This can be handy when you are working with the editors and navigating between files. It also resets the filter. To keep your filter settings when navigating between files, disable this action. The following figure shows the DemoExtension project with three files copied as extensions from the Standard and Solution Layers view. The locations of the files in the folders are created automatically.

Changing Standard Files The location of standard files is defined when creating a project, and it can be changed at any time by right-clicking on the project, then selecting MaconomyExtender » Standard files path. Set the project as active after changing the path. Then the Standard Files view is updated. By default, standard files are downloaded from the server repository, where they are packaged in a zip file. If the standard files are not available from the repository, you can download them at any time from a server in the Servers view. Right-click on a server with File or SSH connection and choose “Extract standard files.” Be aware that it can be a time-consuming operation because more than 4000 files will be downloaded. The first time that files are downloaded, a zip file with all of the files is produced and placed on the server. The next user who downloads files from the server will download the zip file, which will only take a few seconds.

Handbook for Using the Maconomy Extender IDE 15

Extending a Maconomy Installation

Updating Standard Files after a Maconomy Upgrade Standard files in the repository and in the project must be updated when the Maconomy server has been upgraded. Right-click the project, then select MaconomyExtender » Version » Check for updates. Select the development server, click Finish, and wait for the process to complete, which can take several minutes, depending on network speed. Standard files are downloaded from the server, zipped, and pushed to the server repository, and the project automatically uses the new standard files. Other consultants who are working on the same customer project must update their standard files to the newest ones in the repository. The preceding section “Automatic Check of the Maconomy Version” describes how to do this.

Inspecting Container Definitions Container definitions, also known as Dialogs ODL and MDSL, can be found in the Container view. This view lists all (known) containers for the Maconomy server. Selecting a container shows information about it and available panes. Selecting a Pane shows available fields, foreign keys, and actions. Each list has an interactive filter that makes it easy to locate specific elements. Columns can also be selected to sort rows. The first time that the view is shown it might take a few seconds to render because it must parse all MDSL files. Click Refresh if it is empty.

Extracting Container Definitions from Coupling Service Container definitions from files on the server are not completely correct. At run time, additional actions and extensions made by the Extension Framework are applied. These resulting Container definitions /MDSL files can be extracted from a Coupling Service (16 SP2 and 15 SP7 onward). In the project properties, select Coupling Service and enter the IP address and web port for the coupling service.

Handbook for Using the Maconomy Extender IDE 16

Extending a Maconomy Installation

To extract existing container definitions, select one or more in the Container view and click the “Extract” action in the top-right corner of the view. To extract a custom container, enter the container name, including its namespace, in the filter field and click the Extract action.

Server-Specific Files Some files, such as the couplingconfiguration.mcsl.xml file, may vary, depending on the server they are deployed or promoted to, which can be handled by creating a server-specific mapping file. Select File » New » Other » Maconomy » Server specific mapping file. The file map.filemapping is created in the ServerSpecific folder. The folder is created if it does not already exist. Next, place the server-specific files into the folder. It is a best practice to place the files in subfolders similar to where they should be installed. For instance, the mcsl files should be placed in a Definitions folder in the ServerSpecific folder. To identify which specific file should only be deployed to a specific server, drag it into the open filemapping file. It is updated with a row that specifies the source file, the ID of the server where it should be deployed, and the target path and file name it should have on the server. You can delete a line in the file mapping by right-clicking and choosing Delete.

When you deploy server-specific files to folders under the CustomizationDir/Custom directory, you must select the CustomFolder extension type in the deployment dialog to get the files copied to the server.

Validating Changes MWSL files are automatically validated when the project is built, for example when it is set active, and when changes are saved to a file. Issues are listed in the Problem view and red markers are shown inside the file. Currently the validation only validates if Panels in MWSL are defined correctly, that is, that the bindings are correct; that the referenced container, layout, and view exist; and that they are of the correct types. It also validates that foreign keys exist and are valid.

Handbook for Using the Maconomy Extender IDE 17

Extending a Maconomy Installation

You can also validate MWSL files in all layers by right-clicking on the project Maconomy » Validate complete customization. Files in standard, solution, and extension layers are then also validated, as customizations might introduce errors to standard files, for example, by removing a view from a shadowed MDML file. You can turn the automatic validation of MWSL files off in the preferences.

Impact Analysis It can be difficult to know the consequences of changing a layout file or view inside it because many workspaces might use it. The Impact analysis feature helps you to understand the impact of making a change to a layout. Inside the source code of an MDML file, right-click and select Maconomy » Impact analysis. If the mouse is located inside a view, only workspaces that reference this view will be found. A location outside a view will find all workspaces that reference the layout file.

Testing Changes on a Local Maconomy Installation After you add files to or delete files from the MaconomyExtension project or change existing files, you can test the changes on the sandbox Maconomy installation, if you set it up when you created the project.

To define a sandbox server, complete the following step: 1. Select Add sandbox server from the View menu and define where it is located. You can define a sandbox server at any time.

To deploy changes locally, complete the following steps: 1. Click Deploy locally on the toolbar (see the following figure) or right-click the Maconomy Extender project and then click MaconomyExtender » Deploy directly to local server.

Handbook for Using the Maconomy Extender IDE 18

Extending a Maconomy Installation

A Deploy Project to Sandbox Server dialog box displays (see the following figure). You can also deploy a single file to the Sandbox server by right-clicking on an open- source editor, or by clicking the Deploy button on the upper-right corner of the Preview editor. 2. On the dialog box, select the resources to be deployed to the sandbox server. Changes are not committed to your local repository. You can deselect extension types that you do not want to deploy.

3. Click OK. Selected changes are installed on the sandbox server. The deployment mechanism first deletes selected resources under the Custom folder, and then it copies the custom files from the workspace to the Custom folder. A warning displays if the sandbox installation is similar to one of the servers in the Servers view. This warns you about the direct installation of changes on a server without first committing and pushing them to the server repository. You can also deploy files to a sandbox server similar to a server in the Servers view. This is described in a following section.

Comparing Files on the Sandbox Server with Files in the Active Project You can also compare files on the sandbox server with files in the active project.

To compare files, complete the following step: 1. Right-click the active project and select Maconomy » Compare with sandbox server from the shortcut menu.

Handbook for Using the Maconomy Extender IDE 19

Extending a Maconomy Installation

Comparing Files from the Standard Layers with Files in the Active Project You can also compare files from the standard, solution, and extension layers with files in the active project. This can be useful to examine which customizations have been made.

To compare files, complete the following step: 1. Right-click the active project, a folder, or a file and select Maconomy » Compare with standard files from the shortcut menu.

Inspecting Installed Files on a Server You can retrieve and inspect files installed on a server with history by right-clicking on the server in the Servers view and choosing “Checkout installed revision.” This checks out the files installed on the server to the active project. You can then use code navigation from the WS client to the code, and compare the files to standard files as described in a previous section. You can switch back, for example, to the development branch from the Deployment diagram.

Pushing Changes to the Server Repository You must commit local changes to the local repository and push them to the server repository to let others merge the changes into their extensions or to deploy the changes to a Maconomy server.

To push changes to the server repository, complete the following steps: 1. Click the Commit and Push button on the toolbar (see the following figure) or right-click the Maconomy Extender project and select MaconomyExtender » Push changes to server.

The Commit and push changes dialog box (see the following figure) is displayed.

Handbook for Using the Maconomy Extender IDE 20

Extending a Maconomy Installation

The commit message displays relevant information about the changes that you made. The commit message is only relevant if there are local changes that you have not committed to the local repository. You can also enter an issue if the commit is related to a registered issue or bug. 2. If you check the Push all branches option all local branches are pushed to the server repository. 3. If you select the Deploy immediately option and select a server, the commit is deployed (installed) immediately after the changes are pushed to the server repository. You can also do the deployment later. As described earlier, deployment only works when there is file access or SSH access to the Maconomy server. If the server is not accessible, a zip file with code to install is generated. 4. You can select to deploy only the files that have changed since the last deployment by selecting the Only deploy files changed since last deployment option. This option is only allowed for servers that keep an installation history. Click Show changes to list all of the files that have changed since the last deployment to the server. 5. Selecting Ask to deploy files after preparation shows a dialog that asks to continue deployment after files have been built. This option makes it possible to prepare/simulate a build without actually deploying the changes. 6. If others have pushed changes since the last synchronization, an error displays, and you cannot push changes. In that case, merge the server repository changes into the local repository before you try again to push changes. See Working with the Git Version Control System, which describes collaboration scenarios. 7. The first time that you execute the push action, you might be asked to provide a user ID and password (see the following figure). If the repository is not set up to use security, you

Handbook for Using the Maconomy Extender IDE 21

Extending a Maconomy Installation

are prompted for a user name and email address. The user name and email combination is used for annotating the commit in the repository. The user ID and password combination is used to authenticate the user and check whether the user is authorized to push to the repository and deploy to the server. See Authentication and Authorization Support for more information about security settings. 8. By default, the user information is cached in memory for three hours. You can set the timeout hours on the MaconomyExtender preference page. It will never expire if you set it to –1. This step is optional.

Deploying Changes You can deploy changes to a server in the following ways: . You can deploy changes immediately after a commit and push. The Deploy immediately option is available in the Commit and push changes dialog box. . You can deploy a tagged commit later. Right-click a server in the Servers view and select Deploy from the shortcut menu, then select a release tag to deploy. In both cases, the deployment process begins. The Console view displays information about the deployment, as illustrated in the following figure.

Delta Deployment When deploying to a server that has history, a delta deployment is performed by default. A delta deployment only installs/deletes files that have changed since the last install. You can also do a full deployment, where the server is first cleaned of old files, and then files from the repository are installed. You perform a full deployment by deselecting the Only deploy files changed since last deployment option on the Commit and push changes dialog box.

Handbook for Using the Maconomy Extender IDE 22

Extending a Maconomy Installation

When deploying to a server, a full deployment means that all of the files in the repository are deployed by default. This means that the server is cleaned of old files and the files from the repository are installed. Delta deployment of Classic files is also supported. If only one report, universe, or mol file has been changed, all files from the respective folder are deployed.

Server Cleanup The deployment mechanism cleans up a server before it deploys files to it. For a delta deployment, only files that were deleted from the repository since the last deployment are deleted. A full deployment deletes all of the files and folders for the workspace client. If you use Maconomy Classic, the Reports, Universes, DialogExtensions, and EntityExtensions directories under the Customization/Custom folder are also deleted before deployment. Furthermore, deployment deletes files for Maconomy Classic that have been deleted from the repository. If MBuilder fails in building a file, the deleted files in the Custom directories are restored. See Development Workflow and Git for more information about the use of branches, the development workflow, and how to deploy changes to different servers.

Handbook for Using the Maconomy Extender IDE 23

Development Workflow and Git

This section describes how to work with the Git Version Control System and how to use the default development workflow featured by Maconomy Extender. The information in this section shows how Maconomy Extender makes it easy to develop, test, and deploy extensions, and how several people can develop, test, and share features simultaneously without hindering each other’s progress. The Deployment Diagram view, in graphical fashion, visualizes all of the branches and servers and the available actions in a given context. This diagram makes it easy to follow the development workflow.

Introduction to Git Maconomy Extender uses Git as a version control system (VCS). Git is a decentralized VCS that provides you with a local repository with a complete history of all changes. You can make and commit changes locally and then synchronize with a remote, shared repository that other developers also synchronize with. Maconomy Extender comes with a standard tool for Git called EGit (for Eclipse Git). The Help system contains comprehensive documentation on how to use EGit.

People who are familiar with a different version control system or Subversion might initially find it difficult to use Git, which does not operate with file differences in the same way that other version control systems do. Extensive documentation is available under Help content in Maconomy Extender. You can also find a good introduction to Git in the book Pro Git, which is available online at http://progit.org/book/. If you are new to Git, focus on the first two chapters, “Getting Started” and “Git Basics.”

Git works differently from traditional VCS like CVS and Subversion. It does not work with a list of file-based changes like many of these systems do. Instead, Git stores data like snapshots of a mini file system. When you commit changes to a set of files in Git, it takes a snapshot of the state of all files and stores a reference to it. This approach makes Git very powerful, and the use of branches becomes more cost-efficient. When using Git, it is common practice to use branches extensively. You can think of a branch as a local copy of all files, where you can make changes and commit and share the changes without changing the original files. Other developers can work on changing files simultaneously in other branches. When changes are committed in a branch, the changes from the branch can be merged into another branch. This enables the merging of the changes made by several people. See Work process and Server setup for more information on how to use branches in Maconomy Extender.

If you are new to Git and you need detailed information about the tool, it is highly recommended to read the "Git Basics" section in the online book "Git Pro" at http://git- scm.com/book/en/Getting-Started-Git-Basics. If you have not worked with branches before, read the chapter "Git branching" at http://git-scm.com/book/en/Git-Branching-What-a-Branch-Is and “Basic Branching and Merging” at http://progit.org/book/ch3-2.html. These chapters provide a good introduction to how branching works.

Handbook for Using the Maconomy Extender IDE 24

Development Workflow and Git

Work Process and Server Setup It is advisable to use the workflow described in this section when developing extensions with Maconomy Extender. The workflow is based on recognized best practices in working with VCS, in general, and with Git, in particular. The workflow is described in details in this article: http://nvie.com/posts/a-successful-git-branching-model/. Maconomy Extender comes with features that use this workflow. They are invoked from the toolbar in the Maconomy Extender perspective and from the Deployment Diagram view.

When you initiate a server repository for a new customer, it is set up with two main branches: development and master. The development branch is used for continued development, while the master branch always contains a production-ready commit. The following figure illustrates the best practice workflow for working with branches. See the link provided above for details.

Handbook for Using the Maconomy Extender IDE 25

Development Workflow and Git

You create feature branches from the development branch to develop specific features, then you create a release branch when you start to prepare a release. When you have developed, tested, and locally committed a feature, you can switch to the development branch and merge the feature branch into it. While developing in the feature branch, you can also push your changes to the server repository so that others can access the changes in the branch. Using feature branches for each feature makes it easier to collaborate and merge changes together in the development branch when several people are working at the same time. Maconomy Extender also introduces the concept of theme branches. A theme branch is similar to a feature branch, except that you can create theme-feature branches created from a theme branch. Theme branches are typically used for larger features where you have to avoid merging back into the development branch before all theme features have been completed. When a release date is approaching, you can create a release branch from the development branch. The release branch is used only for smaller bug fixes while preparing the release. By

Handbook for Using the Maconomy Extender IDE 26

Development Workflow and Git having a specific release branch, you do not need to lock the development branch while you are finalizing the release. The development branch can continuously be used for development for the next release. When the code in the release branch has been tested by end users, you switch to the master branch and merge it with the release branch. Then you tag the head of the master branch with a release tag in the form v...

Server Setup and Relation to Branches By default, the repository is set up with a stack of four Maconomy servers called Development, Release Test, Pre Live, and Live. Each server is configured to allow deployment from specific branches and has a number of other properties. The servers are listed in the Servers view, where you can change their properties. After setting up a new server repository, you must configure how the servers are accessed. For more information, see Working with Servers. The four default servers use the branches described above in the following ways: • The Development server is used to test changes from the development branch and from theme and feature branches. Developers are the target for the test. Only the head of the development or a feature branch can be deployed to this server. This server does not keep a history of installed revisions. • The Release Test server is used for testing changes from release branches and from hotfix branches. This server keeps a history of installed revisions. The head of a release branch can be installed on this server. End users should be involved in the testing. • The Pre Live server is used to verify that everything is as expected before installing on the Live server. Only a release tag created on the master branch can be installed on this server. It keeps a history of previously installed tags. • The Live server is the production server. A revision cannot be deployed directly to this server. Instead, it must be promoted from the Pre Live server. • All branches can be deployed to sandbox servers. Each customer might have other server setups, and the server stack can easily be changed. For more information, see Working with Servers. Maconomy Extender provides other features on top of the general Git user interface in Eclipse. This includes features that are available from the toolbar and from the Deployment Diagram view that make it easy to use the suggested workflow. If you have a good reason to deviate from the workflow or use a completely different workflow, it is still possible by using the standard functionality in EGit. Maconomy Extender automatically switches to the development branch when you create a project. It is advisable that you start in the development branch.

Deployment Diagram The Deployment Diagram view shows the relationships among all branches, servers, and actions that are available for a given context. In the following figure, the development branch is checked out. It is possible to create branches to commit and push, to merge the feature-CRM branches that have not yet been merged, and to deploy to the Development server.

Handbook for Using the Maconomy Extender IDE 27

Development Workflow and Git

Has Remote Commits ahead Branch

Remote Branch

The Deployment Diagram view is interactive, and you can handle most of the development workflow directly from that diagram. For instance, you switch branches by clicking a branch. You create feature and release branches from the development branch and hotfix branches from the master branch. You can see which branches have not yet been merged into the current branch, and you can merge them directly. You can create release tags from the master branch, and you can deploy to the allowed servers directly from the branch that you are in. The Fast Deploy option in the development branch is a convenient and quick way to get changes that have been made in the development branch into production. This action automatically creates a release branch, merges it into the master branch, creates a release tag, and deploys it to the server. This feature is mainly for non-technical users. The icon shows that the branch is also in the server repository, while the number to the right shows how by many commits the branch is ahead of/behind the remote branch. A remote branch that does not exist locally is dark gray. To create the local branch, click the remote branch. You can delete local and remote branches from the diagram. Be careful when you delete remote branches, because doing so affects the work of other people. You can set visualization options for the diagram from the View menu. For instance, you can hide remote branches, as well as inactive deploy and merge connections.

Rules Imposed by Maconomy Extender Maconomy Extender imposes a number of rules concerning the actions that are available from the toolbar and the Deployment Diagram. When a project becomes active (right-click the project and select Maconomy » Set as active), it fetches changes from the server repository to determine whether the branches are in sync. A fetch is also performed when creating or merging branches to warn the user against merging local branches that are behind the server repository. If a branch is behind the remote branch, it should be merged with the remote branch before being merged with other branches.

Handbook for Using the Maconomy Extender IDE 28

Development Workflow and Git

You can create theme, feature, and release branches only from the development branch. These are automatically prefixed with theme-, feature-, and release-. Only hotfix branches can be created from the master branch, and they are prefixed with hotfix-. You can merge theme and feature branches into the development branch; you can merge release branches into the development and master branches; and you can merge hotfix branches into the development, master, and release branches. Each server is set up to allow deployment and has a list of branch prefixes for branches that are allowed to deploy to the server. These rules are implemented in the deployment actions, so only the servers that are allowed to deploy from the current branch are available in the Deploy dialog box and as deploy connections in the Deployment Diagram.

Workflow Examples

Using Feature Branches and Testing Changes Scenario: Lars is a developer who is assigned to a customer project. He is developing extensions for a CRM feature. Lars creates a Maconomy Extender project based on the customer’s server repository and is automatically switched to the development branch. Because CRM feature development has not yet been started, he creates a CRM branch by clicking Create Branch and entering CRM as the name. The branch is automatically named feature-CRM, and the project is automatically switched to this new branch. Lars creates and modifies the necessary files and commits the changes locally several times. When Lars wants to share the branch with others or have the changes backed up, he pushes the changes to the server repository by clicking . Lars tests the changes locally on the available sandbox server. When the changes are ready to be tested on the customer’s development server, Lars switches to the development branch by clicking Switch branch on the toolbar or clicking the branch in the diagram. Then he clicks Merge branch and selects the CRM branch (as an alternative, Lars can also click Merge connection in the diagram). A result dialog box lists the changed files. Merge conflicts—such as files that have also been changed by others, and which the merge mechanism could not figure out how to merge—are annotated with a red double-arrow icon. Lars manually opens these files and resolves the merge conflicts. Lars uses a powerful merge tool for figuring out changes by right-clicking the project and selecting Team » Merge tool from the context menu. If the feature branch is in the remote repository, and Lars’s local branch is behind it, Lars gets a message advising him to merge the feature branch with the remote before merging it into the development branch. If the development branch is behind, he gets a warning and is asked if he wants to continue. After the merge, Lars clicks , clicks Deploy immediately, and selects the Development server (as an alternative, he can also click the Deploy connection in the diagram). This action involves a push of the changes to the server repository. If other developers have pushed changes since the last time that Lars merged the development branch from the server repository, he must merge the local development branch with the remote development branch. If Lars does not push the CRM branch to the server repository, it will only exist in his local repository. Because the changes have been merged into the development branch, Lars can now delete the CRM branch (if it is no longer needed). Martin, another developer working on the project, has created a feature branch for Notifications. Martin merges his branch into the development branch similarly to the way that Lars did and pushes the development branch to the server. Martin is required to merge his local development branch with the changes that Lars pushed from the CRM branch. For files that were not changed by Lars or by Martin, the merge is trivial. The changed files (including the files that Lars changed),

Handbook for Using the Maconomy Extender IDE 29

Development Workflow and Git on the other hand, are now available in Martin’s development branch, which he can then commit and push to the server repository.

Releasing Changes and Testing by End Users Scenario: Lars releases the CRM and Notification features to the Live system, while Martin continues to develop on the Notification branch for the next release. Martin is also developing a new feature for time management. Lars creates a release branch from the development branch by clicking Create branch. The release branch is named as the upcoming release version (v1.1). The newly created branch is automatically named release-v1.1. Lars deploys the release branch to the Release Test server and asks end users to verify the CRM and Notification features. Smaller bug fixes are made and committed in the release branch. New requests are postponed for the next release. If bug fixes are made in the release branch, they can be merged back into the development branch by switching to the development branch and clicking Merge branch.

Deploying to the Live Server Scenario: After end users have verified and accepted the installation on the Release Test server, Lars deploys to the Live server. First, Lars switches to the master branch by clicking Switch branch on the toolbar or by clicking the branch in the diagram. He clicks Merge branch and selects the release branch (as an alternative, he can also click the Merge connection in the diagram). The changes from the release branch are merged into the master branch. Conflicts are resolved and committed. Lars then clicks Create release tag from the diagram or toolbar to create a version tag on the master branch. He enters the same version number that was used to name the release branch (v1.1). The release tag and the commits in the master branch are automatically pushed to the server repository. Lars installs the tagged version on the Pre Live server by right-clicking the server in the Servers view and selecting the newly created version tag (as an alternative, he can also click the Deploy Tag connection in the diagram). After verifying that the installation on the Pre Live server functions as expected, Lars promotes the changes to the Live server by right-clicking the Pre Live server and selecting Promote (as an alternative, he can also click the Promote connection in the diagram).

Creating a Hotfix to a Production Release Scenario: Martin creates a hotfix to address bugs found in v1.0, which is currently on the Live server. Martin switches to the master branch that is currently pointed at the commit that is tagged as v1.0. Martin clicks Create branch to create a hotfix branch. He enters v1.0.1 as the name, and the branch is automatically named hotfix-v1.0.1. The hotfix is ready to be implemented and tested on the Release Test server. Martin switches back to the master branch and merges the hotfix branch into it. He creates a release tag named v1.0.1, deploys it to the Pre Live server, and then promotes it to the Live server. The hotfix branch should also be merged into the development branch so that it will be available during development for future releases. This step is optional, but it is a good practice to follow. If the hotfix branch is not merged into the development branch, and release branches are not yet merged into the master branch, you will be testing releases without the hotfix branch. This might result in bugs during production. In the case of a hotfix for a released version that is not the head of the master branch, you must create the hotfix branch from the tagged version. You cannot use the Maconomy Extender’s

Handbook for Using the Maconomy Extender IDE 30

Development Workflow and Git

Create branch feature to do this. You must use the standard Git functionality from the Git Repositories view. Right-click the tag and create the hotfix branch. Then, manually set the name, including the release- prefix. You must also use the standard Git functionality to merge the hotfix branch with the tagged version, and then tag this new commit with a new version number.

A Business Developer Makes and Deploys a Simple Change Scenario: Anders, a business developer, makes simple changes to a layout. The customer installation is live, and no other consultants are working on extensions. Anders starts Maconomy Extender and creates a project from the GitHub repository. Alternatively he activates the project in Maconomy Extender if it already exists. Anders makes the necessary changes to the layout file. He then tests the layout file on the Development server. From the Deployment Diagram, Anders clicks Fast Deploy to deploy to the Pre Live server. He clicks Yes when asked if he wants to continue. Anders enters a commit message describing the change and enters a version number for the change. The dialog box for creating a release tag suggests a version number based on the highest available number (for example, if the highest release number is v0.5, the system suggests v0.5.1). After Anders clicks OK, Maconomy Extender automatically creates a release branch, merges it into the master branch, creates a release tag, pushes the tag to the server repository, and deploys the release tag to the Pre Live server. After validating the changes on the Pre-Live server, Anders deploys them to the Live server by clicking the Promote connection. The following figure shows a Deployment Diagram after the user has clicked Fast Deploy. A release branch and a release tag were automatically created.

Handbook for Using the Maconomy Extender IDE 31

Maconomy Classic Support

You can create, edit, and deploy Maconomy Classic files, such as universes, reports, dialog extensions, entity extensions, portal changes, and so on, if you have file access to the Maconomy server as well as the web servers. You must also have the MBuilder application installed. There is no longer any need for MStamper or license files because these are built into the extender. This means that the Extender can stamp all file types for all customers and for all namespaces.

Creating Maconomy Classic Folders

To create Maconomy Classic source folders, complete the following steps: 1. Right-click a Maconomy Extender project and select Maconomy » Create Maconomy Classic folders from the shortcut menu. Folders are created. 2. Delete the folders that you do not need. 3. Add files to the folders.

Specifying Customer Numbers and Building and Stamping Options Before you deploy changes to a server, you must specify a customer number and build and stamp options. You can define this on a server, or you can define it in the project properties. If you define the properties on the server, they are automatically shared in the server repository, and you do not need to set anything up. For more information on setting up server properties, see Working with Servers. If you do not define the properties on the server, you must set it up using the project properties. These options are local for the project on your machine.

To specify a customer number and build and stamp options on the project, complete the following steps: 1. Right-click a Maconomy Extender project and select Properties from the shortcut menu. 2. On the Properties dialog box, click MaconomyExtender » Maconomy Classic. 3. Click Restore Defaults to set default stamper options. 4. In the Customer Number field, enter the customer number. 5. Set stamper options. If you are developing for a specific namespace, then you have to set the option --TAC Namespace . If you do not set the namespace, you will get an error saying “The namespace wildcard (*) is only valid in Maconomy HQ license files.”

Handbook for Using the Maconomy Extender IDE 32

Maconomy Classic Support

6. Optionally select the folder where MBuilder is located. By default, the programs are executed without a file path. The following figure shows Maconomy Classic properties on the project.

The following figure shows Maconomy Classic Properties on a server.

If you have files that are deployed to a Web server, you need a Web server that is defined under a server in the Servers view. Select the server in the Servers view and select Add web server. When the server is set up with build and stamp properties, and it has one or more Web servers, you can deploy files to a server from the button or from the Deploy Diagram. The deployment mechanism automatically builds, stamps, and installs the Maconomy Classic files on the Maconomy server and on the Web server(s). You can see the result of the deployment process in the Console view.

Handbook for Using the Maconomy Extender IDE 33

Maconomy Classic Support

Need a Special License File? Maconomy Extender comes with a built-in license file, and it should no longer be necessary to use personal license files. However, if special circumstances should occur, for example, when developing industrial accelerators in Deltek Engineering, a special license file might be required. To use a special license file, edit the MaconomyExtender.ini file by adding the following line:

-Dlicensefile= Then restart the Extender, and it will use the license file specified in the line that you added.

Deploying Reports If you are deploying reports and do not have a local Maconomy installation, the MBuilder will fail. This is an MBuilder issue that can be circumvented by adding key-values to the Windows Registry.

Handbook for Using the Maconomy Extender IDE 34

Working with Servers

Each Maconomy customer has a specific setup of Maconomy servers and rules for how to deploy and promote changes between servers. Maconomy Extender supports setting up several servers and rules in the server repository. Maconomy Extender has a Servers view, in which available servers are listed along with the actual installed commit or release tag. When a server repository is created, it is initially set up with four servers as previously described and as listed in the following table. You can delete, edit, and add servers from the view. The following figure illustrates the Servers view for a project with the four servers. This is the recommended setup.

You can add, edit, and delete servers from the view menu in the top right corner, and you can also view or edit a server definition by double-clicking on the server. A Server represents a Maconomy server, and it can have Coupling services and sub servers as children. These are used at deployment time when customizations have been made to Extension Framework extensions or to the portal.

Server Description

Development The Development server is used to test changes from the development branch and from feature branches. Developers are the target audience for the testing. Only the head of the development or a feature branch can be deployed to this server. This server does not keep a history of installed revisions.

Release Test The Release Test server is used for testing changes from release branches and from hotfix branches. This server keeps a history of installed revisions. The head of a release branch can be installed on this server. End users should be involved in the testing.

Pre Live The Pre Live server is used to verify that everything works as expected before installing on the Live server. Only a release tag created on the master branch can be installed on this server. It keeps a history of previously installed tags.

Live The Live server is the production server. A revision cannot be deployed directly to this server. It must be promoted from the Pre Live server. Only a release tag created on the master branch can be installed on this server. It keeps a history of previously installed tags.

Handbook for Using the Maconomy Extender IDE 35

Working with Servers

Deploying to a Server You can deploy files from a branch to a Maconomy server if there is file or SSH access to the Maconomy server installation and the coupling service and web servers. If the server is not accessible, the deployment builds an SPU/zip file that you must manually copy to the server. The SPU file cannot (yet) be installed by MConfig. Instead it must be manually installed. The deployment mechanism handles all details about the stamping, building, and installing customizations. As a developer you can concentrate on the business logic and let the tool handle the technical details about deployment. You cannot install directly on the Maconomy server from the local repository without pushing the changes to the server repository. This is to ensure that changes are shared before they are deployed. You can handle deployment to a server in the following ways: • From the Deployment Diagram, click the Deploy connection from the current branch to the server. • From the toolbar, click and select the server to deploy to. • Click the Deploy tag connection to deploy a release tag to a server. • Right-click a server in the Servers view and select Deploy. This allows you to deploy a release tag to the server, or the head of the current branch. • Right-click a row in the installation history view to install an earlier release to the server.

Promoting to a Server Not all servers allow direct deployment from the repository. For instance, the Live server, by default, must have extensions promoted from the Pre Live server. You can perform a promotion to a server from the Deployment Diagram by clicking the Promote connection, or from the Servers view.

To promote to a server from the Servers view, complete the following steps: 1. Right-click the Pre Live server and select Promote. The Promote dialog box (see the following figure) displays. It lists the servers to which you can promote changes. See Changing the Server Configuration for more information.

2. Click OK. The release tag installed on the Pre Live server is now installed on the Live server.

Handbook for Using the Maconomy Extender IDE 36

Working with Servers

Forced Deploy (Deploy to Server) In emergency cases, it might be necessary to skip the promote steps and deploy directly to a server. If this happens, you can use a forced deploy.

To use force deploy, complete the following steps: 1. Right-click the Live server and select Deploy to server from the shortcut menu. 2. In the Reason field on the Force deploy dialog box (see the following figure), enter a reason. If security is used, you can only implement a forced deploy if you have the ForceDeploy role.

Viewing Installation History The Installation History view (see the following figure) shows the history of installations for a specific server selected in the Servers view. To swap between server histories, click View or select another server.

For each installation, the history contains information on when it was installed, what revision tag and revision were installed, who was responsible, and what type of installation (deploy, fast track deploy, promote, or forced deploy) was performed. For a forced deploy, the reason is also listed. You can right-click a row and choose to deploy this revision to the server.

Changing the Server Configuration You can modify servers shown in the Servers view, and you can add more servers. If security is used for the repository, you must have the ChangeConfiguration role.

When you change servers the changes are automatically pushed to the server repository, and other team members also get the changes.

Handbook for Using the Maconomy Extender IDE 37

Working with Servers

To change the server configuration, complete the following steps: 1. Select one of the following actions from the View menu: . To modify an existing server, select it and then select Edit. . To delete an existing server, select it and then select Delete. . To add a server, select Add. If you select Edit or Add, the Add/Edit dialog box is displayed. 2. Select the Allow deploy option if the server allows direct deployment. This step is optional. 3. Specify whether the server should keep the installation history and whether it requires a release tag to be installed. 4. Select the branch prefixes that are allowed to deploy to the server. You can only use branch prefixes when the server does not require a release tag. 5. Use Promote from servers to specify which servers can promote to this server. The servers to promote from must have the same release tag setting and must have history. 6. Set up how to access the server. For file access, enter a UNC path. If there is no UNC path, you can enter a path to a network drive. This requires users to map the server to a mapped network drive on their machines when they work with the server. 7. On the Maconomy Classic tab, set the customer number, builder options, and stamper options used by MBuilder and MStamper. If a customer number is set on this tab, all values from the tab are used when deploying Maconomy Classic files to the server. Options set for the active project as described in Maconomy Classic Support are ignored. 8. Click OK. A message notifies you that the changes have been pushed to the server repository so that other team members can access the changes. These are automatically updated when you restart Maconomy Extender, or when you promote changes.

Handbook for Using the Maconomy Extender IDE 38

Working with Servers

You can also add a sandbox server from this view, and you can add web servers and coupling services to a Maconomy server. This is necessary when you perform Maconomy Classic development or use the Extensibility framework.

Handbook for Using the Maconomy Extender IDE 39

Using the Editors

The Maconomy Extender comes with a specialized editor, the “Maconomy XML Editor,” which provides a textual as well as a graphical interface for viewing and changing files. You can use this editor to open files of the types MMSL, MWSL, MDML, MCSL, and MDSL. The editor contains schemas for the file types, as well as syntax highlights and content assist tools. For MMSL, MWSL, and MDML, it also provides a Preview tab, which previews how the specification file will be rendered in the Workspace Client. For MDML, and partly MWSL, the Preview also allows you to make changes. By default, the editor opens on the Preview tab. You can change this to the Source tab in the Preferences under Maconomy Extender » Default tab in Maconomy XML Editor. You are only allowed to use the Source tab if you have one of the Extensibility or ShowSource roles. If the background of the editor is yellow, it means that the file comes from one of the standard layers. You can copy it to the custom layer by right-clicking when the Source tab is used and by clicking the top-right “Copy” icon in the Preview tab.

Working with the Source

Press + to display suggestions for allowed content.

The XML editor also provides content assist and tooltips for values of attributes that reference other files (see the following figure). For example, the editor has content assist for the value of the source attribute in a workspace element in an MMSL file. This attribute points to an MWSL file from the standard layer. When you press F3, the file referenced by the attribute opens. If you press F3 when the cursor is on the source attribute value shown in the following figure, the ContactCompanies MWSL file opens as read-only. If the file exists in the custom layer, the file opens from that layer as an editable file. The following figure shows a tooltip in the XML editor. The value of the source attribute points to an MWSL file from the standard layer.

The following figure shows content assist for the source attribute pointing to an MWSL file.

Handbook for Using the Maconomy Extender IDE 40

Using the Editors

Some elements have attributes that are implicitly defined by other attributes, which can be in the same element, from a parent element, or from an attribute in another file. You can see the values of such attributes by moving the cursor over the element. The following figure illustrates the hover information for a Card element in an MWSL file. Maconomy Extender has collected information from the implicit attributes and presents the values and their origins. For example, it shows that the value of the view attribute is Full, and that it is the first Form element in the MDML file called joboverview.

You can also open a file that an implicit attribute points to. Press F3 on the element, and the dialog box in the preceding figure is displayed. If you select the attribute, the file it points to opens. The following figure shows the open MDML file with the Form named Full selected. The view attribute points to this form.

Handbook for Using the Maconomy Extender IDE 41

Using the Editors

The following figure shows a file opened from the View Attribute on a Card in an MWSL file. The referred line is automatically selected in the file.

Working with the MMSL Preview The MMSL editor contains a Preview tab, where the menu can be simulated as if it were shown in the Workspace Client. The left column allows you to simulate the context in which the menu is shown. This includes user roles, environment variables, and variables that the menu uses. In the middle, the simulated structure of the menu is shown, and in the right column, the menu is simulated as it would be rendered in the client. You can navigate to the source code by clicking a menu item in the middle or right column and selecting the Source tab. You can open the corresponding workspace file by double-clicking on a menu item. The Preview does not yet support editing the menu.

Working with the MWSL Preview The MWSL editor contains a Preview tab, illustrated in the following figure, that renders the structure of the workspace as it will be rendered by the client. It also shows content from sub- workspaces. Content from a sub-workspace is colored blue. The editor provides two-way navigation between Preview and Source. Double-click in the preview, and it switches to the Source tab and selects the correct line of code. Double-click on a tab, and it also navigates to the source code. Switch back to the Preview tab, and the graphical element is surrounded by a thick line. For sub-workspaces, double-clicking on an element opens that workspace file in a separate editor.

Handbook for Using the Maconomy Extender IDE 42

Using the Editors

Panes that refer to Table, Filter, and Form elements in an MDML file have two or three buttons: . Open MDML View — Opens the related MDML file in a separate editor and selects the related view. . Load MDML View — Loads the related view from the MDML file and renders it inside the MWSL preview. . Customize MDML View — This button is only shown if the related MDML view is defined in the standard layer. When you click this button, the view from the standard MDML file is copied to a custom file under the custom namespace, and the workspace file is copied to the custom layer and changed to relate to the custom MDML file. This is a best practice for extending MDML views instead of copying the complete MDML file to the custom layer.

The following figure shows the MWSL editor previewing the JobBudgetting Workspace from the Custom Layer. The editor opens when the Card panel in the Jobs workspace is clicked. By default, hidden panels and sub-workspaces are shown as tabs. In the Workspace Client, these are hidden. There is a toggle button in the upper-right corner of the editor where the “Show hidden” option can be turned on and off.

Using the Preview for Making Changes You can use the MWSL Preview window to make changes to the workspace. The following tools are available for you:

. Delete — Click the icon to delete a selected tab.

. Edit — Click the icon to change the properties of a selected tab. . Add — Click the icon to add additional tabs before or after a selected tab. . Move — Click the to move panels to the left or right.

Handbook for Using the Maconomy Extender IDE 43

Using the Editors

Structures like Assistants, Expansions, and Formation can be inserted into/under an existing panel or section by using the “+” icon.

Handbook for Using the Maconomy Extender IDE 44

Using the Editors

Changing or adding structure to a workspace can be complicated and requires prior knowledge about the Maconomy data model. Panels in a workspace represent data that is connected hierarchically through bindings. When you add a panel to the workspace, you are asked which binding type to use. The following illustrates the wizard page for selecting a binding type. When inserting a Card, Hidden card, or Table under another Panel, you can choose among Mount, With, and Bind bindings. When you insert a Filter, you must use a Restrict binding, and when you insert a sub-workspace, you can choose any of these bindings. See the MWSL reference manual for more information on binding types.

Handbook for Using the Maconomy Extender IDE 45

Using the Editors

After you select a binding type, use the following wizard page for choosing which panel to insert and how to render it.

The Source attribute selects the dialog to use. The Layout attribute points to the MDML/Layout file to use, and the View attribute selects the view in which the dialog data should be presented. The wizard page automatically restricts the values you can choose to only valid values. Use the “Simple” button to show most commonly used attributes, while “Advanced” shows additional ones. Also, in Simple mode, the wizard cannot finish if there are errors, for example, if you chose a nonexistent layout. In Advanced mode, the error is shown, but you can finish. You can only use the Advanced button if you have one of the Extensibility or ShowSource roles.

Working with the MDML Preview The MDML editor contains a Preview tab that renders a Filter, Form, or Table as it will be rendered by the client. It also shows content from MDML fragments, as well as from the globaldefinitions MDML file. Content from fragments and globaldefinitions is colored blue. The editor provides two-way navigation between Preview and Source. Double-click in the preview, and it switches to the Source tab and selects the correct line of code. Double-click on a Condition tab, and it also navigates to the source code. Switch back to the Preview tab, and the graphical element is surrounded by a thick dashed line. You navigate to fragments and globaldefinitions by double-clicking a field in the blue area. You can select the Filter, Table, or Form to be rendered from the Preview menu in the upper-left corner. The following figure shows the MDML preview of the standard form from the Joboverview MDML file.

Handbook for Using the Maconomy Extender IDE 46

Using the Editors

The following figure shows the menu for selecting which form, filter, or table to render.

Using the Preview for Making Changes You can use the MDML Previewer to make most customizations to MDML Filters, Tables, and Forms. There is an edit button next to editable elements in the previewer. Depending on the type of field, different actions are available, including Delete, Modify, Add before, Add after, Cut for move, and Add Element into.

Handbook for Using the Maconomy Extender IDE 47

Using the Editors

When you select Add Before/After/Into, you can only select allowed field types. Select a field type and fill in the data. Refer to the MDML reference manual for information about the different field types. A Modify page is shown where you can enter all relevant data for the selected field type. The following figure shows an Add/Modify page for a reference field. The left side shows all available attributes (Advanced button), while the right side shows only the simple attributes (Simple button).

The Field page contains code completion and drop-downs for attributes relating to styles, to MDSL dialog fields, to workspace files, and to layout files.

Handbook for Using the Maconomy Extender IDE 48

Authentication and Authorization Support

When you initiate the server repository, you can set it up without security or set it up with simple security. Simple security uses a simple user database in the server repository and provides a User Authorizations view that lists users.

To display the User Authorizations view, complete the following steps: 1. Click Window » Show view » Other » Maconomy Extender » User Authorizations. On the User Authorizations view (see the following figure) you can add, modify, or delete users. You must have the ChangeConfiguration role to modify the users. By default, one admin user with the password password is created and has the ChangeConfiguration access role. Use the admin user role when you change the configuration, for changing servers or changing users to assume other roles to work with extensions, deploy to servers, or promote to servers.

You can change the Authentication type of the repository from the Servers view. Select Change Authentication Type from the view menu and choose simple or no authorization. You must have the ChangeConfiguration role to do this. You can switch user easily from the User view by right-clicking on a user and choosing Switch user.

Access Roles A user must have the correct access rights to push changes to the server repository, deploy changes to a server, promote from one server to another, and make forced deployments. A user must have the Extensibility role to create Extension Framework bundles and to push such changes to the repository, and a user must either have the Extensibility or ShowSource role to see source code. You must log in as administrator to add or manage users or user roles. To edit a user or switch between users, right-click on a user name and select “Switch user” or “Edit user,” depending on what action you want to perform. When creating or editing a user, you can choose specific roles and to which servers that user should have deploy/promote rights.

Handbook for Using the Maconomy Extender IDE 49

Authentication and Authorization Support

Login Dialog The following login dialog shows all available user IDs for the project. Select your user ID and enter your password. You can choose that the password is remembered. If you opt to have your password remembered, you will not be prompted for your password when the project becomes active or when you start the Extender. You can also choose to log in silently. This means that you will not be prompted when switching user or setting the project to active.

Handbook for Using the Maconomy Extender IDE 50

Extension Framework Development

This section describes how to use Maconomy Extender for developing and deploying Extension Framework bundles. Information about the Extension Framework itself is found in a separate document.

Prerequisite Developing Extension Framework bundles requires that the repository has been set up with authorization, and that the user has the Extensibility role. Users without the Extensibility role cannot commit changes to bundles, and they do not see the bundles in the workspace, even though they exist in the repository and the file system. However, they can deploy bundles to a server. A 64-bit version of Maconomy Extender with 64-bit Java 1.7 SDK installed is required for developing Extension Framework bundles. A JRE is not sufficient. After installing a JDK, follow these steps: . Choose Preferences » Java » Installed JREs and click Add to add the JDK. . Remember to select the JDK after adding it. . Select the Execution Environments item below the Installed JREs. Then select the Java SE-1.7 execution environment and select the newly added JDK. . If you already are working on a project, you must set the target platform again. See “Setting the Target Platform” for details.

Creating a Bundle You can create an Extension Framework bundle from File » New » Extension Framework bundle. Select Connect to active project to add the bundle to the active project and to share it in the same repository. Select Create Example to create a hello world example, extend an existing container, or create another root container. You can also perform this step later.

If you choose Extend Container, you can choose the container to extend and other options in the next wizard pages. See “Extending a Container” for details.

Handbook for Using the Maconomy Extender IDE 51

Extension Framework Development

Extending a Container You can extend an existing container, either when creating a bundle, or by choosing File » New » Other » Maconomy » Extend Container.

Fill in the fields and click Finish. You have extended the container, and it is ready to modify the generated template code. The container to extend the field should include the namespace for the container, such as helloworld:HelloWorld. The Maconomy namespace is implicit for standard Maconomy containers. In the preceding figure, you could specify Maconomy:accesslevels.

Creating a Root Container If you choose to create a root container, you must first choose a container name including a namespace. Also choose a package name and the name of the container class. You can choose to use localization of terms. Then the generated code will use the Terms API. Be aware that this only works for Maconomy version 16sp2 and 15 sp7 and above.

Handbook for Using the Maconomy Extender IDE 52

Extension Framework Development

The next three pages contain information about the Filter, Card, and Table panes. For each pane that is to be implemented, a MOL file can be used to generate initial code. This is recommended, and is the easiest approach to get started.

Handbook for Using the Maconomy Extender IDE 53

Extension Framework Development

Setting the Target Platform The target platform is used for compiling Extension Framework bundles. If the target platform is not set or is wrong, the bundles cannot compile, and there will be errors in the source code. You can set the target platform in two ways: You can set it as a file path in the active project properties, and you can set it from a coupling service in the Servers view. Maconomy Extender automatically asks to set the target platform when a project becomes active—if the project has Extension Framework bundles. Set the target platform by doing one of the following . Right-click on a Coupling Service in the Servers view and choose Set as target platform. This sets the target platform path at the project properties and changes the target platform in the Extender. . Right-click the active project, then select Properties » MaconomyExtender » Extension Framework » Target platform. Change the path to point to a coupling service and click OK. . Right-click on a Coupling Service and choose Download and use Coupling Service locally. This downloads a copy of the Coupling service and sets the target platform to this.

Handbook for Using the Maconomy Extender IDE 54

Extension Framework Development

Whitelist Only certain Maconomy APIs can be used. If illegal APIs are used, compile errors are shown. There is a whitelist that contains allowed Maconomy APIs. You can see the APIs by right-clicking the active project then select Properties » MaconomyExtender » Extension Framework.

Download a Coupling Service If the coupling service is accessed through SSH, or if the network connection is slow, it can be a good idea to have a local coupling service and use it as target platform. You can set this up by right-clicking on the coupling service in the Servers view and choosing Download and use Coupling Service locally. You can also set this up manually by copying a coupling service of the correct version to the local machine and setting up the target platform path in the active project properties.

It might not be possible to download the coupling service if it is running. If the download causes problems, try to stop the coupling service on the server and download it again.

Starting the Coupling Service for Testing You can test and debug Extension Framework bundles locally without installing them on the coupling service. To test bundles in the workspace, do the following:

To test bundles in the workspace, complete the following steps: 1. Ensure that the target platform has been set and that there are no compile errors. 2. If the coupling service has been downloaded from a server, open the server.ini property file under the configuration folder and set the server.address property to the IP address of the Maconomy server. Most often the coupling service is installed on the Maconomy server, and the value is localhost. 3. Start the coupling service locally from the Servers view. Click the Run or Debug button in the view toolbar. It starts the coupling service locally. 4. Start the workspace client, choose localhost as the server address, and use the same port number as defined in the web.home property in the server.ini file. If the coupling service is 64-bit, you must use a 64-bit JDK; if it is 32-bit, you must use a 32-bit JDK. If the coupling service was started in Debug mode, you can set breakpoints in the Java code. When the Workspace Client accesses a dialog that has extensions, the Debug tool in the Maconomy Extender is automatically started, and you can execute the code step by step. If the coupling service from the Extender fails or changes that you made do not display, other coupling service instances might be running on your machine. To terminate these other instances, open the Task Manager and disable or stop all running coupling services. The Extender will warn you of coupling services already running in the Extender, and automatically terminates the instance before starting a new one.

Deploying Changes Use the normal deployment mechanism in the Extender to deploy bundles. This ensures that bundles are compiled without any errors or warnings and that they are installed into the coupling services registered on the server in the Servers view. A person who does not have the Extensibility role can deploy bundles.

Handbook for Using the Maconomy Extender IDE 55

Extension Framework Development

If you deploy to an inaccessible server, do the following to install the Extension Framework bundles into the coupling service: . Unzip the SPU file that was built by Maconomy Extender and copy the file custom.extensions.zip to the Extensions folder under the Coupling Service installation directory. . Open a command prompt in the Coupling Service installation directory and execute the command: . Windows: CouplingService --install-extensions ./Extensions/custom.extensions.zip . Linux/Unix: ./CouplingService --install-extensions ./Extensions/custom.extensions.zip . Verify that the extensions were installed by executing the command: . CouplingService.exe --list-extensions -console -noexit . Ensure that there is a com.maconomy…group in the console and that the timestamp in the name is similar to the timestamp for building the SPU file. . Close the command window.

Uninstalling Extensions You can uninstall all custom extensions on a coupling service from a command line. Use the following to uninstall custom extensions: • CouplingService --uninstall-extensions -console -noexit • Wait until a confirmation appears on the console. It might take a minute. • Close the console.

Handbook for Using the Maconomy Extender IDE 56

Custom Dictionaries

This section introduces how to update static and dynamic localization texts for the Workspace Client using new or updated dictionaries. Localization is used to translate various terms in the Workspace Client to different languages. This translation requires a new or an updated Dictionary to be present for each language. The Workspace Client does not need to be updated to the existing languages, because it already comes with a set of predefined translations to specific languages. The Maconomy Extender can translate the static texts in the Workspace Client and package them into an update site. This update site can be installed by MConfig to a web server from which the Workspace Client automatically updates itself and installs new translations. It can also install the updated translations on the Maconomy server to update dynamic texts.

Add and Modify Dictionary Files Custom dictionaries are located in the Dictionaries folder in the repository. You can create this folder by right-clicking Maconomy » Create Dictionaries folder.

To add and modify custom dictionaries, complete the following steps: 1. For the translation files that should be modified in the Extender, manually copy them from the Server location .../MaconomyDir/Definitions to the /Dictionaries folder in the MaconomyExtender Project (see the following figure). You can edit the Translation files from the Editor directly in the Extender.

2. After you modify the Translation files, they must be validated and stamped manually at the "Ordbogsportalen" as usual. Go to http://dictionary.maconomy.com/cgi-bin/motv.pl, log in with your user, and validate the files. You must then copy the validated version of the Translation files back into the MaconomyExtender Project under the /Dictionaries folder. This overwrites the existing file in the folder.

Deploying Dictionaries By default, custom dictionaries located in this folder are copied to the MaconomyDir/Definitions folder on the server, and the update site containing static texts is not built. If the portal is used,

Handbook for Using the Maconomy Extender IDE 57

Custom Dictionaries you should also copy the translation files to the portal. See the documentation on the "Ordbogsportalen" for detailed information. If static translations are needed, you must build the Dictionaries update site based on the translation files. To enable building and deploying an update site in the deployment process, create a file deploy.properties in the Dictionaries folder and add a line containing updatesite = true.

To build the Dictionaries update site in the Extender deployment process, complete the following steps: 1. Update the deploy.properties file to contain the line updatesite = true. 2. All dictionaries from the MaconomyDir/Definitions folder on the server are needed when building static texts. Standard files used from the Repository do not include dictionary files. Therefore, if you use standard files where dictionaries are not present, you must manually copy the files from the server to the local folder where you have the standard files before deploying. 3. Set up the path to the Workspace Client that the customer uses in the Properties of the MaconomyExtender Project under MaconomyExtender » Workspace Client (see the following figure):

4. Deploy changes to the server. If you perform a full deployment, or if the Translation files have been modified since the previous deployment and you perform a delta deployment, the deployment process automatically runs the Localization tool to perform translations and build a Localization update site. The update site is built and placed on the Server under the ExtenderDeployFolder/Dictionaries path, and the dictionary files are copied to the MaconomyDir/Definitions folder. If the Server is not available, the Update site and the translation files are packaged into the SPU. 5. You can install the newly created Update site for Static Localizations on a web server using MConfig as usual. See the detailed description of this process in “The MConfig Installation Guide.”

Handbook for Using the Maconomy Extender IDE 58

Working with the Git Version Control System

This section contains additional collaboration scenarios that can arise when working with Git. It also contains tips and tricks for working with Git.

Scenarios

Scenario 1: Another User Has Pushed Changes to the Server Repository before You You added, deleted, or modified files and commits and pushed the changes to the server repository. Another user has already pushed other changes to the server repository. You receive a message saying that you must merge the changes from the server repository with the changes that are committed in your local repository before pushing the merged changes back to the server repository. Assume that you made a change in the B.mdml.xml file. You commit and push the change to the server repository. However, others have made changes since you last pushed or merged your changes. The Unable to push to Server Repository dialog box shown in the following figure is displayed and asks if changes should be fetched and merged from the server repository.

Handbook for Using the Maconomy Extender IDE 59

Working with the Git Version Control System

Click Fetch and Merge. The Fetch and Merge result dialog box (see the following figure) is displayed when the merge process is complete.

In this case, changes were made to the A.mdml.xml file and a new file called D.mdml.xml was added. Changes from the server repository were merged with your local changes. You can now push changes to the server repository.

Commit Graph The commit graph looks like this:

Scenario 2: Files Have already Been Changed by another User You made changes to a file that another user has already changed and pushed to the server repository. This scenario is similar to the previous scenario, except that the merge mechanism will also merge changes that you and the other user made in the same file. Git can merge the contents of files if changes are made to different places in the file. However, if the changes are made to the same lines, the merged file is marked as conflicting, and a conflict annotation icon marks the file in Project Explorer. After the merge, you must examine the merged file as in shown in the following figure, make corrections, and then commit and push the file again. You can use a Git Merge editor to compare files and see the differences between the two commits that were merged. On a project with merge conflicts, select Team » Merge tool. You are asked to compare the auto-merged content in the project or the latest commit before the merge. Normally, it is easiest to compare the latest commit with the commit that you are merging. Then, you can view the conflicting files and make the merge yourself.

Handbook for Using the Maconomy Extender IDE 60

Working with the Git Version Control System

The previous figure shows the Fetch and Merge result dialog box with conflicting files. The following figure shows the Project Explorer view with the conflict annotation icon.

The following figure shows the merged file with changes on the same line. You must remove any Git annotations manually.

Handbook for Using the Maconomy Extender IDE 61

Working with the Git Version Control System

You can use the Merge tool that is part of the EGit tools to compare your original version of the files with the remote files. Right-click a project that contains the conflicting files and select Team » Merge tool. When asked to select a Merge Mode, select Use HEAD of conflicting files.

This compares your latest commit with the commit that was merged into the current branch. The compare editor shown in the following figure shows the differences between the files. You can change the file on the left side and save your changes, then you can commit the merged file to the repository.

Commit Graph The commit graph is similar to the one shown in the previous scenario.

Scenario 3: You Will Work on Two Features but only Deploy one of Them Because Git works with revisions and not individual files, you cannot work on two features simultaneously and then deploy only one of them. For each feature, you must create a feature branch that is separately deployable. Assume that you must develop three features: A, B, and C. You want to deploy feature A separately from features B and C. You must create a topic branch called A, where you develop A separately from B and C. You can develop features B and C in the development branch, or better yet, you can create topic branch BC for these features. In this example, it is assumed that features B and C are developed in the development branch.

Develop and Deploy Feature A 1. Create feature branch A and switch to this branch. 2. Add files for feature A, such as A.mdml.xml, under DialogLayouts. 3. Commit and push the changes.

Handbook for Using the Maconomy Extender IDE 62

Working with the Git Version Control System

4. Deploy to a server. This step is optional.

Develop and Deploy Features B and C 1. Switch to the development branch. 2. Add files for features B and C, such as B.mdml.xml and C.mdml.xml, under DialogLayouts. 3. Commit and push the changes. 4. Deploy to a server. This step is optional.

Merge Feature A with Features B and C 1. Switch to the development branch. 2. Click Merge on the connection from the feature A branch in the Deployment Diagram. 3. The Merge result dialog box displays, listing the changed files. 4. The development branch now contains features A, B, and C.

Handbook for Using the Maconomy Extender IDE 63

Working with the Git Version Control System

Commit Graph The commit graph looks like this:

Scenario 4: You Want to Change one File on a Server that Has an Old Commit Installed and Still Be Able to Deploy Current Revisions to Other Servers Assume that a customer has a Development server, a Test server, and a Live server. The master branch in the server repository contains features A, B, C, and D, and these are currently deployed on the Development and Test servers. The following figure shows the files from the master branch. The Live server does not have features A, B, C, and D installed and needs a hotfix with a small change to the globalmenu.mmsl.xml file. The following figure shows files in the master branch that are deployed on the Development server.

The following figure shows the versions installed on the servers. The Development and Test servers have features A, B, C, and D installed while the Live server as an old version installed without these features.

How do you make a hotfix with Git? You use branching—you create a hotfix branch based on the revision installed on the Live server. You can see the revision and the tag installed on the Live server in the Installation History view and in the Servers view.

Handbook for Using the Maconomy Extender IDE 64

Working with the Git Version Control System

In the Git Repositories view, right-click the tag under the Tags folder and select Create branch. Give the branch a name related to the hotfix and check out the branch. The active project contains files exactly as they are on the Live server without features A, B, C, and D. You can perform the hotfix, commit it, push it to the server repository, and deploy it to the Live server. The following figure shows that the Live server has the hotfix installed, while the Development and Test servers still have the current version.

The following figure shows the hotfix deployed to the Live server without changing the master branch and other server installations.

After completing the hotfix, you might want to provide the same change to features A, B, C, and D. You can do this by merging the master branch with the hotfixX branch. Double-click the master branch in the Git Repositories view. Right-click and select Merge. Select the hotfixX branch as illustrated in the following figure. The second figure shows the merged result of the two commits. Double-click either one to launch a commit editor. From the commit editor, double-click a file to open a compare editor for analyzing the differences between the checked out version of the file and the file from the commit.

The following figure shows the Merge Result dialog box, showing the two commits that are merged.

Handbook for Using the Maconomy Extender IDE 65

Working with the Git Version Control System

The following figure shows a commit editor, showing the hotfix commit that has been merged into the master branch.

The following figure shows the Compare view of the globalmenu.mmsl.xml file, showing the differences between the previous master branch version and the hotfixed version. Double-click the file in the commit editor (see the previous figure) to open this view.

Commit Graph The commit graph looks like this:

Handbook for Using the Maconomy Extender IDE 66

Working with the Git Version Control System

Tips and Tricks

View a Project in the Git Repositories View Right-click a project and select Team » Show in Repositories view.

Compare Files in the Active Project with the Server Repository Right-click the project and select Team » Synchronize workspace. This displays the Synchronize view for reviewing the differences between the files in the active project and the server repository.

View Commit History and Branches for a Repository Right-click a project and select Team » Show in history view to show the commit history. Select a commit in the list to display the files affected by the commit. You can also create branches from this view.

View Older Changes to a Specific File and Compare Versions Right-click a file and select Team » Show in history view to display the commit history. Doubleclick to open the compare editor, which shows the differences between the current file in the project and the old file. To open the old version, right-click the file and click Open.

View What the Last Commit—or any Specific Commit—Contained You can view commits from several places. From the History view, you can see which files were affected by the commit. Double-click the file to open the Compare editor. You can also use the Git Reflog view, which displays all commits in one column.

Replace Everything in a Branch with an Earlier Commit You might want to go back in history and use an earlier commit as the current head.

To replace everything in a branch with an earlier commit, complete the following steps: 1. In the Git repository perspective, right-click the repository and select Show in history view. 2. Find the commit that should be the head of the current branch. 3. Right-click the commit and select Reset. Select Hard if you want to replace all uncommitted changes in the working directory. The local branch now points to the earlier commit, and the working directory contains the files from this commit. A push will then update the remote branch to point to the same commit as the local branch. Change the files, then commit and push. The commit tree now has the old commits as an unnamed branch that is no longer used—these are the commits that followed the earlier commit that you reset to. You can leave these commits untouched in the history, or you can delete them.

Handbook for Using the Maconomy Extender IDE 67

Working with the Git Version Control System

Merge Specific Files from One Branch into Another (Cherry Picking) The files must be in one commit. All changes from this commit can be "cherry picked" into the current branch. You can merge specific changes from one branch into another. This is called cherry picking.

To cherry pick changes, complete the following steps: 1. Fetch changes from the remote repository to get access to available changes by clicking Team » Fetch from upstream. 2. In your current branch, select the commit from another branch that has the changes that you want to bring into your branch. You can also view the commit history by right-clicking your project and selecting Team » Show in history view. 3. Right-click the commit and select Team » Cherry Pick. The changes that you selected are merged into your current branch.

Compare Differences between Two Commits Select the two commits in the Git history view, then right-click the selected commits and select Compare.

Conflicting Files—Use Merge Tools If you have conflicting files in a project after merging two branches or merging with the remote branch, use the EGit merge tool to resolve the conflicts. This is much easier than using the auto merged files with Git annotations. To start the merge tool, right-click a conflicting project and select Team » Merge tool. For more information, see Scenario 3: You will work on two features but only deploy one of them.

Undo a Previous Commit Reversing a commit enables you to roll back a commit that you pushed to the server repository. In the History view, right-click the commit and select Revert commit.

Handbook for Using the Maconomy Extender IDE 68

Writing Release Notes

Writing and using release notes is useful for a release manager to understand and control what is part of a release. It is most useful for larger implementations with many developers involved. The idea of this feature is that a consultant writes a release note after he or she has completed the implementation and test of a feature. The release note is attached to the latest commit of the branch in which the feature was implemented. In a Release Note view the release manager can see all release notes written. From the view, release notes can be modified and deleted, and an HTML report can be generated

Adding Release Notes You add release notes are added from the deployment diagram. Click the “Pen” icon on a branch to open the release note dialog.

Viewing, Modifying, and Deleting Release Notes Release notes are listed in the Release Note view. Open the view from the menu Window » Show view. Select one or several notes to export or to delete. Double-click a note to edit it. Click the Refresh action to refresh the view. To limit the release notes displayed, choose values for the From and To release tags.

Generate Release Note Report From the Release notes view, select the release notes needed for the report, and then click the “Export” action. This generates an HTML file that opens inside the Extender.

Handbook for Using the Maconomy Extender IDE 69

References

Online Resources You can find resources about Eclipse and Git online: . Eclipse tutorial: http://www.vogella.de/articles/Eclipse/article.html . Git version control: See the Eclipse help system in Eclipse. Click File » Help content.

Books Deltek recommends Pro Git, written by Scott Chacon and published by Apress. It is available here: http://progit.org/book/.

Handbook for Using the Maconomy Extender IDE 70

Appendix A: Using GitHub

To use GitHub for hosting a server repository, complete the following steps: 1. Create a GitHub account at www.github.com. 2. In Eclipse, ensure that the SSH settings are set correctly on the Preferences page.

3. If you do not have SSH keys, you can generate them on the Key Management tab on the Preferences page. Use a good passphrase to protect your private key. 4. Retrieve your public key so that you can use it in your GitHub account. The public key is located in the text field on the Key Management tab. You can load an existing key from this tab, and your public key will display in the text field. Copy the public key from the text field. 5. Log in to your GitHub account. 6. Go to Account Settings, select SSH Keys, and click Add SSH Key. Enter a title, paste your public key, and click Add. 7. If you are a Deltek employee, ask the Deltek GitHub admin team ([email protected]) to add your user to the Deltek team so that you get access to the customer’s repositories. 8. If you are responsible for setting up a new customer, ask the Deltek GitHub admin team ([email protected]) to create a source repository and a configuration repository for your customer and to give you access rights. You must provide the following information: . Name of the customer repository. . An optional list of customer and partner GitHub user IDs that should have access to the repository. These customers will be able to add/remove colleagues to and from the team.

Handbook for Using the Maconomy Extender IDE 71

Appendix A: Using GitHub

Some customers may require that the repository is hosted on their GitHub account and that they control the repository and the access rights to the repository. If you need to use a customer’s GitHub account to host the repository, you must do the following on the customer’s GitHub account: 1. Create a repository with the name . 2. Create a repository called Configuration. Maconomy Extender uses this repository to store information about the configuration. 3. Create a team that has pull/push access to the repositories. 4. Add users to the team. If you create the team with administration rights, the users can add and delete team members themselves. In Maconomy Extender, you must change the GitHub preference under Maconomy Extender preferences to use the customer’s GitHub account instead of Deltek’s account.

Handbook for Using the Maconomy Extender IDE 72

Appendix B: SSH Access to a Git Server

It you or the customer do not want to use GitHub to host the server repository, you can set up your own server to host the repository. You can access a server repository through SSH. With this setup, consultants do not need direct file access to the repository server. The SSH protocol is also fast and secure. It allows access through the use of usernames/passwords, as well as public/private key authentication. The repository server can be any of the following: . A customer server . A Deltek server . A cloud-based server, such as Amazon . A commercial Git provider, such as GitHub. GitHub uses SSH access exactly as if it were a normal SSH-based server. The easiest solution is to pay for an account at GitHub and create a repository there. This is globally accessible and permits users to access the repository. Another option is to set up a Linux-based server, which comes with SSH installed. To use public key authentication, you must generate a private/public key pair at your local machine and add the public key to the authorized_keys file on the server. To set up a Git repository on the server, use the New Server Repository wizard. The wizard guides you through the steps for connecting to the server, initiating the Git repository, and setting up the Git repository.

Generating Public/Private Keys Putty is often used to generate public/private key pairs for SSH access. However, Putty uses its own format for storing the private key, and Eclipse does not support this format. You must generate a private/public key pair with another tool, or convert the private key that Putty generated. Eclipse provides a functionality to generate keys.

To generate keys, complete the following steps: 1. Click Window » Preferences » General-Network Connections » SSH2. 2. Click the Key management tab. 3. Click Generate RSA key. 4. Enter a passphrase to encrypt the private key. 5. Click Save private key. 6. Save the private key in the SSH2 Home folder defined on the General tab. 7. Restart Eclipse before using the key. Eclipse might not recognize the key before it has been restarted.

Handbook for Using the Maconomy Extender IDE 73

Appendix B: SSH Access to a Git Server

After you complete this procedure, copy the public key and add it to the authorized_keys file on the server, as described in Adding a public key to the server. The following figure shows SSH2 settings on the Preferences page.

Adding a Public Key to the Server To use private/public keys authentication, you must create an authorized_keys file under the .ssh folder in the user’s home directory:

mkdir /home//.ssh This file contains public keys from consultants who are allowed to access the repository Add the public key for each user to the file:

cat /.pub >> /home//.ssh/authorized_keys

Preparing a Repository Server with SSH Access If SSH is not yet installed, you can install OpenSSH using this command:

sudo apt-get install openssh Install the Git version control system:

sudo apt-get install git-core Create a user—such as “maconomy” or “git” —to be used for accessing the repository. All consultants will use this user role:

sudo adduser maconomy

Handbook for Using the Maconomy Extender IDE 74

Appendix C: Troubleshooting

This appendix contains a list of common problems and solutions to them.

Starting the Extender or Activating a Customer Project Takes a Long Time If you work on a customer server with file access through a VPN channel or on another domain, you might experience very long response times for starting up the Maconomy Extender or activating the customer project. The Maconomy Extender is set up to show standard files in the Standard files view. By default, it uses the files from the Server repository. By using this option you will not experience long response times. However, standard files might not have been setup in the repository, and then standard files are often used from the default server (development server) in the Servers view. There are about 4000 files, and the information about these file are retrieved from the server. Due to a Windows security feature, Windows may check authorization for every file that is accessed from outside the domain. This could take as long as an hour. There are three solutions to this problem: 1. You can update the server repository with standard files from the server. This can be done from the project properties page under Maconomy Extender->Versions. Click “Check for updates” to update the server repository and your current project with files from the server. This operation might take several minutes or hours depending on your connection to the server. 2. You can access the server through SSH, and you can extract standard files from the server to a local machine from the servers view by right-clicking on the server. The extraction of files will probably take too long when accessed through file access. 3. You can zip the standard files on the server and extract them on your machine. You need to do the following: a. Zip the following files/directories on the server: /MaconomyDir/ContainerDefinitions /MaconomyDir/DialogLayouts /MaconomyDir/WorkspaceDefinitions /MaconomyDir/Icons /MaconomyDir/Notifications /MaconomyDir/Definitions/globalmenu.mmsl.xml /MaconomyDir/Definitions/couplingconfiguration.mcsl.xml b. Extract to, for example, c:/maconomyextender//standard, and ensure that the MaconomyDir directory is in the folder. c. Right-click on the project in the Extender then select Properties » MaconomyExtender, and set the standard files path to the path you unzipped to in the previous step, for example, C:/maconomyextender//standard. d. Right-click the project then select Maconomy » Set as active, and verify that you see files in the standard view.

Deploying Files to a Customer Server Takes a Long Time Long deployment times to a customer server that is accessed through file access may be related to the same issue as described above. The best solution is to install an SSH server on the

Handbook for Using the Maconomy Extender IDE 75

Appendix C: Troubleshooting

Maconomy server and deploy through SSH. This usually solves the problem. Another solution is to ensure that the server definition in the Servers view is set up with history. When a server has history, deployment by default only copies/deletes files that have been changed since the last deployment. When the server does not have history, the deployment mechanism first deletes all custom files and then installs them again. The deletion of files takes a long time when the server is accessed through VPN.

Error Appears When a File is Deployed When you deploy a file, you may get the “Custom namespace validation failed” error, as shown in the dialog below:

This error happens when you have custom files that do not shadow any of the standard, solution, or extension files in the DialogLayouts, Definitions, or WorkspaceDefinitions folders. To address this issue, place custom files in subfolders, which is also called namespaces.

Coupling Service Commands Do not Seem to Work At some server installations Coupling Service command line commands do not work. This is because they must be executed with admin rights.

To execute the commands with admin rights, complete the following steps: 1. Right-click on CouplingService.exe » properties » If Compatibility pane available » Run this program as an administrator » Apply » OK. 2. After executing the commands, remove the administrator right or other problems will occur, such as network drives disappearing.

Handbook for Using the Maconomy Extender IDE 76

Appendix D: Set Up SSH Access to a Windows Server

This appendix discusses the process of setting up SSH access to a Windows server, which is most often used to access a Maconomy server. SSH also supports access to Git Windows, web, or Coupling Service servers. Maconomy Extender requires more than SSH access. Extender also requires a command shell on the server to enable UNIX commands. The most common product for this is Cygwin, which also contains an SSH server, called OpenSSH. This is the same implementation as used in Linux servers. Some customers, however, do not allow installation of open-source products; hence, purchasing a commercial version such as CopSSH, is recommended. CopSSH bundles Cygwin and OpenSSH, and combines these with a graphical user interface. This section discusses only free Cygwin distribution. To install Cygwin, follow the guide found in this link: http://www.howtogeek.com/howto/41560/how-to-get-ssh-command-line-access-to-windows-7- using-cygwin/ Once you have Cygwin installed, you must do the following: • Create a Maconomy user directory: /home/maconomy/. The casing of the Maconomy user name and the directory should be the same. Hence the directory name must be Maconomy if the user name is Maconomy. • Create an "authorized_keys" file in the /home/maconomy/.ssh/ folder, if PPK is used. • Add public keys of authorized users in the "authorized_keys" file. • Ensure that the username in the directory and the username in the Extender are similar. This includes same casing.. • Use /cygdrive/ in the Extender, such as /cygdrive/d/maconomy/w_15_0 • Copy the content of your rsa_pub key and append it to the .../maconomy/.ssh/authorized_keys file, if accessing through PPK. • Disable password authentication in the file /etc/sshd_config. Set PasswordAuthentication from “Yes” to “No” as follows:

o #PasswordAuthentication yes changed to

o PasswordAuthentication no To restart sshd, enter net stop sshd and net start sshd. • Test that the SSH connection with private/public key authentication works from another machine. This is easiest to do using a command line interface. On windows install Cygwin to get the SSH command program. On Mac and Linux, it is already avaiblable. Enter ssh –v Maconomy@:. You should then be prompted for the keyphrase for your private key. Then you should get access to the home directory for the user.

Handbook for Using the Maconomy Extender IDE 77

Deltek is the leading global provider of enterprise software and information solutions for professional services firms, government contractors, and government agencies. For decades, we have delivered actionable insight that empowers our customers to unlock their business potential. Over 14,000 organizations and 1.8 million users in approximately 80 countries around the world rely on Deltek to research and identify opportunities, win new business, optimize resource, streamline operations, and deliver more profitable projects. Deltek – Know more. Do more.® deltek.com