# urpaform
Extension for filling in forms with [UltimateRPA](https://www.ultimaterpa.com).
You need to have the [UltimateRPA Tools installed](https://www.ultimaterpa.com/documentation/_install.html).
Urpaform allows you to
- distinguish between several forms in your robotization,
- assign form fields of various types to a specific form,
- maintain the form fields.
## Examples
### Basic Usage - Form with a Simple Edit Box
The name given to the form appears in logs. A form field type is specified
as EditElement, added to a form, assigned with the desired value to be filled in
and finally, the form is completed.
```python
from urpaform import Form, EditElement
app = urpa.exec_app("Some_application.exe")
edit_element = app.find_first(cf.name("Username").edit())
edit_field = EditElement(edit_element)
test_form = Form("my forms's name")
test_form.add(edit_field, "UltimateRPA")
test_form.complete()
```
Alternatively, you can take advantage of a context manager to complete the form.
```python
from urpaform import Form, EditElement
app = urpa.exec_app("Some_application.exe")
edit_element = app.find_first(cf.name("Username").edit())
edit_field = EditElement(edit_element)
with Form("my forms's name") as test_form:
test_form.add(edit_field, "UltimateRPA")
```
Note, that there are several ways to add one or many fields to your form using the `add()` method.
You can add fields separately one by one by passing two parameters, where an element is followed by a value.
Alternatively, you can add multiple fields at once by passing any number of tuples with elements and values for each field.
```python
# adding 1 field
test_form.add(some_edit_field, "some value")
# adding 2 fields as tuples
test_form.add((some_edit_field, "some value"), (another_field, "some value"))
```
If needed, Form can be initialized with custom values for arguments:
* `attempts`: how many times can be completion of the form attempted (default value is 3)
* `delay`: how many second should pass between filling of two fields (default value is 0)
### Options for Logging and Checks
For several form field types, you can determine whether the filled values
appear in logs. You can also control whether the check of desired value and truly filled
value will be performed.
```python
from urpaform import Form, ComboElement
app = urpa.exec_app("Some_application.exe")
combo_element = app.find_first(cf.name("Usual").combo_box())
combo_field = ComboElement(combo_element, show_in_log=True, allow_check=False)
test_form = Form("my forms's name")
test_form.add(combo_field, "Saturday")
test_form.complete()
```
### Maintaining a Password Box
Maintenance of a password box is similar to an edit box. You can even choose
between keyboard input and pasting just like in edit box. However, the filled
value in a password box cannot be checked. The password itself can be stored in
Windows Credential Vault and retrieved with `urpa.get_password()`. More details
in [Vault Tutorial and documentation](https://www.ultimaterpa.com/documentation/_vault.html).
```python
from urpaform import PasswordElement
app = urpa.exec_app("Some_application.exe")
password = urpa.get_password(system, user)
password_element = app.find_first(cf.name("Password").edit())
password_field = PasswordElement(password_element)
test_form = Form("my forms's name")
test_form.add(password_field, password)
test_form.complete()
```
### Setting Specific Behavior of Elements - Edit Elements
When [inspecting](https://www.ultimaterpa.com/documentation/_search_elements.html) an edit element, you may discover, that it has some specific behavior.
- For most, the filled value is placed in value property, but for others in the name property or even the text_value property.
You can control the respective set up with `value_is_in` parameter.
- Some can contain a default value that cannot be removed from the edit box. For example,
predefined dots for a date. You can use the `default_value` parameter.
- You have an option to define your own combination of keys with `clear_keys` to clear
the field, in case the default setting fails for your application.
- There is na alternative way to fill an edit box (default method is `writing` using keyboard input). You can switch to pasting the value into the field from clipboard by setting `send_method` at `pasting` and `paste_keys` at demanded paste shortcut (default CTRL+V).
```python
from urpaform import Form, EditElement
app = urpa.exec_app("Some_application.exe")
edit_element = app.find_first(cf.name("Username").edit())
edit_field = EditElement(edit_element, value_is_in="name", default_value=" . . ")
test_form = Form("my forms's name")
test_form.add(edit_field, "UltimateRPA")
test_form.complete()
```
### Setting Specific Behavior of Elements - Combo Boxes
Based on specific behavior of the combo box in your form, you can choose the method
to fill in your desired value. Many would accept the desired value as a text. For others,
you may need to activate the `walk_type` to walk through all available values in the
combo box to find the desired one.
It is recommended to use the default method and to use the other method only if the
default method fails to set the value in your combo box.
```python
from urpaform import Form, ComboElement
app = urpa.exec_app("Some_application.exe")
first_combo_element = app.find_first(cf.name("Usual").combo_box())
first_combo_field = ComboElement(first_combo_element, walk_type=False)
test_form = Form("my forms's name")
test_form.add(first_combo_field, "Tuesday")
second_combo_element = app.find_first(cf.name("Unusual").combo_box())
second_combo_field = ComboElement(second_combo_element, walk_type=True)
test_form.add(second_combo_field, "Saturday")
test_form.complete()
```
### Maintaining Check Boxes and Radio Buttons
You can check and uncheck check boxes in your forms, as well as activate radio buttons.
```python
from urpaform import Form, CheckElement, RadioElement
app = urpa.exec_app("Some_application.exe")
test_form = Form("my forms's name")
first_check_element = app.find_first(cf.name("a)").check_box())
first_check_field = CheckElement(first_check_element)
test_form.add(first_check_field, True)
second_check_element = app.find_first(cf.name("b)").check_box())
second_check_field = CheckElement(second_check_element)
test_form.add(second_check_field, False)
radio_element = app.find_first(cf.name("2").radio_button())
radio_field = RadioElement(radio_element)
test_form.add(radio_field, True)
test_form.complete()
```
## Changelog
[Changelog is here](https://github.com/ultimaterpa/urpaform/blob/master/CHANGELOG.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/ultimaterpa/urpaform",
"name": "urpaform",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Robotic Process Automation,RPA,UltimateRPA,form filling",
"author": "anerold",
"author_email": "support@ultimaterpa.cz",
"download_url": "https://files.pythonhosted.org/packages/ed/46/5a15e79896b5826461c05ab24c5718f82b21cb35fefd1c88075f822c3570/urpaform-0.1.0.tar.gz",
"platform": null,
"description": "# urpaform\n\nExtension for filling in forms with [UltimateRPA](https://www.ultimaterpa.com). \nYou need to have the [UltimateRPA Tools installed](https://www.ultimaterpa.com/documentation/_install.html). \nUrpaform allows you to \n- distinguish between several forms in your robotization, \n- assign form fields of various types to a specific form,\n- maintain the form fields.\n\n\n## Examples \n\n### Basic Usage - Form with a Simple Edit Box\n\nThe name given to the form appears in logs. A form field type is specified \nas EditElement, added to a form, assigned with the desired value to be filled in \nand finally, the form is completed.\n\n```python\n\nfrom urpaform import Form, EditElement\n\napp = urpa.exec_app(\"Some_application.exe\")\nedit_element = app.find_first(cf.name(\"Username\").edit())\nedit_field = EditElement(edit_element)\ntest_form = Form(\"my forms's name\")\ntest_form.add(edit_field, \"UltimateRPA\")\ntest_form.complete()\n```\nAlternatively, you can take advantage of a context manager to complete the form.\n\n```python\n\nfrom urpaform import Form, EditElement\n\napp = urpa.exec_app(\"Some_application.exe\")\nedit_element = app.find_first(cf.name(\"Username\").edit())\nedit_field = EditElement(edit_element)\nwith Form(\"my forms's name\") as test_form:\n test_form.add(edit_field, \"UltimateRPA\")\n```\n\nNote, that there are several ways to add one or many fields to your form using the `add()` method. \nYou can add fields separately one by one by passing two parameters, where an element is followed by a value. \nAlternatively, you can add multiple fields at once by passing any number of tuples with elements and values for each field.\n\n```python\n# adding 1 field\ntest_form.add(some_edit_field, \"some value\")\n\n# adding 2 fields as tuples\ntest_form.add((some_edit_field, \"some value\"), (another_field, \"some value\"))\n```\n\nIf needed, Form can be initialized with custom values for arguments:\n* `attempts`: how many times can be completion of the form attempted (default value is 3)\n* `delay`: how many second should pass between filling of two fields (default value is 0)\n\n### Options for Logging and Checks\n\nFor several form field types, you can determine whether the filled values \nappear in logs. You can also control whether the check of desired value and truly filled \nvalue will be performed. \n\n```python\nfrom urpaform import Form, ComboElement\n\napp = urpa.exec_app(\"Some_application.exe\")\ncombo_element = app.find_first(cf.name(\"Usual\").combo_box())\ncombo_field = ComboElement(combo_element, show_in_log=True, allow_check=False)\ntest_form = Form(\"my forms's name\")\ntest_form.add(combo_field, \"Saturday\")\ntest_form.complete()\n```\n\n### Maintaining a Password Box\n\nMaintenance of a password box is similar to an edit box. You can even choose\nbetween keyboard input and pasting just like in edit box. However, the filled \nvalue in a password box cannot be checked. The password itself can be stored in \nWindows Credential Vault and retrieved with `urpa.get_password()`. More details \nin [Vault Tutorial and documentation](https://www.ultimaterpa.com/documentation/_vault.html).\n\n```python\nfrom urpaform import PasswordElement\n\napp = urpa.exec_app(\"Some_application.exe\")\npassword = urpa.get_password(system, user)\npassword_element = app.find_first(cf.name(\"Password\").edit())\npassword_field = PasswordElement(password_element)\ntest_form = Form(\"my forms's name\")\ntest_form.add(password_field, password)\ntest_form.complete()\n```\n\n### Setting Specific Behavior of Elements - Edit Elements\n\nWhen [inspecting](https://www.ultimaterpa.com/documentation/_search_elements.html) an edit element, you may discover, that it has some specific behavior.\n- For most, the filled value is placed in value property, but for others in the name property or even the text_value property.\nYou can control the respective set up with `value_is_in` parameter.\n- Some can contain a default value that cannot be removed from the edit box. For example, \npredefined dots for a date. You can use the `default_value` parameter.\n- You have an option to define your own combination of keys with `clear_keys` to clear \nthe field, in case the default setting fails for your application.\n- There is na alternative way to fill an edit box (default method is `writing` using keyboard input). You can switch to pasting the value into the field from clipboard by setting `send_method` at `pasting` and `paste_keys` at demanded paste shortcut (default CTRL+V).\n\n```python\n\nfrom urpaform import Form, EditElement\n\napp = urpa.exec_app(\"Some_application.exe\")\nedit_element = app.find_first(cf.name(\"Username\").edit())\nedit_field = EditElement(edit_element, value_is_in=\"name\", default_value=\" . . \")\ntest_form = Form(\"my forms's name\")\ntest_form.add(edit_field, \"UltimateRPA\")\ntest_form.complete()\n```\n\n\n### Setting Specific Behavior of Elements - Combo Boxes\n\nBased on specific behavior of the combo box in your form, you can choose the method \nto fill in your desired value. Many would accept the desired value as a text. For others,\nyou may need to activate the `walk_type` to walk through all available values in the \ncombo box to find the desired one.\n\nIt is recommended to use the default method and to use the other method only if the \ndefault method fails to set the value in your combo box.\n\n```python\nfrom urpaform import Form, ComboElement\n\napp = urpa.exec_app(\"Some_application.exe\")\nfirst_combo_element = app.find_first(cf.name(\"Usual\").combo_box())\nfirst_combo_field = ComboElement(first_combo_element, walk_type=False)\ntest_form = Form(\"my forms's name\")\ntest_form.add(first_combo_field, \"Tuesday\")\nsecond_combo_element = app.find_first(cf.name(\"Unusual\").combo_box())\nsecond_combo_field = ComboElement(second_combo_element, walk_type=True)\ntest_form.add(second_combo_field, \"Saturday\")\ntest_form.complete()\n```\n\n\n### Maintaining Check Boxes and Radio Buttons\n\nYou can check and uncheck check boxes in your forms, as well as activate radio buttons.\n\n```python\nfrom urpaform import Form, CheckElement, RadioElement\n\napp = urpa.exec_app(\"Some_application.exe\")\ntest_form = Form(\"my forms's name\")\nfirst_check_element = app.find_first(cf.name(\"a)\").check_box())\nfirst_check_field = CheckElement(first_check_element)\ntest_form.add(first_check_field, True)\nsecond_check_element = app.find_first(cf.name(\"b)\").check_box())\nsecond_check_field = CheckElement(second_check_element)\ntest_form.add(second_check_field, False)\nradio_element = app.find_first(cf.name(\"2\").radio_button())\nradio_field = RadioElement(radio_element)\ntest_form.add(radio_field, True)\ntest_form.complete()\n```\n\n## Changelog\n\n[Changelog is here](https://github.com/ultimaterpa/urpaform/blob/master/CHANGELOG.md)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Form Filling Module with UltimateRPA",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/ultimaterpa/urpaform"
},
"split_keywords": [
"robotic process automation",
"rpa",
"ultimaterpa",
"form filling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f9519b06d1464b05c68f5c46a883d08c30b9ae40db81d554083618ec96d9606",
"md5": "e88a4b38166d52d6b1faabebbb20ca12",
"sha256": "0056a4caa6e93f6fb2451cab0639e6f7c0235fa5752090eaff15a7e467f50dff"
},
"downloads": -1,
"filename": "urpaform-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e88a4b38166d52d6b1faabebbb20ca12",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7911,
"upload_time": "2023-08-28T11:47:41",
"upload_time_iso_8601": "2023-08-28T11:47:41.094986Z",
"url": "https://files.pythonhosted.org/packages/2f/95/19b06d1464b05c68f5c46a883d08c30b9ae40db81d554083618ec96d9606/urpaform-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed465a15e79896b5826461c05ab24c5718f82b21cb35fefd1c88075f822c3570",
"md5": "c7812a706187a7dadae3bd823f312a3c",
"sha256": "a63b0d243b11f2cf545d1db8aa2df56be5a05bc97a825029c4790da442b582c4"
},
"downloads": -1,
"filename": "urpaform-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c7812a706187a7dadae3bd823f312a3c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7230,
"upload_time": "2023-08-28T11:47:43",
"upload_time_iso_8601": "2023-08-28T11:47:43.007921Z",
"url": "https://files.pythonhosted.org/packages/ed/46/5a15e79896b5826461c05ab24c5718f82b21cb35fefd1c88075f822c3570/urpaform-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-28 11:47:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ultimaterpa",
"github_project": "urpaform",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "urpaform"
}
JSON
