Order Entry
Order Status
Order Summary
|
|||||||||||||||||||||||||||||||||||||
|
GENERAL FAQs |
|||||||||||||||||||||||||||||||||||||
|
Q: What is the Covad xLink API?
The Covad xLink API is an interface which partners can use to send common business requests to Covad such as service pre-qualification, order entry, and order status tracking. These functions behave just as if you used the Customer Care Center to perform these functions. The advantage of the xLink API is that you can directly integrate your order management systems with Covad's, thereby producing considerable time and cost savings.
Q: What does Covad's xLink API do? The Covad xLink allows ISPs, resellers, and Corporate customers to integrate their internal systems with the CovadŐs Ordering system. This allows for seamless flow through of orders and order status between the two, otherwise disjoint systems. As the number of Internet users grows, the need for a high volume ordering system becomes apparent. It is no longer practical to order large volumes of services through an interactive system.
Q: What can we do with the xLink API?
Here are a few examples of how you can use the API:
Q: What benefits will we experience by using the Covad xLink API?
Q: How can we start using the xLink API? Once you have signed the necessary contractual agrrements and your account team has set you up as a registered Covad xLink API network member, you can begin developing or enhancing your programs that will work with the Covad xLink
API specification (http://xapi.covad.com/dtd/). Specifically you will need to
develop programs that will send in a request, and receive and process the API's response. When you are ready to test your system, your will submit sample requests to our xLink API server testbed
site at http://xapi-test.covad.com/servlet/MainVCAServlet. To start, you can submit the sample scenario xml requests we provide and process the corresponding responses. The responses must correspond to the ones provided on the website. Once you have tested all of the listed sample requests successfully, you may talk to your Covad account manager and request access to the production server. Please provide a contact person (first and last name and e-mail address), your desired login (usually containing a reference to xapi in it) and your preferred password. When you eventually move to production, you may wish to use the same login for both test and production sites, but you must use different passwords. This will prevent you accidently submitting xml to the wrong system.
Q: What application interfaces does the xLink API support? Currently, the Covad xLink API
supports the following interfaces:
Q: How do I obtain access to the production server?
After you have successfully tested your system against xapi-test.covad.com, inform your account team and request access to the production system. Please provide a contact person (first and last name and e-mail address), your desired login (usually containing a reference to xapi in it) and your preferred password. You may wish to use the same login for both test and production sites, but you must use different passwords. This will prevent you accidently submitting xml to the wrong system.
Q: How does the Covad xLink API work? The Covad xLink
API is an HTTP-based interface to which you, as a Covad partner, can directly
connect and provide business information. The system you create to handle your business processes makes an
HTTP connection to the xLink API, http://xapi.covad.com/servlet/MainVCAServlet. In the URL connection, you must pass an HTTP variable called 'request' whose value is the request message you are sending to Covad. The request message must conform to Covad's Markup Language (http://xapi.covad.com/dtd/request.dtd). The Covad xLink API
server responds to your request within a few seconds, returning information in XML format (http://xapi.covad.com/dtd/response.dtd). You can read the supporting DTDs for the xLink API at http://xapi.covad.com/dtd/. Q: Where can I learn more about XML? Here are three good reference sites. 2. O'Reilly's XML
site: 3.
IBM's XML Resource Center:
top
This is how to send a request to xLink: Test: xapi-test.covad.com:80 2. Send an HTTP request like this one:
Line 1 lists the action, resource and protocol.
Line 1 states the protocol version, response code, and response string.
Q: What are the different HTTP status codes I can expect? HTTP Status codes tell you whether your POST to the server was successful or unsuccessful. It appears on the very first line of the response:
The Reason-Phrase is gives you a short textual description of the Status-Code. Automata usually parse the Status-Code while people usually find the Reason-Phrase most informative. The first digit of the Status-Code defines the class of response. The last two digits do not have any categorization role. Some common status codes appears below, but please refer to the relevant RFC 2616 for a complete list.
|
|||||||||||||||||||||||||||||||||||||
|
Q: What is the Service Availability API? This is a subrequest that lets you automate the end-user service qualification process. The Service Availability API checks if a given service address qualifies for DSL service. If so, the services brands and the API returns their available dates in the response XML. Q: How do I check for service availability? You can determine what services are available by submitting one of the following:
The next
three FAQs discuss each of these methods. Q: How do I check for service availability using vendorordernumber? If you wish to determine what services are available for an order in progress, you
can post a serviceavailability request xml with the bynumber element and set the id
to the vendorordernumber. You might do this if, for example, the customer wants to increase the speed of their connection right after they placed their order. Q: How do I check for service availability using covadcircuitnumber? If an order is already in service and you want to know how it could be upgraded, you can post a serviceavailability request xml with the covadcircuitnumber element. You would want to perform this type of request before placing a service change order to confirm that the circuit can support the new service brand. Q: What does type='orderable' signify? When you submit a serviceavailability request xml with the attribute type set to 'orderable', Covad returns all the orderable DSL services and circuits in the response xml. Before submitting an order to Covad, you should post an orderable serviceavailability request xml to retrieve a list of valid services and circuits. You might notice fewer services returned, when you post a request xml of this type. Q: When I post a service availability request of type='orderable', the response xml does not contain any services. When I post without including the type orderable, the response xml returns services. Why? When you submit a serviceavailability request without specifying orderable services, the API returns all services that Covad can provide at that service location. However, when you submit a service availability request of type='orderable', the API will return only services that your backhaul circuits support. If you have no backhauls to support service, the API will therefore return no services at all. Please contact your account team to set up your backhauls.
Q: When should I use the 'service' element and when should I use 'dslservice'? serviceavailabilityresponse uses the dslservice element to represent a qualified service. dslservice has more details than the service element which only has an id:
The 'id' of the service element is an enumerated value. You can obtain the valid values from
the dslserviceid_enum.pen file. The contractid is the number of years the customer has signed for a DSL service agreement.
Note that you can use either service or dslservice when submitting an order, but dslservice requires that you submit a number of mandatory subelements, mandatory as required by the DTD definition but otherwise not relevant to the order.
Q: When should I specify a CPE? CPE means "Client Premises Equipment" and is the DSL modem or other equipment that permits the customer's computer(s) to access the Internet over the copper loop. CPEID is an enumerated value. See cpemodelid-enum.pen or consult the Xlink Resource Guide for more information. If you specify a cpeid in a serviceavailability request, the API's response will contain only services that are compatible with that CPE.
Q: When I post a serviceavailability request, why don't I see linesharing in the list of services? Currently linesharing service is available to a few selected xLink partners only. If you wish to be enabled for this, please contact your Covad account team.
Q: I would like to test linesharing service. Can you please provide me with sample addresses? These addresses
should give you full DSL service qualification: 1) All Central Office
addresses and corresponding phone numbers. 2) Central Offices
addresses and corresponding phone numbers enabled for LINESHARING.
Q: When I check serviceavailability on the production site xapi.covad.com, the results do not match what I get when using xapi-test.covad.com. Why? Data on the test server xapi-test is deliberately not in sync with data on the production server, and so serviceavailability results will vary between the two. The xapi-test data is more static in nature, and furthermore the system performs the more advanced geodata functions only in the production environment. Use the xapi-test environment to confirm that you can send and receive responses and can parse them properly, but do not use the response's actual content for business decisions.
Q: How can I retrieve a list of all backhauls assigned to us? To retrieve all
the backhauls assigned to you, use the backhaullookuprequest API. You can retrieve all the circuits if you submit a backhaullookuprequest with no elements. You can also retrieve circuits according to particular criteria: bycentraloffice, byregion, byzone, bynumber, or all national circuits.
Q: Is there a region and zone cross-reference table? The
cross-reference table is located on the xLink site's Products and Services page. |
|||||||||||||||||||||||||||||||||||||
|
Q: How do I submit an order to Covad? The xLink system lets you submit orders electronically to Covad using the Order Entry API. Simply post an orderentryrequest xml with an orderentryinformation element and the action set to 'submit'.
Q: What is the difference between 'save', 'submit', and 'test' actions? The action element defines the type of order you want to submit to Covad. To submit new service orders you must 'submit' an order. Here are details about each action type:
Q: When submitting an order, which elements are required and which elements are optional? The elements and values that are needed for creating a new service are listed in the orderentryrequest DTD.
Q: What is the significance of billingcode? This is the billing code of the service user. We provide this element for your own use, which is completely optional. You may use this element to pass client billing order id, department code for tracking your order internally, or some other number for your own purposes.
Q: Which element should I use to submit an order: service or dslservice?
You should use the service element to submit an order. dslservice element is used in the serviceavailabilityresponse element to represent a qualified service to you. It has more details such as servicebrandname, downstreamlimit, upstreamlimit, and others which are not required when you submit an order. If you used dslservice, you would have to include them, so it is best for you to use the simpler service element.
Q: How will I know that Covad's system has accepted my order successfully?
The orderentry response xml will contain a transcation code 2000 as well as vendorordernumber and covadcircuitnumber elements. You can later submit an orderstatus request xml to retrieve the status of the order or manually check the order using the Connect website.
Q: Is it possible to submit an order without the customer circuit id?
The API requires you so include the customer circuit id or backhaulcircuit id when you submit an order for all services except Telesurfer Anywhere DSL+IP (29) service.
Q: Do you support international telephone number formats in the contact information data?
Currently we do not support international telephone number formats. However, we may support this feature in a future release of the API. If you would find this feature useful, please inform your account team. Q: Which operating systems and CPEs do the DTDs support? You will find information about CPEs and the networking protocols they support in cpemodelid-enum.pen and you will find operating system information in operatingsystem-enum.pen
Q: What additional information do we need to provide when ordering linesharing? To order linesharing services, the service id in the orderentryrequest should be one of
the following 24 (TeleSurfer)
These service brands are compatible with ENI SpeedStream 5260 [21], the ADSL - DMT Compatible CPE [30], the ZyXEL 643 ADSL Gateway [31], and the ZyXEL 645M [34] CPE models only. You must therefore provide either of those ids in the cpe element (cpemodelid-enum.pen). Note: CPE ID 30 is a generic placeholder CPE that Covad uses for self-install & professional-install orders. The install order will be updated with the actual CPE shipped after kit shipment. Specific details of line sharing should be provided in the clientsitedetails element:
Q: In which API do we specify the backhaul circuit information? You should specify the backhaul circuit id when you submit an orderentry request. It is referred in the orderentryinformation element as customercircuit element. You can obtain the backhaulcircuit id value using one of the following methods:
Q: Is assignedpvc only used when we request a particular VPI/VCI and Covad overrides that request and assigns another VPI/VCI?
|
|||||||||||||||||||||||||||||||||||||
|
Q: When should I use the Order Status API? You will need to
use the Order Status Request to make an inquiry into the status of orders
submitted to Covad. The main element that needs to be populated for
submitting an order status request is orderstatusrequest. You can check the
status of one or more orders according to several criteria: 1. bynumber &mdash for an
individual order
Q: What are the transaction codes related to the Order Status API? The following are
the transaction codes related to order status API 3000: Success 3002: No Results 3101: Missing
information 3303: Status
unavailable Q: Is it possible for me to retrieve orders whose status has been recently updated? You can submit an
orderstatusrequest request xml with byactiondate element. You can set the
value of actiontype attribute to orderupdated for a given range of time. The
response xml will return all order that have been updated in the requested
date range. The other possible values you can check for status are listed in osrbyactiondate-enum.pen.
Q: What is the difference between basic, full, and fulllog details? You can submit an
orderstatusrequest request xml with details set to the following: basic returns general information such as lastmilestone and dates for major milestones full returns all the specific details of an order such as the dates the milestones were updated, assignedpvc, etc. fulllog returns the specific detail and the worklog information for an order. Please note that you
need to submit an orderstatusrequest request xml with detail set to basic to
retrieve the lastmilestone element.
Q: I am trying to test the Order Status interface. How do I move some orders to different milestones? You need to submit
a request to xLink-support with a list of orders and their new statuses. We will
update the order statuses for you. Please limit your list to no more than 20 orders per
day for either cancellations or "Closed (In-Service)" requests. If you need orders moved to other states, please submit no more than five orders. Q: How do I access
the worklog information for an order? You can access the
worklog information by posting an orderentryrequest request xml with the
details attribute set to "fulllog". A sample xml for this type of request is
available in the usecases. Q: Could you give me a listing of all possible values for the STATUS field when an order is pulled up, so that we can trigger a particular response for any given status? Status field is a text field. Click here for the list
of possible values. |
|||||||||||||||||||||||||||||||||||||
|
Q: How does the Order Summary xLink API work? Use this interface to obtain high level summary information about orders that satisfy one of the input criteria:
|
Updated 3 Jan 2006
