How to build an ARGOS Low-code/RPA Python Plugin

Prepare Python IDE

One of these IDEs (Integrated Development Environment) can be used

• PyCharm

• Visual Studio Code for Python

Download Plugin Template

Plugin Template

Unzip and open the files in IDE

• Unzip above zip file

• Open directory plugin-demo at your IDE

Change Python Package name

• Above template has the Python package name your.demo.helloworld

• Change this package as you desire such as my.api.crm

• Three parts changed with the new package name like below

  • __main__.py : change ‘from your.demo.helloworld import main’ into ‘from my.api.crm import main’

  • setup.yaml : change ‘your.demo.helloworld: [‘icon.*’] into ‘my.api.crm: [‘icon.*’]’

  • test_me.py : change ‘from your.demo.helloworld import _main as main’ into ‘from my.api.crm import _main as main’

Design user arguments and result

ARGOS Low-code/RPA Python plugin is regarded as a CLI (Command line interface) program. User run CLI program with arguments as user input and the output is the result.

Plugin developers must design the user arguments (which becomes the parameter/property box in STU) and result (the output).

How to design user arguments

You can specify user arguments at function _main() in __init__.py file.

When an original Python code looks like below,

################################################################################
def _main(*args):
    """
    Build user argument and options and call plugin job function
    :param args: user arguments
    :return: return value from plugin job function
    """
    with ModuleContext(
        owner='YOUR-LABS',
        group='demo',
        version='1.0',
        platform=['windows', 'darwin', 'linux'],
        output_type='text',
        display_name='My World',
        icon_path=get_icon_path(__file__),
        description='Hello World friends',
    ) as mcxt:
        # ##################################### for app dependent parameters
        mcxt.add_argument('name', nargs='+', help='name to say hello')
        argspec = mcxt.parse_args(args)
        return helloworld(mcxt, argspec)

you need to change it to,

################################################################################
def _main(*args):
    """
    Build user argument and options and call plugin job function
    :param args: user arguments
    :return: return value from plugin job function
    """
    with ModuleContext(
        owner='MyCompany',
        group='api',
        version='1.0',
        platform=['windows', 'darwin', 'linux'],
        output_type='text',
        display_name='CRM Op',
        icon_path=get_icon_path(__file__),
        description='Our Company CRM API',
    ) as mcxt:
        # ######################################## for app dependent options
        mcxt.add_argument('--type', '-t',
                          display_name='Value Type', show_default=True,
                          choices=["auto", "string", "int", "float", "date", "datetime"],
                          default='auto',
                          help='Set Value type, one of {"auto", "int", "float", "date", "datetime"}.'
                               ' Default is auto which means try to guess the best type of value')
        mcxt.add_argument('--date-format',
                          display_name='Date Format',
                          choices=list(BinOp.DATE_FORMAT.keys()),
                          default='YYYYMMDD',
                          help='Set the format of Date')
        mcxt.add_argument('--datetime-format',
                          display_name='DateTime Format',
                          choices=list(BinOp.DATETIME_FORMAT.keys()),
                          default='YYYYMMDD-HHMMSS',
                          help='Set the format of DateTime')
​
        # ##################################### for app dependent parameters
        mcxt.add_argument('left',
                          display_name='Left Val',
                          help='Left operand for binary operation')
        mcxt.add_argument('operation',
                          display_name='Operator',
                          choices=['+', '-', '*', '/', '%'],
                          help='Binary operation, one of "+(add),-(subtract),*(multiply),/(divide),%%(modular)"')
        mcxt.add_argument('right',
                          display_name='Right Val',
                          help='Right operand for binary operation')
        argspec = mcxt.parse_args(args)
        return do_binop(mcxt, argspec)

Whereas,

• ModuleContext instance defines plugin and attributes. User arguments are defined using mcxt.add_argument method (mcxt is the ModuleContext instance variable).

• mcxt.add_argument is the superset of Python argparse standard library

