ART#213 - How to generate custom repository id with suffix or prefix in ATG?

Back



Next

Now that we have understood the basics of repositories, we will understand the process of generating custom repository IDs.

Why do we need to generate custom repository IDs?

We have many repositories in ATG. Each repository has many item-descriptors. For each item you create for an item-descriptor, ATG creates a repository-id by itself.
Now, in most (not ALL) item-descriptors, the ID is simply numeric.
In some item-descriptors, there is a prefix followed by a numeric ID. For example, in OrderRepository, you have a "commerceItem" item-descriptor.
For all items of this item-descriptor, you will always have a prefix "ci" attached to the id (e.g. ci98289191).

You might have a requirement of adding a prefix/suffix for some item-descriptors, which may be OOTB or entirely custom.
If you dont have that sort of requirement, it is always a best practice to have at least a prefix for each item-descriptor.
This can be achieved by using ATG's OOTB IdGenerator component which uses OOTB idspaces.xml file. We have the flexibility to override both.

How to generate custom repository IDs?

If you go to the dyn/admin of your application and search for IdGenerator, it can be found at /atg/dynamo/service/IdGenerator. Also, you can refer to its intialIdSpaces property which holds the location of idspaces.xml which is located at /atg/dynamo/service/idspaces.xml. This XML contains the information regarding your IDs.
You can override idspaces.xml using any of the combination modes. If you are not sure, how to override XMLs, you can refer to ART#202 for more detail.

Now, getting to the point. Let us understand how we create custom repository IDs.

1. idspaces.xml
All custom IDs are included in <id-spaces> tag.
Each id is represented by an <id-space> tag. Therefore, all <id-space> tags are enclosed within ONE <id-spaces> tag.
<id-space> tags have the following attributes:-
a. name: This should be the name of your item-descriptor for which you want to generate custom repository-id.
b. seed: The number from which the numeric part of your ID starts. [Typically, this is "1"]
c. batchSize: The value of this attribute reserves the IDs upto the count of this value. Typically this is set as 10000.
d. prefix: The prefix you want to add for your custom repository-ids.
e. suffix: The suffix you want to add for your custom repository-ids.

Below is how your idspaces.xml should look like:-

2. das_id_generator
This is an OOTB table, in which the dynamic values of ID-Generator are stored.
Below screenshot describes the table.

1. This should be the name of your item-descriptor. For example "order" or "user" etc.
2. Seed value refers to the point, from where your numeric part of repository-id starts.
This can be set to any numeric value. If you set this as "100000", your first repository-id will be <prefix>100000<suffix>. 
3. Batch size refers to size of IDs you want to reserve in one go. For example, you seed=1 and batch_size=10000, then ATG will reserve repository IDs starting from 1 till 10000. Once the repository id with numeric part reaches 10000, the seed value is updated to 10001 and IDs are reserved for next batch.
NOTE: Setting batch size is important from performance perspective. It is better to set batch size to higher values, as ATG would have to hit database for every batch completed.
4. Prefix: self explanatory
5. Suffix: self explanatory

Why do we need das_id_generator, when we have already defined idspaces.xml?

• Adding an entry in idspaces.xml mostly does the job, and makes an entry in das_id_generator by itself.
• Sometimes, this does not work, as ATG might chose to ignore the idspaces.xml if das_id_generator is not empty.
• If adding an entry in idspaces.xml does not work, you can put a manual entry into das_id_generator with the same values as present in your xml, to make it work.
• NEVER delete everything from das_id_generator.

3. Linking <id-space> to Repository item-descriptor.
You'd pretty much have to do nothing here.
See below screenshot, on how they are linked automatically.

1. You define an <id-space> tag and set its "name" attribute to the target item-descriptor name.

2. For each <item-descriptor> tag, you would a <table> tag, which would be your primary table. In this table, you define an attribute "id-column-name", which refers to the column of this table, which stores the repository id. Now, the <table> tag also has an optional attribute viz. "id-space-names".
If you do not define this attribute, the value of "id-space-name", is defaulted to your item-descriptor name.

3. Since no "id-space-names" is defined, the value of this attribute is set as the name of the enclosing item-descriptor i.e. "my-item-descriptor".

4. Now, the value of "name" in <id-space> tag is same as the value of "id-space-names" attribute in <table> tag.

Therefore, you did not have to do anything, but add an entry in idspaces.xml, and ATG takes care of all the linkages.

NOTE #1: For tables with primary key as multiple columns, the value of "id-space-names" attribute is defaulted to primary-table.id-column-names.
Example:-

In above case, 
primary-table-name = MY_TABLE
id-column-names = FIRST_NAME,LAST_NAME

therefore, the id-space-name property would default to MY_TABLE.FIRST_NAME,LAST_NAME

NOTE #2: You can manually change the value of "id-space-names" attribute to anything you want. But, you'd have to change the corresponding values in "idspaces.xml" and "das_id_generator".
For idspaces.xml -> "name" attribute
For das_id_generator -> "id_space_name" column.

That is pretty much it for the IdGenerators. 
We will now be moving onto last article of our "Repository Basics" chapter for cache-modes, and after that we will be starting on much awaited Commerce Articles.


Back



Next