1 Overview

This chapter describes an overview of the data loading service.

The Data Loading Services are a collection of web services that provide operations to manage certain entities within OSL. These entities represent data that are typically loaded from external systems and can be broadly classified under the following categories:

Calendar
Classes & Enrollment
Courses & Tags
Framework
Institution
Offerings
People & Relationship

1.1 Creation of Department

The Data Loading Services do not provide a service to create the Department. The Department is created during installation of OSL. The Data Loading Services provide a service to update the Department attributes.

1.2 Security

The Data Loading Services are secured services that are protected by the WebLogic Security mechanism. The default security policy configuration is defined by oracle/wss_username_token_service_policy. Any client access to these services is authenticated and authorized. The default security configuration can be overridden post deployment of the application.

1.2.1 Authentication

The oracle/wss_username_token_service_policy requires the client to pass in the credentials in the SOAP Header.

Below is an example of a SOAP message containing the credentials in the SOAP Header.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:dat="http://www.oracle.com/osl/lt/service/dataloading" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <soap:Header>
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>dataloading</wsse:Username>
        <wsse:Password>xxxxxxxxxxx</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    ---
  </soap:Body>
</soap:Envelope>

1.2.2 Authorization

All the services that are part of Data Loading are accessible to users that belong to the "DataLoadingGroup". The Data Loading Services expect a user with uid "dataloading" to be part of the "DataLoadingGroup". The authenticated user's uid should be "dataloading" and the user should be part of the "DataLoadingGroup".

1.3 Entity Identification Mechanism

At any point, a record in OSL can be uniquely identified either through the OSL Id or the combination of External Id and External System Id.

1.3.1 oslId

The oslId is the identifier generated by OSL for internal representation of data loaded through the Data Loading Services. The oslId is contained in the response to any successful create operation.

1.3.2 externalId and externalSystemId

OSL external systems require a mechanism to cross-reference individual records. The recommendation is to use an externalId and an externalSystemId to uniquely identify individual records. Any external system loading data into OSL can optionally provide these identifiers. When provided, OSL keeps track of them and external systems can cross-reference these records based on the externalId and externalSystemId.

1.4 Action List and List

To explain this concept, the PersonInfo data structure is used.

<xs:complexType name="personInfo">
    <xs:sequence>
      <xs:element name="academicYearLevel" type="xs:string" minOccurs="0"/>
      <xs:element name="addressActions" type="tns:addressActionInfoArray"
                  minOccurs="0"/>
      <xs:element name="addresses" type="tns:addressInfo" minOccurs="0"
                  maxOccurs="unbounded"/>
      <xs:element name="birthDate" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="countryOfBirth" type="xs:string" minOccurs="0"/>
      <xs:element name="deathDate" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="emailContactActions" type="tns:contactActionInfoArray"
                  minOccurs="0"/>
      <xs:element name="emailContacts" type="tns:contactInfo" minOccurs="0"
                  maxOccurs="unbounded"/>
      <xs:element name="firstName" type="xs:string" minOccurs="0"/>
      <xs:element name="gender" type="tns:personGender" minOccurs="0"/>
      <xs:element name="id" type="tns:idInfo" minOccurs="0"/>
      <xs:element name="languageActions" type="tns:languageActionInfoArray"
                  minOccurs="0"/>
      <xs:element name="languages" type="tns:languageInfo" minOccurs="0"
                  maxOccurs="unbounded"/>
      <xs:element name="lastName" type="xs:string" minOccurs="0"/>
      <xs:element name="loginId" type="xs:string" minOccurs="0"/>
      <xs:element name="maritalStatus" type="xs:string" minOccurs="0"/>
      <xs:element name="middleName" type="xs:string" minOccurs="0"/>
      <xs:element name="nameSuffix" type="xs:string" minOccurs="0"/>
      <xs:element name="phoneContactActions" type="tns:contactActionInfoArray"
                  minOccurs="0"/>
      <xs:element name="phoneContacts" type="tns:contactInfo" minOccurs="0"
                  maxOccurs="unbounded"/>
      <xs:element name="photograph" type="xs:base64Binary" minOccurs="0"/>
      <xs:element name="placeOfBirth" type="xs:string" minOccurs="0"/>
      <xs:element name="preferredName" type="xs:string" minOccurs="0"/>
      <xs:element name="relationshipActions"
                  type="tns:relationshipActionInfoArray" minOccurs="0"/>
      <xs:element name="relationships" type="tns:relationshipInfo" minOccurs="0"
                  maxOccurs="unbounded"/>
      <xs:element name="title" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

In the PersonInfo structure, phoneContactActions and relationshipActions are Action Lists. In the same structure, addresses, emailContacts, languages, phoneContacts and relationships are Lists.

Lists are returned by the service in response to certain operation and Lists are never sent in any request message. In other words, Lists are always constructed by the service and clients typically read the Lists.

The data structure of the Action Lists is similar to that of Lists except that an action flag on individual element indicates the action that is being performed on them. A client always sends an Action List to the service during create, createOrUpdate and update operation. The action flag can have the following permissible values:

