R4160: Addon-XML config format

This is the format of the Addon XML that defines a Service Task when creating a custom automated step.

Element Structure

An Addon XML describes the following elements under the root element <service-task-definition>.

<?xml version="1.0" encoding="UTF-8"?>
<service-task-definition>

  <label>Number: Generate Random</label>
  <label locale="ja">数値: 乱数生成</label>

  <summary>Generates a random number.</summary>
  <summary locale="ja">乱数を生成します。</summary>

  <license>…</license>

  <help-page-url>…</help-page-url>
  <help-page-url locale="ja">…</help-page-url>

  <configs>
    <config name="conf_Lower" required="true" el-enabled="true" form-type="TEXTFIELD">
      <label>A: Set Lower Limit</label>
      <label locale="ja">A: 下限値をセットしてください</label>
    </config>
  </configs>

  <engine-type>3</engine-type>
  <last-modified>2023-08-08</last-modified>
  <deprecated>false</deprecated>

  <script><![CDATA[
    // Write server-side script here
  ]]></script>

  <icon>
    iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAAB...
  </icon>

</service-task-definition>

To group configuration items, instead of placing <configs> directly under the root, place <tabs> directly under the root and describe a <configs> within each <tab> under it. When using <tabs>, you cannot place <configs> directly under the root.

<service-task-definition>

  <tabs>
    <tab>
      <configs>
        <config name="conf_Lower" required="true" form-type="TEXTFIELD">
          <label>A: Set Lower Limit</label>
        </config>
        <config name="conf_Upper" required="true" form-type="TEXTFIELD">
          <label>B: Set Upper Limit</label>
        </config>
      </configs>
    </tab>
    <tab>
      <configs>
        <config name="conf_DataIdC" required="true" form-type="SELECT" select-data-type="DECIMAL">
          <label>C: Select NUMERIC DATA for Generated Number</label>
        </config>
      </configs>
    </tab>
  </tabs>

</service-task-definition>

Element Reference

Element	Description	Constraints / Format
`<label>`	Abstract name of the automated step (Service Task)	Max 64 characters. Use the `locale` attribute to specify per language (en, ja, etc.)
`<summary>`	Summary	Max 256 characters. The `locale` attribute can be used
`<license>`	License notation	—
`<help-page-url>`	Help page URL	Max 1000 characters. The `locale` attribute can be used
`<last-modified>`	Last modified date	YYYY-MM-DD
`<deprecated>`	Whether the item is deprecated	true / false
`<engine-type>`	Script engine	Required. Specify `3` (GraalJS)
`<icon>`	Step logo	A Base64-encoded string of a JPEG / GIF / PNG image no larger than 64px. Displayed when the step is placed on the workflow diagram via Drag & Drop
`<configs>` / `<config>`	Configuration items	Up to 20 `<config>` elements can be listed as children of `<configs>`. `<configs>` is placed either directly under the root or under a `<tab>`
`<tabs>` / `<tab>`	Grouping of configuration items	`<tabs>` is placed directly under the root, and each `<tab>` under it contains a `<configs>`. When using `<tabs>`, `<configs>` cannot be placed directly under the root
`<script>`	Server-side script	Written between `<![CDATA[` and `]]>`. Subject to the same constraints as [Script Task] (processing time limited to 30 seconds, HTTP requests limited to 10 per automated step, etc.)

Referencing Configuration Values from Scripts

From scripts written within the Service Task definition (Addon-XML), configuration values are referenced via the configs object.

const processId = configs.get( "conf_ProcessId" );

String get(String configName) — Returns the following string depending on the form-type setting.

form-type	Return Value
TEXTFIELD, TEXTAREA	Returns the entered string, or the string resulting from evaluating the SpEL expression (when `el-enabled="true"`)
SELECT	Returns the Data Item number of the specified Data Item, or the entered string (when `editable="true"`)
SELECT_LIST_SUB_DATA	Returns the field name of the selected sub Data Item
SELECT_ITEM	Returns the value of the selected choice (item)
TOGGLE	Returns a boolean value as a string (true or false)
QUSER	Returns the user ID of the selected Quser (User)
QGROUP	Returns the organization ID of the selected Qgroup (Organization)
OAUTH2	Returns the settingName of the selected OAuth2 setting

Object getObject(String configName) — Returns the following object depending on the form-type setting.

form-type	Return Value
TEXTFIELD, TEXTAREA	null
SELECT	Data definition object (ProcessDataDefinitionView). Returns null when `editable="true"` and a fixed value is specified
SELECT_LIST_SUB_DATA	Sub Data Item object (SubDataDefinitionView)
SELECT_ITEM	Choice object (ItemView)
TOGGLE	boolean (true or false)
QUSER	Quser object (QuserView)
QGROUP	Qgroup object (QgroupView)
OAUTH2	HTTP authentication setting object (AuthSettingWrapper)

