Synchronizing Sources
This page is for the developer who brings source objects into the Rule Repository. A source object describes the data your rules work with: its fields, the methods rules can call, the actions they can run, and the lists of values users pick from. Users can only write rules against source objects your application has synchronized into the repository, and synchronization is the only way a source object or a new source version ever gets there. No user can create one on the screen.
For the full technical reference, with code, see Source Synchronization and Reindexing in the Implementation Guide.
Synchronizing compares each source object you give it with what the repository already holds and decides, for each one, whether to leave it alone, update its labels, or store a new source version. You can run it as often as you like: a source object that has not changed costs almost nothing and writes nothing.
The parts involved:
Context.SyncSources(..), the one call that does the work. Your application calls it on the server, whenever it suits: at startup, from an administration screen, on a schedule or during a deployment.- The sync settings (
SourceSettings), which hold the source objects to check and decide how new versions are handled.
- The sync result (
SyncResult), which tells you what happened to each source object.
Giving the Repository Your Source Objects
You can give source objects in three forms, and mix them in one call:
- .NET classes (
SourceTypes): the classes your rules evaluate, described by their attributes, as for the Rule Editor.
- Source XML documents (
SourceXmls): source objects already described as documents.
- Adaptive Source providers (
SourceProviders): source objects whose fields and methods come from your application at run time. The repository stores what the provider describes; its editors then always work from that stored description, never from the provider directly.
All three are turned into the same stored description, so they are handled the same way from then on.
A source object is identified by its full class name or its alias, never by its display name. Rebuilding your application or moving the class to another assembly keeps it the same source object. Renaming its namespace, its class or its alias makes it a different source object, and the rules written for the old one stay with the old one.
What Happens to Each Source Object
- A source object the repository has never seen is stored with its first version, and that first version is live at once: it is the only one.
- A source object the repository already has is compared with one of its stored versions:
- Nothing changed: nothing is written.
- Only labels changed (display names, descriptions, groups, formats and similar settings that cannot change how a stored rule evaluates): the stored version is updated in place, and the activity log records what changed.
- Something changed that could make a stored rule evaluate differently (a member added, removed or renamed, a type or its nullability, a minimum or maximum value, how text is compared, and similar): a new source version is stored.
Each source object is handled on its own. If one fails, the others are still processed, and the result tells you which one failed and why.
The Settings That Decide How New Versions Are Handled
| Setting |
What it decides |
Default |
ComparisonType |
Which stored version a source object is compared with: the last one, the live one, or every version (the newest match wins). |
The last version |
NewVersionsGoLive |
Whether a new version becomes the live version at once. |
No |
TestsHandling |
Which saved tests a new version gets: copied or moved from the live version or from the last one, or none. Copied and moved tests start as Not Run. |
Copied from the live version |
UserId, UserName, UserType |
Who asked for the synchronization. Leave them empty for a synchronization nobody asked for, such as one at startup; its changes are then shown as made by System. |
Empty |
TypeResolver |
A function that finds types the stored description names when your application cannot find them on its own. |
None |
Choosing NewVersionsGoLive. The live source version is what users build new rules and tests on. Set it to yes when the application that synchronizes is also the one that evaluates the rules, with the very classes it synchronizes. Leave it at no when rules run somewhere else, such as another service, another environment or a later deployment, that may still receive data shaped like the previous version. A person then makes the new version live in the repository when the time is right. See Source Versions.
Reading the Result
SyncSources(..) returns one entry per source object you gave it, saying what happened: unchanged, labels updated, source created, version created, or failed, with the IDs involved, a message and, for a failure, a control number.
The result also carries two warnings to act on:
- Source objects whose usage index needs rebuilding, for example after an upgrade. Call
Context.Reindex(..) for them; it is safe to run while users are working.
- Source objects out of step with each other, when one source object includes a class that is also synchronized as a source object of its own, and the two latest versions describe it differently.
If any source object failed, the call throws a RepositoryException that carries the full result, so you can log which ones failed and which succeeded.
See Context, SourceSettings, SyncResult and SourceResult.