Maintaining Syntaxes
Overview
Syntax supports the need for every laboratory to have a series of incremental numbers and mechanisms to determine the next code or name assigned to a particular entity, using either simple syntax definitions, or more complicated syntax definitions involving script.
Syntaxes are available in CCLAS 6 to configure the ways that the system generates a range of unique and sequential string or number values, for a range of CCLAS entities. These syntaxes consist of system syntaxes (those syntaxes with a specific code that the system looks for to then use), and those that are configurable at both organisation and laboratory level.
The generation uses a pattern and counters, and can use properties values of the related entity.
Once a syntax definition is applied, it generates the entity with the specified format. When some entities are created, the entity's code is created using a syntax with a particular syntax code, and when other entities are created, the entity's code is created using a syntax selected by the user.
Multiple entities can be generated at once, with each having a specified increment value in the naming convention.
Syntaxes can reference syntax variables and script. Syntax variables can have org-scope or lab-scope. Syntax variables can use attributes related to the entity it is coding, including the invoking of custom script. Refer to the API for the related entity.
Process
Syntaxes are maintained using the CCSNTX—Syntax application.
Syntaxes returned from a search can be exported to a report. Refer to Generating Grid Reports. Available report templates are defined in the SEARCH_REPORT_CCSNTX application preference.
Syntaxes are created either with org-scope or lab-scope. An organisation or laboratory can contain multiple syntaxes.
Whilst syntaxes are typically set at the organisation level and inherited at laboratory level, syntaxes are also specified for new laboratories that wish to use a slightly different configuration than the organisation. The same sorts of checks and updates should also be performed for the laboratory preferences, if they are to be different to the organisation.
A syntax cannot be deleted if it is linked to by an entity.
Syntaxes by Entity Type
Syntaxes can be classified by type: Job Code, Job Name, Job Description, Batch Code, Batch Name, Sample, Quote, Standard Lot, Invoice, Statement, Report, Report Request, Report Filename, Instrument Uploader, Container Name, Invoice Request, Other.
The following attributes are generated using an org-scope or lab-scope syntax.
| Syntax use | Syntax Type | Syntax Code | Comments |
|---|---|---|---|
|
Syntax use |
Syntax type |
Syntax code |
Comments |
|
Client's Code, when the client is generated via script |
Other |
CLIENT_CODE_SYNTAX |
|
|
Contact's Code, when the contact is generated via script |
Other |
CONTACT_CODE_SYNTAX |
|
|
Quote's Code |
Quote |
QUOTE_CODE_SYNTAX |
Where the syntax does not exist, then the code is generated using a simple numbering pattern set on the laboratory. |
|
Standard lot's Code, when the standard lot is generated via script |
Standard Lot |
Defined by the script |
|
|
Job's Code |
Job Code |
JOB_CODE_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Job's Name, for a production, proposal, internal, template or schedule job |
Job Name |
JOB_NAME_SYNTAX |
|
|
Job's Name, for a production or internal job created from a schedule or draft job |
Job Name |
As defined by the schedule job's Production Job Name Syntax Code |
|
|
Job's Description |
Job Description |
As defined by the schedule job's Production Description Name Syntax Code |
|
|
Job's Code, for a laboratory or subcontract batch job |
Batch Code |
BATCH_CODE_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Job's Name, for a laboratory or subcontract batch job |
Batch Name |
Defined by the DEFAULT_BATCH_NAME_SYNTAX or the DEFAULT_SUBCONTRACT_NAME_SYNTAX application preference |
|
|
Sample's Code |
Other |
SAMPLE_CODE_SYNTAX |
Only one syntax per job type should be in use per current lab or organisation. |
|
Sample's Name, for a sample in a production, proposal, internal, template or schedule job |
Sample Name |
SAMPLE_NAME_SYNTAX |
The syntax generator first looks for a script exists that has a code of SAMPLE_NAME_SYNTAX and runs it to establish variables for use by the syntax script. This allows for a common configuration where the sample name is generated by a concatenation of the Job Name + "." + a running sequence of numbers (001 onwards). |
|
Sample's Name, for a sample in a production or internal job created from a schedule or draft job |
Sample Name |
As defined by the schedule sample's Production Client Sample Name Syntax Code |
|
|
Sample's Description, for a sample in a production or internal job created from a schedule job |
Sample |
As defined by the schedule sample's Production Description Syntax Code |
|
|
Sample's Client Sample Name |
|
Entered by the user |
The user can reference a syntax to generate client sample names: Syntax(SYNTAX_CODE) To create multiple outputs, use the format: {<SyntaxDefinition>}n. Note that the length of the sample's Client Sample Name field is 4000 characters to cater for example, 200 sample where each client sample name is 20 characters. |
|
Sample's Description |
|
Entered by the user |
The user can reference a syntax to generate sample descriptions: Syntax(SYNTAX_CODE). To create multiple outputs, use the format: {<SyntaxDefinition>}n. Note that the length of the sample's Description field is 4000 characters to cater for example, 200 samples where each description is 20 characters. |
|
Sample portion's Multi Container Name |
Container Name |
Defined by the container type's Container Name Syntax Code |
|
|
Instrument file upload's Code |
Instrument Uploader |
UPLOADER_CODE_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Report request's Code |
Report Request |
REP_REQ_CODE_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Report request's Name |
Report Request |
REP_REQ_NAME_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Report request's Email Subject Text |
Email Subject |
EMAIL_SUBJECT_TEXT |
|
|
Report request's Email Message Text |
Email Message |
EMAIL_MESSAGE_TEXT |
|
|
Report request's Code, for a report request created from workbook |
Report Request |
WKBK_REP_REQ_CODE |
Only one syntax should be in use per current lab or organisation. |
|
Report request's Name, for a report request created from workbook |
Report Request |
WKBK_REP_REQ_NAME |
Only one syntax should be in use per current lab or organisation. |
|
Report's Report Code, for a preliminary or final certificate report |
Report |
REPORT_CODE_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Report's Report Number, for a preliminary or final certificate report |
Report Request |
REPORT_NUMBER_SYNTAX |
Only one syntax should be in use per current lab or organisation. |
|
Report's Report Filename, for a preliminary or final certificate report |
Report Filename |
Defined by the report template The report request's Filename Syntax Code is inherited from the report template's Output File Name Syntax and is updatable by the user where a fixed report request's File Name is not entered. |
|
|
Report's Report Code, for a report created from workbook |
Report |
Selected by the user |
Only one syntax should be in use per current lab or organisation. |
|
Invoice's Name |
Invoice |
INVOICE_NAME |
|
|
Invoice's Number, for a production invoice |
Invoice |
INVOICE_SYNTAX_CODE |
Where this syntax is not defined, the laboratory's Invoice Number Pattern and Invoice Last Used Number is used to generate the invoice number. |
|
Invoice's Number, for a proposal invoice |
Invoice |
PROPOSAL_SYNTAX_CODE |
Where this syntax is not defined, the laboratory's Proposal Invoice Pattern and Proposal Invoice Last Used Number is used to generate the invoice number. |
|
Invoice's Number, for a credit note |
Invoice |
CREDIT_SYNTAX_CODE |
Where this syntax is not defined, the laboratory's Credit Note Pattern and Credit Note Last Used Number is used to generate the credit note number. |
|
Invoice's File Name |
Invoice |
Selected by the user |
The i is generated using syntax from the current laboratory or organisation, where the syntax's Syntax Type is Invoice and the Syntax Code is selected by the user. |
|
Invoice's Email Subject Text |
Invoice |
EMAIL_SUBJECT_TEXT |
|
|
Invoice's Email Message Text |
Invoice |
EMAIL_MESSAGE_TEXT |
|
|
Report's Report Filename, for statement grid reports |
Statement |
As selected by the user |
|
|
Report's Report Filename, for grid reports |
Report Filename |
As defined by the report template |
|
Example of generating a job code from the Job Code syntax:
$yyyy/$MM/$dd $Job.code.asEllipseValue-#####
may return:
2018/06/04 Lab1Job123-00001
Defining Syntax Sequences
A syntax can have:
- An outer sequence with increment, floor, ceiling and last number used
- An inner sequence with increment, floor, ceiling, last number used and a flag to indicate whether the inner sequence is reset upon each use
- Syntax text list for a text sequence.
Syntax character mapping is as follows:
|
Inner |
Outer |
|---|---|
|
& |
# |
|
& |
! |
|
& |
@ |
|
! |
# |
|
@ |
# |
|
@ |
! |
where:
- #—Outer sequence of incremented numbers. Only one group of # characters is allowed, for example, ## or ###.
- &—Inner sequence of incremented numbers that must be completed before the outer sequence is incremented. Only one group of & characters is allowed, for example, & or &&.
- !—For the insertion of strings from the text list. If present, both # and & cannot be in the syntax. If # is present, the ! is an inner sequence, if & is present, the ! is an outer sequence.
The syntax portion sequence control string is a portion of the syntax string that is used to decide which numbering sequence should be used to increment the outer sequence.
For example, for the syntax:
$yyyy-$MMM $LabCode ###
and a syntax portion start of 1 and a syntax portion length of 4, if the syntax was not previously used in 202021 to generate output, but was used to generate output on 24/Jan/202021 in the LAB1 laboratory, then the generated output would be 202021-JAN LAB1 001, the syntax portion control string would start at position 1 in that string and be 4 characters long, that is, it would be "202021". The "001" counter would be set against "202021".
If this code was used again on 3/Apr/202021 in the LAB1 laboratory, then the generated output would be 202021-APR LAB1 002, the syntax portion control string would be "202021", and the "001" counter would be incremented to have "002" set against "202021". If this code was used again on 8/Sep/202021 in the LAB1 laboratory, then the generated output would be 202021-SEP LAB1 003, the syntax portion control string would be "202021". The "002" counter would be incremented to have "003" set against "202021".
However, if this code was used again in the following year and the syntax was not previously used in that year to generate output, then the generated output would end in "001" again and the syntax portion control string would start at position 1 in that string and be 4 characters long, that is, the length of the character year. The "001" counter would be set against the following year.
If the syntax portion sequence control string used a client code instead of the year, the counter would be set against each client code that used the syntax.
Configuring a Syntax to use the Database's Next Sequence
Where multiple codes or names are required at a time from a syntax, the syntax generator uses the default mechanism which locks the syntax record, after which the system repeats the following steps for as many codes or names as are required: a) generate one code or name at a time, b) increments the last number used in the syntax, c) performs other database activities for the current process; then after this has finished, unlocks the syntax record.
Where many codes or names are required at a time, the default mechanism involves an extended locking process in which conflicts and time-outs can occur when a large number of concurrent users are registering samples.
To overcome this, a syntax is configured to bypass the default mechanism to instead use the database's next sequence to generate the multiple codes or names. Where the syntax's outer and inner sequence ceiling are both set to 0, the syntax generator uses the bypass.
Change the next sequence number a syntax is to use
Where the syntax string contains both the # and & string patterns, but only one of the Outer Seq Ceiling and Inner Seq Ceiling values is set to 0, then an error is raised.
Where the syntax string only contains the # string pattern, and the Outer Seq Ceiling or Inner Seq Ceiling value is set to 0, then the syntax generator uses the database's next sequence.
Where the syntax string only contains the # string pattern, and neither the Outer Seq Ceiling and Inner Seq Ceiling value is set to 0, then the syntax generator uses the default mechanism.
Note: Where the bypass mechanism is in place, increments are ignored.
Examples for Sample Name Syntax
1) Where the syntax string only contains the # string pattern:
${String Lab=Laboratory.name.asEllipseValue
return Lab}$dd$MM-##
| Outer Seq Floor | Outer Seq Ceiling | Outer Seq Increment | Last No | Inner Seq Floor | Inner Seq Ceiling | Inner Seq Increment | Last No | Inner Seq Reset Each Use | Text Sequence Text List |
|---|---|---|---|---|---|---|---|---|---|
|
1 |
0 |
1 |
0 |
|
0 |
|
|
|
|
|
Output: E2E_LAB1803-12756 E2E_LAB1803-12757 E2E_LAB1803-12758 E2E_LAB1803-12759 E2E_LAB1803-12760 E2E_LAB1803-12761 E2E_LAB1803-12762 E2E_LAB1803-12763 E2E_LAB1803-12764 E2E_LAB1803-12765 |
|||||||||
|
1 |
0 |
2 |
0 |
|
0 |
|
|
|
|
|
Output: E2E_LAB1803-12766 E2E_LAB1803-12767 E2E_LAB1803-12768 E2E_LAB1803-12769 E2E_LAB1803-12770 E2E_LAB1803-12771 E2E_LAB1803-12772 E2E_LAB1803-12773 E2E_LAB1803-12774 E2E_LAB1803-12775 |
|||||||||
|
1 |
99 |
1 |
20 |
|
|
|
|
|
|
|
Output: E2E_LAB1803-21 E2E_LAB1803-22 E2E_LAB1803-23 E2E_LAB1803-24 E2E_LAB1803-25 E2E_LAB1803-26 E2E_LAB1803-27 E2E_LAB1803-28 E2E_LAB1803-29 E2E_LAB1803-30 |
|||||||||
|
1 |
99 |
2 |
20 |
|
|
|
|
|
|
|
Output: E2E_LAB1803-22 E2E_LAB1803-24 E2E_LAB1803-26 E2E_LAB1803-28 E2E_LAB1803-30 E2E_LAB1803-32 E2E_LAB1803-34 E2E_LAB1803-36 E2E_LAB1803-38 E2E_LAB1803-40 |
|||||||||
2) Where the syntax string contains both the # and & string patterns:
${String Lab=Laboratory.name.asEllipseValue
return Lab}$dd$MM-##-&&
| Outer Seq Floor | Outer Seq Ceiling | Outer Seq Increment | Last No | Inner Seq Floor | Inner Seq Ciling | Inner Seq Increment | Last No | Inner Seq Reset Each Use | Text Sequence Text List |
|---|---|---|---|---|---|---|---|---|---|
|
1 |
0 |
1 |
0 |
1 |
0 |
1 |
0 |
Y |
|
| Output:
E2E_LAB1803-12776-12776 E2E_LAB1803-12777-12777 E2E_LAB1803-12778-12778 E2E_LAB1803-12779-12779 E2E_LAB1803-12780-12780 E2E_LAB1803-12781-12781 E2E_LAB1803-12782-12782 E2E_LAB1803-12783-12783 E2E_LAB1803-12784-12784 E2E_LAB1803-12785-12785 |
|||||||||
|
1 |
0 |
2 |
0 |
1 |
0 |
1 |
0 |
Y |
|
| Output:
E2E_LAB1803-12786-12786 E2E_LAB1803-12787-12787 E2E_LAB1803-12788-12788 E2E_LAB1803-12789-12789 E2E_LAB1803-12790-12790 E2E_LAB1803-12791-12791 E2E_LAB1803-12792-12792 E2E_LAB1803-12793-12793 E2E_LAB1803-12794-12794 E2E_LAB1803-12795-12795 |
|||||||||
|
1 |
99 |
1 |
2 |
1 |
5 |
1 |
0 |
Y |
|
| Output:
E2E_LAB1803-03-01 E2E_LAB1803-03-02 E2E_LAB1803-03-03 E2E_LAB1803-03-04 E2E_LAB1803-03-05 E2E_LAB1803-04-01 E2E_LAB1803-04-02 E2E_LAB1803-04-03 E2E_LAB1803-04-04 E2E_LAB1803-04-05 |
|||||||||
|
1 |
99 |
2 |
2 |
1 |
5 |
1 |
0 |
Y |
|
|
Output: E2E_LAB1803-04-01 E2E_LAB1803-04-02 E2E_LAB1803-04-03 E2E_LAB1803-04-04 E2E_LAB1803-04-05 E2E_LAB1803-06-01 E2E_LAB1803-06-02 E2E_LAB1803-06-03 E2E_LAB1803-06-04 E2E_LAB1803-06-05 |
|||||||||
3) Where the syntax string contains both the # and ! string patterns:
${String Lab=Laboratory.name.asEllipseValue
return Lab}$dd$MM-##-!
| Outer Seq Floor | Outer Seq Ceiling | Outer Seq Increment | Last No | Inner Seq Floor | Inner Seq Ceiling | Inner Seq Increment | Last No | Inner Seq Reset Each Use | Text Sequence Text List |
|---|---|---|---|---|---|---|---|---|---|
|
1 |
0 |
1 |
0 |
|
0 |
|
|
N |
A,B,C,D |
|
Output: E2E_LAB1803-12797-A E2E_LAB1803-12797-B E2E_LAB1803-12797-C E2E_LAB1803-12797-D E2E_LAB1803-12798-A E2E_LAB1803-12798-B E2E_LAB1803-12798-C E2E_LAB1803-12798-D E2E_LAB1803-12799-A E2E_LAB1803-12799-B |
|||||||||
|
1 |
0 |
2 |
0 |
|
0 |
|
|
N |
A,B,C,D |
| Output:
E2E_LAB1803-12801-A (Outer seq skipped 1; known defect) E2E_LAB1803-12801-B E2E_LAB1803-12801-C E2E_LAB1803-12801-D E2E_LAB1803-12802-A E2E_LAB1803-12802-B E2E_LAB1803-12802-C E2E_LAB1803-12802-D E2E_LAB1803-12803-A E2E_LAB1803-12803-B |
|||||||||
|
1 |
99 |
1 |
20 |
|
|
|
0 |
N |
A,B,C,D |
| Output:
E2E_LAB1803-20-B (Inner seq skipped 1; known defect) E2E_LAB1803-20-C E2E_LAB1803-20-D E2E_LAB1803-21-A E2E_LAB1803-21-B E2E_LAB1803-21-C E2E_LAB1803-21-D E2E_LAB1803-22-A E2E_LAB1803-22-B E2E_LAB1803-22-C |
|||||||||
|
1 |
99 |
2 |
20 |
|
|
|
0 |
N |
A,B,C,D |
| Output:
E2E_LAB1803-20-B E2E_LAB1803-20-C E2E_LAB1803-20-D E2E_LAB1803-22-A E2E_LAB1803-22-B E2E_LAB1803-22-C E2E_LAB1803-22-D E2E_LAB1803-24-A E2E_LAB1803-24-B E2E_LAB1803-24-C |
|||||||||
Related processes...