[Note: this is not a current document, it is a writing sample from Robert Lauriston's technical writing portfolio.]

Frequently asked questions about ServicePort's XML interface and APIs

Note for Portera internal users only: If your ServicePort security option is login SSL or full SSL, your XML applications must use SSL. If your ServicePort security option is cleartext (no SSL), your XML applications must not use SSL. The XML interface should not be enabled for cleartext subscriber instances.

What can we do with XML?

ServicePort's XML interface is designed for integrating ServicePort with other applications. You can use to pass data about people, client companies, projects, assignments (staff roles), and business groups from ServicePort to other applications, and/or to have other applications pass new or revised data to ServicePort.

The most common use for the XML interface is to integrate ServicePort with accounting and ERP software. Portera is using it internally to integrate ServicePort with hosted Oracle Financials, Human Resources, and Procurement and to provide reporting tools for the optional Project Accounting module..

The XML interface is not designed for reporting. We will be addressing that requirement through the data download capabilities of our new reporting tools and, in a future upgrade, through an optional pivot-table analysis tool.

Why isn't XML working?

By default, XML is disabled. When you have Portera Professional Services enable XML, they set the following three options:.

allow_xml=yes
allowed_xml_clients=[IP address or range];[IP address or range];...
max_xml_failures=[number of allowed failures]

allow_xml=yes enables XML.

allowed_xml_clients controls which computers will be allowed to access the XML interface. If a client computer's IP address is not within one of the specified ranges, it will not be allowed to initiate an XML transaction. For example, if the specified range is 10.*.*.*, an attempt to perform an XML transaction from a client with the IP address 192.168.0.1 will fail.

max_xml_failures controls how many successive failed attempts to initiate an XML transaction ServicePort will allow before sending an e-mail warning to the system administrator of a possible security violation and disabling XML. Failures can be caused by use of a nonexistent login or the wrong password, attempting to access data the user does not have the necessary security privileges to view or edit, and XML syntax errors. If you accidentally exceed the failure limit, contact Professional Services to re-enable XML.

How can we avoid failures due to inadequate security privileges?

The login used by an XML application must have all the security privileges required to view (and, if updating, edit) the data the application will access. You must either write your XML applications carefully to stay within specified security privileges, or have the XML application log on as a system administrator (Cybrarian). For additional information on security privileges, see the ServicePort 5.0 User Guide (go to Help / Help in ServicePort).

What parser does Portera use?

IBM's XML Parser for Java (com.ibm.xml.parser).

Does Portera have any sample code?

We have created two sample applications to help you get started: a Java HTTP client (text file) and a Visual Basic data-import utility (Excel spreadsheet).

Does Portera have a client-side library?

No. The Java sample application uses a freeware client library from Innovation GmbH.

Where can I find the DTD?

You can view ServicePort's Document Type Definition (DTD) by logging on to ServicePort and pointing your browser to html://host/company_name/DTD/Portera.dtd (where host and company_name are the same as the first two parts of your ServicePort URL).

Which ServicePort fields are accessible through XML?

Most fields relating to people, clients, projects, assignments (staff roles), and business groups are accessible through HTML. See the DTD for details.

Are XML field names the same as the corresponding ServicePort fields?

With the following exceptions, field names are similar enough that the correspondence should be clear.

XML field name	ServicePort field name	Comments
Person / code	Person Info / Emp Number
Person / assFirstName & assLastName	Person Info / Assistant	ServicePort automatically splits the Assistant field into first and last name fields in an XML Person entity.
Person / typeCode	Person Info / User Type
Person / staffroleCode	Person Info / Std Role
Assignment / code		ServicePort automatically assigns a unique ID number to each XML Assignment entity. This number does not appear on the corresponding Role Info page in ServicePort.
Assignment / nameTag	Role Info / Resource Name
Person Access / code	Person Info / Emp Number

Last updated 10/19/00. Thanks in advance for any feedback or corrections you wish to submit.