Managing Service Operations

This chapter provides an overview of managing service operations and discusses how to:

• Access and view service operation definitions.

• Add service operation definitions.

• Define service operations.

• Set permissions to service operations.

• Change the services with which service operations are associated.

• Manage service operation versions.

• Attach files to service operations.

• Rename and delete service operations.

Understanding Managing Service Operations

This section discusses:

• Service operations.

• Service operation types.

• Service operation aliases.

• Service operation versions.

• Mapping service operations.

Service Operations

A service operation definition consists of general information about an operation, such as its name, description, and so on. It also specifies an operation type, which determines how the operation is to be processed, synchronously or asynchronously. In addition, it contains routings, which determine the direction, inbound or outbound, of the service operation. A service operation has one or more handlers, which contain and run the programming logic for sending or receiving the message, manipulating message content, and so on.

Note. Beginning with the PeopleTools 8.48 release, service operations house the processing logic found in messages, transactions and relationships used in earlier versions of PeopleSoft Integration Broker.

Service Operation Types

Service operation types determine the type of message processing. There are four service operation types:

Service Operation Aliases

A service operation alias or operation alias is the service operation name that displays for the service operation when WSDL is provided.

Service operation aliases may be mixed case.

Duplicate service operation alias names within a service are not allowed.

Service Operation Versions

When you create a service operation, the operation that you create automatically becomes the default service operation version.

If you add a new version to the operation, the newly added version automatically becomes the default.

To continue to use a non-default service operation version, you must create a transformation.

Mapping Service Operations

You can map inbound, asynchronous, one-way service operations to more than one service operation.

Accessing and Viewing Service Operation Definitions

This section discusses how to:

• Access service operation definitions.

• View service operation definitions.

Pages Used to Access and View Service Operation Definitions

Accessing Service Operation Definitions

Use the pages in the Service Operations component (IB_SERVICE) to access and view service operation definitions. The following example shows the General tab of the Service Operations component:

To access a service operation definition:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.

   The Find Service Operation search box appears.

2. Search for a service operation definition to view.

   You can search for an operation in one of two ways:

   • Click the Search button to display all service operation definitions in the system.

   • Enter search criteria in one or more of the following fields, and then click the Search button:

     Service	Enter the service name that contains the service operation that you want to view, or click the Lookup button to search for and select a service name.
     Service Operation	Enter the name of the service operation to view, or click the Lookup button to search for and select an operation.
     Operation Type	From the Operation Type dropdown list box, select an operation type. Values are: Asynch Request/Response Asynch to Synch Asynchronous – One Way Synchronous

3. Click the name of the service operation to view.

   The Service Operations – General tab appears with data for the service operation that you selected.

Viewing Service Operation Definitions

The Service Operations component includes three pages:

Viewing General Service Operation Information

When you access a service operation, the General tab appears.

The top portion of this page contains basic information about a service operation, including its name, description, and so on. The Service Operation Security link opens the permission list for the service. Note that the Service Operation Security link appears only after a service operation definition is saved.

The Default Service Operation Version section displays service-operation version information, whether nonrepudiation is in effect, and whether runtime schema validation is enabled. The Introspection link enables you to access the Introspection and Validation page.

The Routing Status group box shows if any-to-local or local-to-local routing definitions have been generated for the service operation. Click the Routings tab to view detailed information about routing definitions that exist for a service operation.

The Routing Actions Upon Save group box shows the possible routings that the system can generate when the service operation definition is saved.

The Message Information section displays the request message, response message information, and fault message for the service operation. The View Message links in this section open the displayed message on the Message Definition page, where you can view additional information about the message. For all operation types other than Synchronous, the queue to which a message belongs also appears. Click the View Queue link or the Add New Queue link to open the Queue Definition page to view additional queue definition information or to add or change a queue to which a message belongs.

See Viewing Routing Definitions.

Viewing Handler Information

The Handlers tab of the Service Operation component lists summary information about handlers that have been added to an operation.

The summary information includes the handler name, the handler type, and the implementation method for the handler. The status of the handler, active or inactive, also appears.

Click the Details link to open the Action Details page for the handler. The following example shows the Actions Details page:

The Action Details page shows additional information about the handler, including the owner and application class or component interface details.

You can also use this page to specify the handler details.

Viewing Routing Information

The Routing tab of the Service Operation component displays a summary of routing definitions for an operation.

The Routings Definition grid on the page lists summary information for routings that are defined for a service operation. Summary information that is displayed includes the routing definition name, service operation version, routing type, sending node, receiving node, direction of the routing and the routing status.

Click a routing definition name to open the routing in the Routing Definitions component, where you can view additional information about the routing.

