xLink Resource Center



FAQs

These FAQs cover five areas: general issues, service availability, order entry, order status, and order summary.

General Issues

Service Availability

Order Entry

Order Status

Order Summary

GENERAL FAQs

What is the Global Capacity xLink API?

The Global Capacity xLink API is an interface which partners can use to send common business requests to Global Capacity 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 Global Capacity's, thereby producing considerable time and cost savings.
top

What does Global Capacity's xLink API do?

The Global Capacity xLink API allows ISPs, resellers, and Corporate customers to integrate their internal systems with the Global Capacity’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.

  • The Global Capacity xLink API provides a standard mechanism for business-to-business communication. Global Capacity xLink allows Customers to seamlessly integrate their internal systems with those of Global Capacity. This allows for integration of business processes, which results in greater efficiency in conducting business.
  • You can use the API to develop customized systems to process orders from your clients and electronically interact with Global Capacity's OSS to qualify, place, and track those orders.

top

What can we do with the xLink API?

Here are a few examples of how you can use the API:

  • You can create extensions to your own internal systems to interface with Global Capacity's Operations Support Systems.
  • You can "batch" your orders and submit them to Global Capacity in bulk. This lets you process orders in a group, on a regular basis.
  • You can perform your own validation and screening, for example to verify credit card or other business information, before Global Capacity qualifies the order.
  • Use can use the API as an alternative to the manual entry of orders, which is tedious and error-prone. A machine-to-machine interface provides higher repeatability, reliability, and throughput.
  • You can submit order-related problems to Global Capacity using the Trouble Ticket API: ticketentryrequest.mod.

top

What benefits will we experience by using the Global Capacity xLink API?

  • Reliability: Global Capacity's xLink API is a machine-to-machine interface, which improves reliability of data transfer. By automating repeatable processes, you can eliminate manual intervention of data transfer especially during pre-qualification, order entry, order status inquiry, and Trouble Ticketing.
  • Business Process Integration: xLink API allows Global Capacity and you to build flow-through ordering systems.
  • Performance: The system architecture is scalable and highly available.
  • Extensibility: Global Capacity can add new modules to the existing infrastructure according to business and partner neeeds.
  • Protection of Investment: Both Global Capacity and you can leverage the same infrastructure for future extensions.
  • Ease of Use: There are many off-the-shelf xml development tools you can use to make use of the xLink API.
  • Adherence to standards: The interface is based on W3C standard XML (www.w3c.org). It is fully compliant with the standard specification, enabling you to use numerous off-the-shelf tools (most freely downloadable) to build your interface system.

