Skip to content

# Usage Examples

## Create a new user and rename it

### 1. Open a `WialonSession` as a context manager and instantiate a user.

Let’s also import `generate_wialon_password` so we don’t have to come up with a valid Wialon password ourselves.

    from terminusgps.wialon.items import WialonUser
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.utils import generate_wialon_password

    with WialonSession(token="my-secure-wialon-token") as session:
        user = WialonUser(
            id=None,
            session=session,
            creator_id="27884511", # Admin user id
            name="test_user",
            password=generate_wialon_password(32)
        )
        print(f"{user.name = }") # user.name = "test_user"

See also

`create()` for details on initializing a user.

### 2. Execute `rename()` on the unit within the session context.

Calling `rename()` renames the unit in Wialon and updates its `name` attribute.

    from terminusgps.wialon.items import WialonUser
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.utils import generate_wialon_password

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        unit.rename("super_test_user")
        print(f"{user.name = }") # user.name = "super_test_user"
        # Session is logged out after exiting scope

### Full code example

    from terminusgps.wialon.items import WialonUnit
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.utils import generate_wialon_password

    with WialonSession(token="my-secure-wialon-token") as session:
        unit = WialonUnit(
            id=None,
            session=session,
            creator_id="123",
            name="test_user",
            password=generate_wialon_password(32)
        )
        print(f"{unit.name = }") # user.name = "test_user"
        unit.rename("super_test_user")
        print(f"{unit.name = }") # user.name = "super_test_user"
        # Session is logged out after exiting scope

## Create an account and migrate a unit into it

### 1. Create a new user for the account.

If you choose to use an already existing user for this process, you may need to pass `skip_creator_check=True` when creating the resource in the next step.

This is because Wialon forbids users from creating accounts if they are already responsible for creating other Wialon objects.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        account_user = WialonUser(
            id=None,
            session=session,
            creator_id="27884511", # Admin user id
            name="account_user",
            password="super_secure_password1!",
        )

See also

`create()` for details on initializing a user.

### 2. Create a new resource with the account user as its creator.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        account_resource = WialonResource(
            id=None,
            session=session,
            creator_id=account_user.id,
            name="account_resource",
        )

See also

`create()` for details on initializing a resource.

### 3. Retrieve a `WialonUnit`.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        unit = WialonUnit(id="12345678", session=session)

See also

`create()` for details on initializing a unit.

### 4. Grant the account user migration permissions.

`grant_access()` grants a user access to a unit using an access mask.

`ACCESSMASK_UNIT_MIGRATION` is an access mask that contains all required permissions migrating a unit into an account.

If you don’t grant these permissions to the account user, the next steps may fail.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        account_user.grant_access(unit, access_mask=constants.ACCESSMASK_UNIT_MIGRATION)

### 5. Transform the resource into an account and enable it.

A `WialonResource` can be turned into a Wialon account by calling `create_account()`.

`enable_account()` must be called at some point because a disabled account cannot migrate units into itself.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        account_resource.create_account("terminusgps_ext_hist")
        account_resource.enable_account()

### 6. Migrate the unit into the account.

Finally, pass the unit into `migrate_unit()` to finish unit migration.

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        account_resource.migrate_unit(unit)

### Full code example

    from terminusgps.wialon import constants
    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import (
        WialonResource, WialonUnit, WialonUser
    )

    with WialonSession(token="my-secure-wialon-token") as session:
        account_user = WialonUser(
            id=None,
            session=session,
            creator_id="27884511", # Admin user id
            name="account_user",
            password="super_secure_password1!",
        )
        account_resource = WialonResource(
            id=None,
            session=session,
            creator_id=account_user.id,
            name="account_resource",
        )
        unit = WialonUnit(id="12345678", session=session)
        account_user.grant_access(unit, access_mask=constants.ACCESSMASK_UNIT_MIGRATION)
        account_resource.create_account("terminusgps_ext_hist")
        account_resource.enable_account()
        account_resource.migrate_unit(unit)

## Add a driver to a resource

### 1. Retrieve a resource.

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonResource

    with WialonSession(token="my-secure-wialon-token") as session:
        resource = WialonResource(id="12345678", session=session)

### 2. Call `create_driver()`.

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonResource

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        resource.create_driver(
            name="test_driver",
            code="1234",
            desc="A test driver.",
            phone="+15555555555",
            mobile_auth_code="1234",
            custom_fields={"my_field_key": "my_field_value"}
        )

### Full code example

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonResource

    with WialonSession(token="my-secure-wialon-token") as session:
        resource = WialonResource(id="12345678", session=session)
        resource.create_driver(
            name="test_driver",
            code="1234",
            desc="A test driver.",
            phone="+15555555555",
            mobile_auth_code="1234",
            custom_fields={"my_field_key": "my_field_value"}
        )

## Update a unit’s “to_number” custom field

### 1. Retrieve a `WialonUnit`.

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonUnit

    with WialonSession(token="my-secure-wialon-token") as session:
        unit = WialonUnit(id="12345678", session=session)

### 2. Call `update_cfield()`.

If the custom field doesn’t exist in Wialon yet, it will be created by `update_cfield()`.

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonUnit

    with WialonSession(token="my-secure-wialon-token") as session:
        ...
        unit.update_cfield(key="to_number", value="+15555555555")
        print(f"{unit.cfields['to_number'] = }") # unit.cfields["to_number"] = "+15555555555"

### Full code example

    from terminusgps.wialon.session import WialonSession
    from terminusgps.wialon.items import WialonUnit

    with WialonSession(token="my-secure-wialon-token") as session:
        unit = WialonUnit(id="12345678", session=session)
        unit.update_cfield(key="to_number", value="+15555555555")
        print(f"{unit.cfields['to_number'] = }") # unit.cfields["to_number"] = "+15555555555"