You can also use this page to add routing definitions to a service operation and to activate or deactivate routings for an operation.

See Adding Routing Definitions, Activating and Inactivating Routing Definitions.

Adding Service Operation Definitions

This section discusses how to add a service operation definition.

Page Used to Add Service Operation Definitions

Adding a Service Operation Definition

To add a service operation definition:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.

   A search page appears.

2. Click the Add Service Operation tab.

3. In the Service field, enter the service name to which the new operation will belong or click the Lookup button to search for a service name.

4. In the Service Operation field, enter a name for the service operation.

5. From the Operation Type dropdown list box, select an operation type. Values are:

   • Asynchronous – One Way

   • Synchronous

   • Asynch Request/Response

   • Asynch to Synch

6. Click the Add button.

The new definition appears on the General tab of the Service Operation component, and you can now define the service operation.

Configuring Service Operation Definitions

After you add a service operation definition to the system, you can define the service operation.

This section discusses how to:

• Specify general information.

• Define service-operations version information.

• Add handlers to service operations.

• Add routing definitions.

• Activate and inactivate routings.

Pages Used to Configure Service Operation Definitions

Specifying General Information

To specify general information:

1. Access the Service Operations-General page.

2. In the Operation Description field, enter a description for the operation.

3. (Optional.) Check the User ID/ Password Required check box to require a user ID and password for inbound service operations.

   See Managing User Authentication.

4. (Optional.) In the Operation Comments field, enter comments about the service operation .

5. (Optional.) From the Object Owner ID field, select the owner of the definition.

   The owner ID helps to determine the application team that last made a change to a service definition. The values in the dropdown list box are translate table values that you can define in the OBJECTOWNERID field record.

6. (Optional.) In the Operation Alias field, enter an alias name for the service operation.

The general information section of this page includes a Service Operation Security link. Granting permissions to service operations is discussed elsewhere in this chapter.

Before you can save the service operation definition, you specify messages for the service operation, as described in the next section.

See Setting Permissions to Service Operations.

The following section continues to describe how to define a service operation and discusses how to assign default versions to service operations.

Defining Service Operation Version Information

When you first create a service operation definition, the definition that you initially define is the default version.

When the newly created service operation definition opens, the Default check box is enabled and is read-only.

You can subsequently define additional service operation versions and assign them as the default.

See Managing Service Operation Versions.

Defining General Version Information

To define the service operation default version:

1. In the Version field, enter a version identifier.

   The default is v1.

2. (Optional.) In the Version Description field, enter a description for the operation version.

   If you enter no information, the description by default is the name of the service operation when you save the definition.

3. (Optional.) In the Version Comments box, enter comments about the version.

4. (Optional.) Check the Non-Repudiation check box to apply nonrepudiation to the message.

5. (Optional.) Check the Runtime Schema Validation check box to enable service schema validation at runtime.

You can click the Introspection link to employ introspection to generate point-to-point routings.

See Using Introspection to Create Routing Definitions.

Continue to the next section to specify messages for service operations. You cannot save the service operation definition until you define messages for it.

Specifying Messages for Service Operations

You specify messages for service operations in the Message Information section of the Service Operations – General page.

The messages that you specify define the structure of the data that is contained in the service operation.

The service operation type determines the number of messages and message types (request or response) that you specify.

To specify messages for a service operation:

1. Locate the Message Information section on the Service Operations – General page.

2. Locate the Type field, and take note of the message type to define.

3. In the Message.Version field, enter the message name followed by a dot and version, or click the Lookup button to search for one.

   After you select the message, you can click the View Message link to view the message.

4. Specify the queue for the message.

   Note. If you are defining a message for a synchronous operation type, you do not need to define a queue.

   Your options are:

   • In the Queue Name field, enter the queue name.

   • Click the Lookup button to search for a queue.

   • Click the Add Queue link to open the Queue Definitions page and define a new queue for the message.

     See Adding Queue Definitions.

5. Repeat steps 1 through 4 for each message type that appears in the Message Information section.

6. Click the Save button.

Specifying Fault Messages for Service Operations

You can specify fault messages for service operations for error handling.

Note. You cannot add fault messages to asynchronous service operations.

To specify a fault message:

1. Locate the Default Service Operation Version section on the Service Operations – General tab.

2. Click the Add Fault Type button.

   A new row appears in which to specify a message. Note that the Type field in the new row displays Fault.

3. In the Message.Version field, enter the message name, or click the Lookup button to search for one.

   After you select the message, you can click the View Message link to view the message.

4. Click the Save button.

