Self-Service Start/Stop/Transfer Operations

Warning:

This topic is only applicable for the integration with Oracle Utilities Digital Self Service.

Retrieve Request Type Details

This operation is used to retrieve the following configuration information at the beginning of the start, stop and transfer transaction:
  • Action Method Role
  • Action Method
  • Self-Service Task Type
  • Customer Service Request Type
  • Person/Business Controls
  • Start Service Controls
  • Stop Service Controls

Action Method Role is determined based on the Request Mode, New Customer indicator and New Account indicator inputs. The Action Method Role is used to determine the Action Method. The Action Method defines the Self-Service Task Type and Customer Service Request Type configuration. Note that the Self-Service Task Type and Customer Service Request Type can differ by CIS Division and/or Customer Class. The Self-Service Task Type defines the self-service task BO to be used. The Customer Service Request Type defines the customer service request BOs used to persist data, and the controls used throughout the transaction. Controls determine the behavior of the self-service application UI, operations, and service task processing. Succeeding operations expect the Self-Service Task Type and Customer Service Request Type as inputs.

Person/Business Controls are based on the input person/business flag. Start Service Controls are returned if the input Request Mode is either 'Start' or 'Transfer'. Stop Service Controls are returned if the input Request Mode is either 'Stop' or 'Transfer'.

Time Zone is returned as part of the Start Service and Stop Service Controls. It comes from one of the following sources:
  1. Customer Service Request Type
  2. Premise - Input premise if available. Otherwise, premise linked to the input account's most recent service.
  3. Installation Options

Retrieve Service-Related Customer Details

This operation is used to retrieve the following service-related information for the input account and/or person:
  • Name
  • Mailing Address
  • Contact Details

If the input account is populated, the input person is either the account owner (main customer) or a guest who was invited by the owner. Name, Mailing Address and Contact Details are based on the account's main customer. If input account is not populated, Name, Mailing Address and Contact Details are based on the input person. Phone and email contact information are always returned. Other contact types are returned based on the corresponding control.

This operation also uses the Should Prompt For ID controls to determine if ID should be prompted for the input account and/or person. If the input account is populated, the account's main customer is used. Otherwise, the input person is used. If ID should be prompted, the valid ID Types controls are returned for input person.

Finally, this operation indicates if a non-final self-service start/stop/transfer task exists for the input account.

Service Eligibility

This operation determines if a customer is eligible to start service. It is used when starting new service, adding service, or transferring service. If the customer is eligible, a new self-service start/stop/transfer task is created where the input customer information and the results of processing performed throughout the transaction are persisted. The service task will remain in Pending status until it is transitioned by the finalize operation. Abandoned service tasks are discarded automatically via a monitor algorithm on the Pending status. The service task ID is returned as well as the customer's eligible and ineligible accounts.

The Retrieve Request Type Details operation that determines configuration information should be called before this operation can be used.

When starting new service for new customer (input person is not populated), the Check For Existing Person Algorithm control is used to determine if an existing person in the system matches the input name, ID, and contact information. If a match is found, the operation returns a match indicator, and no further processing is performed.

When starting new service or adding new service, person identity checks may be performed based on the ID check controls. The Should Prompt For ID controls are used to determine if ID should be prompted for the input person. This is the same step performed in the Retrieve Service-Related Customer Details operation and both should have the same result. It is necessary to do this step in this operation because the result from the Retrieve Service-Related Customer Details operation is not persisted.

The Start Service Eligibility Algorithms control determines eligibility. It uses the input information to this operation, the ID check results, and the ID prompt result. This control also determines the customer's eligible and ineligible accounts.

Process Other Person

This operation process additional persons when starting new service. The main customer's eligibility should be evaluated, and a pending self-service start/stop/transfer task already exists before this operation can be used. Eligible persons are persisted on the service task. Ineligible persons may be persisted based on the service task based on the Other Person Eligibility controls. Each person's eligibility is returned as output. Note that any additional persons that are currently in the self-service start/stop/transfer task are replaced with the input when this operation is called.

The Search For Person Algorithm control is used to find an existing person in the system that matches the input name, ID, and contact information. The search result (Match / No Match / Ambiguous Match) is returned as output. If the search resulted in an ambiguous match, the person is skipped. Person identity checks may be performed based on the ID check controls.

