M416: Create your own Auto-Step for Workflow App Definitions

 

If you want to automate a Processing step to, for example, obtain the number of characters and the hash value, you have to write scripts using a [Script Task]. If you need to use the same [Script Task] in different places you should consider packaging the script as an [Add-on XML]. (Service-Task Addon)

1. Overview of the Advantages of Creating Addon XML (Packaging)

a. Aspects of IT skill requirements (compared with a Script Task)

A flow designer who does not have script knowledge should be capable of workflow automation as well.

b. Aspects of the modelling cost (compared with Script Task)

There will be no need to write the same script repeatedly.

  • The boundary between the IT Department's and the App owner's responsibilities should be considered
  • Go to M415 for more info on how to import a pre-existing [Addon XML]
  • Go to M416 (Bottom of this page) or to "Download" in M415 for Sample codes

2. Determine the Package Name

a. Aspects of output by auto-step

E.g. contents of data to be stored, contents of external system auto-operation, etc.

b. Aspects of input by auto-step

E.g. business data to be inspected, data name in external system to be referenced, etc.

  • You can set the file name of the package file (Add-on XML) with 52 characters or less.
  • The name of the auto-step (Service Task) is defined in <label> element (64 characters max.)
  • Sample of a: <label>Random Number Generator</label>
  • Sample of b: <label>Weather Info Getter</label>
  • You can define an overview in <summary> element (250 characters max.)
  • You can define the URL of the help page in <help-page-url> element (250 characters max.)
  • You can define the last modified date in <last-modified> element (YYYY-MM-DD)
  • You can define whether the item is deprecated or not in the <deprecated> element (true / false)

3. Determine the Configuration Items Required

a. Business Data Items which are to be referenced by the Step (SELECT)

E.g. To write to Data A, To read Data B. etc.

b. Fixed values used in the Step (TEXTFIELD, TEXTAREA, QUSER, OAUTH2)

E.g. Maximum value: "100", Status: This Draft is at the "not yet approved" stage, etc.

  • List configuration items with <config> which is a child element of <configs>
  • You can list up to 20 configuration items using <config>
  • Mandatory element <config> can also be grouped with its parent element <tab> (from v15.0)
  • When using the grouping element <tab>, the parent element (root element) <tabs> is required
  • The <config> element can be shown or hidden depending on the values of other configuration items by specifying the depends-on attribute

R4160: Addon-XML Attributes of config element
R2272: Output of Strings via EL syntax

4. Determine Automatic Processing Behavior

1. Write a server-side script

Write in ECMA code that can be used in the script Step (M230).

  • Knowledge of ECMAScript (JavaScript) is required
  • Using parts of Java classes is also possible
  • Script is described between <script><![CDATA[ and ]]></script>
  • Use the special method configs.getObject("♦configName♦") and configs.get("♦configName♦") for referring to config
    • configs.getObject("♦configName♦") will return the following objects :
      • form-type="QUSER" : QuserView object
      • form-type="SELECT" : ProcessDataDefinitionView object
        • If typing in a text field with the config defined as editable="true": null
        • configs.get("♦configName♦") will return the strings entered in the text field
    • configs.get("♦configName♦") will return  java.lang.String object
  • Use findData( ♦dataDef♦ ) and findDataByNumber( "♦dataId♦" ), etc. for referring to Business Data (M230)
  • Use setData( ♦dataDef♦, ♦value♦ ) and setDataByNumber( "♦dataId♦", ♦value♦ ), etc. for updating Business Data (M230)
  • When setting the processing engine to "GraalJS", <engine-type> 3 </ engine-type> is specified
    • (<engine-type> element is required)
  • HTTP requests must be up to 10 per one automatic Task

R2300: Java Classes available in Script Task
R2301: Script Data Retrieving / Updating

5. Determine the Step Logo (Optional)

1. Prepare an image file

Prepare a image file of less than 64px (JPEG, GIF, PNG only)

2. Encode to Base64

Use converter software or a web service

  • Define using the icon data <icon> element
  • The logo will be displayed upon placement using Drag & Drop

6. Support Multiple Languages (Optional)

1. Add label elements with the locale attribute

Add <label> for as many languages as you need for your Workflow designers

  • E.g. Configure <label locale="es">Generador de Numeros aleatorios</label> for Spanish designers
  • en(default), ja, ko, zh_CN, zh_TW

416-2-en.png

A. Sample of Addon XML

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

<label>#Number: Generate Random</label>

<summary>Generates a random number. When a token reaches this automated step, a numerical value within the specified range is generated each time. The decimal part is rounded down toward 0 according to the workflow data definition.</summary>

<license>(C) Questetra, Inc. (MIT License)</license>

<help-page-url>https://support.questetra.com/addons/number-generate-random-2021/</help-page-url>

<configs>
<config name="conf_Lower" required="true" el-enabled="true" form-type="TEXTFIELD">
<label>A: Set Lower Limit (e.g. "0", "-0.5")</label>
<config name="conf_Upper" required="true" el-enabled="true" form-type="TEXTFIELD">
<label>B: Set Upper Limit (e.g. "10", "0.5")</label>
</config>
<config name="conf_DataIdC" required="true" form-type="SELECT" select-data-type="DECIMAL">
<label>C: Select NUMERIC DATA for Generated Number (update)</label>
</config>
</configs>

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