For details on the return value objects (ProcessDataDefinitionView, SubDataDefinitionView, ItemView, QuserView, QgroupView, AuthSettingWrapper), see R2300: Java Classes Available in Script Task.

Attribute Reference

name *

Value	Description
name="conf_MaxNum"	Alphanumeric characters and "_" (underscore) can be used. Max 64 characters

form-type

Value	Description
form-type="TEXTFIELD"	Specified by text input (single line)
form-type="TEXTAREA"	Specified by text input (multi-line)
form-type="SELECT"	Specified by selecting a Data Item (use "select-data-type" to specify the data type)
form-type="SELECT_LIST_SUB_DATA"	Specified by selecting a sub Data Item of a Table-type Data Item. Used together with "depends-on", which points to a configuration item with form-type="SELECT". This configuration item is displayed only when a Table-type Data Item is selected in the referenced configuration item
form-type="SELECT_ITEM"	Specified by selecting from a choice list (choices are defined with `<item>`)
form-type="TOGGLE"	Specified by ON / OFF
form-type="QUSER"	Specified by selecting a User
form-type="QGROUP"	Specified by selecting an Organization
form-type="OAUTH2"	Specified by selecting an HTTP authentication setting name. Specify "OAUTH2" even when using "BASIC authentication / direct token specification" in the HTTP authentication settings

The default when omitted is "TEXTFIELD"

Example of defining choices with "SELECT_ITEM":

<item value="editor"><label>Editor</label></item>
<item value="viewer"><label>Viewer</label></item>

select-data-type

Value	Description
select-data-type="STRING"	Filter selection to String-type Data Items
select-data-type="STRING_TEXTFIELD"	Filter selection to String (Single-line) Data Items
select-data-type="STRING_TEXTAREA"	Filter selection to String (Multi-line) Data Items
select-data-type="STRING_MARKDOWN"	Filter selection to String (Markdown) Data Items
select-data-type="STRING_MULTILINE"	Filter selection to String (Multi-line / Markdown) Data Items
select-data-type="DECIMAL"	Filter selection to Numeric-type Data Items
select-data-type="DATE"	Filter selection to Date-type Data Items
select-data-type="DATE_Y"	Filter selection to Date (Year) Data Items
select-data-type="DATE_YM"	Filter selection to Date (Year-Month) Data Items
select-data-type="DATE_MD"	Filter selection to Date (Month-Day) Data Items
select-data-type="DATE_YMD"	Filter selection to Date (Y/M/D) Data Items
select-data-type="DATETIME"	Filter selection to Datetime-type Data Items
select-data-type="SELECT"	Filter selection to Select-type Data Items
select-data-type="SELECT_SINGLE"	Filter selection to Select (Single-select) Data Items (Single-select: Radio Button / Select Box / Search Select Box)
select-data-type="SELECT_CHECKBOX"	Filter selection to Select (Checkbox) Data Items
select-data-type="QUSER"	Filter selection to User-type Data Items
select-data-type="QGROUP"	Filter selection to Organization-type Data Items
select-data-type="LIST"	Filter selection to Table-type Data Items
select-data-type="FILE"	Filter selection to File-type Data Items
select-data-type="DISCUSSION"	Filter selection to Discussion-type Data Items

The default when omitted is "STRING"

required

Value	Description
required="true"	Specifying "required=true" makes the item mandatory
required="false"

The default when omitted is "false"

el-enabled

Value	Description
el-enabled="true"	Whether to allow SpEL expressions. When allowed, for the format of values specified in this configuration item, see R2272: Automatic Assignment to Title / String Type (Data Setting Expression)
el-enabled="false"

The default when omitted is "false"

editable (for form-type="SELECT")

Value	Description
editable="true"	Whether to allow text field input for a configuration item with form-type="SELECT"
editable="false"

The default when omitted is "false"

depends-on

Value	Description
depends-on="configName"	Specify the name value (configName) of a configuration item with form-type="TOGGLE" to show/hide this configuration item based on the TOGGLE selection. For configuration items with form-type="SELECT_LIST_SUB_DATA", specify the name value of a configuration item with form-type="SELECT"

Configuration example:

<config name="checked" form-type="TOGGLE">
 <label>Checked</label>
 <label locale="ja">チェック済</label>
</config>
<config name="note" form-type="TEXTFIELD" depends-on="checked">
 <label>Note</label>
</config>

Element Structure

Element Reference

Referencing Configuration Values from Scripts

Attribute Reference

name *

form-type

select-data-type

required

el-enabled

editable (for form-type="SELECT")

depends-on

Articles in this section

In-site Links

Element Structure

Element Reference

Referencing Configuration Values from Scripts

Attribute Reference

name *

form-type

select-data-type

required

el-enabled

editable (for form-type="SELECT")

depends-on

Articles in this section

In-site Links

Related articles