.. |n0| replace:: n\ :sub:`0` .. |m0| replace:: m\ :sub:`0` .. _label-data-entities: Data Entities ============= These are the data entities the new system is supposed to model. Each of these entities should be addable, editable, and removable as covered in more detail in :ref:`label-use-cases`. For each entity we give a short description to tell what it means, what its purpose is and in what regards (and how) it should be handled by the system. Again the more detailed actions on these entities provided by the system are described in the :ref:`label-use-cases` section. The data entities are sorted alphabetically, not by importance or similar. Used description terms should link to other respective entities/terms where possible. Each data entitiy description provides a list of use cases and other data entities connected. Connections to other data entities contain a relationship telling how many instances of the described entity are connected to how many instances of the related entity. The following relation types may occur (in both directions): - 1:1 (one on one) - n:1 (many on one) - n:m (many on many) - p:1 (many or none on one) - p:q (many or none on many or none) - p:n (many or none on many) - b:1 (one or none on one) with - n, m element of {1, 2, ...}, - p, q element of {0, 1, 2, ...} - b element of {0, 1} Examples: 1:p service-contract relation means that each service offered can result in various contracts, but each contract is only based on one service. p:q useraccount-userrole relation means that each user account can have no role or several roles and each role can be assigned to no user account or several user accounts. Relations can always be read in two directions. .. _label-business-unit: Business Unit ------------- An organisational unit for grouping of :ref:`label-officer`\ s (staff members) and :ref:`label-service`\ s. A business unit may correspond with an administrative division (geographical unit, government area) or any department or body of the distribution company. Business units can be nested, i.e. a business unit may contain other business units like wards, districts or undertakings. Connected to: :ref:`label-officer` (n:p), :ref:`label-service` (n:p), .. _label-contact-address: Contact Address --------------- A postal address. Connected to: :ref:`label-contact-data` (p:1) .. _label-contact-data: Contact Data ------------ The data neccessary to contact some :ref:`label-customer`, :ref:`label-officer` or similar entity. Contact data might contain several addresses, phone numbers, emails, etc. Connected to: :ref:`label-customer` (1:1), :ref:`label-contact-address` (1:p), :ref:`label-contact-email` (1:n), :ref:`label-contact-phone` (1:p) .. _label-contact-email: Contact Email ------------- An email address with optional additional clear name. For email addresses we store some timestamp that indicates when the respective email address was last checked successfully (thus marking it a 'valid' one). No timestamp means, the email address has never been checked. Connected to: :ref:`label-contact-data` (n:1), :ref:`label-timestamp` (1:q), :ref:`label-user-account` (1:b) Used in the following use cases: :ref:`label-uc-user-add`, :ref:`label-uc-user-manage`, :ref:`label-uc-service-manage` .. _label-contact-phone: Contact Phone ------------- Mobile phone number which is capable of receiving sms text messages. Connected to: :ref:`label-contact-data` (p:1) Used in the following use cases: :ref:`label-uc-user-add`, :ref:`label-uc-user-manage` , :ref:`label-uc-service-manage` .. _label-contract: Contract -------- A contract is created whenever a :ref:`label-customer` orders some :ref:`label-service` from the system. It is always connected to a :ref:`label-customer` and a :ref:`label-service` . A contract is not necessarily written on paper and signed by people. Instead it is an abstraction used inside the system. It is always created from a :ref:`label-service`, which tells about the basic data, with additional parameters set that depend on the type of :ref:`label-service` ordered. Contracts can trigger :ref:`label-transaction`\ s. For instance if some :ref:`label-customer` orders a service. When the service charges become due, a respective :ref:`label-transaction` is triggered. Contracts can have multiple :ref:`label-supp-contract`\ s. Connected to: :ref:`label-service` (p:1), :ref:`label-customer` (p:1), :ref:`label-supp-contract` (1:p), :ref:`label-transaction` (1:p), :ref:`label-meter` (1:b) .. _label-customer: Customer -------- A user data entity and beneficiary of :ref:`label-contract`\ s. Customers are added to the system by initial import (migration phase), being created by staff or can register themselves (self-registration) to the system. Each customer has a :ref:`label-user-account`. Customers have to provide :ref:`label-contact-data` and get :ref:`label-login-credentials` to login to the system. Once logged in, customers get a 'My Eko-Disco' page where they can - see their current orders - watch their consumption - order more services - handle contractual problems - get help if problems arise - retrieve bills - change their passwords Customers can order :ref:`label-service`\ s and pay these (kinds of payment depend on the type of service/good ordered and the available payment methods). Customers and their data can be managed by customers themselves (for instance when postal addresses change), and by officers. Connected to: :ref:`label-contract` (1:p), :ref:`label-contact-data` (1:1), :ref:`label-login-credentials` (1:1), :ref:`label-user-account` (b:1) .. _label-location: Location -------- A real-world location. Used for instance for meters to store information about their place. The location of a meter does not necessarily correspond with one of the :ref:`label-contact-address`\ es. Locations can either be less formal, for instance describing a location in words, or very precise by using GPS data. Connected to: :ref:`label-meter` (1:p) .. _label-login-credentials: Login Credentials ----------------- A set of username and password assigned to user accounts. Passwords are stored inside the system using strong cryptographic hash functions. Passwords can be reset on request. Connected to: :ref:`label-customer` (1:1), :ref:`label-user-account` (1:1) .. _label-meter: Meter ----- A meter measures power consumption. It has a place where it is installed and might be connected to one or several contracts. For a given time a meter can be connected to one or zero contracts. Each meter has to provide a :ref:`label-location` that tells, where it is installed. Meters also contain a history of meter values (:ref:`label-meter-value`), which is basically a list of meter values at a given time. Connected to: :ref:`label-contract` (b:1), :ref:`label-meter-value` (1:n), :ref:`label-location` (p:1) .. _label-meter-value: Meter Value ----------- The value of a :ref:`label-meter` at a certain point in time (providing a :ref:`label-timestamp`) authorized by some user or device. It serves mainly for computing power consumption of :ref:`label-customer`\ s. When a new meter value is added to the system (the respective :ref:`label-meter` is 'updated'), the system also registers how the the new value was entered, i.e. by whom and when. The system will be prepared to collect meter values in two ways: a) (push-method): by being fed with respective data by authorized users (officers) b) (pull-method): by polling dedicated hardware that provides the neccessary interface (automatic remote-reading). The second choice requires appropriate hardware to be in place, which in detail is not part of this specs. The system will, however, be prepared to collect meter data from external devices. Connected to: :ref:`label-meter` (n:1), :ref:`label-timestamp` (1:1), :ref:`label-user-account` (p:1) .. _label-officer: Officer ------- A user data entity of a staff member with certain permissions to manage portal data. Each officer has a :ref:`label-user-account`. Actors are called :ref:`Manager `\ s if they are officers with local managing permission. Connected to: :ref:`label-login-credentials` (1:1), :ref:`label-user-account` (b:1), :ref:`label-user-role` (1:p), :ref:`label-business-unit` (p:n) .. _label-report: Report ------ Administrative report or list to give overviews over current state of business. Includes lists of customers sorted by various categories (type of contract, amount of fees paid, etc.), lists of services sorted by various categories, etc. Reports are generated as PDF documents and are available for download by authorized users. Connected to: (almost everything else) .. _label-service: Service ------- Services are provided to :ref:`label-customer`\ s. They can have arbitrary forms, including one-time services (like installation of meters) and open-ended long-time services (like delivering power based on contract). Services are offered by :ref:`label-business-unit`\ s which means, each service belongs to one or more business units. They are managable by staff like goods offered in a shop. Services define the conditions under which they can be ordered by :ref:`label-customer`\ s, including prices, runtimes, etc. Services also serve as factories for :ref:`label-contract`\ s. Connected to: :ref:`label-contract` (1:p), :ref:`label-business-unit` (p:n) .. _label-supp-contract: Supplementary Contract ---------------------- A supplementary contract always belongs to some already existing :ref:`label-contract` but comes with an own set of parameters. A typical supplementary contract materialises if a customer orders an amount of electrical energy on the bases of a 'main' contract achieved between the customer and the distribution company. The parent contract for instance may guarantee a special price per kilowatt hour of electrical energy. Supplementary contracts are created by :ref:`label-contract`\ s. Connected to: :ref:`label-contract` (p:1), :ref:`label-service` (p:1), :ref:`label-customer` (p:1), :ref:`label-transaction` (1:p) .. _label-timestamp: Timestamp --------- A timestamp can be a calendar date or a calendar date plus some day time. The system will internally use UTC-based timestamps only to minimize ambiguities. In menus, frontends, etc. timestamps are displayed in local Lagos time. Connected to: :ref:`label-meter-value` (1:1), :ref:`label-contact-email` (p:1) .. _label-transaction: Transaction ----------- A transaction is some business-relevant action taken. A transaction means basically, that something happened, that leads to increased or decreased customer accounts. Normally this is something like a payment, some service order or similar. Transactions do always belong to one certain customer account. They also contain some amount of money which is thereby transfered to or from a customer's account. They also always reference a service which is consumed, purchased, or (pre-)paid by the respective customer. Connected to: :ref:`label-customer` (p:1), :ref:`label-service` (p:1), :ref:`label-contract` (p:1) .. _label-user-account: User Account ------------ A user account is a set of user data and :ref:`label-login-credentials` which allows a user (agent) to authenticate against the system and let the system store some information required for user handling, such as real name, email address and/or mobile phone number. An email address and/or phone number ensures that the user can be contacted electronically by the system. :ref:`label-user-role`\s are assigned to user accounts and managed by the system to grant authorization for the various views of the portal. Real-world officers (staff members) and customers are different to the system as they will get different roles. Also anonymous users (users without user account) are accepted by the system to provide marketing pages, service offers, etc. Users can be blocked or removed from the system. Connected to: :ref:`label-login-credentials` (1:1), :ref:`label-customer` (1:b), :ref:`label-user-role` (p:q), :ref:`label-contact-email` (b:1) .. _label-user-role: User Role --------- A set of permissions assigned to a group of :ref:`label-user-account`\ s. Connected to: :ref:`label-user-account` (p:q)