Creating Component Interface-Based Services

This chapter discusses how to:

Select component interfaces to expose as services.
Select component interface methods to include in service operations.
Generate component interface-based services and service operations.
View component interface-based service definitions.

Understanding Creating Component Interface-Based Services

PeopleSoft Integration Broker enables you to take an existing component interface and create a service that can be used to invoke the component interface. Further, it creates service operations, including request messages and response messages (if appropriate). The system creates an inbound any-to-local routing for the service operation version, as well as handlers for each method you choose to include in the service.

All service operations you generate from component interfaces are synchronous service operations.

Naming Conventions Integration Metadata Created

This section highlight the naming conventions that the PeopleSoft system uses when it creates services and services-related data based on component interfaces.

When it creates a web service from a component interface, the PeopleSoft system adds a CI_ prefix to the component interface name. So if the component interface name is MYCI, the service name the system creates is CI_MYCI

The following table highlights naming conventions the PeopleSoft systems applies to other services data based on the method with which you are working:

Component Interface Method	Service Operation Name	Message Name	Component Interface Handler	Request Message Shape	Response Message Shape
Create	<service_name>_C	Mxxxxxx	ONREQUESTHDLR	CI Buffer	Key
Find	<service_name>_F	Mxxxxxx	ONREQUESTHDLR	Get Keys	CI Buffer
Get	<service_name>_G	Mxxxxxx	ONREQUESTHDLR	Find Keys	Key Collection
Update	<service_name>_UP	Mxxxxxx	ONREQUESTHDLR	CI Buffer	Notification
Updatedata	<service_name>_UD	Mxxxxxx	ONREQUESTHDLR	CI Buffer	Notification
User-defined	<service_name>_<method_name>	Mxxxxxx	ONREQUESTHDLR	CI Buffer	Method Return Type

The naming convention used for message names, Mxxxxxx, is the letter M followed by a random six-digit number, as denoted by the x's. An example of a message name is M548902.

Note. The maximum number of characters for a service operation name is 30. If using a user-defined method name yields a greater result, the name is used is <service_name>_Mxxx, where xxx is a three-digit random number. An example of such a name is CI_USERCI_M101023.

User-Defined Method Restrictions

All user defined methods that will be accessed via the service interface must have a doc string.

The doc string contains:

The keyword GET or CREATE.
An ordered list of parameter names corresponding to the method's parameters.

The following example shows the format of the doc string:

Function simpleFunction(&sParm As string, &dParm As date, 
                        &nParm As number, &bParm As boolean) 
                        Returns string
   Doc "GET, StringParm, DateParm, NumParm , BoolParm"
   
   Local string &aString = &sParm;
   &aString = &aString | " -- " | &dParm;
   &aString = &aString | " -- " | &nParm;
   &aString = &aString | " -- " | &bParm;
   Return &aString;
   
End-Function;

The contents of the doc string are used when the function is invoked. If GET is specified, then the GET keys are set, and GET is called on the component interface before the used-defined method is invoked. If CREATE is specified, the CREATE keys will be set and CREATE will be called before the method is invoked.

The list of parameters are used at runtime to match the data in the input message with the method's parameters. This is an ordered list; if the parameter list in the doc string and the method parameters don't match, then the method may not work correctly. The names in the doc parameter list will be the names visible in any WSDL created for the service.

Method parameters and return values must be of a primitive type, such as a string, date or number. Object parameters or return values are not supported.

Impact of Changing Component Interfaces

If a user modifies or deletes a component interface in PeopleSoft Application Designer, when the user saves the changes, PeopleSoft Integration Broker checks if a service exists for the component interface. If a service exists, and the component structure/properties have changed in the component interface, a warning message appears stating that a service exists for the component interface.

If the component interface structure changes, a status of Does not match appears in the CI-Based Services Review Status grid, and the operation appears as active in the Service Operations component.

Prerequisites

Prior to creating any component interface-based web services and service operations, you must define the schema namespace, service namespace, and target location in the Service Configuration page

See Configuring PeopleSoft Integration Broker for Handling Services.

Selecting Component Interfaces to Expose as Services

This section discusses how to select component interfaces to expose as web services.

Page Used to Select Component Interfaces

Page Name	Object Name	Navigation	Usage
Select Component Interfaces	IB_CISERVICES	Select PeopleTools, Integration Broker, Web Services, CI-Based Services.	Choose component interfaces to expose as a web service.

Selecting Component Interfaces

The first step to creating component interface-based services is to choose the component interface on which to base a service. To do so, use the CI-Based Services component (IB_CISERVICES) and the CI–Based Services – Select Component Interface page. The following graphic shows this page:

When you search for component interfaces to select, the system returns results only for those component interfaces to which you have permissions.

To select a component interface:

Search for a component interface:

Note. You can search only for those component interfaces to which you have permissions.

Click the Search button to search from all component interfaces in the database, or

Select one or more of the following criteria to narrow your search and then click the Search button.

Component Interface Name	Enter part or all of the name of the component interface to use, or click the Lookup button to search for one.
Component Name	Enter part or all of the component name to which a component interface belongs.
Owner ID	Owner ID dropdown list box, select the person or group that owns the component interface.

The Select CIs grid displays are component interfaces that match your search.

