14 The Work Management API

WMSession Interface Operation Descriptions

• startTaskGenerationSubSession

  Obtains the object reference for the TaskGenerationSubSession

• destroyTaskGenerationSubSession

  Triggers destruction of the TaskGenerationSubSession object

• startTaskViewingSubSession

  Obtains the object reference for the TaskViewingSubSession

• destroyTaskViewingSubSession

  Triggers destruction of the TaskViewingSubSession object

• startTaskCompletionSubSession

  Obtains the object reference for the TaskCompletionSubSession

• destroyTaskCompletionSubSession

  Triggers destruction of the TaskCompletionSubSession object

The requestID parameter used by many of the operations in the Work Management API is an arbitrary, user-defined number that provides a means of relating requests and notifications when performing asynchronous operations. The Work Management operations do not make use of this parameter. Instead, they return it unchanged and unevaluated when executing the notification method.

Many of the descriptions of the operations in the Work Management API state that the operation returns a value or values. In such cases, remember that the operation returns that value by invoking the appropriate response operation on the notification object.

TaskGenerationSubSession Interface Operation Descriptions

• generateAndSaveTasks

  Given an order (document_number), a provisioning plan ID, and the time zone of the client, this operation generates tasks for that order along with completion dates for each task. A sequence of tasks with their dates are returned along with a sequence that contains the relationship between these tasks and a status. generateAndSaveTasks supports the MetaSolv Solution rules and behaviors functionality when generating tasks.

• getAllQueues

  This operation provides the functionality to return a sequence of all available work queues in the MetaSolv Solution database if the work queues are to be manually assigned.

• getAllProvPlans

  This operation provides the functionality to return a sequence of all available provisioning plans in the MetaSolv Solution database if the provisioning plan is to be assigned manually.

• getPlanID

  This operation provides the functionality to return a specific provisioning plan name specified by the third party developer. This operation returns the ID of the plan using a plan name. This is an alternative method to choosing a default provisioning plan for internet services.

• getAutoPlanID

  This operation provides the functionality to automatically pick a provisioning plan based on predefined third-party criteria. This operation returns the first plan ID which is defined under the organization, jurisdiction, and the service group of the given order (document_number.)

TaskViewingSubSession Interface Operation Descriptions

• getUserWorkQueue

  This operation provides the functionality to return all work queues owned by the user ID passed in to the operation. This process uses some of the existing functionality and SQL used in the Work Management subsystem to build a list of personal work queues.

• getWorkGroupWorkQueue

  This operation provides the functionality to return all work queues except those owned by the user ID passed in to the operation. This process uses some of the existing functionality and SQL used in the Work Management subsystem to build a list of work queues.

• getTasks

  This operation provides the functionality to return task information for the work queue passed in to the operation. Date/time fields are converted to local time using the local time zone that is passed in. Task information returned includes task_type, task_status, revised_completion_date, queue_status, type_of_sr (type of service request) pon, first_ecckt_id, document_number, and task_number.

• getPredecessorTasks

  This operation provides the functionality to return the task information of predecessor tasks for a given task. Predecessor task information includes task_type, task_status, scheduled_completion_date, actual_release_date, revised_completion_date, estimated_completion_date, work_queue_id, actual_completion_date, task_critical_date_ind (critical task ind), task_status_date, document_number, task_number, first_jeopardy_id (jeopardy ind), and auto_comp_ind (auto completion ind.)

• getFollowerTasks

  This operation provides the functionality to return follower task information for a given task. Follower task information includes task_type, task_status, scheduled_completion_date, actual_release_date, revised_completion_date, estimated_completion_date, work_queue_id, actual_completion_date, task_critical_date_ind (critical task ind), task_status_date, document_number, task_number, first_jeopardy_id (jeopardy ind), and auto_comp_ind (auto completion ind.)

• getTaskCircuits

  This operation provides the functionality to return circuit information as it relates to a given task. Task circuit information includes ecckt (circuit ID), act_comp_date (circuit completion date), jeopardy_ind, ckt_design_id, complete_ind (circuit completion ind) and, notes_ind (circuit notes ind.)

• getTaskChecklist

  This operation provides the functionality to return the checklist items for a given task. Task checklist information includes check_code (checklist identifier code), check_comp_date (checklist completion date), check_seq, check_desc (checklist description), and complete_ind (checklist completion ind.)

