Lab 2.5: Implementing Job Options
|
Time Estimates for Completion
|
||
|---|---|---|
|
Add job options.
|
Description:
|
5 minutes
|
|
Lab exercise:
|
15 minutes
|
|
Description
A job may require additional parameters affecting the job execution rather than job data export or job result handling. For this purpose the (optional) Options section in the job's XML configuration allows the specification of an implementation of the IJobOptions interface.
Instead of implementing the interface IJobOptions it may be more convenient to use or extend the class JobOptions that supports these parameter types:
• text parameter
<parameter-name type="text">default text
<DisplayName>My Parameter</DisplayName>
</parameter-name>
• choice parameter
<parameter-name type="choice">value2
<ChoiceValue>value1
<DisplayName>Display Name 1</DisplayName>
</ChoiceValue>
<ChoiceValue>value2
<DisplayName>Display Name 2</DisplayName>
</ChoiceValue>
...
</parameter-name>
• boolean parameter
<parameter-name type="boolean">true
<DisplayName>My Parameter</DisplayName>
</parameter-name>
Lab Exercise
Extending the Simple Model Geometry Check by a parameter CheckType requires the following actions:
1. Evaluating the CheckType parameter in SimpleModelGeometryCheckTemplate.lsp.
CheckType can be set to either Minimal or Maximal, using Minimal as the default value.
2. Configuring the CheckType parameter in the job's XML configuration.
3. Updating the job xml configuration file to include the job options.
Prerequisites
You need the SimpleModelGeometryCheckJob.xml and SimpleModelGeometryCheckTemplate.lsp files from Lab 2.4.
 |