<xs:simpleType name="action">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Create"/>
      <xs:enumeration value="Update"/>
      <xs:enumeration value="Delete"/>
      <xs:enumeration value="CreateOrUpdate"/>
    </xs:restriction>
  </xs:simpleType>

During a create operation, the service assumes an implicit value of "Create" for the action flag. During an update and createOrUpdate operation, any of the permissible values can be specified and the service processes accordingly.

For instance, if a new address is to be added to a PersonInfo object, an action flag of "Create" should be passed in for that element during the updatePersons operation.

Similarly, if an existing address is to be deleted from a PersonInfo object, an action flag of "Delete" should be passed in for the element during the updatePersons operation, in addition to passing the identifiers that can uniquely identify the element.

If an action flag of "CreateOrUpdate" is provided for the address element during the updatePersons operation, if the address exists, it shall be updated. If it does not exist, it will be created and appended to the existing list of addresses.

1.5 Entity Operations

The Data Loading web services provide CRUD (Create, Read, Update, and Delete) operations on most of the entities. Delete operations are not supported on Person and Institution entities. This is to preserve data consistency as deleting a Person or an Institution could have adverse effect. The semantics of the various operations supported by Data Loading Services are summarized in the following sections.

1.5.1 create Operation

This operation supports the creation of an array of homogeneous entities as an atomic unit of work. The entire transaction is rolled back if any failure occurs during the creation process.

On successful creation, the response includes the oslId of each entity that has been created.

1.5.2 createOrUpdate Operation

This operation supports creating or updating an array of homogeneous entities as an atomic unit of work. The entire transaction is rolled back if any failure occurs during the create or update process.

If an oslId is specified, the service tries to locate the entity to update based on the oslId. If found, the entity is updated.

If no entity is retrieved for the specified oslId, the services check if the combination of externalId and externalSystemId is specified. If specified, the service tries to locate the entity based on the externalId & externalSystemId. If the entity is found, it is updated.

If the identification mechanism does not fetch an entity, a new record is created and the oslId pertaining to the record is returned to the caller in the response.

1.5.3 update Operation

This operation supports updating an array of homogeneous entities as an atomic unit of work. The entire transaction is rolled back if any failure occurs during the update process.

If an oslId is specified, the service tries to locate the entity to update based on the oslId. If found, the entity is updated.

If no entity is retrieved for the specified oslId, the service checks if the combination of externalId and externalSystemId is specified. If specified, the service tries to locate the entity based on the externalId & externalSystemId. If the entity is found, it is updated.

If the identification mechanism does not fetch an entity, an error is raised.

In an update operation, it is not required to send the entire object structure. In addition to the identification of the entity, it is sufficient to specify only the elements to be modified. The service updates the entity with only the modified elements. For instance, if the preferredName of a person with oslId 100 is modified to "John", it is sufficient to send the following information to the service.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:dat="http://www.oracle.com/osl/lt/service/dataloading" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
  <soap:Header>
    <wsse:Security>
      <wsse:UsernameToken>
        <wsse:Username>dataloading</wsse:Username>
        <wsse:Password>welcome1</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <dat:createPersons>
      <persons>        
        <id>
          <oslId>100</oslId>
        </id>
        <preferredName>John</preferredName>
      </persons>
    </dat:createPersons>
  </soap:Body>
</soap:Envelope>

1.5.4 remove Operation

This operation supports deleting an array of homogeneous entities as an atomic unit of work. The entire transaction is rolled back if any failure occurs during the deletion process.

If an oslId is specified, the service tries to locate the entity to delete based on the oslId. If found, the entity is deleted.

Only the object identification mechanism must be specified for the remove operation. If other elements are specified, those are ignored by the service.

1.5.5 get Operation

This operation supports querying entities based on the identifiers.

If an oslId is specified, the service tries to locate the entity based on the oslId. If found, the entity is returned.

Only the object identification mechanism must be specified for the get operation, if other elements are specified, those are ignored by the service.

1.6 Web Service Exceptions

During Data Loading Service operations, Web Service Exceptions might be encountered. These exceptions indicate possible errors or business rule violations in the input parameters. To help locate the root cause, error codes and error messages are contained within the exceptions. A summary of the Web Service Exceptions are provided below.

1.6.1 CreationException

A CreationException is thrown when the system cannot create the specified entity when attempting to save the data into the database.

1.6.2 DataConstraintException

A DataConstraintException is thrown when the modified data is in violation of the business rules. Common situations include updating the start date of a framework such that the start date is later than the end date or creating a framework with a non-unique name.

1.6.3 InvalidParameter

An InvalidParameter exception is thrown when the input parameters are invalid or required fields are missing.

1.6.4 RemoveException

A RemoveException is thrown when an entity cannot be removed. This occurs when an attempt is made to remove an entity that is in use. For example, an attempt is made to remove a context adoption when the adopted context is referenced in a learning item demonstration.

1.6.5 UpdateException

An UpdateException is thrown when the system cannot update the specified entity when attempting to save the data into the database.

1.6.6 ServiceException

A ServiceException is a general service exception that is thrown for an unspecified condition.