Making SOAP Calls

The SOAP API is an object-oriented interface.

• You pass in an array of OpenAir Complex Type objects as a parameter. An error will be returned if the array contains more than 1000 objects.

  Note:

  You create a complex type object with the NSOA.record.<complex type>( [id] ) function. For the list of supported object types, see XML and SOAP API Business Object Reference.

• Some functions also require an array of Attribute objects as the first parameter.

• Functions return either an object or array of objects:

  • NSOA.record.<complex type>( [id] ) returns an OpenAir Complex Type object.

  • NSOA.wsapi.read(readRequest) returns an array of ReadResult objects.

  • NSOA.wsapi.add(objects), NSOA.wsapi.delete(objects), NSOA.wsapi.modify(attributes, objects), and NSOA.wsapi.upsert(attributes,objects) return an array of UpdateResult objects.

Important:

The updated and created fields are maintained automatically by OpenAir. You can read these values, but they cannot be modified.

Tip:

It is more efficient to batch a series of objects together into a single SOAP API call rather than making a separate call for each object. The objects in the array are processed according to their order in the array.

Adding data

You add data to OpenAir by creating one or more OpenAir Complex Type objects, placing them into an array, and passing the array to the NSOA.wsapi.add(objects) function. You must specify all the required fields for the objects passed. The ID, updated and created fields are set automatically by OpenAir.

To add data to OpenAir

1. Create an OpenAir Complex Type object with the NSOA.record.<complex type>( [id] ) function.

                       var category = new NSOA.record.oaCategory(); 
   
                 

2. Fill out the properties for the object, see Objects.

                       category.name = "New Category";
       category.cost_centerid = "123";
       category.currency = "USD"; 
   
                 

3. Place the object into an array of objects, see Arrays.

                       // To turn an object into an array of object, simply place it inside square brackets
       var objects = [category]; // or just pass [category] 
   
                 

4. Pass the objects as a parameter to the NSOA.wsapi.add(objects).

                       var results = NSOA.wsapi.add( [category] ); 
   
                 

5. Check for any errors, see Handling SOAP Errors.

Modifying data

You modify data to OpenAir by creating one or more OpenAir Complex Type objects, placing them into an array, and passing the array to the NSOA.wsapi.modify(attributes, objects) function. In each object passed, you need to specify the internal id and only the properties (fields) in the objects that you want to change. The updated field is set automatically by OpenAir.

To modify data in OpenAir

1. Create an OpenAir Complex Type object with the NSOA.record.<complex type>( [id] ) function.

                       var category = new NSOA.record.oaCategory(); 
   
                 

2. Fill out the internal ID for the object and the properties you want to change, see Objects.

                       category.id = 79; // This is the ID of the existing customer
       category.cost_centerid = "453"; // The new value 
   
                 

3. Place the object into an array of objects, see Arrays.

                       // To turn an object into an array of object, simply place it inside square brackets
       var objects = [category]; // or just pass [category] 
   
                 

4. Optionally create an array of attributes to pass.

                       var attributes = []; 
   
                 

5. Pass the objects and attributes as parameters to the NSOA.wsapi.modify(attributes, objects).

                       var results = NSOA.wsapi.modify( [attributes], [category] ); 
   
                 

6. Check for any errors, see Handling SOAP Errors.

Deleting data

You delete data from OpenAir by creating one or more OpenAir Complex Type objects, placing them into an array, and passing the array to the NSOA.wsapi.delete(objects) function. In each object passed, you need to specify the internal id.

Important:

You cannot delete an entity (database record) that has dependent records. You must first delete all the dependent records.

To delete data in OpenAir

1. Create an OpenAir Complex Type object with the NSOA.record.<complex type>( [id] ) function.

                       var category = new NSOA.record.oaCategory(); 
   
                 

2. Fill out the properties for the object, see Objects.

                       category.id = 79; 
   
                 