<script><![CDATA[// GraalJS Script (engine type: 3)
// GraalJS Script (engine type: 2)
// (c) 2021, Questetra, Inc. (the MIT License)

//////// START "main()" ////////
main();
function main(){


//// == Config Retrieving ==
const lower = configs.get( "conf_Lower" ) + ""; // config required
const upper = configs.get( "conf_Upper" ) + ""; // config required
const dataIdC = configs.get( "conf_DataIdC" ) + ""; // config required
// 'java.lang.String' (String Obj) to javascript primitive 'string'

// Design-time Config Format Check
const numLower = parseFloat( lower );
engine.log( " AutomatedTask Lower Limit: " + numLower );
const numUpper = parseFloat( upper );
engine.log( " AutomatedTask Upper Limit: " + numUpper );
if( isNaN(numLower) ){
throw new Error( "\n AutomatedTask ConfigError:" +
" Config {Lower} is not a number \n" );
}
if( isNaN(numUpper) ){
throw new Error( "\n AutomatedTask ConfigError:" +
" Config {Upper} is not a number \n" );
}
if( numLower > numUpper ){
throw new Error( "\n AutomatedTask ConfigError:" +
" Config {Lower} is greater than {Upper} \n" );
}


//// == Data Retrieving ==
// nothing (This Service Task is a CREATE type)


//// == Calculating ==
let numDiff = numUpper - numLower;
let mathRand = Math.random(); // Math.random(): 0.00 to 0.99
engine.log( " AutomatedTask Math.random(): " + mathRand );
let numRand = mathRand * numDiff + numLower;
engine.log( " AutomatedTask Generated Random: " + numRand );


//// == Data Updating ==
engine.setDataByNumber( dataIdC, new java.math.BigDecimal( numRand ) );


} //////// END "main()" ////////

]]></script>


<icon>
iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAEWUlEQVRYR8WXXUiUWRjHf6+ObuOo
la6uYuuKKVvrGrkiSazlst4UBCFetH4QKjaTGKwgLN0UBIHSxm5B23jhepFpX7vQVbFiH7hLElIG
4SaOJbVKZq7fHzM5vss59uY4vvPO2O7iEW9mnuc8//M8////nFFY46UEXL+eMFTyUfgKlQwUkoCN
b/NHUelH4SEqt1H4FSszgeztH0Ajcbj4DrAB6wLZFJgD7IRSRykvjXKMAdixofA9YAmwsHfYNCo1
2LD7yvcNoJ6fgMPvWdg77TxWKvX20gdgpxmFb/6j4ovbqLRgo9B7z5UAAjh5xZYKCpILiAuLY8I1
wdWnVzn7+GwgeFd0YjmAxZmf97VTREgEjbmN7E/aT7AS/C5MRaX1r1YKWguYfDNpDETlsCcnlgAs
st1hRLjT2ac58vkRQoJCVhRxq24u9l7k4J2D/joxTSgpmjqWANTzA/Ctr+ysmCxavm5hc+RmnwWG
ZocovVPKjRc3/IH4ESvVImgRgDAZGDHSeVVaFbU7auXpxb/yNlWkz8zP8GTsCSmRKZx5fIZjncf8
ARA+ES3MahGAnWIULhhl1efUU7G1graBNnZ+tJMwk8AMrgUX155e4/nUc8q3lHNr4BYH2g74AyBU
UYKNJq0DDUCZUdap7FPsjt+NSTHJDlhCLAQpQYg/QTzRBVOQifuv7mNtt/oHAD9jpVzrwAMUMryz
smOzObT1EJf7LnM04yi74nfJkNn5WQTptCWAiI6IsTwaecT2X7aTE5dD10iXb1WoPMTGF1oH/va4
WN5tXJJawrkvz+Fyu+if6ifzw0z5XfdoN60DrWyL2oZjwkF6VDoCrPadkGh8WDxVf1RxodfnZEex
EqUBUPV6tufjPVL34mQNPQ0UpRSRGJ4oQ+fccwxODxJrjiU8JFx+Njw3TFNvE8WpxYQGhVL5eyXN
jmbf47CiGAKQAsmppyi1iLuDd4kxxzDqHJUk1IpqKrg3dE+ak3PBSW58Lu0v28n/Ld/YmDwA6I5A
g77Jsom8hDzqdtQRvS6avok+esZ6JOnGnGOyG3sT90oeCDMym8zcfHGTS32XjMjoMQI7uiQU2WWf
lnEy66QknZCcOLnQ/IK6gMVkIcGSIO8E0ZnO4U6SI5OlH/h1Ri8S6srQ0/2Ey4mZJ0UkseGDDZIX
AoRQgLbmF+Z5PfeaWfes5Mq4axxbu01eVjprmQx1jUhTgTi1qqrLihn1VpxegBMdq+mowd6t8x7x
MiJdKxYduJJ3RZ76fdazyWcUthXS8arDO93LiiXd9S+j45nHqU6vZn3o+lVhEP4gTn+9/7pentdl
JEIMrmOhgn2f7MP2mY20jWlyFFNvpjAHm6USvJdwyhMPTlDbVatX3Md1LEL9PEi8dxMeIUxHyM/p
dsqZizvBMe7A/qddmtKK5fNBokUG8CRb1SyWB/t5kmnBa/oo/X86scpn+VIn1vCHiQZiTX+aeRJo
zX6c/gvKB5L6D2XHtzBjw0oRAAAAAElFTkSuQmCC
</icon>

</service-task-definition>

Please also see each Add-on XML file (Add-on example) that is publicly available.
Support site:  Add-on Auto-Steps

X. Blog Articles

X. Business Apps

Articles in this section

See more

Related articles