top

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 Global Capacity xLink API network member, you can begin developing or enhancing your programs that will work with the Global Capacity xLink API specification (http://connect.globalcapacity.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://connectuat.globalcapacity.com/api. 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 Global Capacity account manager and request access to the production server. Please provide a contact person (first and last name and e-mail address) whom we can contact with questions or if problems arise with your interactions with the API. 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.

top

What application interfaces does the xLink API support?

Currently, the Global Capacity xLink API supports the following interfaces:

  • Service Availability - Use this interface to request a list of qualified services available at a given location. The request you submit must contain the address and telephone of the end-user site, and the response contains the various qualified services and the corresponding central office information. The response will contain error infomation if the system cannot process your request.
  • Order Entry - Use this interface to order Global Capacity service for a qualified location. We strongly recommend that you first make a serviceavailability request to prequalify a location before you submit an order entry request.
  • Order Status - Use this interface to obtain the status of orders you previously submitted to Global Capacity. Your request can refer to the order's confirmation number, various date ranges, or for orders in a particular state within their lifecycle.
  • Order Summary - Use this interface to receive a high level view of orders you have submitted to Global Capacity. You can request an order summary based on the various order states or date ranges.
  • Order Modification: - Use this interface to modify the request before Global Capacity has provisioned the service. After provisioning, you must submit a Service Change order to change the customer's service.
  • Order Cancellation: - Use this interface to cancel orders before Global Capacity has provisioned the service. After provisioning, you must submit a Service Disconnect order to terminate the customer's service.
  • Service Change: - Use this interface to change the service after Global Capacity has provisioned it at the client premises.
  • Service Disconnect: - Use this interface to disconnect a functioning service.
  • Network Weather Report: - Use this interface to learn the state of the network on Global Capacity circuits.
  • CPE Lookup: - Use this interface to identify the kinds of Client Premises Equipment (CPE) that are available for the type of service you specify in your request.
  • BackhaulLoop Lookup: - Use this interface to learn the available backhaul circuits for the service address.

top

How do I obtain access to the production server?

After you have successfully tested your system against our testbed, please inform your account team and request access to the production system. Please provide a contact person (first and last name, e-mail address, and a team or title reference) an example of a successful request and response for each type of request you are submitting. This is so that we can confirm that you are submitting your request successfully and getting back the expected response. Most partners start with the serviceavailabilityrequest module and then move on to the orderentryrequest and orderstatusrequest modules, followed by the covadcircuitstatusrequest module. Your account team can tell you about other modules that you might find useful, depending on your business needs.

You may wish to use the same login for both test and production sites but it is better to use two different logins--if you need to send us xml for analysis, you should remove your password from it but leaving in the login will help us identify the environment. In any case, you must use different passwords. This will prevent you accidently submitting xml to the wrong system.

top

How does the Global Capacity xLink API work?

The Global Capacity xLink API is an HTTP-based interface to which you, as a Global Capacity 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://connect.globalcapacity.com/api. In the URL connection, you must pass an HTTP variable called 'request' whose value is the request message you are sending to Global Capacity. The request message must conform to Global Capacity's Markup Language (http://connect.globalcapacity.com/dtd/request.dtd). The Global Capacity xLink API server responds to your request within a few seconds, returning information in XML format (http://connect.globalcapacity.com/dtd/response.dtd). You can read the supporting DTDs for the xLink API at http://connect.globalcapacity.com/dtd/.

top

Where can I learn more about XML?

Here are two good reference sites.

1. Extensible Markup Language (XML):
http://www.w3.org/TR/1998/REC-xml-19980210.html

2. O'Reilly's XML site:
http://www.xml.com/

top


What is the format of the HTTP 'request'?

This is how to send a request to xLink:

1. Open a secure socket to either the test or production site

Test: connectuat.globalcapacity.com:443

- or -

Production: connect.globalcapacity.com:443

2. Send an HTTP request like this one:


POST /api HTTP/1.0
Content-Type: text/xml
User-Agent: xLinkClient
Content-length: 544

<?xml version="1.0" standalone="no"?>
<!DOCTYPE request SYSTEM "http://connect.globalcapacity.com/dtd/request.dtd">
<request>
<header>
<sender>
<key>
<login>PUT YOUR LOGIN ID HERE</login>
<password>PUT YOUR PASSWORD HERE</password>
</key>
</sender>
</header>
<body>
<subrequest type="serviceavailability">
<serviceavailabilityrequest>
<address>
<street1>1016 Asbury Way</street1>
<city>Mountain View</city>
<state>CA</state>
<zip>94043</zip>
</address>
</serviceavailabilityrequest>
</subrequest>
</body>
</request>


A breakdown of the HTTP request format:

Line 1 lists the action, resource and protocol.
You'll use the same first line for your own requests.


Line 2 specifies the Content-type. Our server supports various formats, but text/xml is the easiest for posting XML.


Line 3 specifies the User-agent. This should be the name of your client program.


Line 4 indicates Content-length. This is the number of bytes in your content (XML request), not including these header lines. It is very important to get this number right.


Line 5 is a blank line. This marks the end of the header. The actual content of your request, meaning the XML, begins with the next line. The Content-length must be the number of bytes following the blank line (end-of-header). This number must be accurate.


3. Read from the socket until end-of-file. You'll receive something like this:


HTTP/1.0 200 OK
Server: WebLogic 4.0.4 08/31/1999 16:41:16 #51196 - internal build by br on client br.santiago
Content-Type: text/xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE response SYSTEM "http://connect.globalcapacity.com/dtd/response.dtd" >

[Additional xml will follow according to your request...]


Line 1 states the protocol version, response code, and response string.

Line 2 gives you the server information.

Line 3 states the return content type.

Line 4 is a blank line, followed by content (the XML response).

top

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:

HTTP/1.0 200 OK

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.

Error Group

Error Code

Error Phrase

2xx Successful

200

OK

201

Created

202

Accepted

204

No Content

3xx Redirection

301

Moved Permanently

302

Found (moved temporarily)

304

Not Modified

4xx Client Errors

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

5xx Server Error

500

Internal Server Error

501

Not Implemented

502

Bad Gateway

503

Service Unavailable

Service Availability FAQ

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.

top

How do I check for service availability?

You can determine what services are available by submitting one of the following:

  1. vendorordernumber
  2. covadcircuitnumber
  3. serviceaddress

The next three FAQs discuss each of these methods.

top

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.

top

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.

top

What does type='orderable' signify?

When you submit a serviceavailability request xml with the attribute type set to 'orderable', Global Capacity returns all the orderable DSL services and circuits in the response xml. Before submitting an order to Global Capacity, 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.

top

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 Global Capacity 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.

top

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:

<service id="5"/>

You should use 'service' when you submit an orderentryrequest.

You can find the 'id' of the service element in the services.txt 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.

top

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.

top

When I post a serviceavailability request, why don't I see linesharing in the list of services?

Please contact your Global Capacity account team to confirm that your profile is able to order lineshare services.

top

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.

top

When I check serviceavailability on the production site connect.globalcapacity.com, the results do not match what I get when using connectuat.globalcapacity.com. Why?

Data on the test server is deliberately not in sync with data on the production server, and so serviceavailability results will vary between the two. Testbed data is more static in nature, and furthermore the system performs the more advanced geodata functions only in the production environment. Use the 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.

top

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.

top

Is there a region and zone cross-reference table?

The cross-reference table is located on the xLink site's Products and Services page.

top

Order Entry FAQ

How do I submit an order to Global Capacity?

The xLink system lets you submit orders electronically to Global Capacity using the Order Entry API. Simply post an orderentryrequest xml with an orderentryinformation element and the action set to 'submit'.

top

What is the difference between 'save', 'submit', and 'test' actions?

The action element defines the type of order you want to submit to Global Capacity. To submit new service orders you must 'submit' an order. Here are details about each action type:

  1. 'save': You can post an orderentryrequest request xml with action set to 'save' if you wish to create an order for later processing. You should submit this type of request when you do not have all the required information to submit a complete order with Global Capacity.
  2. 'submit': To submit a new service order to Global Capacity, post an orderentryrequest with action='submit'. You must also provide "serviceaddress", "clientcontactinformation", "service", "cpe", "customercircuit", "clientsitedetails", and "networkconfiguration" information.
  3. 'test': An orderentryrequest with action='test' instructs the system to check the order's parameters for consistency and validity.

top

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.

top

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.
top

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.

top

How will I know that Global Capacity's system has accepted my order successfully?

The orderentry response xml will contain a transaction 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.

top

Can we submit a Layer 2 order without a customer circuit id?

No, you must specify a backhaul when you submit an order for any Layer 2 service. You may optionally specify a PVC, but if you do not then we will pick one for you.

top

Do you support international telephone number formats in the contact information data?

Currently we do not support international telephone number formats.

top

Where can I learn about the CPEs you support?

You will find information about CPEs and networking protocols in cpemodelid-enum.pen.

top

What additional information do we need to provide when ordering linesharing?

You must specify the appropriate service id in the orderentryrequest element. Please consult with your Global Capacity account team to determine which ones you are able to order.

Specific details of line sharing should be provided in the clientsitedetails element:

numberofdevicesonline: A maximum of five devices can share a line. The default value is '1'.
specialdevicesonline: You must indicate if there are any special devices on the line. The default value is 'no'.
alarmonline: You should set this attribute to 'yes' if the customer would like to share the line with a house alarm. The default value is 'no'.
tddonline: You should set this attribute to 'yes' if the customer would like to share the line with a TDD device. The default value is 'no'.

top

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:

  1. When you are requesting a serviceavailability response for a specific address, submit a service availability request of type='orderable'. This will return all the available services and their corresponding backhaul circuit ids.

    or

  2. You can also submit a backhaulcircuitlookup request to retrieve all your available backhauls and their status and region of coverage.

top

Is assignedpvc only used when we request a particular VPI/VCI and Global Capacity overrides that request and assigns another VPI/VCI?

Global Capacity uses assignedpvc. When you submit an order you must include the requestedpvc value. Global Capacity checks the validity and sets it as the assignedpvc. If you do not submit a requestedpvc value, Global Capacity assigns a PVC value (assignedpvc), which you can retrieve by submitting an orderstatusrequest request xml with its details attribute set to full or fulllog. See the networkconfiguration.mod file for more information.

top

Order Status FAQ

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 Global Capacity. 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
2. bymilestone &mdash for a batch of orders that have reached a certain milestone such as linecommitted
3. byactiondate &mdash to specify the actiontype attribute to qualify the actiondate. The timeframe can either be in the form of 'daysback', 'monthsback' or a range of dates (fromdate and todate).
4. byfield &mdash for a particular billingcode. This criterion is very useful if you have affiliates in your program.


You need to specify the type of order detail basic, full or fulllog you are requesting in the 'details' attribute.

top

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

top

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.

top

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.

top

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 within 48 hours, though we will do our best to respond the same day. 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 or made ready to have change orders placed on them, please submit no more than five orders.

top

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.

top

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.

top

Order Summary FAQ

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:

  • bymilestone
  • byactiondate

Updated 29 Jan 2015



Copyright © 2017 Global Capacity. All rights reserved.