Recents
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. With "gamhome" of the GAM Backend running, 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 details):

  • 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 this user's password. 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).
    • It can also be a new role created automatically in the new repository. In this case, the role is called "Administrator", and it is assigned to the Role External Id = "is_gam_administrator". The main purpose of this is to enable users to access the GAM Web Backoffice.  See Restricted access to GAM Backend. Afterwards, 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 users to create the GAM Backend Application in the Repository that 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. Whether you will need to activate CreateGAMApplication or not will depend on your particular case.

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 created repository.
See GAM Manager Repository, where this property is 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 (including menus and permissions)
  • Roles (without permissions)
  • Security Policies
  • Role Permissions (the relation between permissions and roles)

    GAMCopyRepSettings

3. CopyRoles

The Copy Roles option allows users to copy the roles of any repository (selected in the Repository Id combo) to the repository that is being created.
You must select the "Administrator Role Id", so the administrator user that is 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. To add the roles' permissions, you must select the 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 Restricted access 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 the edit box "Copy from Application Id". 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 Roles-Permissions association, select this option.
You must provide 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 option allows copying 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, while simultaneously creating the repository and initializing that repository with the Application created.
In this scenario, the Application has to be populated with data afterwards.

  • 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 the CopyFromApplicationId method, it overrides the Application method of the RepositoryCreate object.
  • Note 2: Another possibility is to import the Application data into the empty repository (using the GAM Deploy Tool).

See Also

HowTo: Creating New Repositories from a GAM deploy tool package





 

Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.