]po[ SOAP::Lite Server

The ]po[ SOAP::Lite package implements a light-weight SOAP server, allowing external systems to modify ]po[ objects in a standard and interoperable way.

 

API Overview

The package implements for each business object the following operations:

  • Create - Create a new object of the specified object type
  • Update - Update the values of an existing object and
  • Select - Get a list of business objects satisfying a specific condition.

 

Technical Implementation

The core of the "intranet-soap-lite-server" package is written in Perl using the SOAP::Lite package, using explicitly typed return variables, allowing for interoperability with Java Axis and .Net.

Two main characteristics have shaped the definition of the Web Service:

  • ]project-open[ DynField architecture allows for adding new fields to objects at runtime. So we won't be able to pass a fixed number of parameters in each call. Instead, the available and required fields can depend on the customer's particular ]po[configuration and

  • ]project-open[ defines a large number (>50) of object types that all need to be exposed via the Web Service client. However, the CRUD (Create, Update, Delete) operations on these objects are very similar.

 

Generic Operations

For these reasons we have decided to use a generic Web Service protocol that only consists of four methods:

  • authenticate(userId, password) -> authToken or fault
  • objectCreate(authToken, objectType, varList) -> objectId or fault
  • objectUpdate(authToken, objectId, varList) -> objectId or fault
  • objectSelect(authToken, objectType, varList) -> objectIdList or fault

 

The VarList Data Structure

In order to deal with the generic parameter passing, we define a SOAP complex data type "varList" consisting of a list of key-type-value tuples:

  • Key: The name of the variable. This must correspond to field names of the object's database table.
  • Type: One of {integer, string, date, timestamptz} (SQL database types)
  • Value: The value of the given type, encoded as a string.

]project-open[ will check the varList at runtime for correctness and completeness:

  • objectCreate:
    In order to create a new object, ]po[ requires a number of variables to be present in the varList and will return a SOAP "fault" otherwise.
    On the other hand ]po[ will match additional variables with the available fields and return a fault if the varList contains an unknown variable.

  • objectUpdate:
    ]po[ will update the included variables and return a fault if one of the variables doesn't exist with the object.

 

Example

For example, in order to create a new project, we will pass ]po[ the following varList to the call "objectCreate(authToken, 'im_project', varList):

  • project_name: string: "First Project"
  • project_nr: string: "first_project"
  • project_path: string: "first_project"
  • parent_id: integer: null
  • company_id: integer: 8720 (corresponding to the company "Tigerpond" in the demo configuration)
  • project_type_id: integer: 2501 (corresponds to "Consulting Project")
  • project_status_id: integer: 76 (corresponds to status "Open")

]po[ will return a SOAP fault if one of these variables is not in the varList, or the type of the variable doesn't comply with the expected type.

 

Available Object Types and Their Parameters 


The following table includes some examples for object types:

  • Object Type contains the "pretty name" of the object type and in parenthesis the ]po[ "internal" name of the object type.
  • ]po[ Object Type is the system name for the object type. This is the string that needs to be passed as part of the SOAP call.
  • Required Parameters for objectCreate: You need to pass these parameters to an objectCreate call, otherwise it will produce a SOAP "fault".
  • Optional Parameters: These are additional parameters that may be passed to an objectCreate call.
Both required and optional parameters can be passed on to an objectUpdate call.

 

Object Type Required Parameters
for objectCreate
Optional Parameters
Project (im_project) project_name, project_nr, project_path, parent_id, company_id, project_type_id, project_status_id description, end_date, expected_quality_id, milestone_p, note, on_track_status_id, percent_completed, project_budget, project_budget_currency, project_budget_hours, project_lead_id, source_language_id, start_date, subject_area_id, supervisor_id, team_size, template_p
 Company (im_company) company_name, company_path, main_office_id, company_type_id, company_status_id

accounting_contact_id, annual_revenue_id, billable_p, business_sector_id, company_group_id, contract_value, default_bill_template_id, default_delnote_template_id, default_invoice_template_id, default_payment_days, default_payment_method_id, default_po_template_id, default_quote_template_id, default_vat, invoice_template_id, manager_id, note, payment_days, payment_method_id, primary_contact_id, referral_source, site_concept, start_date, vat_number
 Office
(im_office)
office_name, office_path, office_type_id, office_status_id, company_id
address_city, address_country_code, address_line1, address_line2, address_postal_code, address_state, contact_person_id, fax, landlord, note, phone
     

A WSDL description of the service will be available in the future.

 

References

  • DynFields - The SQL metadata system that allows extending ]po[ objects at runtime
  • Object Types - The list of all available ]po[ object types and their fields.


  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

E-08907 Hospitalet de Llobregat (Barcelona)

 Tel Europe: +34 932 202 088
 Tel US: +1 415 429 5995
 Mail: info@project-open.com