...
Introduction
This document describes and sub-documents describe the processes how offering rules (for registrations and instructors) are generated and updated using the Offering Rule Matrix (aka Registration Rule Generator) and the Offering Rule Generator (aka Registration Rule Generator) DOS prompt tool in combination with the Core client command GetOfferingRuleMatrix.
The Offering Rule Matrix is usually extracted with the Core client command GetOfferingRuleMatrix before any changes are made to the existing rules. This ensures an accurate picture of what is in the system before any change is made. The section Offering Rule Matrix and Offering Rule Generator#Customer Customer Specific Processes below describes any customer specific requirements.
...
The customer would get a pre-filled Offering Rule Matrix (with courses and OrgProfileField values) which has been extracted from the LMS via Core command
GetOfferingRuleMatrixcommandThe Offering Rule Matrix can be split into sub-matrices so only a portion of the courses' offering rules are replaced.
Important: if a course has multiple rules a sub-matrix must contain all rules for that course - rules for one course can’t be split across multiple sub-matrices (this is automatically considered by the Core commandGetOfferingRuleMatrix).
Generate the offering rules (either instructor or registrations) using the Offering Rule Generator
Pause the offering rule background thread via command
PauseAutomaticOfferingRuleProcessing. Check the status of the background thread with with the commandGetOfferingRuleStatusto make sure the thread is paused and not in the middle of processing. It may take a bit to finish if the background thread is paused in the middle of processing.Remove previous offering rules for courses (the set of rules to be removed commands to remove offering rules is created by the Offering Rule Generator) by executing the commands provided by the Offering Rule Generator
Add new offering rules - commands created by the Offering Rule Generator
Note: The commands to add new offering rules automatically checks if the OPF single choice values existRe-evaluate the rules for courses for which the rules have been changed (student and/or instructor) via command
ReEvaluateOfferingRulesByCoursePathMatch(task https://marinels.atlassian.net/browse/
will add the proper commands to the output file of the Offering Rule Generator)Jira Legacy server System JIRA serverId 23f523ea-1678-3ca2-a1e8-2de53fd3b74a key PSDEV-760
Note: while re-evaluation is being executed you can check the progress of the re-eval command by executingGetOfferingRuleStatusin a new pages/dev client window.Continue rule background thread via command
ContinueAutomaticOfferingRuleProcessingonce all re-eval commands have finished.Check the that the background thread is not paused anymore with
GetOfferingRuleStatus
| Info |
|---|
It is not required to keep the Offering Rule Matrix on file because if the customer asks for an Offering Rule Matrix the next time we will freshly export a new matrix via comand |
| Info |
|---|
Since release v3.0.5+ any updated offering rules need to be re-evaluated manually to bring the rule engine up to date. The rules need to be run because rule changes/invalidate the ‘from’ date that the new rule engine uses internally to scan for changes. If you just let the engine run normally after rule updates it might miss people who are: (a) affected by the new rule, and (b) have not changed since the internal from date the engine records. There are command lines to run the rules only for specific courses, so if you have only changed the rules for a small set you can just re-eval the rules for those (i.e. The rule engine doesn’t care that offering rules have been updated (i.e. by the rule generator) and doesn’t make any attempt to determine if offering rules have changed. So its up to a human in this case to decide what rules have changed semantically and ensure to manually run the rules for those courses. |
| Info |
|---|
Before updating any offering rule the rule engine needs to be paused. Commands to pause/continue/check status of the automatic offering rule processing:
|
Offering Rule Matrix (general information)
The Offering Rule Matrix (aka Registration Rule Matrix) is a csv representation of registration and instructor rules for courses. The instructor and registration rules matrix’s format is are slightly different.
In general, one column determines one rule for a course. Multiple columns for the same course is are allowed - a user gets registered/added as instructor if at least one rule applies to the user. Rows specify org profile field names and their values - OPF name and values start from row 9+ for registration rule matrix and row 7+ for instructor rule matrix. An ‘x' in a course column and OPF value row specifies that a user requires that OPF value in order to get registered. ‘!x' specifies that a user gets registered if they DON’T have that specific value - see Invert-OPF-Selection for more details on '!'.Rules are able to add users as student or
The offering rule matrix may change over time/LMS versions as the offering rules' capabilities are being extended. Please refer to the corresponding LMS version in sub documents for format references.
Rows specify the requirements for a user to get registered/added as instructor.
| Info |
|---|
See sub-document with proper version for details. |
De-Registration and Remove Instructor Rules
Offering rules are able to add registrations for users or add the user as instructor. You can also specify offering rules to remove students registrations or instructors from a course, as soon as the offering rule requirements doesn’t apply to for a user anymore (i.e. due to a vessel change).
Registration Rule Matrix (v4.3+)
...
Course Name
...
TRG-OHS-2205 Working at Height Training for Workers
...
EO Costa Atlantica PDR - Technical Training Qualification Card
...
Confined Spaces
...
Course Path
...
/Root/Carnival/CMG/HESS/WorkingHeightWorker
...
/Root/Carnival/CMG/PDRs/EO/CostaAtlantica/PDR3
...
/Root/Carnival/CMG/EOT/ConfinedSpaces
...
Registration Type
...
OneTime
...
ReRegistration
...
Deactivated
...
Re-Registration Before Certificate Expiry
...
30d
...
Certificate Short Id
...
CourseCompleted1Y
...
De-Registration
...
OPF Name
...
OPF Value
...
Vessel
...
Shore
...
!x
...
Vessel
...
AIDAblue
...
x
...
Vessel
...
Costa Atlantica
...
x
...
x
...
Rank
...
Captain
...
Rank
...
Engineer
...
x
...
x
...
Rank
...
Environmental Officer
...
x
Course Name
A human readable name of the course - this is not used in any rule creation - for information only.
Course Path
Full LMS path to the course the rule applies to
Registration Type
A registration type determines the behaviour of the course like re-occurring or only one-time registration.
OneTime: one time registration - doesn't re-register as soon as a completed registration exists (uses predicate HasNoRegistrations())
ReRegistration: re-registers users in combination of a Certificate with expiry (column Certificate Short Id is mandatory). Uses predicates !HasActiveRegistrations() and CertificateWillExpire(..) (a user without a certificate will get registered because the predicate CertificateWillExpire(..) returns true for that case.
OnlyWithCompletedRegistration: registers and re-registers users who have an already completed at least one registration. This is only available in combination with a Certificate with expiry (column Certificate Short Id is mandatory). Uses predicates HasCompletedRegistrations(), !HasActiveRegistrations() and CertificateWillExpire(..)
Deactivated: a course which was in use before but has been discontinued. This creates a delete NavPage attribute to delete any rule for this course (differentiates between Student and Instructor)
No value (empty cell): no rules or delete commands are generated. Rows with no registration type value can be used to prepare courses for the future
Re-Registration Before Certificate Expiry
Only used if a certificate is used for the rule. Determines the period of time a user should be re-registered before their certificate expires. If left empty the user is re-registered on the day their certificate expires.
Value format is duration in days, months or years (i.e. 1d, 2m or 3y)
Certificate Short Id
The LMS certificate short Id which is awarded for completing the course. The certificate is used to determine the re-registration date according to the certificate’s validity duration. Only available for registration types ReRegistration and OnlyWithCompletedRegistration.
De-Registration
Set an ‘x' into a course column to add de-registration rules. An active registration would be removed as soon as the registration rule requirements won’t apply anymore (i.e. due to a vessel change)
OPF Name
Org profile name which can be used in registration rules
OPF Value
Org profile value which can be used in registration rules
Notes
If no value is set for column Registration Type no registration rule is generated for this course. This would allow to create registration rule matrices which have more courses listed than used - possibly useful to prepare registration rules for not yet published courses.
If no requirement (OPF value) is selected no registration rule is generated. However, if Registration Type ‘OneTime’ is selected but no OPF value is selected the generator outputs a warning (console). This would indicate that the rule was left empty unintentional.
Commands to delete any 'registration rules' and 'de-registration rules' are generated if the column Registration Type has any value. This is to remove any old rules.
Instructor Rule Matrix (v4.3+)
...
Course Name
...
TRG-1701 - EFFECTIVE SUPERVISION
...
TRG-1701 - EFFECTIVE SUPERVISION
...
Course Path
...
/Root/Carnival/CMG/HESS/PubHealth1
...
/Root/Carnival/CMG/HESS/PubHealth1
...
Instructor Rule Status
...
Active
...
Active
...
Remove Instructor
...
x
...
x
...
OPF Name
...
OPF Value
...
...
...
Vessel
...
Shore
...
...
Vessel
...
AIDAblue
...
x
...
...
Vessel
...
Costa Atlantica
...
x
...
Rank
...
Captain
...
...
x
...
Rank
...
Engineer
...
...
x
...
Rank
...
Environmental Officer
Course Name
A human readable name of the course - this is not used in any rule creation - for information only.
Course Path
Full LMS path to the course the rule applies to
Instructor Rule Status
Active: Instructor rule is active
Deactivated: Instructor rule is deactivated - a course was discontinued. This creates a delete NavPage attribute to delete any instructor rules for this course
no value (empty cell): no rules or delete commands are generated. Rows with no value can be used to prepare courses for the future
Remove Instructor
Set an ‘x' into a course column to add a remove instructor rules. An instructor would be removed as soon as the instructor rule requirements wouldn’t apply anymore (i.e. due to a vessel change)
OPF Name
Org profile name which can be used in instructor rules
OPF Value
Org profile value which can be used in instructor rules
Notes
...
If no requirement (OPF value) is selected for a course no instructor rules are generated for this course. However, if a Instructor Rule Status ‘Active’ is selected but no OPF value is selected the generator output a warning (console). This would indicate that the instructor rule was left empty unintentional
...
The matrix usually contains a row similar to De-Registration or Remove Instructor. Adding an 'x' in this row and course (column) will add de-registration/remove instructor rules.
Multiple columns for one course must have all the same value - either an ‘x' or nothing. Multiple offering rules for the same course can’t be mixed.
OPFs as Offering Rule Requirement
Org Profile Fields (OPFs) and values can be specified as offering rule requirement as well. An ‘x' in a course column and OPF value row specifies that a user requires that OPF value in order to get registered. ‘!x' specifies that a user gets registered/added as instructor if they DON’T have that specific value - see Invert OPF Selection for more details on '!'.
Invert OPF Selection
If you need the opposite of an OPF value as registration/instructor requirement you can invert the selected OPF value. In order to do that we use the Boolean NOT character '!' in front of 'x'.
OPF values selections can be marked with an ‘x' or ‘!x' (for the inverse) for a course (column). Selected values of one OPF name must have either all ‘x‘x' or all '!x' within one course. You can't have a mix of 'x' and '!x' in one column within one OPF name. The Offering Rule Generator will throw an exception if '!x' and 'x' are mixed within one column and OPF name.
...
For example, if all users should be registered who are NOT assigned to Vessel: Shore use '!x' for OPF value Shore. This will result in a simpler offering rule which uses !ProfileValueIn(Vessel,Shore) instead of ProfileValueIn(Vessel,[list all vessels]).
https://marinels.atlassian.net/browse/PSDEV-768
https://marinels.atlassian.net/browse/PSDEV-726
https://marinels.atlassian.net/browse/PSDEV-755
...
| 1 | Course Name | TRG-OHS-2205 Working at Height Training for Workers | |
| 2 | Course Path | /Root/Carnival/CMG/HESS/WorkingHeightWorker | |
| 3 | Registration Type | OneTime | |
| 4 | Re-Registration Before Certificate Expiry | ||
| 5 | Certificate Short Id | ||
| 6 | De-Registration | ||
| 7 | |||
| 8 | OPF Name | OPF Value | |
| 9 | Vessel | Shore | !x |
| 10 | Vessel | AIDAblue | |
| 11 | Vessel | Costa Atlantica | |
| 12 | Rank | Captain | |
| 13 | Rank | Engineer | x |
| 14 | Rank | Environmental Officer |
...
Registration Rule Matrix
| Info |
|---|
See sub-document with proper version for matrix details. |
Instructor Rule Matrix
| Info |
|---|
See sub-document with proper version for matrix details. |
Example Offering Rule Matrices
| Info |
|---|
See sub-document with proper version for matrix examples. |
Get Offering Rule Matrix via GetOfferingRuleMatrix (general information)
The command GetOfferingRuleMatrix is able to extract registration/instructor rules into an Offering Rule Matrix (csv format) accepted by the Offering Rule Generator and makes it easy to update any rules.
| Code Block |
|---|
GetOfferingRuleMatrix [orgPath] [type: 'Registration' (student) or 'Instructor'] [Optional: IsTransposed (Default to true for new format, false for original matrix format] [Optional: CsvOutputPath (Note: if not provided, outputs to command line)] [optional: -includeOpfs:"OPFName1|OPFName2|…|OPFNameX"] [optional: -includeAllOpfValues] |
All OPFs and OPF values which are being used in rules are automatically included in the matrix. That means if an OPF 'Rank' contains values Captain, Engineer and Deckhand and the rules only use Captain, only Captain is included in the matrix.
Note: switch parameters can be placed in any order - they are identified by the parameter name like '-includeAllOpfValues'
mandatory: orgPath
The organization path to extract the offering rules from
mandatory: type
The offering rule type to export - Registration or Instructor rules
semi-optional: IsTransposed
By default we only export transposed Offering Rule Matrices (IsTransposed=true). That is, csv rows for OPF values and columns for courses. Use false to get the old Offering Rule Matrix format
Note: if parameter CsvOutputPath is used, this parameter is mandatory
optional: CsvOutputPath
The Offering Rule Matrix output will be written directly into a file on the hosting server. The Offering Rule Matrix is also output to the client command window.
Note: the parameter IsTransposed must be set if this parameter is used (order of parameters is important)
optional switch parameter -includeAllOpfValues
This option will include all OPF values of an SCS OPF in case the OPF is referenced in a rule (order all OPF values alphabetically).
Example:
An OPF 'Rank' single-choice-string contains 3 values Captain, Engineer and Deckhand. If the rules only referenced Rank values Captain and Deckhand, the option -includeAllOpfValues would also include the not used OPF value Engineer in the Offering Rule Matrix.
optional switch parameter -includeOpfs:OPFName1|OPFName2|…|OPFNameX
This parameter includes all listed OPFs in the Offering Rule Matrix even if they are not referenced in any rule. All OPFs listed must be single-choice-strings. The list is still valid if an OPF is already referenced by a rule. The Offering Rule Matrix would contain all available OPF values.
If an OPF name contains white spaces, enclose the whole OPF list with double quotes - example: -includeOpfs:"Rank|Functional Position|Vessel"
...
| Info |
|---|
See sub-document with proper version for command details. |
Limitations for GetOfferingRuleMatrix
All limitations for the client command also apply to the Offering Rule Generator:
some rule predicates are not supported and can't be extracted. If a rule does contain one of those not (yet) supported predicates it will list them in the command output
Manual rules are not included in the matrix - in order to include in the matrix the rule needs to be marked as AUTO
De-registration rules are interpreted as inverts of registration rules. Therefore, asymmetric registration/de-registration rules pair will loose the asymmetry, using the registration rule as truth.
Offering Rule Generator (general information)
The Offering Rule Generator (aka Registration Rule Generator) creates LMS Core commands to replace and add new offering rules based on an Offering Rule MatricesMatrix. The tool The DOS prompt tool input can be the old (deprecated) or new transposed (preferred) format of an Offering Rule Matrix. The tool generates LMS Core client commands to remove any old registration/instructor rules for which the Offering Rule Matrix has a course for and commands to add the new registration/instructor rules.
The Offering Rule Generator tool itself can be found attached /belowto the sub-document with the proper version. Unzip the latest version to a local folder and run DOS prompt (Ctrl+R, type 'cmd' and hit enter).
| View file | ||
|---|---|---|
|
mandatory: Student/Instructor
The first parameter decides which rules should be created - student registration rules or instructor rules.
mandatory switch parameter: -f
The Offering Rule Matrix with registration/instructor rules as csv file incl. absolute path
mandatory switch parameter: -o
Output file with the commands to replace and add the registration/instructor rules.
mandatory switch parameter: -p
Organization path of the courses in them matrix
optional switch parameter: -v
If used, the DOS prompt output is more elaborate what the rule generator is doing.
Parameter Examples
Example for Registration Rules
| Code Block |
|---|
Student -f "D:\CMG\cmgtestRegRulesTest.csv" -o "D:\CMG\CmgTestRegistrationRule_Commands.txt" -p /Root/Carnival/CMG -v |
Example for Instructor Rules
| Code Block |
|---|
Instructor -f "D:\CMG\cmgtestInstructorRulesTest.csv" -o "D:\CMG\CmgTestInstructorRule_Commands.txt" -p /Root/Carnival/CMG -v |
Replace/Upload Offering Rules in LMS (in progress)
TODO: add full manual on how to replace/upload registration rules created by the Offering Rule Generator.
| Info |
|---|
Since release v3.0.5+ any updated registration rule needs to be run manually to bring the rule engine up to date. The rules need to be run because rule changes/invalidate the ‘from’ date that the new rule engine uses internally to scan for changes. If you just let the engine run normally after rule updates it might miss people who are: (a) affected by the new rule, and (b) have not changed since the internal from date the engine records. There are command lines to run the rules only for specific courses, so if you have only changed the rules for a small set you can just run the rules for those (i.e. reEvaluateOfferingRulesByCoursePathMatch (-logOnly, -debug) [RuleType (Registration, Instructor, All)] [string: startPath] [string: terminalElement] [batchSize: optional, default Core.OfferingRuleEvaluatorBatchSize]) The rule engine doesn’t care that the attributes have been updated (i.e. by the rule generator) and doesn’t make any attempt to determine if rules have changed. So its up to a human in this case to decide what rules have changed semantically and ensure to manually run the rules for those courses. |
| Info |
|---|
Before updating any registration rule the rule engine needs to be paused. Commands to pause/continue/check status of the automatic registration rule processing:
|
...
| Info |
|---|
See sub-document with proper version for details (e.g. parameters). |
| Info |
|---|
The code for the Offering Rule Generator can be found in Git PS repository MarineLS\RegistrationRuleGenerator |
Customer Specific Processes (deprecated?)
Some customers will have certain workflows how the Offering Rule Matrix will be updated and where the file will be maintained. This section contains a list and description of the common process for customers.
...
Moran Tug usually provides an updated Offering Rule Matrix file on their shared OneDrive: https://morantug-my.sharepoint.com/:f:/p/louisew/ElaWorMNr_9FkAfKd4mu6LoBfqE4pwv-8hT8p4WE0i_D8gEiPxFVLmbhlBlo4XITf3dhcB_ZrEtzDsriaCGiVRMDBiMg?e=5%3ab6a80c75e1bf4883bed19030ccb784c55%3aTmOPYT&at=9
Login as support@marinels.com
...
| Filter by label (Content by label) | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Page Properties | ||
|---|---|---|
| ||
|