Introduction to Configuration Manager 2.0
Configuration Manager (also known as FlexCM) is a standalone tool that allows you to pull configurations from one Flex account (the source) and push those configurations to another account (the target). This is useful in situations such as migrating configuration from staging to production environments or when restoring an account to a known "good" state.
Installation and Setup
Instructions on where to download FlexCM and how to setup your first source and target account can be found here.
Getting Started
Once installed, you can get started with your first Flex CM from here.
Command Reference
Reference documentation for all FlexCM commands can be found here.
Out of scope
FlexCM is strictly designed to manage configuration and is not meant to manage running objects such as assets, workflows, or jobs. A full list of supported objects can be found here.
Installing and Setting Up Configuration Manager
In order to start using FlexCM, there are a number of steps that you must carry out. Firstly, you will receive the FlexCM package via your preferred method of delivery. This package will contain the FlexCM .jar file.
Running FlexCM
- Copy the .jar file into your local home directory. E.g.: In Windows: C:\Users\<<Username>>
- Next, open the command console, and from the directory where you have placed the .jar file, run the following command: java -jar flexcm-tools-cm-2.0.0.jar
- When you have done this, you will see the following welcome message:
Setting up a Repository
- Run the following command: repository --defaultPath <absolute_dir> --defaultRepository <name_of_repository>. This will create the folder and produce a miocm-config.yml file in ~/miocm-config.yml (this is the home directory).
- When the repository has been created, you will see a confirmation message which reads Repository created, as shown in the example below:
FlexCM will store Dalet Flex environment configurations, change sets, and logs in your repository.
Creating an Environment Structure Inside the Repository
Next, you will need to set up an environment structure inside your repository. This means you will need to specify a source environment and a target environment.
- Run the following command: environment --envname <name_of_environment> --endpoint <endpoint> --username <username> --password <password>
- If the command has been run successfully, you should see the following response: Environment created: Environment (name=my_source_env, uuid=12dafb34-5678-9123-4d5c-be6ef7ab89b1, dirName=C:\my_new_repo, endpoint=my_dalet_flex_environment.com, username=mypassword, password=myusername, hostHeaderParam=null, isReady=true)
- Now, a folder will be created in your repository for each environment you have specified. In the example below, you can see a folder for a source environment, and one for a target environment.
- Each environment folder will have a .yml file inside. This .yml file will contain the information for that specific environment. This information in each .yml file can be altered at any time, simply by opening it in a text editor.
The information in each .yml file must be accurate. For example, if the password for one of your environments you are using changes, you must open the .yml file associated with that environment, and update that piece of information.
Getting Started
Once you have a source and target environment setup, the following steps will pull an action from your source account and then create it in your target account to create your first change request.
Initial Commands
You can run the following command before starting your change request, or at any point in the steps below:
List all actions in an environment: list --environment source --type action (here the --environment flag can be source or target)
Get help for any command: help list (you can substitute list for any other command, e.g. help open)
Start a new change request
open --source <name_of_source_environment> --target <name_of_target_environment>
Manually create a new action in the Source
- Login to the Flex Core UI of your Source environment
- Navigate to Settings > Actions
- Click "New" to create a new Action (any type will do)
- Add some basic configuration to the General and Configuration tabs
- Save and enable the Action
- Copy the UUID of your new Action for the next step
Pull the new Action configuration
pull -–type action -–uuid <uuid_of_newly_created_action>
Add the new action to your change request
add
Commit the change request
commit
You can now login to the Target Flex Account to check that the new Action was created. It even has the same UUID as the Source.
Commands for Configuration Manager
All Commands
Command | Description |
help | This shows you all the commands available in the system |
version | Displays the shell version |
exit, quit | Exits the shell |
clear, cls | Clears the console |
[add](#add) | This pushes the target changes to the environment |
bootstrap | Bootstraps objects that do not have an UUID |
[commit](#commit) | Commits the changes to git repository |
[dependencies](#dependencies) | Pulls dependencies of object of passed UUID from the remote environment |
environment | Creates a new environment configuration |
info | Shows all the supported objects and their extended data |
gitdiff | Displays information about tracked and untracked changes based on the changeset and the git repository. This only displays changes that have taken place in the folder that represents your target environment. |
[mapper](#mapper) | Set mapper configuration. Mapper will be applied to current change request. e.g. file: { "sourceUuid": <uuid>, "targetUuid": <uuid> },... |
prepare-bootstrap | Populates the objects with a new UUID |
[list](#list) | Lists available objects from the source environment by default, but you can list objects in the target as well |
[open](#open) | Creates a new change request or opens an existing one |
[pull](#pull) | Pulls source or target configuration objects from the remote environment |
remove | Removes all objects from the target environment |
repository | Creates a new repository and config files |
script | Parses the specified resource file and executes its commands |
[session](#session) | Shows information about the current session. |
showchangeset | Shows changeset |
[showrepos](#showrepos) | Lists available repositories |
[status](#status) | Lists all change requests in the current repository |
system properties | Shows the shell's properties |
tag | Adds the tag to commit |
[update](#update) | Updates all objects from source environment to target environment |
Command Details
showrepos
The showrepos command displays the repositories you’ve created.
Example:
Available repositories: - Repository name: my_repo
status
The status command displays the status of the Change Request created by the system. If you use the status command, you will see a response which is similar to the following:
Name | Created On | Source | Target | Committed on |
CR_1202151204 | 02/12/2015 | 12:04:56 | MioStage | MioStageTarget 02/12/2015 12:36:05 |
open
open --source <name_of_source_env> --target <name_of_target_env>
This command creates a new change request. With this command, you can change which environment is your source and which is the target for a particular change session.
Example: open --source my_source_env --target my_target_env
If the change session has been setup successfully, you will see the following response:
Note: The name of source and target environment should match the folder name in your repository.
open --cr change_request_name
This command is used to switch the environments or load an existing change request.
Example:
ChangeRequest loaded: [name=CR_0612151434, uuid=66d36f8f-7f9a-4dd0-b5f6-d3f9887657ba, source=DEV, target=QA, created on=12/06/2015 14:34:09, committed on= not yet]
open --source <name_of_env> --target <name_of_env> --keep_organisational
By running this command, you can indicate whether or not to keep account / user settings that are found in the source environment, and apply them to the target environment. So when you pull items, and then push them to the target, they will automatically conform to the organisational details you have specified.
The following options can be used with this command:
- all: By specifying this option, you can keep all the account / user settings found in the source, and apply them to the target.
- none: By specifying this option, you are choosing not to apply any of the account / user settings found in the source environment, to the target environment.
- user: By specify this option, you are only choosing to apply the user settings found in your source environment, to your target environment.
- account: By specify this option, you are only choosing to apply the account settings found in your source environment, to your target environment.
Example: The following command would keep all the settings associated with users.
open --<source_env_name> --<target_env_name> --keep_organisational user
session
The session command provides you with the details of the current session.
Example: Working path: C:\miocm_reposRepository: MioCMEnvironments: There are 2 environments - Environment name: MioStage - Environment name: MioStageTargetCurrent CR: There is no change request open
list
list [[--type <object_type>]|[--uuid <uuid>]][--environment source|target]]|
The list command currently supports the following object types:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player Definition
- Timed Action
- Account Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
Example: Using list --type action lets you see a list of all the actions you have in a particular environment. The information for each action in the list will be displayed in the following order <lastmodified><uuid><type_object><name>. This is shown in the screenshot below:
pull
The pull command lets you pull objects from an environment.
pull [[--type <object_type>]|[--uuid <uuid>]] [--environment <source|target>]] |
Examples:
- pull --environment <source|target>
- pull --type --action
- pull --uuid --<uuid>
By default, executing the pull command will pull objects from the source environment. If you execute the command by itself without specifying an object type, FlexCM will pull all the available object types by default.
If you use the pull --environment command, you can select --environment <source|target> label.
The pull --type action command will take all the actions from the source environment, and send them to the source folder inside the repository.
The pull command currently supports the following object types:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player Definition
- Timed Action
- Account Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
add
add [[--type <object_type>]|[--uuid <uuid>]]|
The add command is used to push changes to the target folder. If the object type and UUID are not specified, all of the environment configuration will be copied across to the target by default. So it is important to specify the object type and UUID if you are only changing one object for example. If you execute the add command by itself without specifying an object type, FlexCM will add all the available object types by default.
Examples:
- add --type action
- add --uuid <uuid>
The add command currently supports the following object types:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player Definition
- Timed Action
- Account Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
update
update [[--type <object_type>]|[--uuid <uuid>]]|
The update command is used to update the target folder with the delta records. If you execute an update by itself without specifying an object type, FlexCM will update all the available object types by default.
Examples:
- update --type action
- update --uuid <uuid>
The update command currently supports the following object types:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player Definition
- Timed Action
- Account Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
commit
The commit command is used to commit changes you have made, to the git repository.
commit [[--type <object_type>]|[--uuid <uuid>]][--message <message_text>][--force true|false][--skip_git_status true|false]
Examples:
commit --message "This is a message providing details about this particular commit"
With this command, you can add messages to your commit so that you can differentiate between different commits in the git repository. If you have spaces in your message you must wrap the message in quotes.
- commit --type action
- commit --uuid <uuid>
Additionally, the commit command accepts the --force option which will change all of the conflict questions to "Include all" without confirmation from the User.
remove
remove [[--type <object_type>]|[--uuid <uuid>]]|
Examples:
- remove --type action
- remove --uuid <uuid>
The remove --type command currently supports the following object types:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player Definition
- Timed Action
- Account Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
dependencies
The dependencies command lists the dependencies of a specific object. This is done by passing the UUID for the object located in the remote environment. For example: you could have a workflow, and that workflow might reference several other objects in order to work, such as actions, event handlers, and so forth. The objects that are referenced by the workflow, may in turn, reference objects as well.
Note: You must open a change session first, in order to use this command.
Below is an example of a list of dependencies for a specific object:
dependencies --environment target --uuid 2bd43348-d6e0-475d-bbd0-be0699a91fef
{
"dependencies": [
{
"referenceLink": {
"id": 19362,
"uuid": "2bd43348-d6e0-475d-bbd0-be0699a91fef",
"name": "Add to Group Action",
"displayName": "Add to Group Action",
"externalIds": [],
"objectType": "<snipped>",
"accountId": 18487,
"enabled": true
},
"upstream": [],
"downstream": []
}
]
}
mapper
The mapper command allows you to map a user, account, or visibility from one environment and apply it to an object located in another environment using UUIDs.
Note: The mapper command doesn’t map internal configuration references. For example, an action using a metadata definition in the configuration will not have the UUID mapped. Only access details are mapped: such as user, account, and visibility.
You need to specify the UUID of the object type you wish to map, and then the UUID of the object you want to map it to.
In order to use this command, you must first specify the object UUIDs in a JSON file. For example you could have the following:
{
"mapping": [
{ "sourceUuid": "4508649d-d697-4c75-8fa0-27ac4ca674c4", "targetUuid": "786a8a14-6533-41c9-ad22-8a54fe9bcbd9" }
]
}
Once you specified the UUIDs in the JSON file, you need to run the following command, containing the exact path to where your JSON file is located.
Example
mapper --file D:/mappers/owner_account_mapping.json
Manually Setting up FlexCM
Although FlexCM enables you to use specific commands in order to automatically set up repositories and specify your environments respectively, you can also do it manually if you prefer. This requires you to manually create the file structure that is needed, and so, it is recommended that you only perform a manual setup if you are more familiar with the tool.
There are a number of steps that you must carry out. First of all, you will receive FlexCM package via your preferred method of delivery. This package will contain:
- The .jar file
- The miocm-config.yml file
- The environment.yml file.
1. Copy both the .jar file and the miocm-config.yml file into your local home directory. Example: In Windows: C:\Users\<<Username>>. Below is the format for the miocm-config.yml file
- default Path: C:\miocm_repos
- default Repository: defaultRepository: mio-Dev-REPO-01
2. Next you must create a working directory in which FlexCM will store Dalet Flex environment configurations, change sets, and logs.
Manually Setting up the Repository
Inside your C:/ drive, create the following folder structure:
Notes:
- You can have any number of environments, within any number of repositories. In the example above, we have shown what the folder structure would look like if you had one repository with only two environments.
- You can use any other path and repository, but you must update the miocm-config.yml file in order for FlexCM to work.
A. Root Folder: This folder represents a workspace in which to manage one or more repositories.
B. Repository: As previously mentioned, you can have multiple repositories. Within each repository you can have two or more environments depending on your needs.
C. Source Environment: This folder represents your source environment. You can make changes and then pull configuration from the source environment.
D. Target Environment: This folder represents the target environment. You can pull configuration from the source environment and apply it to the target environment.
E. environment.yml for Source Environment: This is a .yml file that you place inside your the source environment folder. This must be configured with the details of your source environment, These details are as follows:
- Endpoint: e.g. myenvironment.dalet.com/api
- Password: The password you use to login to the environment
- Name: The name of your environment e.g. my_source_env
- UUID: e.g. c4a1ea01-f42d-4683-8aeb-1cdfdbdf716e
- Username: The username you use to login to the environment
F. environment.yml for Target Environment: This is a .yml file that you place inside your the target environment folder. This must be configured with the details of your target environment. These details are as follows:
- Endpoint: For example: myenvironment.dalet.com/api
- Password: The password you use to login to the environment
- Name: The name of your environment e.g. my_source_env
- UUID: e.g. c4a1ea01-f42d-4683-8aeb-1cdfdbdf716e
- Username: The username you use to login to the environment
Configure each environment manually by opening the enviroment.yml files in a text editor, and adjust the details accordingly. The configuration of the environment .yml files should be as follows:
- name: DevEnv1
- uuid: 47c07ee7-a9f8-46bc-b171-9242540b1435
- endpoint: https://test-dalet-flex-env.com/api
- Username: username
- password: password
Once you apply this configuration to the environment .yml files, you will have a repository with two environments.
UUID
The UUID (Universally Unique Identifier) is a system defined read-only field. The UUID is generated upon an object's creation, and so, every object has a UUID.
- UUIDs are returned in the REST API as a JSON property and for existing objects.
- A UUID will be generated when an object is created and it is immutable.
- A UUID can be seen in the Dalet Flex Console, in the Object Details section for that object.
- A UUID will be returned in the configuration object REST API responses.
- A UUID will be used to uniquely identify an object in the REST API URL parameters.
Revision Numbering
A revision number will be generated when an object is created, and it will be updated when the configuration changes are saved.
Example: Any change to the name or description of an object is a new revision version.
The revision number can be viewed in the Dalet Flex UI, in the Object Details section for a specific object. The revision number will be in the following format:
- Number: is local to the environment and is a sequentially generated number (0, 1 ...N). This number represents the number of updates that have been committed for that specific object in this environment only. FlexCM manages revision changes across multiple environments and warns, as well as prevents committing configuration changes to target environments when the revisions don’t match FlexCM central revision store. Dalet Flex updates the new revision codes for each configuration object. Then, it will maintain the revision code, recalculating it with every change that is made using the UI or FlexCM commit deployment.
- HashCode: is a unique 32 bit java hash for the object.
Supported Objects
The objects that FlexCM supports are as follows:
- Action
- Account
- Workflow Definition
- Resource
- Metadata Definition
- Event Handler
- Message Template
- Profile
- Player
- Definition
- Timed Action
- Account
- Property
- Group
- Workspace
- User
- Role
- User Defined Object Type
Once you begin using FlexCM, you can use the info command, in order to list all of the supported object types, as shown below:
Known Issues when Working with Configuration Manager
Certain objects have certain dependencies which you should take note of:
Users
Committing a new User: In the current version, Dalet Flex requires that an account and role are created before a new user is committed. This should be done in two/three different change requests:
1. First change request: is to create and progress an account from your source environment to your target environment. This will include the default role as part of account creation.
2. The second change request: is to create and progress new roles from your source environment to your target environment, if there are any being referenced by new users. (This is optional).
3. The third change request: is to create and progress new users from your source environment to your target environment.
User Passwords: If you transfer a new user from your source environment to the target environment, the new user will not be able to login via the UI, until the super user has reset that particular user’s password.
Note: The password will not be moved over with the user, so the super user
must reset the password for that user, once it has been moved over to the target environment.
Note: The password for a user can be reset, by going to the details section for that particular user, and clicking the Reset Password link, located in the top-left corner. An email is then sent to that user, requesting that they change their password.
Mappers
FlexCM can’t be used with mappers to create new objects in same environment in a different account. For example: if you have account A in source environment you will not be able to move all objects from account A to account B if the target environment is same as the source environment.
Object Visibility
If the visibility of an object is updated at the super user level, to add a root account, that particular item will not be able to progress using FlexCM or the REST API.
Accounts
If you want to create a new account in an environment via FlexCM, e.g moving an account from your source environment to the target environment, the account in the source needs to be enabled, so that you can apply the information from the account to the target environment, such as an accounts default role.
Workflow Definitions / Events
If you try to transfer an event or a workflow definition from the source environment to the target environment without configuring the filter/config or structure, then it cannot be enabled.
Creating a new account using a variant with a metadata definition of the same account can't be created in same change request
Workaround for this problem:
1. First create a change request in order to deploy the account. A warning will be shown, that informs you the metadata definition can’t be referenced to create the variant.
2. Open a new Change Request in order to deploy the metadata definition.
3. Finally create a new change request to update the same account. This will create a variant using the already deployed metadata definition from the change request in step two.
Comments
1 comment
Hello, regarding this part:
" Firstly, you will receive the FlexCM package via your preferred method of delivery. This package will contain the FlexCM .jar file."
What would be the process of requesting the jar file?
Please sign in to leave a comment.