• In addition to add_argument of standard argparse library next arguments can be added.

  • display_name is the label in STU

  • Options are usually not shown in default in STU but in advanced group. If show_default is true then this option is shown default in STU

  • input_method specifies how to input from user in STU

    • password shows password using ‘*’ characters.

    • fileread shows file dialog to read a file

    • fileread;xlsx shows file dialog to read a file which has the extension of xlsx

    • filewrite shows file dialog to write a file

    • filewrite;txt,pdf shows file dialog to write a file which has the extension of either txt or pdf

    • folderread shows folder dialog to read

    • folderwrite shows folder dialog to write

    • dateselect shows date picker dialog

    • textarea shows multiple text input control

    • radio shows radio button according to group (refer to input_group)

    • combobox shows combo-box for choice

    • imagebox shows image

  • input_group is used for grouping in STU

    • “groupname” is the grouping name which is used for the group of arguments

    • “groupname;groupbox” shows group box named “groupname”

    • “radio=a” shows group of radio buttons named “a”

    • “radio=a;default” shows group of radio button as a default

  • min_value or greater_eq check if the user input value is greater than or equal to given value

  • max_value or less_eq check if the user input value is less than or equal to given value

  • greater or min_value_ni check if the user input value is greater than given value

  • less or max_value_ni check if the user input value is less than given value

  • equal check if the user input value is equal to given value

  • not_equal check if the user input value is not equal to given value

  • re_match check if the user input value is RE matched for given value

How to design result

You can change user function body helloworld() into do_binop() in __init__.py file.

When an original Python code looks like below,

################################################################################
@func_log
def helloworld(mcxt, argspec):
    """
    plugin job function
    :param mcxt: module context
    :param argspec: argument spec
    :return: True
    """
    mcxt.logger.info('>>>starting...')
    print('Hello world %s' % argspec.name)
    mcxt.logger.info('>>>end...')
    return 0

You can change it to a code below.

################################################################################
@func_log
def do_binop(mcxt, argspec):
    mcxt.logger.info('>>>starting...')
    try:
      if not argspec.message:
         raise ValueError(f'Invalid Message')
      direction = argspec.direction
      justify = argspec.justify
      width = int(argspec.width)
      f = Figlet(font=argspec.font, direction=direction,
         justify=justify, width=width)
      print(f.renderText(argspec.message), end='')
      return 0
   except ZeroDivisionError as err:
      msg = str(err)
      mcxt.logger.error(msg)
      sys.stderr.write('%s%s' % (msg, os.linesep))
      return 1
   except IOError as err:
      msg = str(err)
      mcxt.logger.error(msg)
      sys.stderr.write('%s%s' % (msg, os.linesep))
      return 2
   except RuntimeError as err:
      msg = str(err)
      mcxt.logger.error(msg)
      sys.stderr.write('%s%s' % (msg, os.linesep))
      return 3
   except Exception as err:
      msg = str(err)
      mcxt.logger.error(msg)
      sys.stderr.write('%s%s' % (msg, os.linesep))
      return 99
   finally:
      mcxt.logger.info('>>>end...')

Whereas,

• Plugin result is the Python’s standard output (like sys.stdout or print)

• mcxt is the ModuleContext instance

  • mcxt.logger is the logger object

• This function return 0 on success otherwise failure

How to test your Python code

You can add each unit-test method in TU class in test_me.py. POT will execute the unit-test during the building time at the end.

Set version

Set version: 1.22.333 at setup.yaml file.

How to build an icon

• Change my-icon.png image file with you own image file.

• Open CMD.EXE (or terminal in Linux or Mac)

• Activate virtual env (like C:\work\py3\Script\activate)

• Run command alabs.icon

• Make sure icon.png image file which will be used as STU icon is well created.

Before building plugin (for the Private Plugin Repository)

• Make your own python private repository by choosing one of the following deployment platforms.

  • How to Create a Private Python Package Repository

  • How To Install A Private Pypi Server On AWS

  • Pypiserver – minimal PyPI server for use in docker container

• Sign-up or Sign-in at rpa.argos-labs.com

• Go to the Plugins page and click on the Private tab in menu

• Add your private repository

  • name: plugin name

  • url: set as pypi url (like http://my.pypi.com/simple or https://my.pypi.com/pypi)

  • user: user for private plugin

  • password: password for the user

How to build plugin and upload it to your Private Plugin Repository

• Open CMD.EXE (or terminal in Linux or Mac)

• Activate virtual env (like C:\work\py3\Script\activate)

• Run command build.bat (or build.sh in Linux or Mac). This batch file will run next commands using the POT utility, alabs.ppm

  • alabs.ppm --venv test: Test your plugin and response to any exceptions in the test process

  • alabs.ppm --venv build: Build your plugin and response to any exceptions in the process

  • alabs.ppm --venv upload: Try to upload to the first Private Plugin Repository list in Chief page (refer above site, rpa.argos-labs.com)

    • This command will ask for user id and password of Supervisor account for uploading your package to the Private Plugin Repository

How to show your Plugins on STU

• Login to STU (if already logged in STU then logout and login again)

• Got to Supervisor (Chief) and go to Plugin menu and then to Private tab.

• Decide which Plugins to use on your STU (you can select by on/off button)

• Restart STU

• Make sure new plugins appear on STU’s Operations box

• Use the plugin and build your bot