HowTo: Creating New RepositoriesOfficial Content

Only administrators of the GAM Manager Repository can create new Repositories.

Using the GAM Backend you can connect as an administrator of GAM Manager Repository and create, update, and delete Repositories. The GAM API provides the necessary methods to manage Repositories so you can change the GAM Backend as desired to change the interface for these operations.

Steps to follow:

1. Connect to GAM Manager Repository

2. Running "gamhome" of the GAM Backend, select the "Repositories" option of the menu (which calls the GAMExampleWWRepositories object). This option is available only when the current repository is "GAM Manager Repository".

There you can add, update, and delete repositories.

Creating a new Repository: basic settings

create GAM Repository

Then, you need to complete the following information (among other):

  • Namespace - Is the Namespace of the Repository. The Namespace is a way to group different Repositories which have something in common (e.g., the company they belong to).
  • Connection User - The Connection User of the new Repository.
  • Connection Password - The Connection Password of the new Repository.
  • Administrator User - The Administrator User of the new Repository.
  • Administrator Password - The Administrator Password of the new Repository.
    Note: If the administrator user is the same as any user of a different Repository which has the same Namespace as the new one, you have to specify the password of this user. Otherwise, the following error will be thrown: Username already exists. (GAM49). This happens because users inherit the Namespace of the Repository where they belong. If a user is going to be defined in a Repository which has the same Namespace as any other, he/she is an already existing user.

    The administrator user is going to be assigned to the Administrator role of the repository. The Administrator role depends on the initialization of the repository.
    • It can be a specific role selected to be copied to the new repository (see 3. below), or
    • It can be a new role created automatically in the new repository. If this is the case, this role is called "Administrator", and it is assigned to the Role External Id = "is_gam_administrator". The main purpose of that is to enable the users to access the GAM Web Backoffice.  See Access restricted to GAM Backend. Afterward, you may populate that role with all the GAM Permissions that you consider necessary.
       
  • Update connection file - If checked, the connection.gam file is updated online. In this case, the connection.gam being used is merged with the connection information to connect to the new Repository. If you want to create a connection.gam file only with the connection information of the new Repository, see HowTo: Get GAM Repository connection information.

The basic code to create a GAM repository is the following:

                &GUID = GUID.NewGuid().ToString()
                &RepositoryCreate.GUID                         = &GUID 
                &RepositoryCreate.Name                         = &Name 
                &RepositoryCreate.NameSpace                 = &NameSpace 
                &RepositoryCreate.Description                 = &Description 
                &RepositoryCreate.AdministratorUserName     = &AdministratorUserName 
                &RepositoryCreate.AdministratorUserPassword = &AdministratorUserPassword 
                &RepositoryCreate.AllowOauthAccess             = &AllowOauthAccess
                &RepositoryCreate.ConnectionUserName         = &ConnectionUserName 
                &RepositoryCreate.ConnectionUserPassword     = &ConnectionUserPassword 
                &RepositoryCreate.GenerateSessionStatistics    = &GenerateSessionStatistics
                &RepositoryCreate.GiveAnonymousSession         = True 
                &RepositoryCreate.AllowOauthAccess            = True
                &RepositoryCreate.CreateGAMApplication        = &CreateGAMApplication
                &isOK = &GAM.CreateRepository(&RepositoryCreate, &UpdateConnectionFile, &Errors) //&Errors is collection of GAMError.
                //RepositoryCreate is based on RepositoryCreate GAM object
                If &isOK
                      Commit
                Else
                      Do 'DisplayErrors'
                Endif

 

1. CreateGAMApplication

This property of the RepositoryCreate GAM object enables to create the GAM Backend Application in the Repository which is going to be created.
If this Application isn't created, the users won't be able to execute the GAM Web Backoffice connected to that repository. It depends on your particular case if you will need to activate CreateGAMApplication or not.

Code:

&RepositoryCreate.CreateGAMApplication        = &CreateGAMApplication

2. Enable gamadmin user to access the new repository

It allows the gamadmin user to be an administrator of the newly repository created.
See GAM Manager Repository, where this property explained in full detail.

Creating a new Repository based on another one

You can initialize a repository using the settings of another one, by copying:

  • The GAM Application (includes menus and permissions)
  • Roles (without permissions)
  • Security Policies
  • Roles Permissions (the relation of permissions to roles)

    GAMCopyRepSettings

3. CopyRoles

The Copy Roles option enables to copy the roles of any repository (selected in the Repository Id combo) to the repository that's being created.
You must select the "Administrator Role Id", so the administrator user that's going to be created will belong to that role.
If you don't select an appropriate role, the following error is thrown:

You must configure an existing role in AdministratorRoleId property. (GAM39)

  • Note 1. If you want to add the permissions of the roles, you must select Copy Roles Permissions option (see 5.).
  • Note 2: If you don't copy roles from a repository, the "Administrator" role is created, and the "is_gam_administrator" External Role Id is added to that role. See Access restricted to GAM Backend.

4. Copy Application

You can initialize the Repository with a GAM Application of another Repository (the repository selected in "Copy from Repository Id"). All the permissions and menus of that Application will be copied.
You must enter an Application Id in "Copy from Application Id" edit box. Otherwise, it throws the error:

You must configure an existing application in the Repository x  (CopyFromRepositoryId). (GAM39)

5. Copy Roles Permissions

If you need to copy the association Roles-Permissions, select this option.
You must give an Application Id (from where the Permissions are going to be copied), along with an Administrator Role Id (because all the Roles are going to be copied from one repository to the other and you have to indicate which is the Administrator role).
The Administrator Role is used to know the role which is going to be assigned to the administrator user.

6. Copy Security Policies

The Copy Security Policies enables to copy all the security policies from the repository indicated in "Copy from Repository Id".

Creating an application from scratch for the new repository 

Instead of initializing a repository from the data of another one (copying the GAM Application of some repository), you can create a GAM Application from scratch, at the same moment of creating the repository and initializing that repository with the Application created.
In this scenario, the Application has to be populated with data afterward.

  • Note: If you don't create any GAM Application in the repository before connecting to it, an error is thrown: Application GUID unidentified. Please contact the application administrator. (GAM174). 

In order to create an Application for the Repository use the Application method of the GAMRepositoryCreate object.

Example:

GUID = GUID.NewGuid().ToString()
&RepositoryCreate.GUID                         = &GUID            //RepositoryCreate is based on RepositoryCreate GAM object
&RepositoryCreate.Name                         = &Name 
&RepositoryCreate.NameSpace                 = &NameSpace 
......
&GAMApplication.GUID = &GUIDApp  //&GAMApplication is based on GAMApplication GAM External Object
&GAMApplication.Name             = &Name
&GAMApplication.Description     = &AppDescription
&GAMApplication.Version         = "1.0"
&GAMApplication.AccessRequiresPermission             = TRUE
            
&RepositoryCreate.Application    = &GAMApplication
&isOK = &GAM.CreateRepository(&RepositoryCreate, TRUE, &Errors)

 

  • Note 1: If you use CopyFromApplicationId method, it overrides the Application method of the RepositoryCreate object.
  • Note 2: Another possibility is to import the Application data in the empty repository (using the GAM Deploy Tool).

See Also

HowTo: Creating New Repositories using GAM API