3.1 Writing Elements

The API provides services that allow clients to add, modify, and remove elements on the Operations Center server, as listed in Table 3-1.

Table 3-1 Services for Writing Elements

Name

Description

 
createElement(session:WsSession, data:ElementCreateData):ElementWriteResponse

Creates a new element on the Operations Center server.

 
updateElement(session:WsSession, data:ElementUpdateData):ElementWriteResponse

Updates an element on the Operations Center server.

 
removeElement(session:WsSession, elementDName:string):void

Removes an element from the Operations Center server.

Element write services are restricted from operating on any element with a DName ending with:

  • root=Administration

  • root=Elements

  • root=Service+Level+Agreements

In addition, you cannot use removeElement on any root element.

The createElement and updateElement services allow the client to manipulate an element’s attributes, relationships, and property page data. These services are not transactional, so it is possible for some parts of the service request to succeed, while others fail. If either of these services returns an exception, then no updates are made. However, if any part of the operation succeeds, then an ElementWriteResponse object is returned.

An ElementWriteResponse contains an updated copy to the element, as well as a listing of any nonfatal errors that occurred. Each listed error includes an error code (WSDL type: MosFault), the type of operation that failed (WSDL type: ElementWriteType), and a qualifier identifying the name of the attribute, property, or relationship that could not be updated.

In the following example, the client attempts to create an element called “test” with an invalid property page called “foo”:

<createElement xmlns="http://wsapi.mosol.com">
  <session>
    :    :    :
  </session>
  <data>
    <DName>org=test/root=Organizations</DName> 
    <addRightRelationships /> 
    <attributes /> 
    <propertyPageNames>
      <item>foo</item> 
    </propertyPageNames>
    <propertyValues>
      <item>
        <fieldName>bar</fieldName> 
        <fieldValue>someValue</fieldValue> 
        <pageName>foo</pageName> 
      </item>
    </propertyValues>
  </data>
</createElement>

The response to this request indicates that the element was created (because the response is not an exception). It also lists failures for adding the property page and setting the property value because no property page name “foo” could be found:

<createElementReturn>
  <element>
    <DName>org=test/root=Organizations</DName> 
       :    :    :
  </element>
  <failures>
    <item>      <faultCode>NOT_FOUND</faultCode> 
      <itemQualifier>foo</itemQualifier> 
      <typeCode>ADD_PROPERTY_PAGE</typeCode> 
    </item>
    <item>
      <faultCode>NOT_FOUND</faultCode> 
      <itemQualifier>foo:bar</itemQualifier> 
      <typeCode>SET_PROPTERY_VALUE</typeCode> 
  </item>
  </failures>
</createElementReturn>