3. Place the object into an array of objects, see Arrays.

                       // To turn an object into an array of object, simply place it inside square brackets
       var objects = [category]; // or just pass [category] 
   
                 

4. Pass the objects as a parameter to the NSOA.wsapi.add(objects).

                       var results = NSOA.wsapi.delete( [category] ); 
   
                 

5. Check for any errors, see Handling SOAP Errors.

Reading data

You read data from OpenAir by creating a ReadRequest object and passing it to the NSOA.wsapi.read(readRequest) function.

Important:

You must specify a limit Attribute.

To read data from OpenAir

1. Create an OpenAir Complex Type object with the NSOA.record.<complex type>( [id] ) function and fill out the properties for the object to specify the search criteria.

                       var user = new NSOA.record.oaUser();
       user.nickname = "jsmith"; 
   
                 

2. Create a limit Attribute.

                       var attribute = {
           name  : "limit",
           value : "0,1000"
       } 
   
                 

3. Create a ReadRequest object and fill out the properties.

                       var readRequest = {
           type : "User",
           method : "equal to", // return only records that match search criteria
           fields : "id, nickname, updated", // specify fields to be returned
           attributes : [ attribute ], // Limit attribute is required; type is Attribute
           objects : [ user ] // One object with search criteria
       } 
   
                 

4. Pass the ReadRequest object to the NSOA.wsapi.read(readRequest) function.

                       var results = NSOA.wsapi.read(readRequest); 
   
                 

5. Check for any errors, see Handling SOAP Errors.

6. Process the results, see ReadResult.

See also the SOAP API — Prevent closing a project with an open issue code sample.

ReadRequest

The ReadRequest object is used to specify the required data to return in the NSOA.wsapi.read(readRequest) function.

              // example read request - assumes attribute and user objects have been defined
    var readRequest = {
        type : "User",
        method : "equal to", // return only records that match search criteria
        fields : "id, nickname, updated", // specify fields to be returned
        attributes : [ attribute ], // Limit attribute is required; type is Attribute
        objects : [ user ] // One object with search criteria
    } 

        

Property	Allowed Values
type	Any OpenAir Complex Type without the oa prefix for example “Issue”. See NSOA.record.<complex type>( [id] ) for the list of types.
method	“all” — Returns all available records. Note: Use this cautiously as too many records may be requested for the server or client to handle. “equal to” — return only records that match search. “custom equal to” — return associated custom fields. “not equal to” — return only records that do not match.
fields	Comma separated list of fields to be returned for example "id, nickname, updated”. For more information about supported fields, see XML and SOAP API Business Object Reference or https://app.openair.com/wsdl.pl.
attributes	Array of attribute objects, see Attribute. Important: The “limit” attribute is required.
objects	Array of OpenAir Complex Type objects, see NSOA.record.<complex type>( [id] ).

Attribute

The attribute object is used to set additional criteria in the following NSOA methods:

• NSOA.wsapi.modify(attributes, objects)

• NSOA.wsapi.read(readRequest)

• NSOA.wsapi.upsert(attributes,objects)

The attribute object is simply a pair of name and value properties.

              var attribute = {
        name  : "limit",
        value : "10"
    } 

        

See the table below for valid combinations of name and value.

name	value
“limit”	A single value (for example “500”) or range (for example “0, 1000”). Single value: "1", "500", "1000" - simply restricts the number of records returned. Range: "0, 1000" - the first integer specifies the offset of the first record to return and the second integer limits the number of records to return. To request data in consecutive batches, only the first part of the limit attribute should be incremented - "0,1000", "1000,1000", "2000,1000", etc. Sequence requests should be submitted until the result comes back empty or has less than 1000 items. See Reading data.
“filter”	“newer-than” “not-exported” “older-than” Note: Options can be placed into a comma separated list, for example "newer-than,older-than,not-exported".
”update_custom”	Set to ”1” to enable the updating of custom fields. See Updating Custom Fields.