This chapter provides overview information about the Oracle Communications Order and Service Management (OSM) Extensible Markup Language (XML) Application Programming Interface (API). It is assumed that the programmer has user-level knowledge of Windows and UNIX operating systems.
The OSM XML API enables you to:
Create, retrieve, and update orders.
Transition orders: Move an order through the various states and tasks of a process. This includes moving an order to a new process through exception processing.
Search for the next order at task: Search for the next available order at a given task.
Copy orders: Copy the data of an existing order to produce a new order.
Suspending and resuming orders: Temporarily halt all provisioning activity on an order and then release the suspended order back into the system for provisioning.
Add attachments and remarks: Add remarks along with optional attachments to orders. After you add the remark, it is stamped with the time, task, and state of the order at that time.
Query: Retrieve a list of orders through two query functions: a predefined query that lists orders of interest to an external agent, and a generalized query that provides external agents a means to define their own query criteria.
Retrieve the order data and process history: Retrieve the history of an order as it moves through the process.
Retrieve user information: Retrieve the user's name and description, as well as the name and description of each workgroup to which they belong.
You can use the XML API for the following purposes:
Customizing the appearance or functioning of a task when customization using behaviors or OSM Java server pages does not satisfy all of your requirements.
Using from within an automation plug-in when necessary because the Web Services API and the OSM automation functionality do not meet your requirements.
You can use the XML API functions from the Automation Framework when running automation plug-ins by using the OSM Java OrderContext class processXMLRequest method. Parts of XML API (mainly GetOrder.Response) appear in various places as a context document throughout the OSM model. For example, when an automated task transitions into the received state, the automation framework starts an automation plug-in associated with it and passes the plug-in the TaskContext object. You can access the data associated to that TaskContext object using the GetOrder.Response XML API function call.
The XML API is deprecated for the following uses:
External automation (for example, polling). Use the event-driven Automation Framework for this purpose.
Integration with an upstream system. Use the Web Service API for this purpose.
Task automation when the equivalent functionality exists in the Automation Framework. See "Localizing OSM" and the OSM Javadocs for more information about automation plug-ins.
Processing manual tasks and order submission when the equivalent functionality exists within the OSM Task web client and the OSM Web Services. See OSM Task Web Client User's Guide and "Using OSM Order Management Web Services" for more information.
The following operations are deprecated for all uses, and are provided for backward compatibility only, since they are not in accord with current OSM direction:
SetException.Request
ListException.Request
GetNextOrderAtTask.Request
AddOrderThread.Request
This chapter is designed for developers familiar with XML 1.0 DOM level-1 and the HTTP transport mechanism for delivery of XML messages. You must ensure that an XML parser and DOM implementation is available on your platform.
OSM assigns all internally processing orders an order ID (OrderID). You can use the OrderID to indicate which order you want to run the function against. You specify the data available to many of the XML API function calls with the View and OrderHistID parameters.
You configure the data available to a View when you create an order specification in Design Studio. In the order specification editor Permissions tab, Query Task subtab, you can select a default Query Task, which is a manual task that is not part of a process flow. All data that you define in the manual task editor Task Data tab represents the data available to XML API functions that use the View field.
OSM generates a OrderHistID every time an OSM task transitions from one state to another of performs a status transition from one task to another. You configure the data available to an OrderHistID when you create a manual or automated task in Design Studio. All data that you define in the manual or automated task editor Task Data tab represents the data available to the XML API functions that use the OrderHistID field.
Oracle recommends that you only use the XML API functions that reference View or OrderHistID in the limited way described in "About Using the XML API."
The OSM XML API provides a single-access point located at an HTTP address. In your web browser, enter:
http://server:port/OrderManagement/xmlapi/
where server is the specific server host name on which the application is deployed and port is the HTTP or HTTPS port on which the application listens. If you have installed OSM in a cluster, the server and port would be the host name and HTTP or HTTPS port number of the software or hardware load balancer configured with the OSM WebLogic cluster. See OSM Installation Guide for more information about HTTP and HTTPS hardware and software load balancing options for OSM WebLogic clusters.
All requests consist of an HTTP POST request and the responses consist of an HTTP response.
See the OSM_home/SDK/XMLSchema/oms-xmlapi.xsd schema for additional information about the OSM XML API, where OSM_home is the directory in which the OSM software is installed.
Before using any API messages, you must login by supplying a valid user ID and password. If the login is successful, a session key is supplied as an HTTP cookie which must be included in the HTTP header of subsequent requests. After using the OSM API, you must release the session key by requesting to logout. The login/logout request is only valid from OMS version 2.5 and is not part of the API message formats.
To login, an HTTP POST message must be sent to:
http://server:port/OrderManagement/XMLAPI/login?username=un&password=pw
where:
server is the specific server on which the application is deployed
port is the HTTP or HTTPS port on which the application listens
un is the username of the authorized user
pw is the password of the authorized user
If you have installed OSM in a cluster, the server and port would be the host name and HTTP or HTTPS port number of the software or hardware load balancer configured with the OSM WebLogic cluster. See OSM Installation Guide for more information about HTTP and HTTPS hardware and software load balancing options for OSM WebLogic clusters.
If successful, an XML API cookie is sent to the client. If unsuccessful, an HTTP FORBIDDEN (403) response is sent.
To logout, an HTTP POST message must be sent to:
http://server:port/OrderManagement/XMLAPI/logout
where server is the specific server on which the application is deployed, and port is the port on which the application listens.
OSM messages follow a simple format that allows for arbitrary data and metadata to be passed across a network.
Each operation that can be requested of the XML API defines its own root element for an XML document with the format command_name.Request. Any required parameters are child elements of the operation request.
For each request operation, there is a corresponding response document with a root element in the form command_name.Response. Any returned data is a child element of the operation response.
If non-critical errors occur during processing of an operation request, they are children of a Warnings element, as shown in Example 3-2.
Example 3-2 Output XML Message Format With Warnings
<command_name.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<result1 />
<result2 />
... additional result elements ...
<Warnings>
<Warning code="1052" desc="SQL Warning">message</Warning>
</Warnings>
</command_name.Response>
If errors occur that prevent a request from being processed, the XML API returns an error document with a root element of command_name.Error. The error(s) that occurred are children of the error document.
You must monitor returning response messages from OSM for any errors that indicate whether the request operation succeeded or failed. If the operation request fails it is the responsibility of the sender to track and resubmit the failed request after troubleshooting the problem.
Example 3-3 Output XML Message Format With Errors
<command_name.Error xmlns="urn:com:metasolv:oms:xmlapi:1"> <Error code="300" desc="Request parameter error">message</Error> </command_name.Error>
If an invalid document is received, the server returns the HTTP code 403: Forbidden.
When you create XML, element values must not contain the characters &, <, or >. The XML standard defines the following replacement text:
& - &
< - <
> - >
' - '
" - "
The date/time format is the same for input and output messages. For any parameter with a date/time value, the format is:
yyyy-MM-ddTHH:mm:ss timezone
where
yyyy is the four-digit year
MM is the two-digit month
dd is the two digit day of the month
HH is the two digit hours in 24-hour format
mm is the two-digit minutes
ss is the two-digit seconds
timezone is a three-letter designation of the time zone
For example:
2013-08-05T14:06:05 EDT
All requests are processed in the context of the privileges assigned to a user ID. Prior to using the messages of the XML API, a user ID must be authorized. An authorization servlet, based on a user ID and password, authenticates a user ID and provides a session ID HTTP cookie to be used by subsequent requests. If further security is required, the XML API can be deployed in an environment that supports HTTPS for secure transport.
The OSM XML API does not provide access to the administrative facilities of OSM. Before using this API, you must use the OSM Administrator to configure a user ID that establishes the security privileges for the external software. This determines the range of data that can be retrieved from OSM.
The mnemonics in Table 3-1 are reserved and used to reference special systems values. If an order data element is created with the same mnemonic as a reserved mnemonic, the system functions correctly. The Worklist and Query response lists two elements with the same element name - one for the system value and one for the data element value.
| Header | Mnemonic |
|---|---|
|
Order Sequence ID |
_order_seq_id |
|
Order History Sequence ID |
_order_hist_seq_id |
|
State |
_order_state |
|
Execution Mode |
_execution_mode |
|
Task Mnemonic |
_task_id |
|
Order Source Mnemonic |
_order_source |
|
Order Type Mnemonic |
_order_type |
|
Order State |
_current_order_state |
|
Target Order State |
_target_order_state |
|
Reference Number |
_reference_number |
|
Priority |
_priority |
|
User |
_user |
|
Process Description |
_process_description |
|
Order Status |
_process_status |
|
Date Created |
_date_pos_created |
|
Date Started |
_date_pos_started |
|
Root node |
_root |
|
Number of Remarks |
_num_remarks |
|
Expected Order Completion Date |
_compl_date_expected |
|
NotificationID |
_notif_id |
|
Notification Description |
_notif_desc |
|
Notification Type |
_notif_type |
|
Notification Priority |
_notif_priority |
|
Notification Timestamp |
_notif_time |
|
Namespace |
Namespace_namespace |
|
Version |
Version_version |
The following list contains all currently available requests and their responses.
AddOrderThread lets you add sub process threads to a pending order. The order must reside in one of the sub processes.
Note:
AddOrderThread has been deprecated and is supported only for backward compatibility. Use amendment processing functionality instead.AddOrderThread
OrderID: The Order ID
Process: The process mnemonic to indicate where the sub process task resides
ProcessPosition: The process position mnemonic of the sub process task.
Add: A list of nodes to be added. The format of this should follow UpdateOrder. Request format. You may add multiple instances of the pivot nodes, multiple threads are created as a result.
Request Example with One Pivot Node Value
<AddOrderThread.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<Process>process_mnemonic</Process>
<ProcessPosition>process_position_mnemonic</ProcessPosition>
<Add path="/client_info">
<address>
<street1>55 James St.</street1>
<city>Washington</city>
<state>DC</state>
<country>USA</country>
<zip>20002</zip>
</address>
</Add>
</AddOrderThread.Request>
In this case, client_info is the pivot node.
<AddOrderThread.Response xmlns="urn:com:metasolv:oms:xmlapi:1"/>
Request Example with Multiple Pivot Nodes
<AddOrderThread.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<Process>process_mnemonic</Process>
<ProcessPosition>process_position_mnemonic</ProcessPosition >
<Add path="/error">
<code>1000</code>
<code>2000</code>
</Add>
</AddOrderThread.Request>
In this case, /error/code is the pivot node.
<AddOrderThread.Response xmlns="urn:com:metasolv:oms:xmlapi:1"/>
200: Order data invalid
232: Order update failed
270: Transaction not allowed
302: Request parameter error
350: Pivot node data is not provided
351: Process position supplied is not a sub process task
352: No sub process task is currently pending
354: Process position not found
355: Pivot node not found
356: Cannot spawn threads for sub-process tasks that support sequential sub-processing
400: Not authorized
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.A list of retrievable acknowledgments for a given notification.
Acknowledgments
The request requires one of two possible parameters:
Notification: If the notification is supplied, all acknowledgments for that notification are returned.
Order ID: If the order ID is supplied, all acknowledgments for all notifications for that order ID are returned.
Namespace: The namespace mnemonic of order type/source.
Version: The version of the order type or source. If you do not indicate a version, OSM uses the default version.
The Notification and NotificationDescription elements are identical for all acknowledgments. If the request was for a Notification, the information is duplicated to keep consistency of the Acknowledgement element's content.
<Acknowledgements.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <Notification>send_order_creation</Notification> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </Acknowledgements.Request>
The response includes the NotificationID or OrderID supplied and zero or more Acknowledgement elements. Each Acknowledgement element includes the following:
Notification ID: The notification ID associated with this acknowledgment.
NotificationDescription: The description of the notification. If no description, it is left blank.
OrderHistID: The order history ID associated with the acknowledgment. If this is not a transition based notification, then OrderHistID is empty.
Time: The time the acknowledgment was created.
Author: The user ID who created the acknowledgment.
Comment: The comment included with the acknowledgment. If no comment is supplied, it is empty.
Action: A string with a value of one of:
Activate: the acknowledgment was created when the notification was activated.
Update: the acknowledgment was added to the notification.
Deactivate: the acknowledgment deactivated the notification.
<Acknowledgements.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<NotificationID>3244</NotificationID>
<Acknowledgement>
<NotificationID>3244</NotificationID>
<NotificationDescription>Poll every hour</NotificationDescription>
<OrderHistID/>
<Time>2000-10-30T14:44:33 EST</Time>
<Author>OMS_160</Author>
<Comment/>
<Action>activate</Action>
</Acknowledgement>
<Acknowledgement>
<NotificationID>3244</NotificationID>
<NotificationDescription>Poll every hour</NotificationDescription>
<OrderHistID/>
<Time>2000-10-30T15:01:22 EST</Time>
<Author>jdoe</Author>
<Comment>Activated switch</Comment>
<Action>deactivate</Action>
</Acknowledgement>
</Acknowledgements.Response>
110: Order not found
190: Notification not found
302: Request parameter error
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Adds an acknowledgment to a notification. A notification can be acknowledged any number of times until is deactivated. Once an acknowledgment with a request to deactivate the notification is received, the notification is no longer included in the list of notifications.
AcknowledgeNotification
NotificationID: The unique identification number of the notification.
OrderID: The order ID associated with the notification. Omitted for system-based notifications.
OrderHistID: The order history ID associated with the notification. Omitted or polled notifications.
Comment: A string description to include with the acknowledgment.
Deactivate: A "true" or "false" value to deactivate the notification.
<AcknowledgeNotification.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <NotificationID>3444</NotificationID> <OrderID>123</OrderID> <OrderHistID>5665</OrderHistID> <Comment>This is a string comment</Comment> <Deactivate>true</Deactivate> </AcknowledgeNotification.Request>
<AcknowledgeNotification.Response xmlns="urn:com:metasolv:oms:xmlapi:1" />
190: Notification not found
302: Request Parameter Error
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Assigns an order to a given user.
AssignOrder
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
User: The user ID to assign to the order.
<AssignOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>22334</OrderHistID> <User>jsmith</User> </AssignOrder.Request>
The AssignOrder response includes the new Order History ID for the order.
<AssignOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>33247</OrderHistID> </AssignOrder.Response>
110: Order not found
251: Transition invalid
253: User not found
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Cancels an order as described below depending on the parameters supplied in the request:
Cancels the pending tasks for an order and sets an exception status regardless of where it currently is in the process flow. All pending tasks are removed and the order goes to the location defined by the exception status - either a particular task, or stopped.
Or
Cancels an order by undoing all completed tasks and returning the order to the creation task.
To cancel and set an exception:
OrderID: The ID of the order to cancel
Status: The exception status mnemonic to set
To cancel and undo completed tasks:
OrderID: The ID of the order to cancel
And one of the following:
Immediate: Force immediate cancellation of all completed tasks in the order.
GracePeriodExpiryDate: A period of time to allow tasks in the Accepted state time to complete.
Infinite: Wait indefinitely until all tasks in the Accepted state complete.
EventInterval: If the cancellation is not immediate, you can set an interval for sending a jeopardy notification.
Reason: The reason for canceling the order.
Request Example 1: Cancel and Set Exception
<CancelOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Status>status_memonic</Status> </CancelOrder.Request>
Request Example 2: Cancel and Undo
<CancelOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Immediate/> <Reason>Customer relocating services</Reason> </CancelOrder.Request>
or
<CancelOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <GracePeriodExpiryDate>2006-10-10T11:10:10 EST</GracePeriodExpiryDate> <EventInterval>PT10S</EventInterval> <Reason>Customer relocating services</Reason> </CancelOrder.Request>
or
<CancelOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Infinite/> <Reason>Customer relocating services</Reason> </CancelOrder.Request>
Response Example 1: Cancel and Set Exception
If the status mnemonic resulted in the order moving to a task, the OrderHistID has a value. If the order is stopped, then OrderHistID is empty.
<CancelOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID/> </CancelOrder.Response>
<CancelOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> </CancelOrder.Response>
110: Order Not Found
255: Invalid Status Mnemonic
270: Transaction not allowed
302: Request Parameter Error
400: Not Authorized
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Completes an order and supplies a status mnemonic for the order.
CompleteOrder
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
Status: The status mnemonic.
<CompleteOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>33251</OrderHistID> <Status>submit</Status> </CompleteOrder.Request>
<CompleteOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID/> </CompleteOrder.Response>
Response Example for Amendment
<CompleteOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>7</OrderID>
<OrderHistID/>
<Amendment xmlns="um:com:metasolv:oms:xmlapi:1">
<matchedOrderID>6</matchedOrderID>
<Status>accepted</Status>
</Amendment>
</CompleteOrder.Response>
110: Order not found
251: Transition invalid
255: Status mnemonic invalid
270: Transaction not allowed
302: Request parameter error
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.You can create a new order populated with the data from an existing order. The old order is retrieved using the order creation template associated with the type and source of the new order. The existing order data that is visible in the new order creation template is inserted into the new order. Any data from the old order that does not map to the new order's creation template is not inserted into the new order.
CopyOrder
OriginalOrderID: The order ID of the existing order to copy.
OrderType: The order type mnemonic for the new order.
OrderSource: The order source mnemonic for the new order.
Reference: The reference number for the new order.
Priority: An integer of 0-9 indicating the priority level of the order. 5 is the default priority.
<CopyOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OriginalOrderID>1235</OriginalOrderID> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <Reference>AA-NEW-345</Reference> <Priority>5</Priority> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </CopyOrder.Request>
The content of the response is the same as CreateOrder, except that CopyOrder.Response is the top level element.
<CopyOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1236</OrderID> <OrderHistID>23334</OrderHistID> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <OrderState>open.not_running.not_started</OrderState> <State>received</State> <Reference>AA-NEW-345</Reference> <Priority>5</Priority> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> <CopyRemarks>false</CopyRemarks> </CopyOrder.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Namespace: The namespace mnemonic of order type/source.
Version: The version of the order type or source.
Scenario 1: Namespace is supplied in the request, but no version. This condition forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, then this cartridge is used. If this legacy cartridge does not exist, an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, an error (150) message is shown.
To create an order you must provide an order type and order source with a CreateOrder operation. The initial data for the order is provided based on the same structure as the order template. The root element of the order has the XML name of _root.
CreateOrder
ParentOrderID: The parent order.
OrderType: The order type mnemonic.
OrderSource: The order source mnemonic.
View: The view (query task) assigned to the order.
Reference: A reference ID string.
Priority: An integer of 0-9 indicating the priority level of the order. 5 is the default priority.
Namespace: The namespace mnemonic of order type/source.
Version: The version of the order type or source.
_root: The root element of the order document.
AddMandatory - If true:
If you delete a mandatory node, AddMandatory replaces the node and populates it with the default value.
If the request is missing a mandatory node, AddMandatory adds the missing node and populates it with the default value.
Note:
If you add a mandatory field, but do not include a value, AddMandatory will not add a default value and the request will generate an error-error code 200.Order header element.
If not explicitly set, defaults to 5.
If the priority specified is above the maximum or below the minimum priority value for the order type/source, it is automatically rounded up or down accordingly.
Note:
If the priority is set outside the range of allowable priority values for the system (0-9) or is set to a non-numeric value, an error is thrown.CreateOrder response always returns the priority regardless of whether it is set or not.
<CreateOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderSource>source1</OrderSource>
<OrderType>phone_transfer</OrderType>
<Reference>3ab34</Reference>
<Priority>5</Priority>
<Namespace>DSL_Highspeedline</Namespace>
<Version>1.1</Version>
<_root>
<client_info>
<name>John Doe</name>
<address>
<street1>1211 Lakeview Dr.</street1>
<city>New York</city>
<state>NY</state>
<country>USA</country>
<zip>12345</zip>
</address>
<client_info>
... more data ...
</_root>
<AddMandatory>true</AddMandatory>
</CreateOrder.Request>
The response includes the new order ID number, the initial state, the order source and type,
and the reference provided with the request. The response always returns a priority value whether it is set or not (defaults to 5).
<CreateOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>678</OrderHistID> <OrderSource>phone_transfer</OrderSource> <OrderType>source1</OrderType> <OrderState>open.not_running.not_started</OrderState> <State>accepted</State> <Reference>3ab34</Reference> <Priority>5</Priority> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </CreateOrder.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
200: Order data invalid
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Initiates fallout from a particular task. This request requires an Order ID, Order History ID, and Fallout mnemonic.
FalloutTask
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
Fallout: The fallout mnemonic as defined in the metadata.
Reason: The reason for the fallout. This parameter is optional.
<FalloutTask.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>501</OrderID> <OrderHistID>3010</OrderHistID> <Fallout>fallout_switch</Fallout> <Reason>Bad switch</Reason> </FalloutTask.Request>
The system returns the response with an accepted status to indicate the fallout has been accepted for processing.
<FalloutTask.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>501</OrderID> <Status>accepted</Status> </FalloutTask.Response>
110: Order not found
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database connection failed
419: The process exception is restricted?
439: Invalid fallout mnemonic
500: Internal ErrorSuspendOrder
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.The request either fails the order, or fails the current task. OSM fails the task when OrderHistID is provided in the request otherwise OSM fails the order. One request cannot be used to fail both task and order at the same time.
FailOrder
OrderID: The ID of the order to fail.
OrderHistID: The order history ID.
Reason: The reason for the failure. This parameter is optional.
And one of the following:
Immediate: Force immediate failure of order or task.
Infinite: Wait indefinitely until all tasks on the order complete or become available.
EventInterval: An event will be generated periodically while the order remains in grace period. This event acts as a warning to external systems than an order is in grace period and awaiting completion of accepted work items. This value controls the frequency that the event will be generated.
GracePeriodExpiry: A point in time, after which the grace period for completing accepted work items expires. After this time, the order will be transitioned regardless of whether or not there are outstanding work items. The grace period expiry date specified here must be within the limits imposed by the grace period expiry range specified in the order state policy.
<FailOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>501</OrderID> <OrderHistID>3010</OrderHistID> <Reason>BadData</Reason> </FailOrder.Request>
The system returns the response with an accepted status to indicate the fallout has been accepted for processing.
<FailOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>501</OrderID> <OrderHistID>3010</OrderHistID> </FailOrder.Response>
110: Order not found
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database connection failed
419: The process exception is restricted?
439: Invalid fallout mnemonic
500: Internal ErrorSuspendOrder
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Allows agents to retrieve an order at a given task and at a specific state. The order returned by GetNextOrderAtTask is the first order found in the OSM database that matches the request criteria. At least one state should be present in GetNextOrderAtTask.Request. Until an order is moved to a task or a state that does not match the request criteria, it remains to be returned by subsequent calls to GetNextOrderAtTask.
GetNextOrderAtTask
OrderID: If specified, retrieves the next instance of a task on the specific order. This is an optional parameter.
Task: The mnemonic for the task.
ExecutionMode: If specified, value may be one of "do", "redo", or "undo". Retrieves the next instance of a task with the given execution mode. This is an optional parameter.
Accept: A value of "true" or "false" indicating if the XML API should accept the order for the user's ID.
State: A state for the task. This element can have multiple instances and the values indicate which states a task must be in for the order to be returned. Acceptable values are:
Assigned: The task is in the Assigned state and is assigned to the current user's ID.
Received: The task is in the Received state.
Accepted: The task is in the Accepted state for the current user's ID.
Suspended: The task is in the Suspended state.
Namespace: The namespace mnemonic of the order type/source.
Version: The version of the order type or source.
<GetNextOrderAtTask.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Task>provision_switch</Task> <ExecutionMode>redo</ExecutionMode> <Accept>false</Accept> <State>received</State> <State>assigned</State> <State>accepted</State> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </GetNextOrderAtTask.Request>
If an order matching the request criteria is found, the response has the same content as GetOrder.Response, except the top-level element is GetNextOrderAtTask.Response. If no matching order is found, the response consists of the top level GetNextOrderAtTask.Response with no child elements.
<GetNextOrderAtTask.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Task>provision_switch</Task> <ExecutionMode>redo</ExecutionMode> <Accept>false</Accept> <State>received</State> <State>assigned</State> <State>accepted</State> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </GetNextOrderAtTask.Request>
If an order matching the request criteria is found, the response has the same content as GetOrder.Response, except the top-level element is GetNextOrderAtTask.Response. If no matching order is found, the response consists of the top level GetNextOrderAtTask.Response with no child elements.
<GetNextOrderAtTask.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<OrderHistID>2333</OrderHistID>
<Task>provision_switch</Task>
<OrderSource>source1</OrderSource>
<OrderType>phone_transfer</OrderType>
<Workgroups>
<Workgroup>workgroup1</Workgroup>
<Workgroup>workgroup2</Workgroup>
</Workgroups>
<OrderState>open.running.in_progress</OrderState>
<State>received</State>
<ExecutionMode>do</ExecutionMode>
<Reference>3ab34</Reference>
<Priority>5</Priority>
<Namespace>DSL_Highspeedline</Namespace>
<Version>1.1</Version>
<_root index="0">
<client_info index="76578">
<name index="76579">John Doe</name>
<address index="76580">
<street1 index="76581">1211 Lakeview Dr.</Street1>
<city index="76582">New York</city>
<state index="76583">NY</state>
<country index="76584">USA</country>
<zip index="76585">12345</zip>
</address>
<address index="80132">
<street1 index="80133">20 Biz drv.</street1>
<city index="80134">New York</city>
<state index="80135">NY</state>
<country index="80136">USA</country>
<zip index="80137">12345</zip>
</address>
</client_info>
... more order data ...
</_root>
<HistoricalPerspective>
<OrderHistID>52</OrderHistID>
<_root index="0">
<customer_ref index="1146675411084">Cust01</customer_ref>
<shape index="1146675411085">circle</shape>
<color index="1146675411086">blue</color>
<pattern index="1146675411087">checkerboard</pattern>
</_root>
<Changes>
<Update path="/color[@index='1146675411086']"
oldValue="blue">green</Update>
</Changes>
</HistoricalPerspective>
</GetNextOrderAtTask.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
270: Transaction not allowed.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request, but no version. This condition forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, then this cartridge is used. If this legacy cartridge does not exist, an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, an error (150) message is shown.
To retrieve the order data, you must provide the relevant IDs obtained from the worklist or another external source. If successful, the response includes the order data values.
To retrieve an order, you must provide the order ID and an Accept parameter indicating whether the order is updated. You may also provide an order history ID or view (query task) ID.
GetOrder
OrderID: The ID of the order.
Accept: Determines whether an attempt was made to move the order to an Accepted state.
And one of the following:
OrderHistID: The history ID of the order.
Note:
You should only use contemporary, current, or historical data that you retrieve using the OrderHistID from a currently received or accepted task. Contemporary, current, or historical data retrieved using OrderHIstID for a task that is already complete may no longer be valid.ViewID: The particular view (query task) associated with the order. You can obtain a list of valid ViewIDs for an order with the ListViews.Request.
OrderChangeId: Determines from which revision the historical and current OCM (Order Change Management) perspectives are to be constructed.
TaskExecutionHistory: Determines the execution history of a revision on a task. It contains details of the execution mode in which the task was executed in the revision, the OrderHistoryID of the task during the revision, and the OrderChangeID of the corresponding revision.
OrderDataFilter: Parent element for the Condition child element that specifies which order data to return in the GetOrder.Response.
Condition: An XPath 1.0 expression against the order data defined by the view (query task). OSM returns only the instances of the order data selected by the expression, not the other instances of the element. All other parent or sibling elements are returned.
For example, in a situation where a customer has multiple <address> instances (where <address> is a multi-instance element), the following expression ensures that OSM returns only the <address> element that contains a child street element with the specified street address. The response includes all child nodes of the instance of the <address> element (city, postal code, and street). The other instances of the <address> element and their child elements (city, street, and postal code) are not returned.
<OrderDataFilter>
<Condition>/subscriber_info/address/[street='190 Drive']</Condition>
</OrderDataFilter>
For example, any sibling elements of <subscriber_info>, or sibling elements of <address> (except for the other instances of the <address> element) would be returned.
There can be as many <Condition> child elements as required. When there are more than one <Condition> elements, each condition is evaluated and applied independently of the other conditions to the sections of the order data respectively.
<GetOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Accept>true</Accept> <OrderHistID>34433</OrderHistID> </GetOrder.Request>
When you are using an order condition that includes an element that is using a distributed order template, you should include the namespace of the data element in the condition. For example:
<OrderDataFilter>
<Condition>
/ControlData/OrderItem[@type='{OrderItemNamespace}OrderItemName' and @LineId='1']
</Condition>
</OrderDataFilter>
The order response includes the order source and type, the reference number, and its current state. If an order history ID is supplied in the request, the response returns the related task mnemonic. The order data is supplied under the _root element. The _root element and all _root child elements include index attributes to uniquely identify each element in any subsequent order updates.
The order response also shows the workgroup associated to the user who has accepted a task, suspended a task, or to whom a task has been assigned. When the task is in the received state, the response displays all workgroups that can possibly work on the task. When the task is in the accepted state, the response displays the user who accepted the task.
If there are remarks associated with the order, there is a Remarks element in the <Remarks> element. A Remark element has the following content:
RemarkID: A unique identifier for the remark.
Time: The time the remark was added.
Author: The user ID of the person who added the remark.
Text: The text of the remark.
TaskID: The task mnemonic of the order when the remark was added.
TaskType: The type of task. For example, creation, manual, automated, rule or delay.
OrderHistID: The order history ID for the order when the remark was created. If the remark was added without using an OrderHistID, the field is empty.
State: The state of the order when the remark was added.
ReadOnly: A "true" or "false" value indicating if the remark can still be modified. To modify, the current user must be the author of the remark and the remark cannot be older than a time specified by your administrator.
ProcessStatus: The process status of the order. Possible ProcessStatus values are taken from the reporting statuses defined in the Studio Process Editor, on the General subtab in the Properties window.
Attachments: A parent for the attachment information having zero or more Attachment elements.
Each attachment element contains:
AttachmentID: A unique identifier for the attachment.
FileName: The name of the file.
<GetOrder.Response xmlns="urn:metasolv:oms:xmlapi_1">
<OrderID>1234</OrderID>
<OrderHistID>34433</OrderHistID>
<Task>SampleTask1</OrderHistID>
<OrderSource>source1</OrderSource>
<OrderType>phone_transfer</OrderType>
<Workgroups>
<Workgroup>workgroup1</Workgroup>
<Workgroup>workgroup2</Workgroup>
</Workgroups>
<OrderState>open.running.in_progress</OrderState>
<State>received</State>
<ExecutionMode>do</ExecutionMode>
<Reference>3ab34</Reference>
<ExpectedOrderCompletionDate>2009-03-10T00:00:00Z</ExpectedOrderCompletionDate>
<Priority>5</Priority>
<ProcessStatus>n/a</ProcessStatus>
<_rootindex="0">
<client_info index="76577">
<name index="76578">John Doe</name>
<address index="76579">
<street1 index="76580">1211 Lakeview Dr.</Street1>
<city index="76581">New York</city>
<state index="76582">NY</state>
<country index="76583">USA</country>
<zip index="76584">12345</zip>
</address>
<address index="80132">
<street1 index="80133">20 Biz drv.</street1>
<city index="80134">New York</city>
<state index="80135">NY</state>
<country index="80136">USA</country>
<zip index="80137">12345</zip>
</address>
</client_info>
... more order data ...
</_root>
<Remarks>
<Remark>
<RemarkID>13444</RemarkID>
<Date>2000-10-30T14:44:33 EST</Date>
<Author>jdoe</Author>
<TaskID>provision_switch</TaskID>
<TaskType>manual</TaskType>
<OrderHistID>34401</OrderHistID>
<State>accepted</State>
<Text>OSM completed</Text>
<ReadOnly>true</ReadOnly>
<Attachments>
<Attachment>
<AttachmentID>111324</AttachmentID>
<FileName>provisioninfo.txt</FileName>
</Attachment>
</Attachments>
</Remark>
<Remark>
<RemarkID>14322</RemarkID>
<Date>2000-10-30T15:01:22 EST</Date>
<Author>jdoe</Author>
<TaskID>provision_switch</TaskID>
<TaskType>manual</TaskType>
<OrderHistID>34401</OrderHistID>
<State>accepted</State>
<Text>Switch activated</Text>
<ReadOnly>false</ReadOnly>
<Attachments/>
</Remark>
</Remarks>
</GetOrder.Response>
Request Example with OrderChangeId
This is an example of a GetOrder.Request in which the OrderChangeId is set to 123. This function sends a request to OSM to retrieve an order with OrderChangeId 123.
<GetOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>34433</OrderHistID> <OrderChangeId>123</OrderChangeId> </GetOrder.Request>
Response Example with OrderChangeId and TaskExecution History
This is an example of a GetOrder.Response in which the TaskExecutionHistory element contains details of order data revisions with corresponding OrderChangeIDs. The base order has an OrderChangeID of 0 and the revised OrderChangeId is indicated by 561.
<GetOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>2845</OrderID><OrderHistID>61926</OrderHistID>
<Task>stask_a</Task>
<State>received</State>
<OrderChangeID>565</OrderChangeID>
<OrderSource>OCMPerspectivesTestOrder</OrderSource>
<Workgroups>
<Workgroup>workgroup1</Workgroup>
<Workgroup>workgroup2</Workgroup>
</Workgroups>
<OrderType>OCMPerspectivesTestOrder</OrderType>
<OrderState>open.running.compensating.amending</OrderState>
<ExecutionMode>redo</ExecutionMode> <Reference/><Priority>5</Priority>
<Namespace>OCMPerspectivesTest</Namespace><Version>1.0.0</Version>
<_rootindex="0">
<data index="1271706877188">rev2</data>
</_root>
<HistoricalPerspective>
<OrderHistID>61917</OrderHistID>
<_root index="0">
<data index="1271706877188">rev1</data>
</_root>
<Changes>
<Update significant="true" path="/data[@index='1271706877188']
"oldValue="rev1">rev2</Update>
</Changes>
</HistoricalPerspective>
<CurrentPerspective>
<_root index="0">
<data index="1271706877188">rev2</data>
</_root>
</CurrentPerspective>
<TaskExecutionHis tory>
<Task>
<OrderHistID>61917</OrderHistID>
<ExecutionMode>redo</ExecutionMode>
<OrderChangeID>561</OrderChangeID>
</Task>
<Task>
<OrderHistID>61904</OrderHistID>
<ExecutionMode>do</ExecutionMode>
<OrderChangeID>0</OrderChangeID>
</Task>
</TaskExecutionHistory>
</GetOrder.Response>
Response Example with Distributed Order Template
This is a partial example of the response for an order in which the order items and their dynamic parameters properties are using the distributed order template.
<GetOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>15</OrderID>
<OrderHistID>236809</OrderHistID>
<Task>configureCustomerSystemTask</Task>
<OrderSource>OsmCentralOMExampleOrder</OrderSource>
<OrderType>OsmCentralOMExampleOrder</OrderType>
<Workgroups>
<Workgroup>workgroup1</Workgroup>
<Workgroup>workgroup2</Workgroup>
</Workgroups>
<OrderState>open.running.in_progress</OrderState>
<State>accepted</State>
<ExecutionMode>do</ExecutionMode>
<Reference>Order1397065147300</Reference>
<RequestedDeliveryDate>2014-03-31T07:05:00 PDT</RequestedDeliveryDate>
<ExpectedStartDate>2014-04-09T10:39:58 PDT</ExpectedStartDate>
<ExpectedDuration>PT0S</ExpectedDuration>
<ExpectedOrderCompletionDate>2014-04-09T10:39:58 PDT</ExpectedOrderCompletionDate>
<Priority>5</Priority>
<Namespace>OsmCentralOMExample-Solution</Namespace>
<Version>4.0.0.0.0</Version>
<ProcessStatus>n/a</ProcessStatus>
<_root index="0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CustomerDetails index="11">
<nameLocation index="13">Jangadeiros</nameLocation>
<typeAddress index="23">Building</typeAddress>
</CustomerDetails>
<OrderHeader index="1">
<numSalesOrder index="2">Order1397065147300</numSalesOrder>
<typeOrder index="3">Add</typeOrder>
</OrderHeader>
<AccountDetails index="24">
<numAccount index="25">TEL1234</numAccount>
<status index="26">Existing</status>
<corporate index="27">PoC</corporate>
<category index="32">Corporate</category>
</AccountDetails>
<ControlData index="1397065199251">
<Functions index="1397065199537">
<SyncCustomerFunction index="1397065194936" instanceLocked="true">
<componentKey index="1397065199567">
SyncCustomerFunction.CustomerSystem.WholeOrder</componentKey>
<orderItem index="1397065199570">
<orderItemRef index="1397065199571" referencedIndex="1397065194907" xmlns:ct234="http://oracle.osm.centralom" xsi:type="ct234:CustomerOrderItemSpecificationType" type="{http://oracle.osm.centralom}CustomerOrderItemSpecificationType">
<ct234:productSpec index="1397065199259" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:productSpec>
<ct234:filfillPatt index="1397065199260" xmlns:ct234="http://oracle.osm.centralom">Service.Broadband</ct234:fulfillPatt>
<ct234:lineId index="1397065199254" xmlns:ct234="http://oracle.osm.centralom">1</ct234:lineId>
<ct234:lineItemName index="1397065199263" xmlns:ct234="http://oracle.osm.centralom">Brilliant Broadband [Add]</ct234:lineItemName>
<ct234:requestedDeliveryDate index="1397065199257" xmlns:ct234="http://oracle.osm.centralom">2014-03-31T07:05:00 PDT</ct234:requestedDeliveryDate>
<ct234:lineItemPayload index="1397065199255" xmlns:ct234="http://oracle.osm.centralom">
<im:salesOrderLine xmlns:im="http://xmlns.oracle.com/InputMessage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<im:lineId>1</im:lineId>
<im:promotionalSalesOrderLineReference>1 </im:promotionalSalesOrderLineReference>
<im:serviceId/>
<im:requestedDeliveryDate>
2014-03-31T07:05:00</im:requestedDeliveryDate>
<im:serviceActionCode>Add</im:serviceActionCode>
<im:serviceInstance>N</im:serviceInstance>
<im:serviceAddress>
<im:locationType>Street</im:locationType>
<im:typeAddress>Building</im:typeAddress>
</im:serviceAddress>
<im:itemReference>
<im:name>Brilliant Broadband</im:name>
<im:primaryClassificationCode>Broadband Service Feature Class</im:primaryClassificationCode>
<im:specificationGroup/>
</im:itemReference>
</im:salesOrderLine>
</ct234:lineItemPayload>
<ct234:Recognition index="1397065199252" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:Recognition>
<ct234:dynamicParams index="1397065199689" xmlns:ct234="http://oracle.osm.centralom" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0" xsi:type="ct264:SA_MobileMessagingCFSType" type="{OracleComms_Model_Mobile/4.0.0.0.0}SA_MobileMessagingCFSType" xmlns:ct135="http://xmlns.oracle.com/communications/studio/ordermanagement/transformation">
<ct264:MMSIncoming index="1397065199692" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSIncoming>
<ct264:MMSOutgoing index="1397065199690" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSOutgoing>
</ct234:dynamicParams>
<ct234:Action index="1397065199256" xmlns:ct234="http://oracle.osm.centralom">Add</ct234:Action>
<ct234:ServiceInstance index="1397065199253" xmlns:ct234="http://oracle.osm.centralom">N</ct234:ServiceInstance>
</orderItemRef>
</orderItem>
[...]
</SyncCustomerFunction>
</Functions>
<OrderItem index="1397065194907" xmlns:ct234="http://oracle.osm.centralom" xsi:type="ct234:CustomerOrderItemSpecificationType" type="{http://oracle.osm.centralom}CustomerOrderItemSpecificationType">
<ct234:productClass index="1397065199259" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:productClass>
<ct234:productSpec index="1397065199260" xmlns:ct234="http://oracle.osm.centralom">Service.Broadband</ct234:productSpec>
<ct234:lineId index="1397065199254" xmlns:ct234="http://oracle.osm.centralom">1</ct234:lineId>
<ct234:lineItemName index="1397065199263" xmlns:ct234="http://oracle.osm.centralom">Brilliant Broadband [Add]</ct234:lineItemName>
<ct234:requestedDeliveryDate index="1397065199257" xmlns:ct234="http://oracle.osm.centralom">2014-03-31T07:05:00 PDT</ct234:requestedDeliveryDate>
<ct234:lineItemPayload index="1397065199255" xmlns:ct234="http://oracle.osm.centralom">
<im:salesOrderLine xmlns:im="http://xmlns.oracle.com/InputMessage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<im:lineId>1</im:lineId>
<im:promotionalSalesOrderLineReference>1 </im:promotionalSalesOrderLineReference>
<im:serviceId/>
<im:requestedDeliveryDate>
2014-03-31T07:05:00</im:requestedDeliveryDate>
<im:serviceActionCode>Add</im:serviceActionCode>
<im:serviceInstance>N</im:serviceInstance>
<im:serviceAddress>
<im:locationType>Street</im:locationType>
<im:typeAddress>Building</im:typeAddress>
</im:serviceAddress>
<im:itemReference>
<im:name>Brilliant Broadband</im:name>
<im:primaryClassificationCode>Broadband Service Feature Class</im:primaryClassificationCode>
<im:specificationGroup/>
</im:itemReference>
</im:salesOrderLine>
</ct234:lineItemPayload>
<ct234:Recognition index="1397065199252" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:Recognition>
<ct234:dynamicParams index="1397065199689" xmlns:ct234="http://oracle.osm.centralom" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0" xsi:type="ct264:SA_MobileMessagingCFSType" type="{OracleComms_Model_Mobile/4.0.0.0.0}SA_MobileMessagingCFSType" xmlns:ct135="http://xmlns.oracle.com/communications/studio/ordermanagement/transformation">
<ct264:MMSIncoming index="1397065199692" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSIncoming>
<ct264:MMSOutgoing index="1397065199690" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSOutgoing>
</ct234:dynamicParams>
<ct234:Action index="1397065199256" xmlns:ct234="http://oracle.osm.centralom">Add</ct234:Action>
<ct234:ServiceInstance index="1397065199253" xmlns:ct234="http://oracle.osm.centralom">N</ct234:ServiceInstance>
</OrderItem>
[...]
</ControlData>
</_root>
</GetOrder.Response>
Request and Response Example with OrderDataFilter
The following GetOrder.Request specifies the demo_query query task that specifies the data to return in the GetOrder.Response from an order with an order ID of 2.
<GetOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>2</OrderID> <View>demo_query</View> </GetOrder.Request>
The following response returned all the data specified by the demo_query query task including all address multi-instance nodes.
<GetOrder.Response>
<OrderID>2</OrderID>
<View>demo_query</View>
<OrderSource>add_adsl_siebel</OrderSource>
<OrderType>add_adsl_siebel</OrderType>
<OrderState>open.running.in_progress</OrderState>
<Reference>1112223333</Reference>
<Priority>5</Priority>
<Namespace>bb_ocm_demo</Namespace>
<Version>1.0.0.0.0</Version>
<ProcessStatus>n/a</ProcessStatus>
<_root index="0">
<subscriber_info index="1414783208019">
<address index="1414783208020">
<city index="1414783208023">MO</city>
<postal_code index="1414783208022">A1A1A1</postal_code>
<street index="1414783208021">Montreal Street</street>
</address>
<address index="1414783208024">
<city index="1414783208027">OT</city>
<postal_code index="1414783208026">B1B1B1</postal_code>
<street index="1414783208025">Ottawa Street</street>
</address>
<address index="1414783208028">
<city index="1414783208031">TO</city>
<postal_code index="1414783208030">M9W6H8</postal_code>
<street index="1414783208029">190 Drive</street>
</address>
<primary_phone_number index="1414783208033">1112223333
</primary_phone_number>
<name index="1414783208032">John Doe</name>
</subscriber_info>
<adsl_service_details index="1414783208034">
<bandwidth index="1414783208035">3</bandwidth>
</adsl_service_details>
</_root>
</GetOrder.Response>
The following request uses the OrderDataFilter to filter out all sibling instances of the address multi-instance node. This functionality is particularly important in large orchestration orders when requesting order item information where an unfiltered GetOrder.Response message containing all the order data would negatively impact performance.
<GetOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>2</OrderID>
<View>demo_query</View>
<OrderDataFilter>
<Condition>/_root/subscriber_info/address[street='190 Drive']</Condition>
</OrderDataFilter>
</GetOrder.Request>
The following response has filtered out two other instances of the address multi-instance node.
<GetOrder.Response>
<OrderID>2</OrderID>
<View>demo_query</View>
<_root index="0">
<subscriber_info index="1414682666683">
<address index="1414682666696">
<city index="1414682666697">TO</city>
<postal_code index="1414682666698">A1B2Z7</postal_code>
<street index="1414682666699">190 Drive</street>
</address>
<phone_number index="1414682666689">1111111111</phone_number>
<name index="1414682666688">John Doe</name>
</subscriber_info>
<adsl_service_details index="1414682666690">
<bandwidth index="1414682666691">3</bandwidth>
</adsl_service_details>
</_root>
</GetOrder.Response>
110: Order not found
232: Order update failed
270: Transaction not allowed
302: Request parameter error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.To retrieve the order data as it exists at a specified task, you must provide the relevant IDs obtained from the worklist or another external source. If successful, the response includes the order data values as they exist at the specified task.
OrderID: The order's ID number
Task: A descriptive mnemonic for the task
<GetOrderAtTask.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Task>SampleTaskl</Task> </GetOrderAtTask.Request>
<GetOrderAtTask.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>204</OrderID>
<OrderHistID>443</OrderHistID>
<Task>SampleTaskl</Task>
<OrderSource>xmlapi</OrderSource>
<OrderType>xmlapi</OrderType>
<OrderState>open.running.in_progress</OrderState>
<State>received</State>
<ExecutionMode>do</ExecutionMode>
<Reference>get_order</Reference>
<ExpectedOrderCompletionDate>2009-03-10T00:00:00Z</ExpectedOrderCompletionDate>
<Priority>5</Priority>
<Namespace>vadim</Namespace>
<Version>1.0</Version>
<_root index="0">
<ProcessStatus index="1">n/a</ProcessStatus>
<order_origination index="2">
<currency index="3">150.55</currency>
<boolean index="4">Yes</boolean>
<m_multiple_lines_text index="5">text1</m_multiple_lines_text>
<m_multiple_lines_text index="6">text2</m_multiple_lines_text>
<options index="7">#1</options>
<phone index="8">1234567890</phone>
<date index="9">2010-10-10T15:10:10 EDT</date>
<numeric index="10">155.0</numeric>
<nested_group index="11">
<currency index="12">200.0</currency>
</nested_group>
</order_origination>
</_root>
</GetOrderAtTask.Response>
Response Example with Distributed Order Template
This is a partial example of the response for an order in which the order items and their dynamic parameters properties are using the distributed order template.
<GetOrderAtTask.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>15</OrderID>
<OrderHistID>236809</OrderHistID>
<Task>configureCustomerSystemTask</Task>
<OrderSource>OsmCentralOMExampleOrder</OrderSource>
<OrderType>OsmCentralOMExampleOrder</OrderType>
<OrderState>open.running.in_progress</OrderState>
<State>accepted</State>
<ExecutionMode>do</ExecutionMode>
<Reference>Order1397065147300</Reference>
<ExpectedOrderCompletionDate>2014-04-09T10:39:58 PDT</ExpectedOrderCompletionDate>
<Priority>5</Priority>
<Namespace>OsmCentralOMExample-Solution</Namespace>
<Version>4.0.0.0.0</Version>
<ProcessStatus>n/a</ProcessStatus>
<_root index="0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CustomerDetails index="11">
<locationType index="12">Street</locationType>
<typeAddress index="23">Building</typeAddress>
</CustomerDetails>
<OrderHeader index="1">
<numSalesOrder index="2">Order1397065147300</numSalesOrder>
<typeOrder index="3">Add</typeOrder>
</OrderHeader>
<AccountDetails index="24">
<numAccount index="25">TEL1234</numAccount>
<status index="26">Existing</status>
<corporate index="27">PoC</corporate>
<category index="32">Corporate</category>
</AccountDetails>
<ControlData index="1397065199251">
<Functions index="1397065199537">
<SyncCustomerFunction index="1397065194936" instanceLocked="true">
<componentKey index="1397065199567">
SyncCustomerFunction.CustomerSystem.WholeOrder</componentKey>
<orderItem index="1397065199570">
<orderItemRef index="1397065199571" referencedIndex="1397065194907" xmlns:ct234="http://oracle.osm.centralom" xsi:type="ct234:CustomerOrderItemSpecificationType" type="{http://oracle.osm.centralom}CustomerOrderItemSpecificationType">
<ct234:productClass index="1397065199259" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:productClass>
<ct234:productSpec index="1397065199260" xmlns:ct234="http://oracle.osm.centralom">Service.Broadband</ct234:productSpec>
<ct234:lineId index="1397065199254" xmlns:ct234="http://oracle.osm.centralom">1</ct234:lineId>
<ct234:lineItemName index="1397065199263" xmlns:ct234="http://oracle.osm.centralom">Brilliant Broadband [Add]</ct234:lineItemName>
<ct234:requestedDeliveryDate index="1397065199257" xmlns:ct234="http://oracle.osm.centralom">2014-03-31T07:05:00 PDT</ct234:requestedDeliveryDate>
<ct234:lineItemPayload index="1397065199255" xmlns:ct234="http://oracle.osm.centralom">
<im:salesOrderLine xmlns:im="http://xmlns.oracle.com/InputMessage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<im:lineId>1</im:lineId>
<im:promotionalSalesOrderLineReference>1 </im:promotionalSalesOrderLineReference>
<im:serviceId/>
<im:requestedDeliveryDate>
2014-03-31T07:05:00</im:requestedDeliveryDate>
<im:serviceActionCode>Add</im:serviceActionCode>
<im:serviceInstance>N</im:serviceInstance>
<im:serviceAddress>
<im:locationType>Street</im:locationType>
<im:typeAddress>Building</im:typeAddress>
</im:serviceAddress>
<im:itemReference>
<im:name>Brilliant Broadband</im:name>
<im:primaryClassificationCode>Broadband Service Feature Class</im:primaryClassificationCode>
<im:specificationGroup/>
</im:itemReference>
</im:salesOrderLine>
</ct234:lineItemPayload>
<ct234:Recognition index="1397065199252" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:Recognition>
<ct234:dynamicParams index="1397065199689" xmlns:ct234="http://oracle.osm.centralom" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0" xsi:type="ct264:SA_MobileMessagingCFSType" type="{OracleComms_Model_Mobile/4.0.0.0.0}SA_MobileMessagingCFSType" xmlns:ct135="http://xmlns.oracle.com/communications/studio/ordermanagement/transformation">
<ct264:MMSIncoming index="1397065199692" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSIncoming>
<ct264:MMSOutgoing index="1397065199690" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSOutgoing>
</ct234:dynamicParams>
<ct234:Action index="1397065199256" xmlns:ct234="http://oracle.osm.centralom">Add</ct234:Action>
<ct234:ServiceInstance index="1397065199253" xmlns:ct234="http://oracle.osm.centralom">N</ct234:ServiceInstance>
</orderItemRef>
</orderItem>
[...]
</SyncCustomerFunction>
</Functions>
<OrderItem index="1397065194907" xmlns:ct234="http://oracle.osm.centralom" xsi:type="ct234:CustomerOrderItemSpecificationType" type="{http://oracle.osm.centralom}CustomerOrderItemSpecificationType">
<ct234:productClass index="1397065199259" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:productClass>
<ct234:productSpec index="1397065199260" xmlns:ct234="http://oracle.osm.centralom">Service.Broadband</ct234:productSpec>
<ct234:lineId index="1397065199254" xmlns:ct234="http://oracle.osm.centralom">1</ct234:lineId>
<ct234:lineItemName index="1397065199263" xmlns:ct234="http://oracle.osm.centralom">Brilliant Broadband [Add]</ct234:lineItemName>
<ct234:requestedDeliveryDate index="1397065199257" xmlns:ct234="http://oracle.osm.centralom">2014-03-31T07:05:00 PDT</ct234:requestedDeliveryDate>
<ct234:lineItemPayload index="1397065199255" xmlns:ct234="http://oracle.osm.centralom">
<im:salesOrderLine xmlns:im="http://xmlns.oracle.com/InputMessage" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<im:lineId>1</im:lineId>
<im:promotionalSalesOrderLineReference>1 </im:promotionalSalesOrderLineReference>
<im:serviceId/>
<im:requestedDeliveryDate>
2014-03-31T07:05:00</im:requestedDeliveryDate>
<im:serviceActionCode>Add</im:serviceActionCode>
<im:serviceInstance>N</im:serviceInstance>
<im:serviceAddress>
<im:locationType>Street</im:locationType>
<im:typeAddress>Building</im:typeAddress>
</im:serviceAddress>
<im:itemReference>
<im:name>Brilliant Broadband</im:name>
<im:primaryClassificationCode>Broadband Service Feature Class</im:primaryClassificationCode>
<im:specificationGroup/>
</im:itemReference>
</im:salesOrderLine>
</ct234:lineItemPayload>
<ct234:Recognition index="1397065199252" xmlns:ct234="http://oracle.osm.centralom">Broadband Service Feature Class</ct234:Recognition>
<ct234:dynamicParams index="1397065199689" xmlns:ct234="http://oracle.osm.centralom" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0" xsi:type="ct264:SA_MobileMessagingCFSType" type="{OracleComms_Model_Mobile/4.0.0.0.0}SA_MobileMessagingCFSType" xmlns:ct135="http://xmlns.oracle.com/communications/studio/ordermanagement/transformation">
<ct264:MMSIncoming index="1397065199692" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSIncoming>
<ct264:MMSOutgoing index="1397065199690" xmlns:ct264="OracleComms_Model_Mobile/4.0.0.0.0">Yes</ct264:MMSOutgoing>
</ct234:dynamicParams>
<ct234:Action index="1397065199256" xmlns:ct234="http://oracle.osm.centralom">Add</ct234:Action>
<ct234:ServiceInstance index="1397065199253" xmlns:ct234="http://oracle.osm.centralom">N</ct234:ServiceInstance>
</OrderItem>
[...]
</ControlData>
</_root>
</GetOrderAtTask.Response>
110: order not found
257: Invalid task mnemonic
302: request parameter error
Provides a list of the creation, update, and deletion of data in an order. Only those data elements that are visible in the order's assigned view (query task) is described in the OrderDataHistory response.
GetOrderDataHistory
OrderID - The order sequence ID.
And one of the following:
OrderHistID: The order history ID.
View: A view (query task) assigned to the order.
With the given parameters, OrderDataHistory returns the order data history for all data elements of the order. To request the data history of specific elements, any number of Field elements can be provided to restrict the returned data history to the specific elements. The Field element contains an attribute and path, which resolves to a mnemonic path (using '/' as separators) for the data element whose data history is requested. Index values can be used in the path to narrow the scope of elements returned. Some examples are:
<Field path="/group_node/value_node" />
Returns data history for the root node, and all instances of /group_node and all instances of /group_node/value_node.
<Field path="/group_node[@index='12234']/value_node" />
Returns data history for the root node, the group_node with index 12234, and all instances of /group_node/value_node having group_node with index 12234 as a parent.
<Field path="/group_node[@index='12234']/value_node[@index='23111']" />
Returns data history for the root node, the group_node with index 12234, and all instances of /group_node/value_node having the index 23111 and group_node with index 12234 as a parent.
<Field path="/group_node/value_node" namespace="DSL_Highspeedline " version ="1.1" />
Returns data history for the root node, and all instances of /group_node and all instances of /group_node/value_node for the cartridge namespace DSL_Highspeedline version 1.1.
<GetOrderDataHistory.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <ViewID>32222</ViewID> </GetOrderDataHistory.Request>
or
<GetOrderDataHistory.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<View>Order_Creation_view</View>
<Field path="/group_node/value_node" namespace="DSL_Highspeedline"
version ="1.1"/>
</GetOrderDataHistory.Request>
The response returns the OrderID and OrderHistID/ViewID provided in the request, in addition to order data history in Field elements.
Each Field element has the following attributes:
path: The mnemonic path for the data element with '/' separating mnemonics.
namespace: The namespace mnemonic of order type/source.
version: The version of the order type or source. If you do not indicate a version, OSM uses the default version.
Index: The index number for the data element.
ParentIndex: The index number of the data element's parent. If the data element is the root node, it has an empty parentIndex (parentIndex="").
Multiple instance data elements have the same path but different indexes.
Each Field element has a Change element for each modification made to a data element. Each Change element has the following attributes:
Action: The action, either create, update, or delete.
User: The user ID that performed the change.
Time: The time of the change.
If the Change element is for a value node and has an action of "create" or "update", the value supplied to the data appears as the text value of the Change element.
<GetOrderDataHistory.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<OrderHistID>32222</OrderHistID>
<Field path="/" namespace="DSL_Highspeedline " version ="1.1" index="1221"
parentIndex="">
<Change action="create" user="oms" time="2000-01-28T14:33:22 EST"/>
</Field>
<Field path="/client_info" namespace="DSL_Highspeedline " version ="1.1"
index="1222" parentIndex="1221">
<Change action="create" user="oms" time="2000-01-28T14:33:22 EST"/>
</Field>
<Field path="/client_info/phone" namespace="DSL_Highspeedline" version ="1.1"
index="1223" parentIndex="1221">
<Change action="create" user="oms" time="2000-01-28T14:33:22 EST">4169999999
</Change>
<Change action="update" user="jdoe" time="2000-01-28T14:35:23 EST">
4168888888
</Change>
</Field>
<Field path="/client_info/address" namespace="DSL_Highspeedline" version ="1.1"
index="12552" parentIndex="1222">
<Change action="create" user="oms" time="2000-01-28T14:33:22 EST"/>
</Field>
<Field path="/client_info/address/street" namespace="DSL_Highspeedline"
version ="1.1" index="12553" parentIndex="12552">
<Change action="create" user="oms" time="2000-01-28T14:33:22 EST">
20 West St.
</Change>
<Change action="delete" user="oms" time="2000-01-28T15:21:45 EST" />
</Field>
</GetOrderDataHistory.Response>
110: Order not found
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Provides a list of each task transition of an order and a summary of the total time an order has been in a process.
GetOrderProcessHistory
OrderID: The order ID for the order.
<GetOrderProcessHistory.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> </GetOrderProcessHistory.Request>
The GetOrderProcessHistory response returns the Order ID provided, and a Summary and Transitions element.
The children of the Summary element are:
ExpectedCompletionDate: The expected completion date of the entire process.
ActualDuration: The sum of the duration of all transitions of the order in seconds.
StartDate: The date the order was started in the process.
CompleteDate: The date the order was completed.
The children of the Transitions element are zero or more Transition elements. Each Transition element has the following children:
TaskID: The task mnemonic.
TaskType: The task type; manual, automatic, and creation.
TaskDescription: The description of the task.
ExpectedCompletionDate: The expected completion date of the task in seconds.
ActualDuration: The actual duration of the task and state in seconds.
StartDate: The date/time the task and state was entered.
CompleteDate: The date and time the task and state was completed.
OrderHistID: The order history sequence ID of the order's task and state.
FromOrderHistID: The order history sequence ID of the previous task and state.
State: The state mnemonic of the order.
Status: The status mnemonic of the order.
TransitionType: There are two transition types "normal", indicating transition within the process or "exception" indicating the transition was to an exception processing transition.
User: The unique identifier of the user who performed the transition.
ParentTaskOrderHistID: If the transition is within a sub-process resulting from an order data based transition, this value indicates the order history ID of the parent process task. If the transition is not within a sub-process, this value is empty.
DataNodeIndex: If the transition or a previous transition resulted from order data, this is a correlation index for the transitions that followed from the order data based transition.
DataNodeMnemonic: If the transition is a sub-process and the result of an order data based task (creates sub-processes), this value contains the mnemonic path (with '/' separators) of the node on which the sub-processes tasks were created.
DataNodeValue: If the transition is based on order data and is a value node, this element provides the value of the order data.
<GetOrderProcessHistory.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<Summary>
<ExpectedCompletionDate>2000-03-25T14:33:22 EST</ExpectedCompletionDate>
<ActualDuration>101000</ActualDuration>
<StartDate>2000-01-28T14:33:22 EST</StartDate>
<CompleteDate/>
</Summary>
<Transitions>
<Transition>
<TaskID>order_entry</TaskID>
<TaskType>manual</TaskType>
<TaskDescription>Order Entry Task</TaskDescription>
<ExpectedCompletionDate>2000-02-15T14:33:22 EST</ExpectedCompletionDate>
<ActualDuration>65</ActualDuration>
<StartDate>2000-01-28T14:33:22 EST</StartDate>
<CompleteDate>2000-01-28T14:34:27 EST </CompleteDate>
<OrderHistID>12432</OrderHistID>
<FromOrderHistID>12431</FromOrderHistID>
<State>received</State>
<Status/>
<TransitionType>normal</TransitionType>
<User>oms</User>
<ParentTaskOrderHistID/>
<DataNodeIndex/>
<DataNodeMnemonic/>
<DataNodeValue/>
</Transition>
... more Transition elements ...
</Transitions>
</GetOrderProcessHistory.Response>
110: Order not found
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Provides a list of each order state transition and its duration.
GetOrderStateHistory
OrderID: The order ID for the order.
Namespace
Version
<GetOrderStateHistory.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> </GetOrderStateHistory.Request>
The GetOrderStateHistory response returns the Order ID provided, and the following Transition elements:
OrderState: The state mnemonic of the order.
TransitionStartDate: The date/time the order state was entered.
TransitionCompletedDate: The date/time the order state was completed.
ActualDuration: The actual duration of the order state in seconds.
User: The unique identifier of the user who performed the transition.
Reason: The reason for the order state transition. Supplied by the system when an order is created (create order) or submitted (submit order). Optionally supplied by the user when an order is suspended or resumed.
<GetOrderStateHistory.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>161</OrderID>
<Namespace>orderamendment</Namespace>
<Version>1.0</Version>
<OrderStates>
<OrderState>
<OrderState>open.not_running.not_started</OrderState>
<TransitionStartDate>2006-04-03T14:08:59 EDT</TransitionStartDate>
<TransitionCompletedDate>2006-04-03T14:19:21 EDT
</TransitionCompletedDate>
<ActualDuration>PT10M22.000S</ActualDuration>
<User>oms</User>
<Reason>create order</Reason>
</OrderState>
<OrderState>
<OrderState>open.running.in_progress</OrderState>
<TransitionStartDate>2006-04-03T14:19:32 EDT</TransitionStartDate>
<TransitionCompletedDate>2006-04-03T14:19:36 EDT
</TransitionCompletedDate>
<ActualDuration>PT4.000S</ActualDuration>
<User>oms</User>
<Reason>submit order</Reason>
</OrderState>
<OrderState>
<OrderState>open.not_running.suspended</OrderState>
<TransitionStartDate>2006-04-03T14:19:36 EDT</TransitionStartDate>
<TransitionCompletedDate>2006-04-03T14:19:36 EDT
</TransitionCompletedDate>
<ActualDuration>PT0.000S</ActualDuration>
<User>oms</User>
<Reason>customer requested hold on order</Reason>
</OrderState>
</OrderStates>
</GetOrderStateHistory.Response>
110: Order not found
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Provides a list of all statuses for a given task.
GetTaskStatuses
Task - A task mnemonic.
Namespace
Version
<GetTaskStatuses.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <Task>new_test_task</Task> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </GetTaskStatuses.Request>
<GetTaskStatuses.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <Task>new_test_task</Task> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> <Status>delete</Status> <Status>dickson1</Status> <Status>dickson2</Status> <Status>end</Status> <Status>false</Status> <Status>redirect</Status> <Status>submit</Status> <Status>true</Status> <Status>undo</Status> </GetTaskStatuses.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request, but no version. This condition forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, then this cartridge is used. If this legacy cartridge does not exist, an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, an error (150) message is shown.
Provides information regarding the current user's ID, the mnemonic and description of all assigned workgroups, and all user-defined columns (flexible headers.)
None
<GetUserInfo.Request xmlns="urn:com:metasolv:oms:xmlapi:1" />
The response includes the following elements:
User: ID of the user currently logged in.
Workgroup: The workgroup mnemonic to which the user is assigned.
The Workgroup element has the following attribute:
Desc: Description of the workgroup.
FlexibleHeaders: A list of all flexible headers available to the user.
The FlexibleHeaders element has the following attribute:
namespace: The namespace mnemonic of order type/source.
version: The version of the order type or source. If you do not indicate a version, OSM uses the default version.
Desc: Description of the flexible header.
<GetUserInfo.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<User>jdoe</User>
<Workgroup desc="Provisioning">provisioning</Workgroup>
<Workgroup desc="Customer Service">customer_service</Workgroup>
<FlexibleHeaders>
<FlexibleHeader namespace="DSL_Highspeedline" version="1.1"
desc="Name">customer.name</FlexibleHeader>
<FlexibleHeader namespace="DSL_Highspeedline" version="1.1" desc=
"Phone Number">customer.phone_number</FlexibleHeader>
</FlexibleHeaders>
<GetUserInfo.Response>
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Provides a list of available exception statuses for a given order. The request message includes an Order ID and Order History ID.
ListExceptions
OrderID: The ID of the order.
OrderHistID: The order history ID.
<ListExceptions.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>3422</OrderID> <OrderHistID>4333</OrderHistID> </ListExceptions.Request>
The response includes the Exceptions element with zero or more status elements. The value of a status element is the status mnemonic.
<ListExceptions.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>3422</OrderID>
<OrderHistID>4333</OrderHistID>
<Exceptions>
<Status desc="Complete">complete</Status>
<Status desc="Delete">delete</Status>
</Exceptions>
</ListExceptions.Response>
110: Order not found
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal Error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Returns a list of states and statuses used to transition a given task.
The task status/state request consists of a ListStatesNStatuses operation with parameters indicating the order ID and order history ID.
ListStatesNStatuses
OrderID: The ID of the order.
OrderHistID: The order history ID.
<ListStatesNStatuses.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>12345</OrderID> <OrderHistID>67890</OrderHistID> </ListStatesNStatuses.Request>
The response has parameters with the requested order ID, the order history ID, and the current state of the task. The list of possible states and statuses are listed under the TaskStatesNStatuses element. There are five possible children:
Received: The task may be set to the Received state.
Accepted: The task may be accepted by the current user. Tasks are automatically moved to the Accepted state when retrieved using GetOrder.Request with an Accept parameter of "true".
Assigned: The task can be assigned to any user ID listed in the User children elements.
Suspended: The task can be suspended by providing any of the state mnemonics listed as children.
Completed: The task can be completed by providing any of the status mnemonics listed as children.
<ListStatesNStatuses.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>12345</OrderID>
<OrderHistID>67890</OrderHistoryID>
<State>Received</State>
<TaskStatesNStatuses>
<Accepted/>
<Assigned>
<User>jdoe</User>
<User>rsmith</User>
</Assigned>
<Suspend>
<waiting_on_provisioning/>
<customer_info_incomplete/>
</Suspend>
<Completed>
<submit/>
<delete/>
</Completed>
</TaskStatesNStatuses>
</ListStatesNStatuses.Response>
110: Order not found
302: Request parameter error
400: Not authorized
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Lists the views (query tasks) associated to a user workgroup for a given order source and type. If there is no view associated with a user workgroup, a view will not be returned. You can associate views with workgroups by bringing up the query task in Design Studio and selecting the Default view. See the discussion of query tasks in the Design Studio online help. (Note also that workgroups are called roles in Design Studio.)
ListViews
OrderType: The type of the order.
OrderSource: The source of the order.
Namespace
Version
<ListViews.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>provisioning</OrderType> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </ListViews.Request>
<ListViews.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>provisioning</OrderType> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> <View desc="Create order" mnemonic="create_order_view">1223</View> <View desc="Provision number" mnemonic="create_order_view">3424</View> </ListViews.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request, but no version. This condition forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This condition generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, then this cartridge is used. If this legacy cartridge does not exist, an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, an error (150) message is shown.
A remark can be modified after it is created, either to change the text of the remark or to add or remove attachments. Only the user who created the initial remark has authorization to change it, and only within an administrator defined time interval. The time interval after creating a remark is specified in the oms-config.xml file of the OSM Task web client with the property name remark_change_timeout_hours.
ModifyRemark
OrderID: The order ID associated with the remark.
OrderHistID: The order history ID associated with the remark. If the remark has no OrderHistID, this field can be omitted or empty.
RemarkID: The unique identifier for the remark.
Text: The replacement text for the remark.
AddAttachments: A list of FileName elements that specify file names for new attachments.
DeleteAttachments: A list of AttachmentID elements that specify attachments to remove from the repository. Invalid AttachmentID values are not reported as errors. When attachments are deleted, the associated file is deleted from the file repository.
<ModifyRemark.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>1234</OrderID>
<OrderHistID>12333</OrderHistID>
<RemarkID>1333</RemarkID>
<Text>This is the new text for the remark</Text>
<AddAttachments>
<FileName>newfile.txt</FileName>
<FileName>moreInformation.doc</FileName>
</AddAttachments>
<DeleteAttachments>
<AttachmentID>10222</AttachmentID>
</DeleteAttachments>
</ModifyRemark.Request>
The response follows the same format as that of UpdateOrder when there is a new attachment. The AttachmentID elements must be used to construct the file name for storing the attachment.
The response has a Remark element with the following child elements:
RemarkID: The unique ID for the remark, assigned by OSM.
Attachment: Zero or more Attachment elements for each attachment. An Attachment element has the following child elements:
AttachmentID: The unique ID for the attachment, assigned by OSM. When adding the attachment with the WebLogic file (T3) service, use the file name AttachmentID.srv, where AttachmentID is the value of the AttachmentID element on the response.
FileName: The name of the file specified for the attachment.
<ModifyRemark.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<Remark>
<RemarkID>1333</RemarkID>
<Attachment>
<AttachmentID>12222</AttachmentID>
<FileName>newfile.txt</FileName>
</Attachment>
<Attachment>
<AttachmentID>12223</AttachmentID>
<FileName>moreInformation.doc</FileName>
</Attachment>
</Remark>
</ModifyRemark>
160: Remark not found
260: Remark cannot be modified
270: Transaction not allowed
302: Request parameter error
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.A list of current retrievable notifications.
Notifications
None
The returned information includes the following information for each notification:
_notif_id: An integer unique identification number for the notification.
_notif_desc: A string description of the notification
_notif_type: Either the string 'poll' for a polled notification or 'process' for a transitional notification.
_notif_priority: An integer indicating the priority level of the notification.
_notif_time: An XML API datetime representing the time the notification was generated.
_order_seq_id: An integer unique identification number of the order for which the notification was generated. If order ID does not exist, an empty value appears.
_order_hist_seq_id: An integer ID number of the order history ID for which the notification was generated.
_order_type: The mnemonic of the order's type. If there is no order, then an empty value appears.
_order_source: The mnemonic of the order's source. If there is no order, then an empty value appears.
_date_pos_created: An XML API datetime representation of the time the order was created. If there is no order, then an empty value appears.
_reference_number: The order's reference string. If there is no order, then an empty value appears.
_priority: An integer indicating the priority level of the order.
_requested_delivery_date: The date when the order is requested to be delivered. If an order contains multiple requested dates, for example because multiple order components have individual requested dates, then the requested date is interpreted to be the one selected for calculation of "expected start date."
_user: The surname currently associated with the order. If there is no order, then an empty value appears.
_ProcessStatus: The process status of the order.
_expected_completion_date: The date that OSM expects order processing to complete.
_expected_duration: The amount of time OSM determines it will take to complete the order. OSM calculates this value from durations given in the OSM model. OSM selects the durations based on the details of a specific order.
_expected_start_date: The date that OSM determines that the order should begin executing the order to meet its requested delivery date. This date is calculated by considering the expected duration. OSM only returns this parameter for orders that use orchestration plans. If an order does not use an orchestration plan, it is not returned.
_namespace: The namespace of the order type/source
_version: The version of the order type/source
In addition, for each flexible header assigned to the user, an instance of the following parameter is returned:
_header: This element has an attribute named mnemonic_path which contains the path of the flexible header. The value of the _header element is the value of the flexible header converted into a string. Table 3-2 lists the formats for data types that require formatting to be converted into a string:
Table 3-2 Formatting for Text Representation of Data Types
| Primitive Type | Format |
|---|---|
|
dateTime |
yyyy-MM-ddThh:mm:ss time zone (for example 2013-10-30T14:33:22 EST) |
|
date |
yyyy-MM-dd |
|
Boolean |
Yes or No |
The notifications retrieved for a given user ID consist of those assigned to the user or any of the user's workgroups still in an active state. The maximum number of notifications returned in one request is defined by the max_notification_rows property in the oms-config.xml.
<Notifications.Request xmlns="urn:com:metasolv:oms:xmlapi:1" />
If there are no notifications for a user ID, the response contains only the Header element.
<Notifications.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<Header>
<_notif_id desc="Notification ID"/>
<_notif_desc desc="Notification Description/>
<_notif_type desc="Notification Type"/>
<_notif_priority desc="Priority" />
<_notif_time desc="Notification Timestamp"/>
<_order_seq_id desc="Order ID"/>
<_order_hist_seq_id desc="Order History ID"/>
<_order_source desc="Source"/>
<_order_type desc="Type"/>
<_reference_number desc="Ref. #"/>
<_priority desc="Priority" />
<_date_pos_created desc="Order Creation Date"/>
<_requested_delivery_date desc="Requested Order Delivery Date"/>
<_expected_start_date desc="Expected Order Start Date"/>
<_expected_duration desc="Expected Order Duration"/>
<_compl_date_expected desc="Expected Order Completion Date"/>
<_user desc="User" />
<_process_status desc="Status"/>
<_namespace desc="Namespace" />
<_version desc="Version" />
<customer.name desc="Customer Name"/>
<customer.phone desc="Customer Phone"/>
</Header>
<Notification>
<_notif_id>4567</_notif_id>
<_notif_desc>Order transitioned</_notif_desc>
<_notif_type>process</_notif_type>
<_notif_priority>1</_notif_priority>
<_notif_time>2000-10-30T14:33:22 EST</_notif_time>
<_order_seq_id>2345</_order_seq_id>
<_order_hist_seq_id>2333</_order_hist_seq_id>
<_order_source>order_entry</_order_source>
<_order_type>pots</_order_type>
<_reference>AA-B3653F</_reference>
<_priority>5</_priority>
<_date_pos_created>2000-10-30T14:30:00 EST</_date_pos_created>
<_requested_delivery_date>2000-10-30T14:30:00 EST</_requested_delivery_date>
<_expected_start_date>2000-10-20T14:30:00 EST</_expected_start_date>
<_expected_duration>P10D</_expected_duration>
<_compl_date_expected>2000-10-30T14:30:00 EST</_compl_date_expected>
<_user>oms</_user>
<_status/>
<_namespace>DSL_Highspeedline</_namespace>
<_version>1.1</_version>
<customer.name>John Doe</customer.name>
<customer.phone>4165555555</customer.phone>
</Notification>
<Notification>
<_notif_id>4568</_notif_id>
<_notif_desc>Pots Order Overdue</_notif_desc>
<_notif_type>poll</_notif_type>
<_notif_priority>1</_notif_priority>
<_notif_time>2000-10-30T18:33:22 EST</_notif_time>
<_order_seq_id>2346</_order_seq_id>
<_order_hist_seq_id>2333</_order_hist_seq_id>
<_order_source>order_entry</_order_source>
<_order_type>pots</_order_type>
<_reference>AA-B3653F</_reference>
<_priority>5</_priority>
<_date_pos_created>2000-10-30T14:30:00 EST</_date_pos_created>
<_requested_delivery_date>2000-10-30T14:30:00 EST</_requested_delivery_date>
<_expected_start_date>2000-10-20T14:30:00 EST</_expected_start_date>
<_expected_duration>P10D</_expected_duration>
<_compl_date_expected>2000-10-30T14:30:00 EST</_compl_date_expected>
<_user>oms</_user>
<_status/>
<_namespace>DSL_Highspeedline</_namespace>
<_version>1.1</_version>
<customer.name>John Doe</customer.name>
<customer.phone>4165555555</customer.phone>
</Notification>
... more notifications ...
</Notifications.Response>
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Orders have an associated source and type that is required prior to creating new orders. The available order type/source combinations are retrieved by requesting OrderTypesNSources. The mnemonics for the type/source pairs can be used to retrieve an order template and create a new order.
OrderTypesNSources
Namespace
Version
<OrderTypesNSources.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </OrderTypesNSources.Request>
<OrderTypesNSources.Response mlns="urn:com:metasolv:oms:xmlapi:1">
<TypeNSource namespace="DSL_Highspeedline" version="1.1">
<Type mnemonic="phone_activation" category="Customer Service"
desc="Phone Activation Order"/>
<Source mnemonic="source1" desc="from front-end system"/>
</TypeNSource>
<TypeNSource namespace="DSL_Highspeedline" version="1.1" >
<Type mnemonic="phone_transfer category="Customer Service"
desc="Phone Number Transfer"/>
<Source mnemonic="source1" desc="from front-end system"/>
</TypeNSource>
</OrderTypesNSources.Response>
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request without a version. This forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, this cartridge is used. If this legacy cartridge does not exist, then an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist an error (150) message is shown.
Scenario 5: If both namespace and version attributes are set to "*", the list of available order types and sources across all namespaces and versions is returned.
Scenario 6: If a namespace is supplied with version "*", the list of available order types and sources corresponding to the namespace across all of its existing versions is returned.
The OrderViewTemplate request provides the data type descriptions, such as minimum and maximum instances of lists, data types, and business names for data elements.
The OrderViewTemplate describes the structure of a particular order type. The types of order templates can be grouped into the following categories:
Order view creation template: You must provide the mnemonics for a valid order type/source pair.
Order view template for a particular task in a process: You must provide the order ID (_order_seq_id in the worklist) and the order history ID (_order_hist_seq_id in the worklist).
Order view templates for orders not in a process: You must provide the order view (query task) template "view ID". You can obtain the list of valid view IDs for an order with a ListViews Request.
Order view templates for a task: You must provide the order type/source and task mnemonic.
OrderViewTemplate
For a creation template:
OrderSource: The order source mnemonic.
OrderType: The order type mnemonic.
For an in-process order:
OrderID: The sequence ID of an order (Orderdata/_order_seq_id from worklist).
OrderHistID: The history sequence ID of an order (Orderdata/_order_hist_seq_id from the worklist).
Namespace: The namespace mnemonic of order type/source.
Version: The version mnemonic of order type/source.
For an order not in a process:
OrderSource: The order source mnemonic.
OrderType: The order type mnemonic.
View: A view (query task) valid for a particular order type and source.
Namespace: The namespace mnemonic of order type/source.
Version: The version mnemonic of order type/source.
For a task order view template:
OrderSource: The order source mnemonic.
OrderType: The order type mnemonic.
Task: The task mnemonic.
Namespace: The namespace mnemonic of order type/source.
Version: The version mnemonic of order type/source.
<OrderViewTemplate.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </OrderViewTemplate.Request>
<OrderViewTemplate.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderType>phone_transfer</OrderType>
<OrderSource>source1</OrderSource>
<Namespace>DSL_Highspeedline</Namespace>
<Version>1.1</Version>
<_root>
<client_info
readOnly="false"
desc="Client Information"
minInstance="1"
maxInstance="1">
<name
readOnly="false"
desc="Name"
minInstance="1"
maxInstance="1"
type="TX"
len="30"/>
<address
readOnly="false"
desc="Address"
minInstance="1"
maxInstance="2">
<street1
readOnly="false"
desc="Street 1"
minInstance="1"
maxInstance="1"
type="TX"
length="50" />
<street2
readOnly="false"
desc="Street 2"
minInstance="0"
maxInstance="1"
type="TX"
length="50" />
<city
readOnly="false"
desc="City"
minInstance="0"
maxInstance="1"
type="TX"
length="25" />
<state
readOnly="false"
desc="State"
minInstance="1"
maxInstance="1"
type="LK" />
</address>
</client_info>
</_root>
<LookupTables>
<state>
<option desc="New York">NY</option>
<option desc="California">CA</option>
<option desc="New Jersey">NJ</option>
... etc ...
</state>
</LookupTables>
</OrderViewTemplate.Response>
The response includes the OrderViewTemplate beginning with a _root element. Each child is named with the mnemonic of that data element, along with the following attributes:
Desc: The business name of the element.
MinInstance: The minimum number of instances allowed (0-n). A field with minInstance > 0 is a mandatory field if the parent is defined in the order.
MaxInstance: The maximum number of instances allowed (1-n).
Mask: The mask associated with an element of type NM or TX.
ReadOnly: A true/false attribute indicating that the field cannot be modified.
Type: The data type of the element. The data type values are:
NM: Numeric type
TX: Text type
D: Date type in the form: yyyy-mm-dd (for example, 2000-03-10)
DT: Date/time type in the form: yyyy-mm-ddThh:mm:ss time zone (for example, 2000-03-10T14:43:00 EST)
PH: Phone number type
YN: Boolean type (Yes/No)
CY: Currency type
LK: Lookup type
Length: The maximum length of the element if the type is NM or TX.
The values for the lookup elements in the view template are rooted at the LookupTables element. The name of a lookup element matches the data elements of type LK in the order template.
150: Namespace/version not found.
152: Invalid namespace mnemonic.
153: No legacy data found. Namespace and Version need to be supplied.
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request, but no version. This forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, this cartridge is used. If this legacy cartridge does not exist, then an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, then an error (150) message is shown.
<OrderViewTemplate.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>12333</OrderHistID> </OrderViewTemplate.Request>
<OrderViewTemplate.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <ViewID>1123</ViewID> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </OrderViewTemplate.Request>
or
<OrderViewTemplate.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <View>phone_transfer</View> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </OrderViewTemplate.Request>
For a Task Order View Template
<OrderViewTemplate.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderSource>source1</OrderSource> <OrderType>phone_transfer</OrderType> <Task>phone_transfer</Task> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </OrderViewTemplate.Request>
Queries the order header information and data elements of orders for inclusion in the Query.Response.
Query
OrderID: An integer value with wildcards for the order sequence ID.
Reference: A string with wildcards for the reference number.
OrderType: An order type mnemonic.
OrderSource: An order source mnemonic.
Task: The task mnemonic.
CreatedDate: The date the order was created. Two attributes, "from" and "to", indicate the beginning and ending date or date/time for the query.
RequestedDeliveryDate: The date requested by the client for the order to be completed.
ExpectedStartDate: The date that OSM will begin processing an order.
ExpectedDuration: The amount of time the order is expected to take to complete processing.
ExpectedCompletionDate: The date that OSM expects the order to complete.
CompletedDate: The date the order was completed.
User: A user ID.
State: A task state mnemonic. The valid mnemonics are:
Received
Assigned
Accepted
Completed
Any user-defined state mnemonics
Status: A task status mnemonic. The valid status mnemonics are those statuses defined in the OSM Administrator.
Priority: An integer indicating the priority level of the order.
OrderState: An order state mnemonic. The valid mnemonics are:
open.not_running.not_started
open.not_running.suspended
open.not_running.waiting_for_revision
open.not_running.cancelled
open.running.in_progress
open.running.compensating.amending
open.running.compensating.cancelling
closed.completed
closed.aborted
open.not_running.failed
TargetOrderState: Same mnemonics as OrderState.
ExecutionMode: An execution mode mnemonic. The valid mnemonics are:
Do
Redo
Undo
FlexibleHeaders: A list of flexible headers available to the user. Can contain zero or more FlexibleHeader elements with the mnemonic paths of flexible headers to include in the output. If FlexibleHeaders is omitted, no flexible headers are returned.
The FlexibleHeaders element has the following attribute:
namespace: The namespace mnemonic of order type/source.
version: The version of the order type or source. If you do not indicate a version, OSM uses the default version.
SingleRow: This element forces OSM to display only a single row if a query returns more than one match per order.
OrderBy: The OrderBy element contains a list of fields on which to order the results. The order of the Field elements is significant: the results are ordered based on the first element, then the second element, and so on.
The order attribute must be either descending or ascending, otherwise an error results. The path attribute must belong to the element name of one of the fixed headers or one of the request's selected flexible headers. If the mnemonic path does not resolve to a valid field to sort by, error code 170: Header for mnemonic path not found is returned.
When sorting on fixed header elements, the sorted value for elements that are represented by an ID (that is, state) will be sorted based on the internal ID's value, not that of the final output.
For querying order data values, a 'Field' element is provided with the following format. If querying for equality:
<Field path="/client_info/address/city" namespace="DSL_Highspeedline" version="1.1">Toronto</Field>
If querying for a range of values:
<Field path="/client_info/address/city" namespace="DSL_Highspeedline" version="1.1"> <From>A*</From> <To>D*</To> </Field>
The "path" attribute of the field is a sequence of data element mnemonics, separated by a slash, "/", indicating the mnemonic path of the data field to be matched against. Only the data elements that are assigned as flexible headers for the user ID can be queried in a Field element. Use the namespace and version attributes to specify the namespace and version mnemonic of order type/source.
You can use wildcard characters with the Order ID, Reference and Field elements whose path attribute resolves to a OSM text field (TX data type). Valid wildcard characters are:
"*" indicates any number of characters
"?" indicates a single character
If an additional element, SingleRow, is "true", an order is listed only once. If SingleRow is "false", the order is listed once for each data element it matches in the query request.
The Query request performs a logical "AND" of all provided parameters.
<Query.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>123*</OrderID>
<FlexibleHeaders>
<FlexibleHeader namespace="DSL_Highspeedline" version="1.1"
path="customer/name"/>
<FlexibleHeader namespace="DSL_Highspeedline" version="1.1"
path="customer/phone"/>
<FlexibleHeader>customer/address</FlexibleHeader>
<FlexibleHeader>customer/name</FlexibleHeader>
</FlexibleHeaders>
</Query.Request>
or
<Query.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<FlexibleHeaders>
<FlexibleHeader namespace="view_framework_demo" version="1.0.0.0.0"path="/account_information/amount_owing"/>
</FlexibleHeaders>
<Field namespace="view_framework_demo" version="1.0.0.0.0" path="/account_information/amount_owing">444</Field>
</Query.Request>
or
<Query.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>123*</OrderID>
<Field path="/client_info/address/city" namespace="DSL_Highspeedline"
version="1.1">Toronto</Field>
</Query.Request>
or
<Query.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>123*</OrderID>
<OrderBy>
<Field order="descending" namespace="DSL_Highspeedline" version="1.1">
customer/phone </Field>
</OrderBy>
</Query.Request>
or
<Query.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderState>open.not_running.not_started</OrderState> </Query.Request>
<Query.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<Header>
<_order_seq_id desc="Order ID"/>
<_order_hist_seq_id desc="Order History ID"/>
<_order_state desc="Task State"/>
<_execution_mode desc="Execution Mode"/>
<_task_id desc="Task Name"/>
<_order_source desc="Source"/>
<_order_type desc="Order Type"/>
<_current_order_state desc="Order State"/>
<_target_order_state desc="Target Order State"/>
<_reference_number desc="Ref. #"/>
<_priority desc="Priority"/>
<_date_pos_created desc="Order Creation Date"/>
<_requested_delivery_date desc="Requested Delivery Date"/>
<_expected_start_date desc="Expected Start Date"/>
<_expected_duration desc="Expected Duration"/>
<_user desc="User"/>
<_process_status desc="Process Status"/>
<_date_pos_started desc="Started"/>
<_compl_date_expected desc="Expected Order Completion Date"/>
<_ord_completion_date desc="Completed Date"/>
<_grace_period_completion_date desc="Expected Grace Period Completion"/>
<_num_remarks desc="Number of Remarks"/>
<_namespace desc="Namespace"/>
<_version desc="Version"/>
<_workgroups desc="Workgroups">
<_workgroup/>
</_workgroups>
</Header>
<Orderdata>
<_order_seq_id>40</_order_seq_id>
<_order_hist_seq_id>502</_order_hist_seq_id>
<_order_state>received</_order_state>
<_execution_mode>do</_execution_mode>
<_task_id>CollectionsFunction_CollectionsSI</_task_id>
<_order_source>OsmCentralOMExampleOrder</_order_source>
<_order_type>OsmCentralOMExampleOrder</_order_type>
<_current_order_state>open.not_running.waiting</_current_order_state>
<_target_order_state/>
<_reference_number>[do:1]$ref1436191716838</_reference_number>
<_priority>5</_priority>
<_date_pos_created>2015-07-06T07:08:36 PDT</_date_pos_created>
<_requested_delivery_date>2015-08-05T10:08:36 PDT</_requested_delivery_date>
<_expected_start_date>2015-07-09T10:08:36 PDT</_expected_start_date>
<_expected_duration>P26D</_expected_duration>
<_user/>
<_process_status>n/a</_process_status>
<_date_pos_started>2015-07-06T07:08:38 PDT</_date_pos_started>
<_compl_date_expected>2015-08-04T10:08:36 PDT</_compl_date_expected>
<_ord_completion_date/>
<_grace_period_completion_date/>
<_num_remarks>0</_num_remarks>
<_namespace>OsmCentralOMExample-Solution</_namespace>
<_version>4.0.0.0.0</_version>
<_workgroups>
<_workgroup/>
</_workgroups>
</Orderdata>
</Query.Response>
The query response uses a similar format as the XMLAPI Worklist message. It consists of a header element that contains descriptive elements for all columns returned. The columns consist of a number of fixed header elements (prefixed with _), followed by any flexible headers defined for the user in the OSM Administrator. Zero or more Orderdata elements follow the Header element with each one corresponding to the data for a particular order matched by the query criteria. If the request has "SingleRow" set to "false", an order appears once for each data element that was matched. If set to "true", it appears only once.
To retrieve an order matched in the query, the GetOrder.Request supports a parameter, "ViewID", which retrieves an order based on a particular view (query task). You can obtain a list of valid ViewIDs for an order source/type with ListViews.Request.
170: Header for mnemonic path not found
302: Request parameter error
400: Not authorized
401: Database connection failed
500: Internal Error
601: Deprecated parameter
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Moves an order to the Received state.
ReceiveOrder
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
<ReceiveOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>222334</OrderHistID> </ReceiveOrder.Request>
<ReceiveOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>33123</OrderHistID> </ReceiveOrder.Response>
The ReceiveOrder response includes the new order history ID for the task.
110: Order not found
251: Transition invalid
270: Transaction not allowed
302: Request parameter error
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Resolves failures from a particular task causing the task to transition from a failed execution mode to a corresponding normal execution mode. The task reverts to the state it had been in before the failure occurred. This request requires an Order ID and Order History ID.
ResolveFailure
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
Reason: The reason for the failure resolution. This parameter is optional.
<ResolveFailure.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>18</OrderID> <OrderHistID>342</OrderHistID> </ResolveFailure.Request>
<ResolveFailure.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>18</OrderID> <OrderHistID>342</OrderHistID> </ResolveFailure.Response>
110: Order not found
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database connection failed
500: Internal ErrorSuspendOrder
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Releases a suspended order back into the system and returns it to the state from which it was suspended. Can also be used to resubmit a canceled order back into the system.
ResumeOrder
OrderID: The ID of the order to resume.
Reason: The reason why the order is being resumed. Optional.
<ResumeOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Reason>Customer requests resumption of order</Reason> </ResumeOrder.Request>
<ResumeOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> </ResumeOrder.Response>
110: Order not found
251: Transition invalid
270: Transaction not allowed
302: Request parameter error
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Retries a failed task causing the task to transition from a failed execution mode to a corresponding normal execution mode. The task reverts to the received state. This request requires an Order ID and Order History ID.
RetryTask
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
Reason: The reason retrying the task. This parameter is optional.
<RetryTask.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>18</OrderID> <OrderHistID>342</OrderHistID> </RetryTask.Request>
<RetryTask.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>18</OrderID> <OrderHistID>342</OrderHistID> </RetryTask.Response>
110: Order not found
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database connection failed
500: Internal ErrorSuspendOrder
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Sets the exception status for a given order. This request requires an Order ID, Order History ID, and Status mnemonic.
SetException
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
Status: The status mnemonic.
<SetException.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>3422</OrderID> <OrderHistID>4333</OrderHistID> <Status>complete</Status> </SetException.Request>
<SetException.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>3422</OrderID> <OrderHistID>4334</OrderHistID> </SetException.Response>
The SetException response includes the new order history ID if the exception goes to a new task.
110: Order not found
256: Invalid exception status mnemonic
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database Connection Failed
419: The process exception is restricted
500: Internal ErrorSuspendOrder
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Suspends an order, or a task, depending on the parameters supplied in the request.
SuspendOrder
For an order:
OrderID: The ID of the order to suspend
And one of the following:
Immediate: Force immediate suspension of all tasks associated with the order.
GracePeriodExpiryDate: A period of time to allow tasks in the Accepted state time to complete.
Infinite: Wait indefinitely until all tasks in the Accepted state complete.
EventInterval: If the suspension is not immediate, you can set an interval for sending a jeopardy notification.
Reason: The reason why the order is being suspended.
For a task:
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
State: The user-defined state mnemonic.
<SuspendOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Immediate/> <Reason>Customer requested hold on order</Reason> </SuspendOrder.Request>
or
<SuspendOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <GracePeriodExpiryDate>2006-10-10T11:10:10 EST</GracePeriodExpiryDate> <EventInterval>PT10S</EventInterval> <Reason>Customer requested hold on order</Reason> </SuspendOrder.Request>
or
<SuspendOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <Infinite/> <Reason>Customer requested hold on order</Reason> </SuspendOrder.Request>
<SuspendOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>22334</OrderHistID> <State>waiting_on_provisioning</State> </SuspendOrder.Request>
<SuspendOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> </SuspendOrder.Response>
<SuspendOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1"> <OrderID>1234</OrderID> <OrderHistID>33247</OrderHistID> </SuspendOrder.Response>
The SuspendOrder response includes the new order history ID for the task.
110: Order not found
251: Transition invalid
254: State mnemonic invalid
270: Order could not be suspended
302: Request parameter error
401: Database Connection Failed
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.The TaskDescription operation retrieves the list of all available tasks.
TaskDescription
Namespace: The namespace mnemonic of the order type/source (optional).
Version: The version of the order type or source (optional).
<TaskDescription.Request xmlns="urn:com:metasolv:oms:xmlapi:1" />
<TaskDescription.Request xmlns="urn:com:metasolv:oms:xmlapi:1"> <Namespace>DSL_Highspeedline</Namespace> <Version>1.1</Version> </TaskDescription.Request>
<TaskDescription.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<Task mnemonic="activate_switch" TaskType="automatic" desc="Activate switch">
<Task mnemonic="provision_number" TaskType="manual"
desc="Provision Customer Number">
</TaskDescription.Response>
400: Not authorized
401: Database Connection Failed
500: Internal errorWorklist
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.The worklist data retrieved by the Client user ID is defined by the OSM Administrator. The Worklist is implicitly defined by the privileges of each workgroup to which the Client ID is assigned.
The worklist response consists of fixed header elements followed by the flexible headers as defined in the OSM Administrator.
An order update consists of an operation UpdateOrder, with the order ID and order history ID to identify the order. The request defines different ways to update the order such as UpdatedOrder, UpdatedNodes, Add, and Delete.
UpdateOrder
This API defines the following parameter:
OrderID: The ID of the order to change.
OrderHistID: The order history ID.
ViewID: The id of the view (query task) that is used for the order update. This is a workgroup view that must be associated with one or more workgroups the requesting user is a member of for the definition of the order.
View: The name of the task (view) that is used for the order update. You must associate the task you want to update to a role (workgroup) in the Design Studio Order editor Permissions Query Task sub tab and set the task as the Default query task. You can associate only one role per task in the Order editor. The user submitting the UpdateOrder must be a member of this role.
ResponseView: An optional parameter that defines the name of the task (view) that specifies what parameters are returned in UpdateOrder responses. If the UpdateOrder request results in a fulfillment state update, the response auto-filters nodes to only include the effected OrderItems and OrderComponents instances.
OrderDataFilter: Parent element for the Condition child element that specifies which order data to return in the OrderUpdate.response specified in the ResponseView parameter.
Condition: An XPath 1.0 expression against the order data defined by the ResponseView. OSM returns only the instances of the order data selected by the expression, not the other instances of the element. All other parent or sibling elements are returned.
For example, in a situation where a customer has multiple <address> instances (where <address> is a multi-instance element), the following expression ensures that OSM returns only the <address> element that contains a child street element with the specified street address. The response includes all child nodes of the instance of the <address> element (city, postal code, and street). The other instances of the <address> element and their child elements (city, street, and postal code) are not returned.
<OrderDataFilter>
<Condition>/subscriber_info/address/[street='190 Drive']</Condition>
</OrderDataFilter>
For example, any sibling elements of <subscriber_info>, or sibling elements of <address> (except for the other instances of the <address> element) would be returned.
When you are using an order condition that includes an element that is using a distributed order template, you should include the namespace of the data element in the condition. For example:
<OrderDataFilter>
<Condition>
/ControlData/OrderItem[@type='{OrderItemNamespace}OrderItemName' and @LineId='1']
</Condition>
</OrderDataFilter>
NewReference: An optional new reference number for the order.
AddMandatory: This parameter is true if the mandatory fields defined in the order view (task) should be added into the order by this order update, otherwise this parameter should be false.
Priority: The priority that the order is set to by this order update.
A choice of:
UpdatedOrder: Allows the user to update the order by supplying a complete order. The existing order is then updated (elements added, changed or deleted as necessary) to match the supplied order.
UpdatedNodes: Allows the user to update the order by supplying only the nodes that should be added or updated. The nodes are supplied in the format of the existing order: The structure of the nodes (parents and children) must match the view (task) specification for the view being used. No deletes are performed using this approach.
Add: Allows the user to update the order by adding new data in the form of a node to be added. The path attribute identifies the parent node under which to add the element.
Delete: Allows the user to update the order by deleting existing data in the form of a node to be deleted. The path attribute identifies the node to delete.
Update: Allows the user to update the order by updating existing data in the form of a node to be updated. The path attribute identifies the node to update.
AddRemark: A remark can be added to the order using an AddRemark parameter. The AddRemark element has the following elements:
Text: The text for the new remark.
Attachments: The parent element for FileName elements. The Attachments element can also have one of the following elements:
FileName: The name of the file for a new attachment. If both the Text and Attachments elements are empty, a remark is not created.
ExternalFulfillmentStates: Allows you to set external fulfillment states instead of using an Add or Update statement on an UpdateOrder. This optional approach improves order processing efficiency, especially in large orders. The ExternalFulfillmentStates element has the following child elements:
OrderItemOrderComponentFulfillmentState: The parent element to the children elements that specify the new external fulfillment state of an order component and order item.
ExternalFulfillmentState: The new external fulfillment state.
OrderComponentIndex: The order component index. Every order component element must specify a unique index attribute. In most cases, the automation running the XML API OrderUpdate already knows which order component the update is for.
OrderItemIndex: The order item index. Every order item element must specify a unique index attribute. In most cases, the automation running the XML API OrderUpdate already knows which order component the update is for.
Note:
If you update an order either to add a node (which includes providing a value to a node that did not previously have one) or to delete a node (which includes setting the value of a node to null), the OSM order transformation manager will not propagate the change in either the forward or reverse direction. For more information about data propagation, see the discussion of mapping rules in the Design Studio Modeling OSM Orchestration Help.
<UpdateOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>702</OrderID>
<View>Update Order View</View>
<NewReference/>
<Add path="/client_info">
<address>
<street1>55 James St.</street1>
<city>Washington</city>
<state>DC</state>
<country>USA</country>
<zip>45432</zip>
</address>
</Add>
<Delete path="/client_info/address[@index='80132']" />
<AddRemark>
<Text>This is the text for the remark</Text>
<Attachments>
<FileName>provisioninfo.txt</FileName>
<FileName>diagram.bmp</FileName>
</Attachments>
</AddRemark>
<ExternalFulfillmentStates>
<OrderItemOrderComponentFulfillmentState>
<ExternalFulfillmentState>COMPLETED</ExternalFulfillmentState>
<OrderComponentIndex>123</OrderComponentIndex>
<OrderItemIndex>456</OrderItemIndex>
</OrderItemOrderComponentFulfillmentState>
</ExternalFulfillmentStates>
</UpdateOrder.Request>
If a remark is added to an order, remark information is returned in the UpdateOrder response. The response has a Remark element with the following child elements:
RemarkID: The unique ID for the remark, assigned by OSM.
Attachment: Zero or more Attachment elements for each attachment. An Attachment element has the following child elements:
AttachmentID: The unique ID for the attachment, assigned by OSM. When adding the attachment with the WebLogic file (T3) service, use the file name AttachmentID.srv, where AttachmentID is the value of the AttachmentID element on the response.
FileName: The name of the file specified for the attachment.
<UpdateOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>702</OrderID>
<View>Update Order View</View>
<Remark>
<RemarkID>3224</RemarkID>
<Attachment>
<AttachmentID>10333</AttachmentID>
<FileName>provisioninfo.txt</FileName>
</Attachment>
<Attachment>
<AttachmentID>10334</AttachmentID>
<FileName>diagram.bmp</FileName>
</Attachment>
</Remark>
</UpdateOrder.Response>
Request Example with ResponseView and OrderDataFilter
<UpdateOrder.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>15778</OrderID>
<View>OsmCentralOMExampleQueryTask</View>
<ResponseView>OsmCentralOMExampleQueryTask</ResponseView>
<OrderDataFilter>
<Condition>/CustomerDetails/typeCompl[@index='15']</Condition>
<OrderDataFilter>
<UpdatedNodes>
<_root>
<CustomerDetails>
<typeCompl>floor</typeCompl>
</CustomerDetails>
</_root>
</UpdatedNodes>
<ExternalFulfillmentStates>
<OrderItemOrderComponentFulfillmentState>
<ExternalFulfillmentState>ExtFulfState1</ExternalFulfillmentState>
<ExternalFulfillmentStateDescription>
</ExternalFulfillmentStateDescription>
<OrderComponentIndex>132490</OrderComponentIndex>
<OrderItemIndex>1434565</OrderItemIndex>
</OrderItemOrderComponentFulfillmentState>
</ExternalFulfillmentStates>
</UpdateOrder.Request>
Response Example with ResponseView and OrderDataFilter
<UpdateOrder.Response xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderID>15778</OrderID>
<View>Update Order View</View>
<Data>
<_root index="0">
<CustomerDetails index="11">
<typeCompl index="15">floor</typeCompl>
</CustomerDetails>
</_root>
</Data>
</UpdateOrder.Response>
110: Order not found
200: Order data invalid
230: Order not accepted by user
232: Order update failed
270: Transaction not allowed
302: Request parameter error
400: Not authorized
401: Database Connection Failed
420: Not authorized to modify order priority
500: Internal error
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Scenario 1: Namespace is supplied in the request, but no version. This condition forces the system to use the default version for the supplied namespace.
Scenario 2: Version is supplied in the request, but no namespace. This generates an error (152) message.
Scenario 3: The first cartridge is reserved for the migrated data. If namespace and version are not supplied, then this cartridge is used. If this legacy cartridge does not exist, an error (153) message is shown.
Scenario 4: If the combination of namespace and version does not exist, an error (150) message is shown.
Returns order data from the worklist.
Worklist
FlexibleHeaders: A list of flexible headers available to the user. It can contain zero or more flexibleheader elements with the mnemonic paths of flexible headers to include in the output. If FlexibleHeaders is omitted, all available flexible headers are returned.
FlexibleHeader: This parameter is a sub-parameter of FlexibleHeaders and has the following attributes:
namespace (mandatory if you use the FlexibleHeader element of Worklist.Request)
version (optional)
OrderBy: The OrderBy element contains a list of fields on which to order the results. The order of the Field elements is significant: the results are ordered based on the first element, then the second element, and so on.
The order attribute must be either descending or ascending, otherwise an error results. The path attribute must belong to the element name of one of the fixed headers or one of the request's selected flexible headers. If the mnemonic path does not resolve to a valid field to sort by, error code 170: Header for mnemonic path not found is returned.
When sorting on fixed header elements, the sorted value for elements that are represented by an ID (that is, state) will be sorted based on the internal ID's value, not that of the final output.
Field: A value on the order, either Fixed or Flexible. This element takes the following mandatory attribute:
Order (you must specify either ascending or descending as the argument.)
FilterStates: A list of the states on which the Task web client filters the Worklist. For example, if FilterStates only contains accepted, then the Worklist displays only those tasks that are in the Accepted state.
OrderState: A state for the order. This element can have multiple instances and the values indicate which states an order must be in to be returned. Acceptable values are: "Amending", "Cancelled", "Cancelling", "Completed", "In Progress", "No state", "Not Started", "Suspended", and any user-defined state states.
State: A state for the task. This element can have multiple instances and the values indicate which states a task must be in to be returned. Acceptable values are:
Assigned: The task is in the Assigned state and is assigned to the current user's ID.
Received: The task is in the Received state.
Accepted: The task is in the Accepted state for the current user's ID.
Suspended: The task is in the Suspended state.
Namespace: The namespace mnemonic of order type/source.
Version: The version mnemonic of order type/source.
UsePreferences: The element uses user-preferences from the Task web client to determine how to filter and sort the Worklist.
<Worklist.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<FlexibleHeaders>
<FlexibleHeader namespace="OrderAmendment" version="1.0"
path="customer/phone"/>
<FlexibleHeader namespace="OrderAmendment" version="1.0"
path="customer/name"/>
</FlexibleHeaders>
</Worklist.Request>
or
<Worklist.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<OrderBy>
<Field order="ascending" path="masks_group/m_numeric_999"/>
</OrderBy>
</Worklist.Request>
or
<Worklist.Request xmlns="urn:com:metasolv:oms:xmlapi:1">
<Namespace>sp_nead</Namespace>
<Version>2.1.2</Version>
<OrderBy>
<Field order="descending">_order_seq_id</Field>
</OrderBy>
</Worklist.Request>
<Worklist.Response xmlns="urn:metasolv-com:oms:xmlapi_1">
<Header>
<_order_seq_id desc="Order ID" />
<_order_hist_seq_id desc="Order History ID" />
<_order_state desc="State" />
<_execution_mode desc="Execution Mode" />
<_task_id desc="Task" />
<_order_source desc="Source" />
<_order_type desc="Type" />
<_current_order_state desc="Order State" />
<_target_order_state desc="Target Order State" />
<_reference_number desc="Ref. #" />
<_priority desc="Priority" />
<_user desc="User" />
<_process_status desc="Process Status" />
<_date_pos_started desc="Started" />
<_requested_delivery_date desc="Requested Order Delivery Date"/>
<_expected_start_date desc="Expected Order Start Date"/>
<_expected_duration desc="Expected Order Duration"/>
<_compl_date_expected desc="Expected Order Completion Date" />
<_num_remarks desc="Number of Remarks" />
<_namespace desc="Namespace" />
<_version desc="Version" />
<customer_phone desc="Customer Phone Number" />
<customer_name desc="Customer Name" />
</Header>
<Orderdata>
<_order_seq_id>390</_order_seq_id>
<_order_hist_seq_id>7822</_order_hist_seq_id>
<_order_state>received</_order_state>
<_execution_mode>do</_execution_mode>
<_task_id>assign_port</_task_id>
<_order_source>order_entry</_order_source>
<_order_type>pots</_order_type>
<_current_order_state>open.not_running.not_started
</_current_order_state>
<_target_order_state />
<_reference_number>SEP-27-0-1</_reference_number>
<_priority>5</_priority>
<_user>oms</_user>
<_process_status/>
<_date_pos_started>2001-10-29T10:30:24 EST</_date_pos_started>
<_requested_delivery_date>2001-10-29T10:30:14 EST</_requested_delivery_date>
<_expected_start_date>2001-10-19T10:30:14 EST</_expected_start_date>
<_expected_duration>P10D</_expected_duration>
<_compl_date_expected>2001-10-29T10:30:16 EST</_compl_date_expected>
<_num_remarks>0</_num_remarks>
<_namespace>OrderAmendment</_namespace>
<_version>1.0</_version>
<customer_phone>4165551212</customer_phone>
<customer_name>John Doe</customer_name>
</Orderdata>
<Orderdata>
<_order_seq_id>391</_order_seq_id>
<_order_hist_seq_id>7718</_order_hist_seq_id>
<_order_state>accepted</_order_state>
<_execution_mode>do</_execution_mode>
<_task_id>assign_port</_task_id>
<_order_source>order_entry</_order_source>
<_order_type>pots</_order_type>
<_current_order_state>open.running.in_progress</_current_order_state>
<_target_order_state />
<_reference_number>SEP-27-0-2</_reference_number>
<_priority>5</_priority>
<_user>oms</_user>
<_process_status/>
<_date_pos_created>2001-10-29T10:31:16 EST</_date_pos_created>
<_requested_delivery_date>2001-10-29T10:30:14 EST</_requested_delivery_date>
<_expected_start_date>2001-10-19T10:30:14 EST</_expected_start_date>
<_expected_duration>P10D</_expected_duration>
<_compl_date_expected>2001-10-29T10:30:14 EST</_compl_date_expected>
<_num_remarks>0</_num_remarks>
<_namespace>OrderAmendment</_namespace>
<_version>1.0</_version>
<customer_phone>4165552121</customer_phone>
<customer_name>Frank Smith</customer_name>
</Orderdata>
</Worklist.Response>
170: Header for mnemonic path not found
400: Not authorized
401: Database connection failed
500: Internal error
601: Deprecated parameter
Note:
See Table 3-3, "Error Code Descriptions" for more information if you receive an error code that is not listed here.Any request can produce warnings as a side effect of accessing the OSM database. The warning element supplies the code and message of any non-fatal warnings that occurred while processing a request. Any changes to the data by the request are still committed. For more information on the cause of the warning codes, consult your Oracle DBA.
Error Codes represent request errors in the XML API that prevent further processing of a request. If an error is returned by a request, data changes are not sent to the database.
Table 3-3 lists the error codes and their descriptions.
Table 3-3 Error Code Descriptions
| Error Code | Description |
|---|---|
|
100: Order type/source not found |
The order type/source does not exist, or is not available to the user. |
|
110: Order not found |
The order does not exist, or is not available to the user. |
|
120: Order template not found |
The order template does not exist, or is not available to the user. |
|
160: Remark not found |
The remark could not be found. |
|
150: Namespace/version not found. |
The namespace or version does not exist or is not available to the user. |
|
152: Invalid namespace mnemonic. |
The order cannot be completed with the given namespace mnemonic. |
|
153: No legacy data found. Namespace and Version need to be supplied. |
Because the legacy data could not be found you must specify a valid Namespace and Version. |
|
170: Header for mnemonic path not found |
The header for a given mnemonic path does not exist, or is not available to the user. |
|
190: Notification not found |
If the notification ID does not exist, is no longer active, or is not assigned to the user ID or user ID's workgroup. |
|
200: Order data invalid |
The format of the order data is not correct. The message details the error location. For example, a message detail, such as: "com.mslv.oms.handler.OrderDataInvalidException: Could not convert input value: value_for_x for field data_field_x", may indicate that value_for_x exceeds the field's acceptable length set in OSM Administrator. |
|
230: Order not accepted by user |
An attempt to update an order was made without first retrieving the order with an Accept parameter of "true". |
|
232: Order update failed |
The order could not be updated due to a data format error. The message details the reason for failure. |
|
250: Mandatory check failed |
A mandatory field was not given a value when attempting to create, assign, complete, or suspend an order. |
|
251: Transition invalid |
The order cannot be transitioned to that state. Use ListStatesNStatuses.Request to get a list of valid states. |
|
252: Unable to accept order |
When retrieving an order for update, the order cannot be accepted by the current user. |
|
253: User not found |
The order cannot be assigned to the given user ID. |
|
254: Invalid state mnemonic |
The order cannot be suspended with the given state mnemonic. Note: Only user-defined states are valid. To complete or assign an order, you must use the appropriate request. |
|
255: Invalid status mnemonic |
The order cannot be completed with the given status mnemonic. |
|
256: Invalid exception status mnemonic |
You used an invalid exception status mnemonic when raising the process exception. |
|
257: Invalid Task Mnemonic |
The supplied task mnemonic could not be found. |
|
260: Remark cannot be modified |
The time interval in which a created remark can be modified has elapsed, or the user trying to change the remark is not the user who created the remark. The remark can no longer be modified. |
|
270: Transaction not allowed |
The requested transaction is not allowed. This error is returned in situations where the transaction has been disabled, or the user or workgroup is not authorized to perform the transaction. It can also be returned when attempting to suspend/resume an order that is already suspended/resumed. |
|
300: Request unknown |
The request type could not be identified from the root element of the XML document of the message. |
|
302: Request parameter error |
A parameter for the request is missing or invalid. The message details the parameter in question. |
|
350: Pivot node data is not provided |
The order cannot proceed because no pivot node is indicated. |
|
351: Process position supplied is not a sub process task. |
The indicated process position is not a sub process task. To add a sub process thread, the order must reside in one of the sub processes. |
|
352: No sub process task is currently pending. |
There are no sub-process tasks to which you can add a thread. |
|
354: Process position not found. |
The indicated process position does not exist or is inaccessible by the order. |
|
355: Pivot node not found. |
The indicated pivot node does not exist or is inaccessible by the order. |
|
356: Cannot spawn threads for sub-process tasks that support sequential sub-processing. |
You cannot add a sub-process thread to a sub-process that supports sequential sub-process. |
|
400: Not authorized |
The user is not authorized to make the request. |
|
401: Database Connection Failed. |
The XML API cannot connect to OSM. |
|
419: The process exception is restricted. |
A process exception cannot be raised, because it is restricted. |
|
420: Not authorized to modify order priority. |
The user does not have the necessary privilege to modify order priority. |
|
500: Internal error. |
An internal application error has occurred. The message details further information. |
|
601: Deprecated parameter |
The parameter identified in the warning details has been deprecated. The details specify an applicable replacement parameter. |
Document Type Definitions are markup declarations that describe the syntax for a class of documents. The DTD is declared within the document type declaration production of the XML file. The markup declarations can be in an external subset (a special kind of external entity), in an internal subset directly within the XML file, or both. The DTD for a document consists of both subsets taken together. The following is a list of the OSM DTDs.
The AddOrderThread XML API is used to implement sub-process creation, (also known as process forking), is implemented by the AddOrderThread XML API.
Note:
AddOrderThread has been deprecated and is supported only for backward compatibility. Use amendment processing functionality instead.<!-- add_order_thread.dtd --> <!ELEMENT AddOrderThread.Request(OrderID, Process, ProcessPosition, View, Add)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Process(#PCDATA)> <!ELEMENT ProcessPosition(#PCDATA)> <!ELEMENT View(#PCDATA)> <!-- The contents of the Add element cannot be described in a dtd Let children := mnemonic for order elements from the template --> <!ELEMENT Add(children+)> <!ATTLIST Add path CDATA #REQUIRED>
<!-- add_order_thread.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT AddOrderThread.Response(warnings?)>
The AssignOrder XML API is used to assign an order.
<!-- assign_order_request.dtd --> <!ELEMENT AssignOrder.Request(OrderID, OrderHistID, User)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT User(#PCDATA)>
<!-- assign_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT AssignOrder.Response(OrderID, OrderHistID, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)>
The CompleteOrder XML API is used to complete an order.
<!-- complete_order_request.dtd --> <!ELEMENT CompleteOrder.Request(OrderID, OrderHistID, Status)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT Status(#PCDATA)>
<!-- complete_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT CompleteOrder.Response(OrderID, OrderHistID, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistIDEMPTY>
The CopyOrder XML API is used to copy an order.
<!-copy_order_request.dtd --> <!ELEMENT CopyOrder.Request(OriginalOrderID, OrderType, OrderSource, Reference, Namespace?, version?)> <!ELEMENT OriginalOrderID(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT Reference(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- copy_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT CopyOrder.Response(OrderID, OrderHistID, OrderSource, OrderType, OrderState, State, Reference, Priority, Warnings?, Namespace, Version)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT OrderState(#PCDATA)> <!ELEMENT State(#PCDATA)> <!ELEMENT Reference(#PCDATA)> <!ELEMENT Priority(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
The CreateOrder XML API is used to create an order.
<!-- create_order_request.dtd -->
<!ELEMENT CreateOrder.Request(OrderSource, OrderType,
Reference, _root, Namespace?, Version?)>
<!ELEMENT OrderSource(#PCDATA)>
<!ELEMENT OrderType(#PCDATA)>
<!ELEMENT Reference(#PCDATA)>
<!ELEMENT Priority(#PCDATA)>
<!-- The contents of the _root element cannot be described in a dtd
Let children := the mnemonics for order elements from the template -->
<!ELEMENT _root(children*)>
<!ELEMENT children(#PCDATA | children*)>
<!ELEMENT Namespace(#PCDATA)>
<!ELEMENT Version(#PCDATA)>
<!-- create_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT CreateOrder.Response(OrderID, OrderHistID, OrderSource, OrderType, OrderState, State, Reference, Priority, Warnings?, Namespace?, Version?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT OrderState(#PCDATA)> <!ELEMENT State(#PCDATA)> <!ELEMENT Reference(#PCDATA)> <!ELEMENT Priority(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
If an error occurs during processing for each of the following request DTDs, the following information is returned.
<!-- error.dtd -->
<!-- let command_name := the command name of the request
that originated the error -->
<!ELEMENT command_name.Error(Error+)>
<!ELEMENT Error(#PCDATA)>
<!ATTLIST Error codeCDATA #REQUIRED>
<!ATTLIST Error descCDATA #REQUIRED>
The GetOrder XML API is used to retrieve an order from OSM.
<!-- get_order_request.dtd --> <!ELEMENT GetOrder.Request(OrderID, (OrderHistID | ViewID))> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT ViewID(#PCDATA)> <!ELEMENT Accept(#PCDATA)>
<!-- get_order_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning;
<!ELEMENT GetOrder.Response(OrderID, (OrderHistID | ViewID,
OrderSource, OrderType, OrderState, State, ExecutionMode,
Reference, Priority, _root, Remarks, Warnings?)>
<!ELEMENT OrderID(#PCDATA)>
<!ELEMENT OrderHistID(#PCDATA)>
<!ELEMENT ViewID(#PCDATA)>
<!ELEMENT OrderSource(#PCDATA)>
<!ELEMENT OrderType(#PCDATA)>
<!ELEMENT Workgroups(#PCDATA)>
<!ELEMENT Workgroup(#PCDATA)>
<!ELEMENT OrderState(#PCDATA)>
<!ELEMENT State(#PCDATA)>
<!ELEMENT ExecutionMode(#PCDATA)>
<!ELEMENT Reference(#PCDATA)>
<!ELEMENT Priority(#PCDATA)>
<!-- The contents of the _root element cannot be described in a dtd
Let children := the mnemonics for order elements from the template -->
<!ELEMENT _root(children*)>
<!ELEMENT children(#PCDATA | children*)>
<!ELEMENT Remarks(Remark*)>
<!ELEMENT Remark(RemarkID, Date, Author, TaskID,
TaskType, OrderHistID, State, Text,
ReadOnly, Attachments)>
<!ELEMENT RemarkID(#PCDATA)>
<!ELEMENT Date(#PCDATA)>
<!ELEMENT Author(#PCDATA)>
<!ELEMENT TaskID(#PCDATA)>
<!ELEMENT TaskType(#PCDATA)>
<!ELEMENT State(#PCDATA)>
<!ELEMENT Text(#PCDATA)>
<!ELEMENT ReadOnly(#PCDATA)>
<!ELEMENT Attachments(Attachment*)>
<!ELEMENT Attachment(AttachmentID, FileName)>
<!ELEMENT AttachmentID(#PCDATA)>
<!ELEMENT FileName(#PCDATA)>
The GetNextOrderAtTask XML API is used to retrieve the next order.
<!-get_next_order_at_task_request.dtd --> <!ELEMENT GetNextOrderAtTask.Request(TaskID, Accept, State+, Namespace?, Version?)> <!ELEMENT TaskID(#PCDATA)> <!ELEMENT Accept(#PCDATA)> <!ELEMENT State(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-get_next_order_at_task_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning;
<!ELEMENT GetNextOrderAtTask.Response((OrderID, OrderHistID, OrderSource,
OrderType, OrderState, State, ExecutionMode, Reference, Priority, _root, Warnings?, Namespace?, Version?) | EMPTY)>
<!ELEMENT OrderID(#PCDATA)>
<!ELEMENT OrderHistID(#PCDATA)>
<!ELEMENT OrderSource(#PCDATA)>
<!ELEMENT OrderType(#PCDATA)>
<!ELEMENT Workgroups(#PCDATA)>
<!ELEMENT Workgroup(#PCDATA)>
<!ELEMENT OrderState(#PCDATA)>
<!ELEMENT State(#PCDATA)>
<!ELEMENT ExecutionMode(#PCDATA)>
<!ELEMENT Reference(#PCDATA)>
<!ELEMENT Priority(#PCDATA)>
<!-- The contents of the _root element cannot be described in a dtd
Let children := the mnemonics for order elements from the template -->
<!ELEMENT _root(children*)>
<!ELEMENT children(#PCDATA | children*)>
<!ELEMENT Namespace(#PCDATA)>
<!ELEMENT Version(#PCDATA)>
The GetOrderDataHistory XML API is used to retrieve order data history for an order.
<!-order_data_history_resquest.dtd --> <!ELEMENT GetOrderDataHistory.Request(OrderID, (OrderHistID | ViewID), Field*)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT ViewID(#PCDATA)> <!ELEMENT FieldEMPTY> <!ATTLIST Field pathCDATA #REQUIRED>
<!-order_data_history_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT GetOrderDataHistory.Response(OrderID, (OrderHistID | ViewID), Field*)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT ViewID(#PCDATA)> <!ELEMENT Field(Change+)> <!ATTLIST Field pathCDATA #REQUIRED> <!ATTLIST Field indexCDATA #REQUIRED> <!ATTLIST Field parentIndexCDATA #REQUIRED> <!ELEMENT Change(#PCDATA | EMPTY)> <!ATTLIST Change action(create | update | delete) #REQUIRED> <!ATTLIST Change userCDATA #REQUIRED> <!ATTLIST Change timeCDATA #REQUIRED>
The GetOrderProcessHistory XML API is used to retrieve the process history for an order.
<!-order_process_history_request.dtd --> <!ELEMENT GetOrderProcessHistory.Request(OrderID)> <!ELEMENT OrderID(#PCDATA)>
<!-order_process_history_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT GetOrderProcessHistory.Response(OrderID, Summary, Transitions)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Summary(ExpectedDuration, ActualDuration, StartDate, CompleteDate)> <!ELEMENT ExpectedDuration(#PCDATA)> <!ELEMENT ActualDuration(#PCDATA)> <!ELEMENT StartDate(#PCDATA)> <!ELEMENT CompleteDate(#PCDATA)> <!ELEMENT Transitions(Transition*)> <!ELEMENT Transition(TaskID, TaskType, TaskDescription, ExpectedDuration, ActualDuration, StartDate, CompleteDate, OrderHistID, FromOrderHistID, State, Status, TransitionType, user, ParentTaskOrderHistID, DataNodeIndex, DataNodeMnemonic, DataNodeValue)> <!ELEMENT TaskID(#PCDATA)> <!ELEMENT TaskType(#PCDATA)> <!ELEMENT TaskDescription(#PCDATA)> <!ELEMENT ExpectedDuration(#PCDATA)> <!ELEMENT ActualDuration(#PCDATA)> <!ELEMENT StartDate(#PCDATA)> <!ELEMENT CompleteDate(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT FromOrderHistID(#PCDATA)> <!ELEMENT State(#PCDATA)> <!ELEMENT Status(#PCDATA)> <!ELEMENT TransitionType(#PCDATA)> <!ELEMENT User(#PCDATA)> <!ELEMENT SubProcessParentTaskOrderHistID(#PCDATA)> <!ELEMENT DataNodeIndex(#PCDATA)> <!ELEMENT DataNodeMnemonic(#PCDATA)> <!ELEMENT DataNodeValue(#PCDATA)>
The GetOrderStateHistory XML API is used to retrieve the order state history for an order.
<!-- get_order_state_history.dtd --> <!ELEMENT GetOrderStateHistory.Request(OrderID)> <!ELEMENT OrderID(#PCDATA)>
<!-- get_order_state_history.dtd --> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderState(#PCDATA)> <!ELEMENT TransitionStartDate(#PCDATA)> <!ELEMENT TransitionCompletedDate(#PCDATA)> <!ELEMENT ActualDuration(#PCDATA)> <!ELEMENT User(#PCDATA)> <!ELEMENT Reason(#PCDATA)>
The GetUserInfo XML API is used to retrieve user information.
<!-user_info_request.dtd --> <!ELEMENT GetUserInfo.RequestEMPTY>
<!-user_info_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT GetUserInfo.Response(User, Workgroup*FlexibleHeaders)> <!ELEMENT User(#PCDATA)> <!ATTLIST User descCDATA #IMPLIED> <!ELEMENT Workgroup(#PCDATA)> <!ATTLIST Workgroup desc CDATA #IMPLIED> <!ELEMENT FlexibleHeaders((FlexibleHeader*)> <!ELEMENT FlexibleHeader(#PCDATA)> <!ATTLIST FlexibleHeader descCDATA #REQUIRED>
The ListExceptions XML API is used to retrieve exceptions.
<!-- list_exceptions_request.dtd --> <!ELEMENT ListExceptions.Request(OrderID, OrderHistID)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)>
<!-- list_exceptions_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning <!ELEMENT ListExceptions.Response(OrderID, OrderHistID, Exceptions, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT Exceptions(Status*)> <!ELEMENT Status(#PCDATA)> <!ATTLIST Status descCDATA #REQUIRED>
The ListStatesNStatuses XML API is used to retrieve the states and statuses.
<!-- task_state_status_request.dtd --> <!ELEMENT ListStatesNStatuses.Request(OrderID, OrderHistID)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)>
<!-task_state_status_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning;
<!ELEMENT ListStatesNStatuses.Response(OrderID, OrderHistID,
TaskStatesNStatuses,
Warnings?)>
<!ELEMENT OrderID(#PCDATA)>
<!ELEMENT OrderHistID(#PCDATA)>
<!ELEMENT TaskStatesNStatuses(Accepted?, Assigned?, Suspend?, Completed?)>
<!ELEMENT AcceptedEMPTY>
<!ELEMENT Assigned(User+)>
<!ELEMENT User(#PCDATA)>
<!-- The content of the Suspend element cannot be described in a dtd
Let userstates := mnemonics for user defined states -->
<!ELEMENT Suspend(userstates+)>
<!-- The content of the Completed element cannot be described in a dtd
Let userstatuses := mnemonics for user defined statuses -->
<!ELEMENT Completed(userstatuses+)>
The ListViews XML API is used to retrieve views.
<!-- views_request.dtd --> <!ELEMENT ListViews.Request(OrderSource, OrderType, Namespace?, Version?)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- views_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT ListViews.Response(OrderSource, OrderType, View*, Warnings?, Namespace?, Version?)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT View(#PCDATA)> <!ATTLIST View desc CDATA #REQUIRED> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
The ModifyRemark XML API is used to modify remarks for an order.
<!-modify_remark_request.dtd --> <!ELEMENT ModifyRemark.Request(OrderID, OrderHistID, RemarkID, Text?, Attachments?, DeleteAttachments?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT RemarkID(#PCDATA)> <!ELEMENT Text(#PCDATA)> <!ELEMENT Attachments(FileName*)> <!ELEMENT FileName(#PCDATA)> <!ELEMENT DeleteAttachments(AttachmentID*)> <!ELEMENT AttachmentID(#PCDATA)>
<!-modify_remark_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT ModifyRemark.Response(Remark?, Warnings?)> <!ELEMENT Remark(RemarkID, Attachment*)> <!ELEMENT RemarkID(#PCDATA)> <!ELEMENT Attachment(AttachmentID, FileName)> <!ELEMENT AttachmentID(#PCDATA)> <!ELEMENT FileName(#PCDATA)>
The OrderTypeNSource XML API is used for the order type and source.
<!-- order_source_type_request.dtd --> <!ELEMENT OrderTypesNSources.RequestEMPTY, Namespace?, Version?> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- order_source_type_request.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT OrderTypesNSources.Response(TypeNSource*, Warnings?, Namespace?, Version?)> <!ELEMENT TypeNSource(Source, Type)> <!ELEMENT SourceEMPTY> <!ATTLIST Source mnemonicCDATA #REQUIRED> <!ATTLIST Source descCDATA #IMPLIED> <!ELEMENT TypeEMPTY> <!ATTLIST Type mnemonicCDATA #REQUIRED> <!ATTLIST Type categoryCDATA #IMPLIED> <!ATTLIST Type descCDATA #IMPLIED> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
The OrderViewTemplate XML API is used for the order view template.
<!-- order_template_request.dtd --> <!ELEMENT OrderViewTemplate.Request((OrderSource, OrderType) | (OrderID, OrderHistID) | (OrderSource, OrderType, ViewID), Namespace?, Version?)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT ViewID(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!--order_template_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning;
<!ELEMENT OrderViewTemplate.Response(((OrderSource, OrderType) |
(OrderID, OrderHistID) | (OrderSource, OrderType, ViewID)),
_root, LookupTables?, Warnings?, Namespace?, Version?)>
<!ELEMENT OrderSource(#PCDATA)>
<!ELEMENT OrderType(#PCDATA)>
<!ELEMENT OrderID(#PCDATA)>
<!ELEMENT OrderHistID(#PCDATA)>
<!ELEMENT ViewID(#PCDATA)>
<!-- The children of _root cannot be described in a dtd.
Let children := the mnemonic of each node in the order template -->
<!ELEMENT _root(children*)>
<!ELEMENT childrenEMPTY>
<!ATTLIST children descCDATA #REQUIRED>
<!ATTLIST children minInstanceCDATA "0">
<!ATTLIST children maxInstanceCDATA "1">
<!ATTLIST children typeCDATA (NM | TX | DT | D | PH | YN | CY | LK) "TX">
<!ATTLIST children readOnly(true | false) "false">
<!-- the mask attribute is only applicable if type = NM or TX and there is a mask defined -->
<!ATTLIST children maskCDATA #IMPLIED>
<!-- the len attribute is only applicable if type = NM or TX and a mask is not defined -->
<!ATTLIST children lenCDATA #IMPLIED>
<!-- The children of LookupTables cannot be described in a dtd.
Let lkchildren := the element name of children[type="LK"]
<!ELEMENT LookupTables(lkchildren+)>
<!ELEMENT lkchildren(option+)>
<!ELEMENT option(#PCDATA)>
<!ATTLIST option descCDATA #REQUIRED>
<!ELEMENT Namespace(#PCDATA)>
<!ELEMENT Version(#PCDATA)>
The Query XML API is used to query an order.
<!-- query_request.dtd --> <!ELEMENT Query.Request(OrderID?, Reference?, Priority? OrderType?, OrderSource?, SingleRow?, TaskID?, CreatedDate?, CompletedDate?, Field*)*, FlexibleHeaders?, Namespace?, Version?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Reference(#PCDATA)> <!ELEMENT Priority(#PCDATA)> <!ELEMENT OrderType(#PCDATA)> <!ELEMENT OrderSource(#PCDATA)> <!ELEMENT SingleRow(#PCDATA)> <!ELEMENT TaskID(#PCDATA)> <!ELEMENT OrderState(#PCDATA)> <!ELEMENT TargetState(#PCDATA)> <!ELEMENT ExecutionMode(#PCDATA)> <!ELEMENT CreatedDateEMPTY> <!ATTLIST CreatedDate fromCDATA #IMPLIED> <!ATTLIST CreatedDate toCDATA #IMPLIED> <!ELEMENT CompletedDateEMPTY> <!ELEMENT CompletedDate fromCDATA #IMPLIED> <!ELEMENT CompletedDate toCDATA #IMPLIED> <!ELEMENT Field(#PCDATA | From, To)> <!ATTLIST Field pathCDATA #REQUIRED> <!ELEMENT From(#PCDATA)> <!ELEMENT To(#PCDATA)> <!ELEMENT FlexibleHeaders(FlexibleHeader*)> <!ELEMENT FlexibleHeader(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- query_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning
<!ELEMENT Query.Response(Header, Orderdata*, Warnings?, Namespace?, Version?)>
<!-- The contents of Header cannot be described in a dtd.
Let children := the mnemonic path of all flexible headers for the user -->
<!ELEMENT Header(_order_seq_id, _order_hist_seq_id,
_date_pos_created, _date_pos_started, _task_id,
_order_type,_order_source, _order_state,
_process_description, _reporting_status,
_reference_number, _priority, _user, _num_remarks, children*)>
<!-- Let headerchild := each of the children of Header -->
<!ELEMENT headerchildEMPTY>
<!ATTLIST headerchild descCDATA #IMPLIED>
<!-- The contents of Orderdata cannot be described in a dtd.
Let orderdatachildren := the mnemonic path of all flexible headers for the user -->
<!ELEMENT Orderdata(_order_seq_id, _order_hist_seq_id,
_date_pos_created, _date_pos_started,
_task_id, _order_type, _order_source,
_order_state, _process_description,
_reporting_status, _reference_number, _user,
_num_remarks,orderdatachildren*)>
<!-- Let ordedatachild := each of the children of Orderdata -->
<!ELEMENT orderdatachild(#PCDATA)>
<!ELEMENT Namespace(#PCDATA)>
<!ELEMENT Version(#PCDATA)>
The ResumeOrder XML API is used to resume an order.
<!-- resume_order_request.dtd --> <!ELEMENT ResumeOrder.Request(OrderID, Reason)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Reason(#PCDATA)>
<!-- resume_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT ResumeOrder.Response(OrderID, Reason, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Reason(#PCDATA)>
The SetException XML API is used to set an exception.
<!-- set_exception_request.dtd --> <!ELEMENT SetException.Request(OrderID, OrderHistID, Status)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT Status(#PCDATA)>
<!-- set_exception_response.dtd --> <!ELEMENT SetException.Response(OrderID, OrderHistID, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)>
The SuspendOrder XML API is used to suspend an order.
<!-- suspend_order_request.dtd --> <!ELEMENT SuspendOrder.Request(OrderID, Reason, OrderHistID, State)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT Reason(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)> <!ELEMENT State(#PCDATA)>
<!-- suspend_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT SuspendOrder.Response(OrderID, OrderHistID, Warnings?)> <!ELEMENT OrderID(#PCDATA)> <!ELEMENT OrderHistID(#PCDATA)>
The TaskDescription XML API is used for the task description.
<!-- task_description_request.dtd --> <!ELEMENT TaskDescription.RequestEMPTY, Namespace?, Version?> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- task_description_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT TaskDescription.Response(Task, Warnings?, Namespace?, Version?)> <!ELEMENT TaskEMPTY> <!ATTLIST Task mnemonicCDATA #REQUIRED> <!ATTLIST Task taskTypeCDATA (automatic | manual | creation | rule | delay) #REQUIRED> <!ATTLIST Task descCDATA #REQUIRED> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
The UpdateOrder XML API is used to update an order.
<!-- update_order_request.dtd -->
<!ELEMENT UpdateOrder.Request(OrderID, ViewID, NewReference?, NewPriority? Add*, Delete*, Update*, AddRemark?)>
<!ELEMENT OrderID(#PCDATA)>
<!ELEMENT OrderHistID(#PCDATA)>
<!ELEMENT NewReference(#PCDATA)>
<!ELEMENT NewPriority(#PCDATA)>
<!-- The contents of the Add element cannot be described in a dtd
Let children := mnemonic for order elements from the template -->
<!ELEMENT Add(children*)>
<!ATTLIST Add pathCDATA #REQUIRED>
<!ELEMENT DeleteEMPTY>
<!ATTLIST Delete pathCDATA #REQUIRED>
<!-- The contents of the Updateelement cannot be described in a dtd
Let children := mnemonic for order elements from the template -->
<!ELEMENT Update(children* | #PCDATA)>
<!ATTLIST Update pathCDATA #REQUIRED>
<!ELEMENT AddRemark(Text, Attachments?)>
<!ELEMENT Text(#PCDATA)>
<!ELEMENT Attachments(FileName*)>
<!ELEMENT FileName(#PCDATA)>
<!-- update_order_response.dtd --> <!ENTITY % warning SYSTEM "warning.dtd"> %warning; <!ELEMENT UpdateOrder.Response(Remark?, Warnings?)> <!ELEMENT Remark(RemarkID, Attachment*)> <!ELEMENT RemarkID(#PCDATA)> <!ELEMENT Attachment(AttachmentID, FileName)> <!ELEMENT AttachmentID(#PCDATA)> <!ELEMENT FileName(#PCDATA)>
The warning DTD is included by all response documents.
<!-- warning.dtd --> <!ELEMENT Warnings(Warning+)> <!ELEMENT Warning(#PCDATA)> <!ATTLIST Warning codeCDATA #REQUIRED> <!ATTLIST Warning descCDATA #REQUIRED>
The Worklist XML API is used for worklists.
<!-- worklist_request.dtd --> <!ELEMENT Worklist.Request(FlexibleHeaders?, Namespace?, Version?)> <!ELEMENT FlexibleHeaders(FlexibleHeader*)> <!ELEMENT FlexibleHeader(#PCDATA)> <!ELEMENT Namespace(#PCDATA)> <!ELEMENT Version(#PCDATA)>
<!-- worklist_response.dtd -->
<!ENTITY % warning SYSTEM "warning.dtd">
%warning;
<!ELEMENT Worklist.Response(Header, OrderData*, Warnings?, Namespace?, Version?)>
<!-- The contents of Header cannot be described in a dtd.
Let children := the mnemonic path of all flexible headers specified in the request -->
<!ELEMENT Header(_order_seq_id, _order_hist_seq_id, _date_pos_created,
_date_pos_started, _task_id, _order_type, _order_source, _order_state,
_execution_mode, _process_description, _current_order_state,
_target_order_state, _reporting_status, _reference_number, _priority,
_user, _num_remarks,children*)>
<!-- Let headerchild := each of the children of Header -->
<!ELEMENT headerchildEMPTY>
<!ATTLIST headerchild descCDATA #IMPLIED>
<!-- The contents of Orderdata cannot be described in a dtd.
Let orderdatachildren := the mnemonic path of all flexible headers specified in the request -->
<!ELEMENT Orderdata(_order_seq_id, _order_hist_seq_id, _date_pos_created,
_date_pos_started, _task_id, _order_type, _order_source, _order_state,
_execution_mode, _process_description,_current_order_state, _target_order_state,
_reporting_status, _reference_number, _priority, _user,_num_remarks,
orderdatachildren*)>
<!-- Let ordedatachild := each of the children of Orderdata -->
<!ELEMENT orderdatachild(#PCDATA)>
<!ELEMENT Namespace(#PCDATA)>
<!ELEMENT Version(#PCDATA)>