To delete a fault message, in the Default Service Operation Version section, click the Delete Fault Type button. Then click the Save button.

Generating Local-to-Local and Any-to-Local Routing Definitions

Use the Service Operations-General page to initiate generating local-to-local and any-to-local routing definitions.

See Initiating System-Generated Routing Definitions.

Adding Handlers to Service Operations

This section discusses how to:

• Add handlers.

• Add handler details.

• Add handler implementation details.

Adding Handlers

To add handlers to a service operation:

1. On the Service Operations component, click the Handlers tab.

   The Handlers page appears.

2. In the Handlers section, enter a handler name in the Name field.

   Note that for OnRequest, and OnRoute handlers, you need not enter a name. The system adds a handler name after you provide the handler details.

3. From the Type dropdown list box, select the handler type.

   The service operation type determines the handler types that are available to choose.

4. From the Implementation dropdown list box, select the method to use to implement the handler.

   The service operation type determines the handler types that are available to choose.

5. From the Status dropdown list box, select a status for the handler. Values are:

   • Active. Select to make the handler active.

   • Inactive. Select to make the handler inactive.

Continue to the next section for information about entering handler details.

Adding Handler Details

This section describes how to add handler details.

Note. You do not enter handler details for handler implementations using data mover scripts or for the deprecated PeopleCode handler.

To add handler details:

1. On the Handlers tab of the Service Operations – Handlers tab, in the Handlers section, click the Details link.

   The Action Details page appears.

2. (Optional.) In the Description field, enter a description for the handler.

3. (Optional.) In the Comments field, enter comments about the handler.

4. (Optional.) In the Handler Owner field, enter the name of the person or group that owns or maintains the handler.

Continue to the next section for information about adding handler implementation details

Adding Handler Implementation Details

This section describes how to add handler implementation details.

Note. You do not enter handler implementation details for handler implementations using data mover scripts or for the deprecated PeopleCode handler.

To add handler implementation details:

1. On the Service Operations – Handlers tab, in the Handlers section, click the Details link.

   The Action Details page appears.

2. Enter details based on the implementation method that is selected:

   Application Class

   When the implementation method is an application class, complete the following fields: Package Name Enter the package name that contains the class that you want to specify, or use the Lookup button to search for and select one. Path Enter the name or names of any subpackages that contain the application class that you want to specify, or use the Lookup button to search for and select one. Class ID Enter the name of the application class that contains the method that you want to specify, or use the Lookup button to search for and select one. Only application classes that implement an appropriate base class are shown. The base class is dependent on the handler type. Method From the Method dropdown list box, select the method from the selected application class that you want to specify. Only methods with the correct signature for the current handler type are shown.

   Component Interface

   When the implementation method is a component interface, complete the following fields: CI Name Enter the component interface name, or use the Lookup button to search for and select one. Method From the Method dropdown list box, select a method

3. Click the OK button.

4. Click the Save button.

Adding Routing Definitions

This section describes how to create point-to-point service operation routing definitions from the Service Operations – Routing page.

Note. You can also create routings using the Routings component, the Introspection component, or the Routings page in the Node Definitions component.

To add a routing to a service operation:

1. On the Service Operations component, click the Routings tab.

   The Routings page appears.

2. In the Routing Name field, enter a name for the routing.

3. Click the Add button.

   The Routing Definition page appears.

   Creating and defining a routing is discussed elsewhere in this PeopleBook.

   See Creating Routing Definitions.

The next section describes how to activate routings.

Activating and Inactivating Routing Definitions

To activate or inactivate a routing:

1. On the Service Operations component, click the Routings tab.

   The Routings page appears.

2. Check the box in the Select column next to the routing definition names that you want to activate or inactivate.

3. Activate or inactivate the routing definition.

   • To activate the routings, click the Activate Selected Routings button.

   • To inactivate the routings, click the Inactivate Selected Routings button.

4. Click the Save button.

Setting Permissions to Service Operations

This section describes how to use the Service Operations component to set permissions to access service operations. You can also set these permission in the Security component.

Understanding Setting Permission to Service Operations

Security operations are secured using permission lists.

When you select the User/Password Required check box on the Service Operations-General page, on inbound integrations, your integration partners must supply a valid user ID that is associated with the permission list you specify to invoke service operations.

Page Used to Set Permissions to Service Operations

Setting Permission Access to Service Operations

To grant permissions to service operations:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations, and select a service operation with which to work.

   The Service Operations - General page appears.

2. Click the Service Operation Security link.

   The Web Service Access page appears.

3. In the Permission List field, enter a permission list for the service operation, or click the Lookup button to search for and select one.

