Multi Version support for Custom Agents

The following steps have to be implemented to enable multi version support functionality for a custom agent::

Identifying the driver entity for the Agent server and stamping Rollout version on the data records: The server’s getJob task relies on creation of jobs based on eligible records returned by SQL query from a database table. In the context of this feature, this table is referred to as the driver entity for the agent server.
A new column ROLLOUT_VERSION needs to be added to this driver entity.

A solution should be introduced by the implementer such that during insert of records in this entity table the new ROLLOUT_VERSION column is populated with the rollout version number defined for the OMS instance. The rollout version for the OMS instance can be obtained by calling the utility method getRolloutVersion() from YCPStageRolloutUtils class. More details about this method are mentioned below.
New utility method getRolloutVersion(): A new method getRolloutVersion() is defined in the class com.yantra.shared.ycp.util. YCPStageRolloutUtils. This method is used to read the Rollout version property, yfs.rollout.version.
public static String getRolloutVersion()

The method reads the rollout version value from the property yfs.rollout.version defined in properties file and returns string value of the rollout version. The Rollout Version supports a valid non-negative Long Value from 0 to 9223372036854775807.

The Rollout version returned by the method is not modifiable at runtime and would require restarting the server once the property is modified.
Add EnableMultiVersionSupport and IsBaseVersion parameter in the agent Critieria template for the Agent:This step requires adding new agentCriteria parameters ‘EnableMultiVersionSupport’ and ‘IsBaseVersion’ to the existing list of agent Criteria parameters, such that these boolean parameters are accessible to the Agent server code.
EnableMultiVersionSupport – Allows enabling and disabling the multiversion support at agent level.

IsBaseVersion –When enabled it allows agent to pick all qualifying transaction data equal or lower than the agent’s Rollout version.
Modify agent server’s ‘getJobs’ implementation: To enable an agent server to pick only version compatible records, the agent server’s get Job task needs to be modified such that it makes use of the ‘IsBaseVersion’ and ‘EnableMultiVersionSupport ‘ agent criteria parameters and the agent server’s Rollout version.
All agent classes extend YCPAbstractAgent class and would inherit the following methods which can be used to add Rollout version to the getJobs SQL query:
- protected void appendRolloutVersionToQueryBuilder(YFCElement elemCriteria, PLTQueryBuilder oPLT, boolean bAppendAnd) {}
- protected void appendRolloutVersionToQueryBuilder(YFCElement elemCriteria, PLTQueryBuilder oPLT, boolean bAppendAnd, String sColumnName) {}
where, elemCriteria –is the Agent Criteria element

oPLT – is the PLTQueryBuilder object for the DB SQL query clause

bAppendAnd - decides wheter to append ‘AND’ to the beginning of the DB SQL query clause.

and sColumnName - is the name of the DB table column. Default is ‘ROLLOUT_VERSION’

The agent server code where the DB SQL query is being constructed can make use of the above method to add Rollout version clause to the DB SQL query.

Here’s a sample code to show the modification required in the agent server class :

Existing code :
```
PLTQueryBuilder existingQry = getOrderWhereClause();
existingQry.appendOrderBy(" ORDER BY  ORDER_HEADER_KEY") 
```
Modified Code :
```
PLTQueryBuilder existingQry = getOrderWhereClause();
appendRolloutVersionToQueryBuilder(elemCriteria ,  existingQry,  true);
existingQry.appendOrderBy(" ORDER BY  ORDER_HEADER_KEY") 
```
For example, if the agent server’s Rollout version is defined as 95101 and agent criteria parameter ‘EnableMultiVersionSupport’ is passed as Y, the SQL query would have the following additional clause:
- For IsBaseVersion=Y: AND (ROLLOUT_VERSION<=95101 OR ROLLOUT_VERSION IS NULL)
- For IsBaseVersion=N: AND (ROLLOUT_VERSION=95101)
To ensure synchronization of getJobs task between multiple agent threads, getLockParameters method should be overridden in the agent class to use the RolloutVersion. This is as explained below.
Manage locking(YFS_OBJECT_LOCK) with getLockParameters method:
1. To manage locking between version specific instances of an agent server, in getLockParameters method of the agent class use the inherited method.
protected String appendRolloutVersion(String sLockParams) {}

from YCPAbstractClass where,

sLockParams is the lock parameter string
Here’s a sample code :
```
protected String getLockParameters(Document inMessage){ 
    	String sLockParams = super.getLockParameters(inMessage);
		sLockParams = appendRolloutVersion(sLockParams);
    	return sLockParams ;
    }
```