For new a new person, eligibility is based on ID check results. Note that if ID check is not performed, the person is considered eligible. Only eligible new persons are persisted on the service task. The Other Person Eligibility control determine the eligibility of an existing person. It is either based on ID check or a set of utility-specific eligibility algorithms. Eligibility based on ID check is evaluated the same way as a new person. Existing persons that are eligible are persisted on the service task. Existing persons that are ineligible are persisted on the service task if the Other Person Processing control is set to 'Review'.

Clear Other Person

This operation removes any additional persons that are currently in the pending self-service start/stop/transfer task.

Determine Services To Start

This operation determines the SP-based services to start at premise when starting new service, adding service, or transferring service. The main customer's eligibility should be evaluated, and a pending self-service start/stop/transfer task already exists before this operation can be used. It uses the Determine Services To Start Algorithm control to get a list of SA to start for SPs at the premise for the input start date. This information is stored in the service task's start service details. Note that SA and SP information currently in the service task are replaced when this operation is called. The operation returns the determined SPs along with badge number of the meter currently installed on the SP.

Note that the start date must be within the range defined by the start service controls. The range is calculated as follows:
  • Start Date Low Limit = Current Date + Lead Days
  • Start Date High Limit = Start Date Low Limit + Maximum Start Days in Future control
Lead Days is initially set to the Lead Days control. If the current time is past the Cutoff Time control, an extra day is added to it. Also, weekends and holidays based on the Work Calendar control are skipped when incrementing the Start Date Low Limit.

Validate Start SP Selection

This operation uses the Validate SPs To Start Algorithms controls to validate the selected SPs where service is being started if Start Level control is 'Individual Services'. It is used when starting new service, adding service, or transferring service. The SP-based services to start at the premise should be determined before this operation can be used.

Service Questions

This operation uses the Read Questions algorithm on the CS request type BO to retrieve the applicable service questions when starting new service, adding service, stopping service, or transferring service. The SP-based services to start at a premise and/or the SP-based services to stop for an account should be determined, and a pending self-service start/stop/transfer task already exist before this operation can be used.

Note that when transferring service, this operation is called for two scenarios - start service and stop service. The operation uses the input Question Placement Group to distinguish between these calls. Question Placement Group is used to logically group questions, based on where the questions are shown on the user interface.
  • If Question Placement Group is 'Start Service', the questions are filtered using the input premise and SPs.
  • If Question Placement Group is 'Stop Service', the questions are filtered using the input premise only. Any further filtering (e.g. SP Type) will be done by the calling system using the applicability list that is returned for each question.

When invoking the algorithm, the input account and SPs are used. If the input Question Placement Group is 'Stop Service' and Stop Level control is 'Account', all premises in the service task's stop details are used. Otherwise, the input premises are used.

Process Services To Start

This operation marks which of the SPs and SP-based SAs previously determined by the Determine Services To Start operation will be started based on the input premise or SPs when starting new service, adding service, or transferring service. If Start Level control is 'Premise' all SPs and SAs are marked. If Start Level control is 'Individual Services' only the input SPs and its SAs are marked.

This operation also process response to start service questions using Process Question Responses routine. In this operation, the routine may change which SAs are marked for start, set an SA's start option, or add non SP-based SAs to the services being started.

All services being started are validated using Validate Service To Start Algorithms control.

Deposit Assessment

This operation determines the deposit requirements when starting new service, adding service, or transferring service. The main customer's eligibility should be evaluated, and a pending self-service start/stop/transfer task already exists before this operation can be used. It uses the deposit controls and the customer information in the service task to determine if deposit is required. If deposit is required, the deposit amount is calculated using the Recommendation Algorithm associated with the Deposit SA Type control's deposit class. The deposit required indicator and deposit amount are persisted on the service task and returned as output. The Allow Pay In Full control is also returned as output.

If the deposit is required, the operation returns deposit installation options collection. Each entry has two attributes:
  • Number of Installments
  • Installment Amount
Number of Installments is based on the Number of Installments control. The corresponding Installment Amount is the deposit amount divided by the Number of Installments. Note that Installment Amount must be greater than or equal to the Minimum Installment Amount control an option to be included in the collection. If Allow Pay In Full control is 'true', the following entry is included in the collection:
  • Number of Installments = 1
  • Installment Amount = Deposit Amount

The operation will fail if deposit is required and not one deposit installation option can be determined.

Start Service Finalization