4. From the Access dropdown list, select an access level for the service operation. Values are:

   • Full Access. (Default.)

   • No Access.

5. Click the Save button.

See Also

Setting Up Permission Lists

Changing the Services with Which Service Operations are Associated

This section discusses how to change the services with which service operations are associated.

Page Used to Change the Services with Which Service Operations are Associated

Changing the Service with Which a Service Operation is Associated

Use the Services Operations page in the Services Administration component to change the services with which service operations are associated. The Services Operations page contains three sections: a Delete section that enables you to delete service operations, a Rename section that enables you to rename service operations, and a Service Change section that enables you to change the service with which a service operation is associated.

Using this page to rename and delete service operations is discussed elsewhere in this chapter.

See Renaming and Deleting Service Operations.

When you first access the Services Operations page, all sections are collapsed. Click the section header arrow buttons to expand and collapse each section.

The following example shows the Services Administration – Service Operations page with the Change Service section expanded:

The service system status that is set on the Service Configuration page affects the ability to change the services that are associated with service operations.

The service system status that you set on the Services Configuration page affects the ability to rename service operations.

See Understanding Configuring PeopleSoft Integration Broker for Handling Services, Setting Service Configuration Properties.

To change the service with which a service operation is associated:

1. Access the Services Administration – Service Operations page.

2. In the Service Operation field, enter a service operation name or use the Lookup button to search for and select one.

   When you select a service operation, the service to which it is currently associated appears in the Service field.

3. In the New Service field, enter the name of the service to associate with the service operation, or click the Lookup button to search for and select one.

4. Click the Change Service button.

Managing Service Operation Versions

This section discusses how to:

• Create service operation versions.

• Use non-default service operation versions.

Page Used to Manager Service Operation Versions

Creating Service Operation Versions

When you create a new service operation version, the new version automatically becomes the active default version.

If you have generated WSDL for the current service operation, after you create the new version you are prompted to generate WSDL for the new version.

To create a new service operation version:

1. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.

   Select the service operation with which to work. The Service Operations–General page appears.

2. At the bottom of the page, click the Add Version hyperlink.

   The Service Operation Versions page appears.

3. In the Service Operations Version field, enter the new version and click the OK button.

   The Service Operations Version page appears.

4. Complete the fields as appropriate for the new service operation version.

   See Defining Service Operation Version Information.

5. Click the Save button.

The new service operation version appears in the Service Operations–General page.

A Non-Default Versions grid appears at the bottom of the page that lists and provides access to the previous service operation version. Note that all versions that display in this grid have a status of Inactive.

Using Non-Default Service Operation Versions

To continue using non-default service operation version you must write and apply transformations to transform message shapes contained in the non-default service operation version to the message shapes contained in the default version.

You need to write and apply transformations only for the changed message shapes. For example, if a service operation contains request and response messages, but only the request message shape has changed between versions, you need only write and apply a transform program to transform the request message on the request message that is contained in the non-default service operation version to the shape of the request message in the default version.

The non-default versions are inactive until the transformations are entered and the status is changed to Active. Then the grid shows the version with Active.

Attaching Files to Service Operations

This section provides an overview of attaching files to service operations and discusses how to:

• Use the FTP Attachment utility.

• Send attachment information with service operations.

• Process attachment information that is included in service operations.

Understanding Attaching Files to Service Operations

PeopleSoft Integration Broker provides an FTP Attachment Upload utility that enables you to upload attachments from any directory to your FTP server and then provide the location of the attachments in service operation PeopleCode. The attachments can be in any file format, such as text files, EDI files, word processing files, and so on.

As the operation is consumed, you can access these attachments using the attachment API. The recipient can get the necessary information about the attachment and can retrieve it using a URL or file location that you provide.

Note. The FTP Attachment Upload utility does not support uploading attachments from the database. To upload attachments from the database, manually retrieve and copy them to the FTP server.

Page Used to Attach Files to Service Operations

Using the FTP Attachment Utility

Use the FTP Attachment Upload page in the Files Utilities component (IB_FILEUPLOAD) to upload files to your FTP server for attaching to service operations. The page is shown in the following example:

You work with the following page elements:

Sending Attachment Information with Service Operations

The following example shows sample PeopleCode for sending attachment information:

Local Message &MSG;
Local Rowset &Flight_Profile;
Local String &Attachment_id;

QE_FLIGHTDATA.QE_ACNUMBER.Value = QE_FLIGHTDATA.QE_ACNUMBER + 1;

&FLIGHT_PROFILE = GetLevel0();

&MSG = CreateMessage (Operation.ASYNC_RR);

&Attachment_id = &MSG.IBInfo.AddAttachment (c:\\temp\\myfile.txt);