Check the Select box next to one or more component interfaces.
Click the Review CI Status button.

The Review CI Status page appears where you can review details about the select component interface and select the methods to include as operations in the service.

Selecting Component Interface Methods to Include as Service Operations

This section discusses selecting methods to include web services as service operations.

Page Used to Select Methods to Include as Service Operations

Page Name	Object Name	Navigation	Usage
Review Status	IB_CISERVICES2	From the CI-Based Services-Select Component Interfaces page, click the Review CI Status button.	Select component interface methods to include as service operations.

Selecting Methods to Include in Service Operations

The following example shows the CI-Based Services-Review Status page:

The Review Status page shows the following information about the component interface you select to expose as a service:

CI Name	Name of the component interface.
Service	Name of the service created based on the component interface. Note that the service name is the component interface name with CI_ added as a prefix.
Description	A description of the component interface. This information is taken from the component interface record and displays if it exists.
Status(Service)	Displays the status of the service. The valid values are: Service does not exist and will be created. Indicates that a services does not exist for the service and the system will create one. Service Exists. Indicates that a service has already been created for the component interface.
Select	Check the box to include a method as an operation for the service. If the box is disabled, the method has already been included in the operation and the Service Operation field displays the name of the operation created. You can check one or more methods at a time.
Action	Displays the action available to perform on the method. The valid values are: Create Operation. This action displays if no service operation exists for the method. Create New Version.. This action displays if the current request or response shape do not match the shapes previously generated. A new service operation version is generated. None. If an operation exists, it compares the component interface and the service operation. If they are in sync, no action is required.
Method	Name of the component interface method. The system displays user-defined and standard methods. All user-defined methods appear in lowercase. You can create service operations based on the following standard component interface methods: Create Get Find Update Updatedata User-defined methods. Update and Updatedata appear if both Get and Save have been enabled in the component interface. Note. All user-defined methods are lowercase. If you have a user-defined method called update, it is a different method than the Update method used here.
Service Operation	Name of the service operation, if one exists for a method. The name the system give the service operation depends on the service name as well as the component interface method.
Status(Service Operation)	The status corresponds to the value in the Action field. The valid values are: Does not exist. No service operation exists for the method. Does not match. The service operation does not match the existing component interface. OK. The service operation matches the existing component interface. Operation created. The system created the operation.
Display Selected Actions	Click the button to display a summary of the actions requested and then generate services and service operations.

Generating Component Interface-Based Services

This section discusses generating service and service operations from component interfaces and component interface methods.

Page Used to Generate Component Interfaced-Based Services

Page Name	Object Name	Navigation	Usage
Confirm Actions	IB_CISERVICES_SEC	From the CI-Based Services-Review Status page, click the Perform Selected Actions button.	Confirm component interface methods to include in service operations for a service and generate the service and operations.

Generating Services and Service Operations

The following example shows the CI-Based Services–Confirm Actions page:

You can work with the following page elements:

Service Alias	(Optional.) Enter an alias name for the service. The name you enter can be lower or mixed-case. If specified, this is the service name that appears in any WSDL documents you generate.
Select	(Optional.) Clear the box to omit creating a service operation for a method.
Alias(Service Operation)	(Optional.) Enter an alias name for the service operation. The name you enter can be lower or mixed-case. If specified, this is the service operation name that appears in any WSDL documents you generate.
Version	(Optional.) Service operations created default version V1. You may enter a different value to use as the version when the service operation is created. This field is a text field, so you may enter numeric or text values.
Perform Selected Action	Click the button to generate services and service operations for the component interface and selected methods. After the service and service operations are created, the CI-Based Services–Review Status page displays and you can review the actions performed as well as access the service definition created.
Return to Select CIs	Click the link to return to the previous page, the CI-Based Services–Review Status page.

Viewing Component Interface-Based Service Definitions

This section discusses viewing service definitions generated from component interfaces.

Pages Used to View Component Interface-Based Service Definitions

Page Name	Object Name	Navigation	Usage
Review Status page	IB_CISERVICES2	On the CI-Based Services-Review Status page, click the Perform Selected Actions button.	Use this page to review the actions performed.
Services page	IB_SERVICEDEFN	On the CI-Based Services-Review Status page, after you click the Perform Selected Actions button to generate the component interface-based service, click the View Service Definition link.	View the service definition for the component interface-based service.

Viewing Component Interface-Based Service Definitions

After you generate services and service operations, the following CI-Based Services–Review Status page appears:

Use this page to review the actions performed. For example, the previous graphic shows the names of the two service operations created as well as the service operation status of Operation created.

From this page you can continue to create additional service operations using the remaining available methods for the component interface.

Or, you can click the Return to Select CI link to return to the CI-Based Services–Select Component Interface page to select new component interfaces for which to generate services and service operations.

You can also click the View Service Definition link to view the service definition for the service created.

When you click the View Service Definition link the service you created, CI_CURRENCY_CD_CI appears in the Services page as shown in the following graphic:

From this page you can perform actions as you would on any other service, including:

Click the Provide Web Service link to generate WSDL for the service.
Use the Service Operations box to add additional service operations to the service.
Click either of the operations that display in the Existing Operations box to generate routing definitions, view the response, request or fault messages, view handler details, and more.
And so on.