Using Constituent Web Services

This document provides an overview of constituent web services, lists prerequisites, and discusses:

• Outbound and inbound services.

• Configuring constituent event triggers.

• Configuring notification handlers.

• Configuring integration with external systems.

Note. If you are implementing separate instances of your PeopleSoft Campus Solutions and PeopleSoft HCM systems, you should read the additional documentation describing how to configure and use External Search/Match directly between the two systems. The CS-HCM Integration Information Knowledge Document details the additional documents that describe the setup, functional, and technical implementation considerations.

See Also

CS-HCM Integration Information, posted to My Oracle Support https://support.oracle.com

PeopleSoft Campus Solutions Constituent Web Services Developer's Guide, posted to My Oracle Support

PeopleTools: Integration Broker

Understanding Constituent Web Services

In general, a web service is a collection of operations that enable software to utilize a resource. The official web service definition can describe almost any standard for exchanging data over the internet, but in common usage the term refers to the exchange of XML messages that follow the SOAP standard using the same HTTP protocol as a web browser. A simple definition of a web service is an internet application programming interface (API) that is self-describing and can work between various programming languages. The constituent web service was developed to be used in a manner consistent with common web services.

The constituent web service manages information about a constituent. A constituent can be a prospect, applicant, student, faculty member, or any other person of interest to your institution. The web service allows the Campus Solutions database to communicate with virtually any other external system, regardless of the technology supporting that system. Prior to web service standards it was difficult to connect systems on disparate technologies, such as operating systems, database platforms, and application architectures. Web service standards make it possible for computer systems on virtually any technology platform to integrate with minimal effort.

Institutions can use constituent web services to integrate constituent data between Campus Solutions and other external systems. The constituent web service:

• Notifies integrated systems when new constituents in Campus Solutions are created or when their information is changed.

  External systems can use this notification to synchronize their version of the constituent or to perform processing based on the changed data.

• Allows integrated systems to update a constituent's information in Campus Solutions, such as adding a new address or changing the constituent's name.

• Allows integrated systems to retrieve a constituent's detailed information.

• Enables Campus Solutions users to run Search/Match against an external constituent repository, such as a data hub.

Constituent web service information flow

Institutions can use the web service to integrate to a variety of administrative and academic systems that comprise the higher education ecosystem. For example, the service can be used to integrate to a data hub (MDM), housing system, human resources, parking system, learning management system, and general purpose registry. Large institutions often deploy hundreds of such systems.

Messaging between the systems is done via synchronous or asynchronous interactions. In a synchronous interaction, the source system issues a request to the target system and then waits until a response is received. Asynchronous interactions involve the source system issuing a request to the target system and not waiting for any response, but instead immediately continuing with processing. The request is assumed to have been received by the target system and to have been processed successfully. Asynchronous requests do not receive a response from the target system. This model assumes that the underlying messaging middleware guarantees the delivery of the request to the target system.

The PeopleSoft Campus Solutions Constituent Web Services Developer's Guide provides the technical details of web services as well as configuration and messaging.

The data that comprises the constituent message includes the core person data contained in the PERSON_BASIC_SYNC message, the Campus Solutions extension data contained in the PERSON_SA message, and affiliations data.

Messaging

Constituent web services uses three types of messaging. The system generates outbound messages when a constituent's data is changed in either Campus Solutions or HRMS (if the institution uses a combined instance of HCM/CS). A change in any data element in the constituent message definition raises this condition. The system publishes the constituent message so that any interested external system can be informed. The system generates inbound messages when a constituent's data is updated in an external system that is integrated with Campus Solutions. When a third-party or external system needs to query the Campus Solutions database to view data, the system generates a query message. This is a synchronous inbound request/response get service, in which a third party raises a query or data request and the Campus Solutions system delivers a response that contains the requested data details.

Constituent web services delivers the following messages, which are defined using PeopleTools Integration Broker:

• SCC_CONSTITUENT_SYNC (Outbound)

• SCC_PERSON_SYNC (Outbound)

• SCC_CONSTITUENT_IN_SYNC_DS (Inbound)

• SCC_GET_CONSTITUENT_REQ_DS (Inbound)

• SCC_GET_CONSTITUENT_RES_DS (Query)

See Also

PeopleSoft Campus Solutions Constituent Web Services Developer's Guide, posted to My Oracle Support https://support.oracle.com

Using External Search/Match

Setting Up Affiliations

Assigning and Managing Affiliations

Prerequisites

Before using constituent web services, your application server must be configured such that the publish/subscribe servers are running, and domains and gateways are configured.

In addition, in order to use the PERSON_DATA queue for web services, configure the Queue Definitions page so that the PERSON_DATA Queue Status is set to Run.

You must also configure the integration gateway using Integration Broker.

See Also

PeopleTools: Integration Broker

Outbound and Inbound Services

The PeopleSoft system delivers three outbound and two inbound web service operations. The PeopleSoft Campus Solutions Constituent Web Services Developer's Guide contains details about these services as well as samples of the XML messages that the services generate.

See Also

PeopleSoft Campus Solutions Constituent Web Services Developer's Guide, posted to My Oracle Support https://support.oracle.com

Outbound Services

The PeopleSoft system delivers three outbound service operations to notify external systems of changes to Campus Solutions constituent data, search/match for constituents in external repositories, and read ("get") constituent details for a single constituent in an external source.

