6Net Change
Net Change
Description
Operation
The Net Change operation extends the functionality of TCC by allowing the customer to reduce the amount of transactions that are required to synchronize his system with the Taleo Enterprise application.
Purpose
The Net Change operation increases the update process efficiency when it's impossible to send only the required changes to a Taleo application, and the only alternative is to send all the data for a certain type of entity.
Net Change checks the data being sent, and removes all unchanged data from the transmission. This improves the integration process by limiting the amount of data applied to the database and making it easier to respect the volume limits.
Process
Net Change uses a flat file proprietary database system to store the data that is equivalent to the target application (e.g. Taleo Recruiting). The Net Change tables are created on an Entity by Entity basis on first time use whether it be Net Change Setup or ongoing run. This information is used to synchronize customer system and target application.
The customer's data must be provided in a standard TCC CSV file. The structure of this file must be created with the TCC Import Wizard. The customer selects the entity on which to apply the Net Change process and builds the CSV file structure by selecting the entity fields available in the entity data model. Standard Net Change templates are available.
The Net Change work-flow is defined in a standard TCC configuration file.
To start a Net Change process, the TCC execution mode (GUI or Command Line) must be invoked. The customer data CSV file is retrieved and processed by Net Change. At this point, the customer data is compared to the Net Change database and transactions are generated for all the differences that are detected. The output of this computation is a T-XML file containing all the transactions required to update the target application. The T-XML file is then wrapped in a SOAP envelope and is sent to the target application.
TCC polls the target application for an import request completion, and retrieves the result document when it's ready. The result processor output is a SOAP wrapped T-XML file that contains Net Change transaction status and attributes for each entity processed. The T-XML output file is converted to a standard TCC CSV response document.
The Net Change Result Processor validates the answer for each transaction, and those successfully processed by the target application are committed to the Net Change database. Transactions reported in error are not committed and will be reprocessed on the next Net Change run. The entities are now synchronized in application and customer databases.
Master Slave Concept
When synchronizing customer and target application data with Net Change, the Master-Slave concept must always be respected. The customer data is the Master and the modified data replicated to the target is the Slave. Modifications must always be done in the Master (CSV file). The modified data replicated to the target (Slave) with Net Change should not be modified in any way.
Certain business cases require that only some of the data be managed by Net Change in a Master-Slave relation, while the target application manages other data known only to itself. Candidate entities give us a good example. There are two types of candidates, external and internal. Internal candidates are managed by the customer system (master) and the external candidates by the Taleo Enterprise system (slave). Only the internal candidates need to be synchronized with the target application.
Recruiting Entities
Candidate
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Inactivate. Invokes entity update operation to set Internal Application to ‘N’ as specified in the CSV file.
Recover: Reactivate. Invokes entity merge operation to set Internal Application to ‘Y’ as specified in the CSV file.
Department
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Inactivate. Invokes the entity update operation to set the Department StateNumber to '1' (Inactive).
Recover: Reactivate. Invokes entity merge operation to set the Department StateNumber to '0' (Active).
Department is a hierarchical entity.
Hierarchical entities require a complete Net Change Setup prior to regular usage of Net Change.
Hierarchical entities require that you select "Skip column if value is empty" for the parent column. Otherwise it will not be possible to import the root element because its parent column will be empty.
Job Template
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Inactivate. Invokes the entity update operation to set the Job Template State Number to '3' (Inactive).
Recover: Reactivate. Invokes the entity merge operation to set the Job Template State Number to '1' (Active).
LUDS (UDSElement)
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Inactivate. Invokes the entity update operation to set the UDS Element Active attribute to false (Inactive).
Recover: Reactivate. Invokes the entity merge operation to set the UDS Element Active attribute to true (Active).
The LUDS (UDSElement) Net Change import file (load file), must have two columns defined on the same path to work correctly.
The first column defines the User Defined Selection (UDS) that contains the UDS Element. This is required because the key is UDS+UDS Element.
-
The column contains "UserDefinedSelection,Code".
Check “Use the value to search or lookup”.
Select UDSElement as Target.
The second column defines to which UDS the UDS Element belongs to.
-
The column contains "UserDefinedSelection,Code".
Check “Use the value to search or lookup”.
Select UserDefinedSelection as Target.
Check “Start a new element in the collection”.
Select UserDefinedSelection as Target.
SmartOrg Entities
Employee
Create: First invokes the recover operation then the merge operation. The Employee is created if it does not exist, or updated if it exists.
Update: Invokes entity merge operation.
Delete: Invokes the delete operation that performs a soft delete of the Employee.
Recover: First invokes the recover operation. Once the Employee is recovered, it invokes the merge operation to update the Employee.
Employee is a hierarchical entity.
Hierarchical entities require a complete Net Change Setup prior to regular usage of Net Change.
Hierarchical entities require that you select "Skip column if value is empty" for the parent column. Otherwise it will not be possible to import the root element because its parent column will be empty.
Group
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Invokes entity delete operation.
Recover: No recover on hard delete.
JobField
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Invokes entity delete operation.
Recover: No recover on hard delete.
Special Processing: Switches the zone into maintenance mode, if not already so, to perform create, update, and delete operations.
JobField is a hierarchical entity.
Hierarchical entities require a complete Net Change Setup prior to regular usage of Net Change.
Hierarchical entities require that you select "Skip column if value is empty" for the parent column. Otherwise it will not be possible to import the root element because its parent column will be empty.
Location
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Invokes entity delete operation.
Recover: No recover on hard delete.
Special Processing: Switches the zone into maintenance mode, if not already so, to perform create, update, and delete operations.
Location is a hierarchical entity.
Hierarchical entities require a complete Net Change Setup prior to regular usage of Net Change.
Hierarchical entities require that you select "Skip column if value is empty" for the parent column. Otherwise it will not be possible to import the root element because its parent column will be empty.
Organization
Create: Invokes entity merge operation.
Update: Invokes entity update/move operation. Update can generate up to two transactions, one to update and one to move. Update invokes entity update operation for changes in fields other than Parent field. For changes detected in Parent field, Update invokes move operation to link Organization to different Parent.
Delete: Invokes entity delete operation.
Recover: No recover on hard delete.
Special Processing: Switches the zone into maintenance mode, if not already so, to perform create, update, and delete operations.
Organization is a hierarchical entity.
Hierarchical entities require a complete Net Change Setup prior to regular usage of Net Change.
Hierarchical entities require that you select "Skip column if value is empty" for the parent column. Otherwise it will not be possible to import the root element because its parent column will be empty.
Position
Create: Invokes entity merge operation.
Update: Invokes entity update operation.
Delete: Inactivate. Invokes entity update operation to set the Position Active attribute to false (Inactive).
Recover: Reactivate. Invokes entity merge operation to set the Position Active attribute to true (Active).
User
Create: First invokes the recover operation then the merge operation. The User is created if it does not exist, or updated if it exists.
Update: Invokes entity update operation.
Delete: Invokes entity delete operation that performs a soft delete of the User.
Recover: First invokes the recover operation. Once the User is recovered, it invokes the merge operation to update the User.
Creating a Net Change Integration
Import Files
CSV and Load Files
Net Change requires an import definition load file and a CSV data file to function. These two files are used by Net Change for both the Setup and Computation runs.
CSV File
Net Change expects a TCC CSV file as input. The file must contain all customer data for an entity. It is:
-
Used as a reference to create the Net Change database during Setup.
-
Compared to the Net Change database to detect any changes during Computation.
Load File Creation
Use the Import Wizard to create the Net change load file that will define the CSV file structure.
Select the net-change operation. This operation is only available for Net Change supported entities.
Column Import Options
Entity Key Column
An entity must have a search key. A key can be composed of one or more fields. This key is used to retrieve corresponding information in the Net Change database.
In the Behavior section, check “Use the value to search or lookup” and “Also set this value in the entity” to create a new entity or to update an existing entity. If “Also set this value in the entity” is not checked for a create operation, certain entity types will create records without a known key value, and it will then be impossible to search for these records to update them afterwards. For other entity types, the records are not created and an error message is returned.
Collections
Do not check “Reset the collection” and “Remove element from the collection”. The Net Change process is designed to manage collection synchronization automatically.
Skip column if value is empty
To prevent the processing of fields where no value is provided, select Skip column if value is empty in the Behavior section.
Hierarchical entities such as Organization, Location, JobField, and Department, where root elements do not have a value in the parent column will be processed anyway.
Collection handling
When using the Skip column if value is empty option on a collection, it is important to understand and apply the following rules:
In the CSV file, the collection elements are not positional. Therefore it makes no sense to set the Skip column if value is empty option only on some columns of the collection.
The Skip column if value is empty option applies to the entire collection. It does NOT apply to an individual element of the collection.
A collection is empty when ALL its elements are empty.
Simple collection
A Candidate who has a collection of JobShifts.
Let say that in the CSV file we support up to three JobShifts:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com | DayJob | OnCall |
Rule 1:
In the CSV file, the collection elements are not positional. Therefore it makes no sense to set Skip column if value is empty only on some columns of the collection.
The following CSV file has exactly the same meaning as the one above:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com | OnCall | DayJob |
The point here is the DayJob value is not associated to the JobShift1.Code column. It is only an element of the JobShifts collection. The Net Change engine will load all the elements of the collection and then it will compare them with the one in its database.
Rule 2
The Skip column if value is empty option applies to the entire collection. It does NOT apply to an individual element of the collection.
First run:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com | DayJob | OnCall |
The engine will add the DayJob and OnCall job shift values in the JobShifts collection.
Second run:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com | DayJob |
Even if the OnCall job shift is no longer in the collection (empty) the entire collection in itself is not empty. The Net Change engine will generate a command to remove the OnCall job shift from the JobShifts collection.
Rule 3
A collection is empty when ALL its elements are empty.
The Skip column if value is empty option will be applicable only in the following scenario:
First run:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com | DayJob | OnCall |
DayJob and OnCall are added in the JobShifts collection.
Second run:
| Candidate, EmailAddress |
JobShift 1. Code |
JobShift 2. Code |
JobShift 3. Code |
|---|---|---|---|
| cand_001@email.com |
When the Skip column if value is empty option is set of the JobShift1.Code, JobShift2.Code and JobShift3.Code columns, then the empty values are ignored (skipped).
Complex collection
Let say that in the CSV file we support two Studies:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 1 | College A | 2 | University Z |
Rule 1
In the CSV file, the collection elements are not positional. Therefore it makes no sense to set Skip column if value is empty only on some columns of the collection.
The following CSV file as exactly the same meaning as the one above:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 2 | University Z | 1 | College A |
Rule 2
The Skip column if value is empty option applies to the entire collection. It does NOT apply to an individual element of the collection.
First run:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 1 | College A | 2 | University Z |
The engine will add the 1, College A and 2, University Z study to the Studies collection.
Second run:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 1 | College A |
Even if the 2 - University Z values are no longer in the collection (empty) the entire collection in itself is not empty. The Net Change engine will generate a command to remove the 2 – University Z study element from the Studies collection.
Rule 3
A collection is empty when ALL its elements are empty.
With the following collection, the Skip column if value is empty option will be applicable only in the following scenario:
First run:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 1 | College A | 2 | University Z |
1, College A and 2, University Z are added to the candidate Studies collection.
Second run:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com |
If the Skip column if value is empty option is set on ALL the columns of the Studies collection (Study1.DisplaySequence, Study1.Institution.Description, Study2.DisplaySequence and Study2.Institution.Description), then the empty values are ignored (skipped).
The following collection is not considered to be empty:
| Candidate. EmailAddress |
Study1. Display Sequence |
Study1. Institution. Description |
Study2. Display Sequence |
Study2. Institution. Description |
|---|---|---|---|---|
| cand_001@email.com | 1 |
Note: If you set the "Skip column if value is empty" option to only one element of the collection, the Net Change engine will automatically set it on the other elements of the collection. So take the good habit of setting that option on all the elements of the collection the same way.
Ignore Column
When the customer system has a column that is known and used only by itself. An ignore column that is never processed can be specified. To define, click Add button, select “Add an ignore column”, and click OK.
Default Column Value
A default value can be specified for columns that have no value set in the customer CSV file. For example, to use English as default value for field User.CorrespondenceLanguage, set the default value to “en” in the column advanced options:
Note that “Default Column Value” processing is not executed when “Skip column if value empty” is checked.
Non-Updatable Column
Some field values only need to be sent to the target application once, usually during the create operation. Once the column is defined as Non-Updatable, the field values contained in that column are not sent to the target application in an update operation.
This advanced option is Net Change specific. No other TCC functionality uses it. Set updatable value to false in the column advanced options:
When all columns are defined, save the input file and generate the CSV file.
Net Change Partial Load
The Net Change partial load processing instruction limits the extraction of collection type relation items to those specified in the customer data file during Net Change Setup. This subset of relation items is used to populate the Net Change database. This allows customers to work with partial collection data sets without creating deletes in their zone with ongoing Net Change runs.
-
netchange.load.partial
Possible values are true (case-insensitive) or false. Anything other than true is considered false.
Setting this processing instruction on a field rather than on a relation has no effect.
Multiple Parameter Entities
The User, Organization, Location, and JobField entity import services have more than one parameter.
During Net Change CSV load file creation, it is mandatory that every available parameter of the service be included in the file. Not doing so will cause Net Change to fail.
The User import service exposes three parameters:
-
User
-
Password
-
ForceChangePassword
You must include the Password and ForceChangePassword simple parameters, and at least one field from the User entity parameter in the CSV file.
The Organization, Location, and JobField import services expose two parameters:
-
Organization, Location, or JobField
-
Sequence
You must include the Sequence simple parameter, and at least one field from the Organization, Location, or JobField entity parameter in the CSV file.
In the Behavior section check “Skip column if empty” for the columns that might not contain a value.
Hierarchical Trees
Net Change must apply a set of special processing rules to entities that are part of a hierarchical tree. For example, before deleting a parent node, all of its children must have been deleted. Net Change recreates the entire hierarchical tree to correctly sequence the order of operations required to synchronize the target application.
Hierarchical Entities:
Department
Employee
JobField
Location
Organization
There are two modes for hierarchical entities, full and partial. The full mode allows only a single root element, while the partial mode allows multiple root elements. By default the mode is full for hierarchical entities. The Employee entity can be full or partial.
The customer input CSV file must contain the entire data set of the hierarchical tree. The first line of the CSV file must be the root element, and will have no parent. In the Parent column, make sure “Skip column if value is empty” is checked. For partial mode, the root elements must precede their children in the CSV file. See partial example below.
"Code(Child)","Parent,Code","Description",... "-1",,"Organization",... "DIV-A","-1","Division A",... "DIV-B","-1","Division B",... "T1","DIV-A","Team 1",... "T2","DIV-A","Team 2",... "T3","DIV-B","Team 3",...
"Code(Child)","Parent,Code","Description",... "-1",,"Boss",... "MNG-A","-1","Manager A",... "E1","MNG-A","Employee 1",... "E2","MNG-A","Employee 2",... "MNG-B",,"Manager B",... "E3","MNG-B","Employee 3",...
Errors
Hierarchical entities must be handled properly to prevent errors. The three main causes that generate errors using Net Change with hierarchical entities (HE) are:
-
Using a parent relation that doesn't exist.
Each time you create an HE that refers to a parent that doesn't exist in Monarch, you will get this kind of error.
Monarch Functional Error: The parent node associated to this key has not been found: …
-
Working with a partial “tree”.
Each time you create an HE that refers to a parent that doesn't exist in partial “tree” but exists in Monarch, you will get this kind of error.
Monarch Functional Error: The parent node associated to this key has not been found: …
-
Transactions done directly in the Monarch application.
-
We can generate an invalid structure in “Net Change database ” and destroy the “Net Change process” when we are doing modification in the UI of Monarch (Element in Green) while doing Net Change with TCC.
If we do a “Net Change Setup” action using an existing element ( in Monarch, Element J) that is not directly linked to an element of the partial “tree” (used in “Net Change”), the “tree” is not valid anymore.
-
If we do a “Net Change Setup” action using an existing element (in Monarch, Element E) that is directly link to an element of the partial “tree” (used in the “Net Change”), the “tree” is valid and it's possible to do Net Change if we do a “Setup” first and then a “Computation”.
-
Examples:
-
Case-1: Do Net Change Computation only (Move “Element J” under “Element B”).
Monarch Functional Error: …You cannot update the following field: BaseComposite.Parent.
Note that the field value and the supplied value don't match (as described in 3-a).
-
Case-2: Do Net Change Setup & Computation (Move “Element J” under “Element B”).
-
Setup runs with success.
-
Computation TCC WorkFlow Error: The parent node associated to this key has not been found …. (as described in 3-a).
-
-
Case-3: Do Net Change Computation only (Move “Element E” under “Element B”).
Monarch Functional Error: …You cannot update the following field: BaseComposite.Parent.
Note that the field value and the supplied value don't match (as described on 3-b).
-
Case-4: Do Net Change Setup & Computation (Move “Element E” under “Element B”).
Setup runs with success.
Computation runs with success (as described on 3-b).
The Partial hierarchical entity “Employee” is not impacted by the behavior described above. When doing Net Change with an Employee, you can get an empty parent or a parent that is not present in your Net Change Database.
We recommend that you always work with a full structure and respect the “Mater-Slave” concept when doing your Net Change otherwise you can end up with a Employee structure that does not represent your company.
CSV File Properties
Special header properties can be added to customize Net Change processing behavior. They are placed at the beginning of the CSV file.
CSV Properties section:
#BEGINPROPERTIES PropertyName=PropertyValue #ENDPROPERTIES
CSVLineCount
This property indicates to Net Change the number of data rows in the request CSV file (excluding the column header row). A mismatch is considered an error.
Example:
#BEGINPROPERTIES CSVLineCount=2 #ENDPROPERTIES ColumnHeader1,ColumnHeader2,ColumnHeader3 Line1_CH1_Data,Line1_CH2_Data,Line1_CH3_Data Line2_CH1_Data,Line2_CH2_Data,Line2_CH3_Data
Import File Modification
Net Change import file modification may or may not have any impact on Net Change. Here are the possible cases:
Entity Search Key Modification
If the defined entity search key must be changed after the first Net Change run, the Net Change database for this entity must be recreated. This can be achieved using the Net Change Setup feature.
Adding a new column
Net Change sees the new column as a new entity field.
When “Skip column if value is empty” is NOT checked, an update is generated for every record.
When “Skip column if value is empty” is checked, an update is only generated for records that have a value for the new column.
Note that only the fields that are detected as changed are sent to the target application.
Removal of a column
If a column is removed, the data associated to this column is no longer part of the Net Change computation process and no actions/updates are sent to the zone.
Changing the column from Updatable to Non-Updatable
The next Net Change computation does not take into account the value of this column for an update operation.
Configuration Files
Setup and Computation Configuration Files
Net Change requires a Setup and a Computation configuration file for each individual integration point. The Setup configuration file is used to create and populate the Net Change database. The Computation configuration file is used for Net Change ongoing runs. The differences between the files are found in the pre and post processing steps.
Configuration File Creation
Use the Configuration Wizard to create the Net change configuration file.
Select Based on another type of request message and the product for that integration point.
All communications with the target application use T-SOAP.
Select T-SOAP in the message type selection window.
Select Endpoint to authenticate yourself to the target application.
General Tab
Net Change requires that both the request and response files be of CSV type.
Pre-processing Steps
Setup
Add a Net Change Setup custom step.
Select the load file to use as import file for this integration. This is the same file as the one used for Computation.
Add a Wrap SOAP step
Select Import in the Action panel.
Computation
Add a Net Change Computation custom step.
Select the load file to use as import file for this integration. This is the same file as the one used for Setup.
Thresholds
You can define thresholds, to limit the number of actions that Net Change applies to the target application. For example, in normal operation mode, the generation of delete actions deleting almost all of the target application database should be considered as an erroneous situation and should be prevented.
The threshold can be defined as a percentage or a number of records. For example a value of 25% stops the Net Change computation and process if more that 250 records out of a 1000 are generating Net Change actions.
An absolute value can be specified that will stop the Net Change computation and process as soon as the number of actions is reached. The number of record in the file has no influence on this threshold. A file of 50 records or 1000 records will stop after 25 processed records.
To disable the threshold, set the value to -1.
A threshold must be defined for each Net Change action: Create, Update and Delete. Recommended values for thresholds are as follow:
-
Threshold for element creation: 10%
-
Threshold for element update: 10%
-
Threshold for element deletion: 10%
Add a Wrap SOAP step
Select Import in the Action panel.
Post-processing Steps
Setup
Add a Net Change Result Processor custom step.
Report Filtering
Filters are available to control the output of the Net Change result file:
All: Detailed status of all actions are reported.
Error only: Detailed status of failed actions are reported.
Error and warning only: Detailed status of actions that have generated an error or a warning message are reported.
When performing a Net Change Setup, this step generates a simple XML report that indicates how many entities have been processed during the operation. Since a Net Change Setup does not import any data into the product, there are no entity results in this report.
Add a Net Change Result Processor custom step.
This step is optional for Net Change Setup. It transforms the file generated by the Net Change Result Processor into a standard TCC CSV file.
Select the load file to use as import file for this integration. This is the same file as the one used for Computation.
Select the Output properties check box to include the CSV file properties in the result file.
Property |
Description |
Example |
|---|---|---|
CSVLineCount |
Number of data rows present in the CSV result file (excluding the column header row). In the case of an Net Change Setup process, this value will always be 0. | CSVLineCount=0 |
total.[entity] |
Total number of entities processed. If no entities are processed by the target application, this property is not included. | total.jobfield=96 |
duration |
Time taken by target application to process entire import file generated by Net Change engine. In the case of an Net Change Setup, no entities are imported in the customer zone, the duration should be close to 0. | duration=0:00:00.106 |
The file generated by Net Change Result Transformation has the following format (Note that if in the configuration general tab you have specified to not output the column header, then no header will be included in the result CSV file):
#BEGINPROPERTIES PropertyName=PropertyValue #ENDPROPERTIES "Index","Identifier","Status","TransactionType","Result","Message"
CSV Result File Description
Net Change Setup processing does not generate any rows in the CSV file since no imports are done on the customer zone.
Computation
Add a Net Change Result Processor custom step.
Report Filtering
Filters are available to control the output of the Net Change result file:
All: Detailed status of all actions are reported.
Error only: Detailed status of failed actions are reported.
Error and warning only: Detailed status of actions that have generated an error or a warning message are reported.
This step processes the target application result file to update the local Net Change reference database in order to reflect the state of the target application.
For each record, if the transaction was successfully processed, then the local Net Change reference database is updated with the new value. If the record was not successfully processed, the Net Change reference database is not updated.
Add a Net Change Result Processor custom step.
This step transforms the file generated by the Net Change Result Processor into a standard TCC CSV file.
Select the load file to use as import file for this integration. This is the same file as the one used for Computation.
Select the Output properties check box to include the CSV file properties in the result file.
Property |
Description |
Example |
|---|---|---|
CSVLineCount |
Number of data rows present in the CSV result file (excluding the column header row). | CSVLineCount=96 |
total.[entity] |
Total number of entities processed. If no entities are processed by the target application, this property is not included. |
total.jobfield=96 |
total.[entity].create |
Total number of entities created. If no entities are created, this property is not included. |
total.jobfield.create=48 |
total.[entity].update |
Total number of entities that are updated. If no entities are updated, this property is not included. |
total.jobfield.update=10 |
total.[entity].delete |
Total number of entities that are deleted. If no entities are deleted, this property is not included. |
total.jobfield.delete=10 |
total.status.success |
Number of entities that are processed with success by the target application. If no success has been detected, this property is included with a value of 0. |
total.status.success=30 |
total.status.error |
Number of entities reported in error at the target application. If no error is reported, this property is included with a value of 0. |
total.status.error=48 |
total.warning |
Number of warning messages generated by the target application. If no warning is generated, this property is included with a value of 0. |
total.warning=18 |
duration |
Time taken by target application to process entire import file generated by Net Change engine. | duration=0:00:03.2890 |
The file generated by Net Change Result Transformation has the following format (Note that if in the configuration general tab you have specified to not output the column header, then no header will be included in the result CSV file):
#BEGINPROPERTIES PropertyName=PropertyValue #ENDPROPERTIES "Index","Identifier","Status","TransactionType","Result","Message"
Column Name |
Description |
|---|---|
Index |
Row sequential number |
Identifier |
Unique key name used Net Change to identify the entity. This key is composed of the following sub sections: Entity Name|Net Change Action|Entity Search Key Id Example: JobTemplate|create|NC2_00791130771 |
Status |
Net Change Result Status for the entity. Indicates whether Net Change operation completed with success or error. The possible values are:
|
TransactionType |
Target application transaction type to perform Net Change action. For example, if an update has been detected for the job template entity, the transaction type will be “jobtemplate.update”. Note that the action done on the target application might be different than the Net Change action. For example, in the case of inactivation when a Net Change delete action is detected, an update operation is required. In this case the Net Change Action will be delete and the transaction type will be update. |
Result |
Not used for now. |
Message |
Detailed message about the error or the warning returned by the target application. |
Using Net Change
Hierarchical Entities Setup
Special care must be taken with hierarchical entities during Net Change Setup. You must make sure to respect the hierarchical structure in order to maintain consistency.
Extract Net Change Setup Data
Net Change Setup extracts from the target application data matching the data keys present in the customer CSV file and fills the Net Change database. Other data, not specified in the CSV file that exist in the target application is not downloaded to the Net Change database.
After Net Change Setup
After a Net Change Setup, a standard Net Change process can be started to synchronize customer data with the target application. Data that is the same does not generate Net Change transactions. Different data generates transactions, customer data that does not exist in the target application generates a create transaction.
First Net Change
Final Result
Invalid Requests
Different Structures
The Net Change Setup of the Net Change database is performed with the keys provided in the Customer input file. The Net Change Setup will fail to create a valid hierarchical structure if the Customer and Taleo structures do not match.
User Entity Constraints
During User Net Change Setup, it is impossible to extract the values for the Password and ForceChangePassword parameters. Therefore, the Net change database is not perfectly synchronized with the Taleo zone.
The User Password and ForceChangePassword parameters require special treatment during first Net Change. Protecting or overwriting the values for those parameters in the Taleo zone determines the treatment to apply.
Protect Values
To protect a password that has already been modified by the user, specify the columns corresponding to the Password and ForceChangePassword parameters as non-updatable. In the advanced options section, enter updatable for the name and false for the value.
Overwrite Values
To overwrite the Password and ForceChangePassword parameter values in the Taleo zone, set the updatable value to true in the advanced options section. This is the default value for the option, therefore it does not need to be specified. During Net change first run all values will be overwritten and the databases will be synchronized.
Setup Usage
The Net Change Setup feature must be used in the implementation phase to fill the Net Change database with target application data.
It can also be used to resynchronize the Net Change database with the target application data. This should be done only in exceptional cases.
It must also be used when the entity key changes. The Net Change tables need to be recreated.
Note that only the Net Change tables for the entity being processed will be deleted at the start of the Net Change Setup process.
Also note that no backup is made before erasing the tables.
Known Limitations
The following limitations must be taken into account when implementing a solution that uses Net Change.
Entity Delete Mode Selection
The delete mode is currently defined in the entity Net Change definition file (feature pack). Only one delete mode is defined. The actual solution does not support the selection of different delete modes per configuration.
Attachment File Support
Attachment files are not supported by Net Change.
Entity Key Modification
If you change a defined entity key after the first Net Change run, the Net Change database for this entity must be recreated. Use the Net Change Setup feature to recreate Net Change database.
storage.properties File Modification
The storage.properties file parameters determine how Net Change stores data in its reference database. The properties than can be set are data compression and encryption, repository location, storage unit interface, and block size.
The values defined in the storage.properties file (UseCompression, EncryptionMode, StorageUnitImplementation, and FileStorageUnit.DefaultBlockSize) must not be changed after the first Net Change run.
If this is required, ALL Net Change database tables must be recreated. Perform an Net Change Setup on every entity subject to a Net Change process.
Multiple Database Synchronization
Net Change maintains a single database to synchronize a customer system data and a Taleo Product data. This implies installing and running a separate instance of TCC for each customer system synchronizing with a Taleo product. For example, synchronizing three different Human Resource Information System (HRIS) databases with one Taleo zone means installing and running three separate instances on TCC. The data provided for synchronization by each HRIS must be mutually exclusive to prevent reversal of operations. For example, if one system deletes an entity on an ongoing integration and the same entity exists on another system, it will be recreated when that system runs its integration.
The same principle applies to synchronizing customer HRIS data with several Taleo zones. For example, synchronizing one customer HRIS with a Taleo production zone and a Taleo staging zone requires installing and running two separate instances of TCC.
Net Change Configuration
The TCC Net Change plug-in uses a configuration file to define properties related to its database. The file name is storage.properties
Properties
-
UseCompression:
Determines the compression or not of stored Net Change data. This property is set to true in the default configuration file, the data is compressed. If the property is removed from the configuration file, the value will default to false, the data will not be compressed.
-
EncryptionMode:
Determines the type of encryption to apply on Net Change data. This property is set to 2 in the default configuration file.
0=No encryption
1=Custom TCC internal encryption
2=AES 128-bit ciphers
-
RepositoryLocation:
Determines Net Change data files repository location. This property is empty in the default configuration file. The default location is [TCCInstallFolder]/system/repository. If the property is absent or empty the default location is used.
-
StorageUnitImplementation:
Advanced property, modify only as instructed by Taleo.
Determines Storage Unit interface implementation. The default value is
com.taleo.integration.storage.FileStorageUnitand is the only value supported at this time. -
FileStorageUnit.DefaultBlockSize:
Advanced property, modify only as instructed by Taleo.
Determines file storage block size in KB (min. 1, max. 128). This property is set to 1 in the default configuration file. If the value is not specified or invalid, the value will default to 2.
Overriding a plug-in configuration location
There are two ways to specify the location of plug-in configuration files:
Default:
-
By default, the plug-in configuration file location is: [PLUGIN_FOLDER]\[PLUGIN_COLLECTION_NAME]\configuration.
-
Nothing special needs to be setup.
-
E.g.: The file “storage.properties” will be located at “c:\Program Files\Taleo Connect Client\extensions\plugins\tcc-netchange\storage.properties”
Root configuration folder:
-
To change the location of plug-in configuration file for every plug-in at the same time.
-
System Property: “com.taleo.integration.client.extensions.plugins.configuration.dir”.
-
E.g: com.taleo.integration.client.extensions.plugins.configuration.dir=c:\PluginConfig.The file “storage.properties” will be located at: c:\PluginConfig\tcc-netchange\storage.properties.