Parameter names must be unique within a job configuration. For example, job options must not have a parameter with the same name as a job data exporter parameter or a job result handler parameter.
|
Evaluate the CheckType parameter
In SimpleModelGeometryCheckTemplate.lsp add the code to evaluate the CheckType parameter:
(in-package :frame2)
;;-------------------------
;; utilities
;;-------------------------
(load "JobUtilities.lsp")
;;------------------------------------------------------------------------------
;; This is the routine that is called by the automation framework in Modeling.
;; When this routine is called, the current directory of Modeling is the one
;; where the input data can be found.
;;
;; parameter : <output-directory> directory for output data
;; return : <error-message> return value 'nil' ==> success
;;------------------------------------------------------------------------------
(defun run-job (output-directory)
(let* (
;; parameters provided by the job
(ann-model-file-name "%AnnotatedModelFileName%")
(check-type (parse-choice "%CheckType%"
'("Minimal" "Maximal")
'(:minimal_check :maximal_check)
:minimal_check))
;; the item to check
(part-to-check nil)
;; variables for XML serialization
(results-element (xml:xml-list-create-element "results"))
(xml-file (create-path output-directory "index.xml"))
;; variables for writing the output file
(file-zipname "model.pkg") ;; the real name of the result file in the ZIP archive
(file-path (create-path output-directory file-zipname)) ;; the path of the result file
(file-name (format nil "~A.pkg" (if (oli:sd-string= ann-model-file-name "") "AnnotatedModel" ann-model-file-name))) ;; the symbolic name of the result file
)
;;---------------------------------------------
;; load input & call the part checker
;;---------------------------------------------
(load-job-data "%ModelFile%")
(setf part-to-check (oli:sd-inq-obj-children (get-all-at-top)))
(k2-ui::check_part :objects part-to-check check-type :labels :on :keep_labels :on)
(collect-check-results (frame2:getres) results-element)
;; -------------------
;; write result data
;; -------------------
;; write the annotated model
(frame2::save-all-in-package file-path)
;; and make a corresponding entry in the index.xml
(xml:xml-list-add-child results-element (make-result-file-element "PKG" :file file-zipname :name file-name))
;;------------------------------------------------------------------------
;; write the index.xml
;; write-xml-to-list serializes the list into XML (see JobUtilities.lsp)
;;------------------------------------------------------------------------
(write-xml-list-to-file results-element xml-file)
;;------------------------------
;; return = nil means 'no error'
;;------------------------------
(get-automation-error)
) ; let
)
(defun collect-check-results (part-check-result results-element)
(let* (
(error-entries (cdr (assoc k2-ui::*body-check-error-string* part-check-result)))
(model-state (if (> (length error-entries) 0) "model_corrupt" "model_ok"))
)
(xml:xml-list-add-attribute results-element "modelcheck" model-state)
)
)
Extend JobOptions to read the <Options> section of the xml file
For parameters that get their values dynamically from the database (such as the list of a drawing's master data), the XML configuration may not be sufficient. The following example shows the implementation of the same AnnotatedModelFileName parameter that we used in Lab 2.3, but as part of the job options that can be edited in the UI. (Click here for a file you can copy and paste into NetBeans.)
package com.acme;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import com.osm.automation.JobOptions;
import com.osm.biz.WMElement;
import com.osm.datamgmt.biz.Model;
import com.osm.ui.builder.descriptor.ParameterDescriptor;
import com.osm.ui.builder.descriptor.TextParameterDescriptor;
public class SimpleModelGeometryCheckJobOptions extends JobOptions {
private final FileNameJobParameterDescriptor filenameJPD;
public SimpleModelGeometryCheckJobOptions() {
super();
this.filenameJPD = new FileNameJobParameterDescriptor();
}
@Override
protected List<ParameterDescriptor> getDeclaredParameters() {
final ArrayList<ParameterDescriptor> jpdList = new ArrayList<ParameterDescriptor>();
jpdList.addAll(super.getDeclaredParameters());
jpdList.add(filenameJPD);
return jpdList;
}
private static class FileNameJobParameterDescriptor extends TextParameterDescriptor {
public static final String PARAMETER_NAME = "AnnotatedModelFileName";
public static final String DISPLAY_NAME = "Annotated Model File Name";
public FileNameJobParameterDescriptor() {
super(PARAMETER_NAME, DISPLAY_NAME, PARAMETER_NAME, true, true, true, null);
}
@Override
public void init(WMElement wmElement, Properties parameters) {
final String value = getValue(parameters);
if (value == null) {
if (getDefaultText() != null) {
setValue(parameters, getDefaultText());
} else if (wmElement instanceof Model) {
final Model model = (Model) wmElement;
try {
setValue(parameters, model.getName() + "_" + model.getState());
} catch (Exception e) {
setValue(parameters, "Annotated_Model");
}
}
}
}
}
}
Update the job's XML configuration
Add the job options to the job configuration xml file.
<?xml version="1.0" encoding="UTF-8"?>
<Job type="modeling.simplegeometrycheck" has_result_data="true">
<DisplayName>Simple Model Geometry Check</DisplayName>
<UI>
<ActionMenu wm_java_class="com.osm.datamgmt.biz.Model" include_derived="true">
<Name>Simple Model Geometry Check</Name>
<JobGroup>Model Checks</JobGroup>
<Action java_class="com.osm.automation.action.MultiSelectCreateJobScheduleAction">
<Description>Checks a model's geometry</Description>
</Action>
</ActionMenu>
</UI>
<Exporter java_class="com.osm.automation.ModelingJobExporter">
<StartScriptTemplate>SimpleModelGeometryCheckTemplate.lsp</StartScriptTemplate>
<ModelLoadRule catalog="model" msg_num="728">Highest Revisions</ModelLoadRule>
</Exporter>
<ResultHandler java_class="com.osm.automation.SaveToFileSystemJobResultHandler">
<DisplayName>Save annotated model to server directory</DisplayName>
<TargetDirectory>C:\taskagent</TargetDirectory>
</ResultHandler>
<Options java_class="com.acme.SimpleModelGeometryCheckJobOptions">
<CheckType type="choice" editable="true">Minimal
<DisplayName>Checks</DisplayName>
<ChoiceValue>Minimal</ChoiceValue>
<ChoiceValue>Maximal</ChoiceValue>
</CheckType>
</Options>
</Job>
|
|
The job data exporter SimpleModelGeometryCheckJobExporter cannot be used with SimpleModelGeometryCheckJobOptions because the job parameter name AnnotationModelFileName would not be unique.
|
Now the Create Task dialog displays both job options — the implemented job parameter AnnotationModelFileName and the CheckType option declared in the xml configuration file.
 |
Use custom parameters whenever possible. Parameter implementations are typically necessary for dynamic value lists, e.g. Masterdata, printer list, etc.
|
 |
For help on implementing job parameters in Java see the API documentation for com.osm.automation.ui.descriptors.JobParameterDescriptor and its derived classes, especially in the com.osm.automation.ui.descriptors package.
|