This is the final operation called when starting new service or adding service. It is used to update additional information on the self-service start/stop/transfer task and to nudge it out of the pending status. The additional information includes:
  • Number of Installments
  • Main customer's contact information
  • Paperless Billing switch
  • Auto Pay Information
  • Web User Information

Algorithms in the service task's lifecycle are responsible for persisting the collected information to the appropriate objects (person, account, premise, SA and SP). Refer to the self-service task BO (C1-SSStartStopXferServiceTask) for more information.

The operation returns one of the following task statuses:
  • In Progress – Service Task is in a non-final status.
  • Complete – Service Task is in the completed status.
  • Error – Service Task is in an error status.

Processing errors are returned as a list of messages. If service task processing resulted in a new account being added, the account ID is returned as an output.

Determine Services To Stop

This operation uses the Determine Services To Stop Algorithm control to determine the SP-based services to stop for an account at a given stop date when stopping service or transferring service. It returns number of premises that have stoppable services.

This operation can be called read-only mode. This mode is used by the self-service application to determine if stop service is available as an option to the user. When not in read-only mode, a self-service start/stop/transfer task containing the determined SP-based services is created if one doesn't exist (initial call when stopping service). The service task will remain in Pending status until it is transitioned by the finalize operation. The ID of the newly created service task is returned as output. If service task already exists (transferring service or stop date is changed when stopping service), the service task ID is passed to this operation and its stop details are replaced with the determined SP-based services.

Note that the stop date must be within the range defined by the stop service controls. The range is calculated as follows:
  • Stop Date Low Limit = Current Date + Lead Days
  • Stop Date High Limit = Stop Date Low Limit + Maximum Stop Days in Future control
Lead Days is initially set to the Lead Days control. If the current time is past the Cutoff Time control, an extra day is added to it. Note that weekends and holidays based on the Work Calendar control are skipped when incrementing the Stop Date Low Limit.

Retrieve Services To Stop

This operation retrieves the premises with stoppable service that were previously determined and persisted on the self-service start/stop/transfer task. A list of SAs is returned for each premise. Each entry has two attributes:
  • Service Type
  • Badge Number of the meters currently installed on the SPs associated with the SA

Pagination is applied to the returned premise list using the page offset and page limit input parameters.

Validate Stop Service Agreement Selection

This operation uses the Stop Level, Require SAs At Same SP To Behave Together, and Validate Services To Stop Algorithm controls to validate the selected SP-based services to stop. It is used when stopping service or transferring service. The SP-based services to stop for the account should be determined before this operation can be used.

Process Services To Stop

This operation marks which of the premises and SP-based SAs previously determined by the Determine Services To Stop operation will be stopped based on the input premises and SAs when stopping service or transferring service. If Stop Level control is 'Account' all premises and SAs are marked. If Stop Level control is 'Premise', all SAs for the selected premises are marked. If Stop Level control is 'SA', only the selected SAs are marked.

This operation also process response to stop service questions using Process Question Responses routine. In this operation, the routine may change which SAs are marked for stop or add non SP-based SAs to the services being stopped.

All services being stopped are validated using the Validate Services To Stop Algorithms control.

Stop Service Finalization

This is the final operation called when stopping or transferring service. It is used to update the self-service start/stop/transfer task with any additional contact information for the main customer and to transition it out of the pending status.

Algorithms in the service task's lifecycle are responsible for persisting the collected information to the appropriate objects (person, account, premise, SA and SP).

The operation returns one of the following task statuses:
  • In Progress – Service Task is in a non-final status.
  • Complete – Service Task is in the completed status.
  • Error – Service Task is in an error status.

Processing errors are returned as a list of messages.

Transfer Service Finalization

This is the final operation called when transferring service. It is used to update additional information on the self-service start/stop/transfer task and to nudge it out of the pending status. The additional information includes:
  • Number of Installments
  • Main customer's contact information
  • Paperless Billing switch
  • Auto Pay Information
  • Web User Information

Algorithms in the service task's lifecycle are responsible for persisting the collected information to the appropriate objects (person, account, premise, SA and SP).

The operation returns one of the following task statuses:
  • In Progress – Service Task is in a non-final status.
  • Complete – Service Task is in the completed status.
  • Error – Service Task is in an error status.

Processing errors are returned as a list of messages. If service task processing resulted in a new account being added, the account ID is returned as an output.