• getTaskGWEvent

  This operation provides the functionality to return the gateway events for a given work_queue_id. Task gateway event information includes event_id, event_nm (event name), task_type, task_type_pre (predecessor task to gateway event's task), force_reopen_ind, status_cd, version, signal_ind, in_out_cd, event_detail, document_number, task_number, task_number_pre, and serv_item_id.

• updateChecklist

  This operation updates the MetaSolv Solution database when the user changes the Completion Indicator field. The completion date for the checklist item is set to null if the completion indicator is set to N or it is set to the current date and time if the completion indicator is set to Y.

• updateGWEvent

  This operation provides the functionality to update the Status field in the gateway events tables.

• getServReqTasks

  This operation returns task information for a given document number (service request). This operation is oriented more toward the view of the service request than the getTasks method is. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• acceptTask

  In the Work Management subsystem, users acknowledge tasks that have been placed in their work queue by accepting them. This operation enables you to acknowledge a task that has been placed in a work queue.

• updateEstCompDate

  This operation updates the estimated completion date for a specified task. Date and time information is stored in the database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• transferTask

  This operation transfers the specified task from the work queue identified by the current WorkQueue parameter to work queue identified by the newWorkQueue parameter.

• rejectTask

  This operation rejects a completed predecessor task. You reject a task to return it to the work queue of the person who completed that task so they can rework the task.

  When you use the rejectTask method, the Work Management API changes the rejected task's reject status to R (Rejected) and the task's status to Ready. The API also changes the reject status of all completed follower tasks to R and sets their status to Pending.

  Note:

  You can find a task's reject status in the rejectStatus field in the predFollow structure and the taskRejectStatus field in the taskView structure.

  You can find a task's status in the taskStatus field in the predFollow structure and the taskStatus field in the taskView structure.

• searchWorkQueue

  This operation takes a string or partial string passed in through the searchKey parameter and tries to match it to existing work queues in the MetaSolv Solution database. The operation returns a sequence of all work queues that match the search criteria. The type of search is determined by the searchType parameter, a value of ”B” requests a ”Begins with” search, and a value of ”C” requests a ”Contains” search.

• getTaskDetail

  This operation returns task detail information for a given document number and task number. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• getServReqDetail

  This operation returns basic service request information for a given document number. Date/time information is returned using the timezone you specify in the timezone parameter. Service request detail information includes type of service request, service request status, responsible party, purchase order number, order number, desired due date, supplement type, and CCNA.

• getServReqNotes

  This operation returns a sequence of all notes that have been entered for the designated service request.

• addServReqNote

  This operation adds a service request note for the designated service request.

• getTaskJeopardy

  This operation returns a sequence of task jeopardy information for the document number/task number passed in to the method. Jeopardy information is used to identify why a task is or was in jeopardy of being completed late. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• getTaskJeopardyDetail

  This operation returns task jeopardy information for a single jeopardy ID passed in to the method. Jeopardy information is used to identify why a task is or was in jeopardy of being completed late. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• addTaskJeopardy

  This operation adds task jeopardy information for the task number you designate. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• updateTaskJeopardy

  This operation updates task jeopardy information for the task number you designate. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks that will be performed in different time zones.

• deleteTaskJeopardy

  This operation deletes jeopardy information for a given task on a given service request.

• getJeopardyCode

  This operation returns a sequence of all available jeopardy codes in the MetaSolv Solution database.

TaskCompletionSubSession Interface Operation Descriptions

• getOrganization

  This operation returns a sequence of all available organization IDs for the organization type defined in the MetaSolv Solution Jeopardy Code Organization Type preference.

• getWhyMissCode

  This operation provides the functionality to return a sequence of whymissed codes used when selecting a whymissed code in the task completion process.

• completeTask

  Given a document number and task number, this operation validates the task to ensure it is ready to be completed. If it passes validation, and is on time, the task is completed. If the task is being completed late, a whymissed code is assigned before completing the task.

• completeTaskOnDate

  This operation completes the task represented by the passed document number and task number, and sets the revised completion date to the passed completionDate if the following conditions are true: The task is late, but not beyond its grace period, and the Allow Edit of Task Completion within Grace Period preference is set to Y. Otherwise, the passed completionDate is ignored.

  Note:

  The completeTaskOnDate operation uses the same return codes as the completeTask operation.

• validateEditActCompDate

  This operation validates whether or not a task's actual completion date can be edited.

• reopenTask

  Reopens the completed task that you identify by document number and task number.

  WARNING:

  Reopening tasks is not recommended for the following reasons:

  • There is no notification, to the owner of a queue, that a task is a reopened task, and no indication in the status column that the status is "Reopened".

  • If the reopened task has any associated gateway events, those gateway events must be reactivated.

  • If the reopened task is a precondition for a gateway event on another task, that gateway event must be reactivated.

  • If there are any completed follower tasks to the one you want to reopen, you must reopen the follower tasks first. If the follower tasks are not in your own work queue, they reappear, when reopened, in their original work queues with a status of Pending. The original queue's owner does not receive notification of reopened tasks in their queue.

• searchCompletedTasks

  This operation returns a sequence of completed tasks that meet the passed search criteria. Date and time information is stored in the MetaSolv Solution database in Greenwich Mean Time (GMT). The Work Management API converts dates and times between the time zone identified by the timezone parameter and the GMT equivalent. This allows coordination of tasks performed in different time zones.

Sample Solicited Message Process Flow

When the Work Management API is the client, the overall process flows as follows:

1. The API client binds to the third-party server to get a WDIRoot object reference.

2. The API client invokes the connect operation of the WDIRoot interface, which yields a WDIManager object reference.

3. The API client invokes the startSignal operation of the WDIManager interface to get a WDISignal object reference.

4. The API client invokes the eventOccurred operation of the WDISignal interface passing a WDIEvent structure to notify the third-party application that an event registered to them has occurred within the database.

5. The API client invokes the destroySignal operation of the WDIManager interface.

6. The API client invokes the disconnect operation of the WDIRoot interface.

7. Once the third-party server completes processing, possibly involving additional unsolicited messages to the MetaSolv Solution Application Server, the third party server binds to the application server and follows the same process described above for the MetaSolv Solution client with the exception that the eventCompleted/Errored operations are invoked passing the original WDIEvent structure.

If the third-party application encounters an error, it throws a WDIExcp as defined by the IDL. The client handles CORBA system exceptions and WDIExcp exceptions.