Constituent Message

Use this operation to notify third parties of the creation, update, or deletion of one or more constituents in the Campus Solutions system. An outbound constituent request is sent whenever a constituent's data is updated. This includes information change by self-service users, administrators, and batch programs (for example, ISIR load).

The notification is sent whenever an administrator accesses any of these person create/update entry points:

• Campus Community – Personal Information

• Campus Community – Personal Information (Student)

• Contributor Relations – Add/Update a Person

• Student Recruiting – Add a Prospect

• Records and Enrollment – Quick Admit

• Student Admission – Application Entry

• Workforce Administration – Add a Person (if the institution is using a combined instance of HCM/CS)

In general an outbound message is published from any place within Campus Community where a person or his attributes can be created or updated: everywhere that PERSON_BASIC_SYNC and PERSON_SA data is used, as well as the Affiliations components and wherever the FERPA flag appears.

Supported Interaction Patterns

Request Message

The request message contains the entire constituent object, including affiliations and the FERPA flag contained in the PERSON_SA record.

Behavior

Whenever constituent information is created or changed an XML message is published.

External Search/Match

The Campus Solutions system uses this operation to search/match (query) against constituents stored within an external system.

Supported Interaction Patterns

Request Message

The request message is the external system Search/Match request object. This is a list of fields that may be partially populated to perform a search against the external system for potential constituents that match the criteria.

Behavior

The response includes all constituents matching the criteria according to the configured matching rules. Alternatively, the system returns a constituent fault message that includes detailed error messages and explanations.

See Prerequisites.

External Read ("Get") Constituent

The Campus Solutions system uses this operation to read a constituent record stored within an external source.

Supported Interaction Patterns

Request Message

The request message contains the EmplID of the constituent stored in the external system.

Response Message

The response includes all constituent details stored in the external system for the given EmplID. If there is no valid response, the system returns a constituent fault message that includes the detailed error messages and explanations.

Behavior

The external system validates the EmplID transmitted in the request message and if the ID is present, the system looks up the given constituent and returns all attributes for the constituent.

Inbound Services

The PeopleSoft system delivers two inbound service operations to manage changes to constituent data. In order to respond to constituent data updates generated in external systems, the constituent web service must listen to and process the inbound response.

Read ("Get") Constituent

Use this operation to request the details of a single constituent in the Campus Solutions system.

Supported Interaction Patterns

Request Message

The request message is the EmplID, the unique identifier for a constituent.

Response Message

If a constituent is found with the supplied EmplID then the service returns the populated constituent object. Otherwise, it returns a null constituent object.

Behavior

The constituent service validates the EmplID, if present, and populates the response message with all details of the constituent accessible to the caller.

Update Constituent

Use this operation to update the information of a single constituent in the Campus Solutions system.

Supported Interaction Patterns

Request Message

The request message contains the EmplID to uniquely identify the constituent to be updated, along with any attributes of the constituent that need to be updated.

Response Message (synchronous only)

The response indicates whether the constituent was updated successfully. If not, the system returns a constituent fault message that includes the detailed error messages and explanations.

Behavior

The constituent service validates the data passed in the request message. If the request is valid and the constituent can be found then the constituent is updated. All CS and HCM validation is performed. If any aspect of the data is invalid then the entire request is rejected. If an attempt is made to update non-updatable constituent attributes then the caller may be warned of this in the response.

Query Constituent

Use this operation to query against the constituents contained within the Campus Solutions system.

Supported Interaction Patterns

Request Message

The request message is the Campus Solutions Search/Match request object. This message contains a list of fields that can be partially populated in order to perform a search against the database for potential constituents that match the criteria. The request also includes the Search/Match setup ID.

Response Message

The response includes a collection of zero to many Search/Match results objects. The Search/Match result object contains partial constituent details along with weighting information that can be used to determine which returned constituent best matches the criteria.

Behavior

The operation validates the Search/Match request. If the request is valid, the system performs a Search/Match against the database and returns the results.

See Using External Search/Match.

Configuring Constituent Event Triggers

To register events, access the Constituent Event Registration page (Set Up SACR, System Administration, Utilities, Constituent Management, Constituent Event Registration).

PeopleSoft delivers three events: SCC_CONSTITUENT_IN_SYNC, PERSON_BASIC_SYNC, and SCC_PERSON_SYNC. Constituent web services utilizes these registered events in their processing.

Warning! Do not modify the delivered events. If your institution creates new events to trigger messaging, you must add the new events here and register them with constituent web services.

Implementation Class

Configuring Notification Handlers

To register all delivered message handlers, access the Notification Handlers page (Set Up SACR, System Administration, Integrations, Notification Handlers).

PeopleSoft delivers three handlers: SCC_CONSTITUENT_IN_SYNC, PERSON_BASIC_SYNC, and SCC_PERSON_SYNC. The service-oriented architecture (SOA) framework uses handlers for its messaging.

Warning! Do not modify the delivered message handlers. If your institution creates new events to trigger messaging, you must add the new handlers here and register them with constituent web services.

Application Class

Configuring Integration with External Systems

Use the External Core Data Integration page to indicate that the Campus Solutions system is integrated with a constituent data hub or other external system managing person data. This page is also used to enable External Search/Match functionality.

See Also

Using External Search/Match