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"