&attachReturn = &MSG.IBInfo.SetAttachmentProperty(&Attachment_id, 
     %Attachment_Encoding, "UTF-8");

&attachReturn = &MSG.IBInfo.SetAttachmentProperty(&Attachment_id, 
     %Attachment_Base, "Standard");

&attachReturn = &MSG.IBInfo.SetAttachmentProperty(&Attachment_id, 
     %Attachment_Disposition, "Pending");

&attachReturn = &MSG.IBInfo.SetAttachmentProperty(&Attachment_id, 
     %Attachment_Language, "English");

&attachReturn = &MSG.IBInfo.SetAttachmentProperty(&Attachment_id, 
     %Attachment_Description, "Parts data");

&MSG.CopyRowset (&FLIGHT_PROFILE);

%IntBroker.Publish(&MSG);

Processing Attachment Information Included in Service Operations

The following example shows sample PeopleCode for processing an attachment from a notification:

import PS_PT:Integration:INotificationHandler;

class FLIGHTPROFILE implements PS_PT:Integration:INotificationHandler;
     method FLIGHTPROFILE();
     method OnNotify(&MSG As Message);

end-class;

/* Constructor */
method FLIGHTPROFILE
     %Super = create PS_PT:Integration:INotificationHandler();
end method;

method OnNotify
     /+ $MSG as Message +/
     /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/

     Local Rowset &rs;
     Local integer &count;
     Local string &Attachment_ID &Results;

     &rs = &MSG.GetRowset();

     &count = &MSG.IBInfo.NumberOfAttachments;
     If &count > 0 Then

          &Attachment_ID = &MSG.IBInfo.GetAttachmentContentID(1);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID, 
            %Attachment_Encoding);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID,
            %Attachment_Type);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID, 
            %Attachment_URL);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID, 
            %Attachment_Base);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID, 
            %Attachment_Location);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID, 
            %Attachment_Disposition);
          &Results = &MSG.IBInfo.GetAttachmentProperty(&Attachment_ID,
             %Attachment_Description);

     End-If;
     /* Process data from message */

end-method;

Renaming and Deleting Service Operations

You can rename and delete service operations using the Services Operations page in the Service Administration component. The Services Operations page contains three sections: a Delete section that enables you to delete service operations, a Rename section that enables you to rename service operations, and a Service Change section that enables you to change the service with which a service operation is associated.

Changing the service with which a service operation is associated is discussed elsewhere in this chapter.

See Changing the Services with Which Service Operations are Associated.

To access the page, select PeopleTools, Integration Broker, Service Utilities, Services Administration and click the Service Operations tab.

When you first access the Services Operations page, all sections are collapsed. Click the section header arrow buttons to expand and collapse each section.

The following example shows the Services Operation page with the Delete and Rename sections expanded:

At the top of the page, the Service System Status displays the current setting. The service system status, set in the Services Configuration page, impacts the ability to rename and delete messages.

See Understanding Configuring PeopleSoft Integration Broker for Handling Services, Setting Service Configuration Properties.

Page Used to Rename and Delete Service Operations

Renaming Service Operations

Renaming a service operation is allowed only if the operation is not referenced in any runtime table. If a service operation is referenced in a runtime table, you must archive the data before you can rename the operation.

You cannot rename service operations associated with the restricted services IB_UTILITY and IB_GENERIC .

To rename a service operation:

1. Access the Services Administration – Service Operations page.

2. Click the arrow next to the Rename section header to expand the section.

3. In the Service Operation field, enter the service to rename, or click the Lookup button to search for and select the service operation to rename.

4. In the New Name field, enter the new name for the service.

5. Click the Rename button.

Deleting Service Operations

You can delete service operations individually, with the exception of the default service operation version. If you mark the default service operation for deletion, the system marks all versions for deletion and the entire service operation is deleted.

Note. When you delete a service operation, you are actually deleting a version of a service operation. An service operation cannot exist without at least one default version.

Deleting a service operation is allowed only if the operation is not referenced in any runtime table. If a service operation is referenced in a runtime table, you must first archive the data before deleting the service operation. Use the Service Operations Monitor to archive data.

See Archiving Service Operation Instances.

You cannot delete service operations associated with the restricted services IB_UTILITY and IB_GENERIC .

To delete a service operation:

1. Access the Services Administration – Service Operations page.

2. Click the arrow next to the Delete section header to expand the section.

3. In the Service Operations field, enter the service operation name to delete and click the Search button.

   Search results appear in the results grid.

4. In the results grid, check the box next to the service operation or service operations to delete.

5. Click the Delete button.