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.

• Configure service operation definitions.

• Set permissions to service operations.

• Manage service operation versions.

• Attach files to service operations.

• Assign multiple queues to process inbound service operations.

• Invoke multiple service operations.

• Rename and delete service operations.

Understanding Managing Service Operations

This section discusses:

• Service operations.

• Service operation types.

• Naming conventions for service operation metadata.

• Service operation aliases.

• Service operation versions.

• Monitoring 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:

Naming Conventions for Service Operation Metadata

When naming the following service operation metadata, names cannot start with “xml,” digits or special characters:

• Service operation names.

• Service operation aliases.

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. The previous version of the service operation remains in the database as a non-default version and you still may use that the non-default version.

See Using Non-Default Service Operation Versions.

Monitoring Service Operations

This section describes several options for monitoring service operation performance.

Monitoring Service Operations in the Integration Broker Service Operations Monitor

PeopleSoft provides an Integration Broker Service Operations Monitor that enables you to monitor asynchronous and synchronous service operation information, node status, queue status, manage domains, and more, from within the PeopleSoft Pure Internet Architecture.

See PeopleTools 8.51 PeopleBook: Integration Broker Service Operations Monitor

Monitoring Service Operations in Performance Monitoring Tools Using Module and Action Information

Several system monitoring tools report metrics by capturing Module and Action information. On an Oracle database, PeopleSoft provides service operation name and PeopleCode event name as Module name and Action name respectively. On an IBM DB2 database, PeopleSoft provides service operationname as Module name (no Action information is provided for DB2 systems). This information enables you to associate service operations with database transactions for monitoring and troubleshooting.

To enable capturing service operation and PeopleCode event metrics you must set the EnableDBMonitoring option in PSADMIN.

See Monitoring PeopleSoft MODULE and ACTION Information, Associating PeopleSoft Users with DB2 UDB Threads, Monitoring Module Information.

Accessing and Viewing Service Operation Definitions

This section discusses how to:

• Access service operation definitions.

• 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 Service Operations– Search page 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 drop-down 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 ( PeopleTools, Integration Broker, Integration Setup, Service Operations, the Service Operations - General page (IB_SERVICE) 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, local-to-local, or in the case of feeds, local-to-Atom, 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.

Viewing Handler Information

To view service operation handler information, click the Handler tab. Doing so displays the Service Operations - Handlers page (IB_SERVICEHDLR) which 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 Handler Details page (IB_SERVICEHDLR_SEC) for the handler. The following example shows the Handler Details page:

The Handler 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

Click the Routing tab to open the Service Operations - Routings page (IB_SERVICERTNGS) to view 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.

See Viewing Routing Definitions in Graphical Format.

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

To add a service operation definition:

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

   The Service Operations – Search page appears.

2. Click the Add a New Value link.

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 drop-down 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 service operation information.

• Define service-operations version information.

• Add handlers to service operations.

• Add routing definitions.

• Activate and inactivate routings.

Specifying General Service Operation Information

To specify general service operation information:

1. Access the Service Operations-General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

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. From the Security Verification drop-down list, select the level of security with which inbound integrations must be sent.

   See Validating Security on Inbound Integrations.

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

6. (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 drop-down list box are translate table values that you can define in the OBJECTOWNERID field record.

7. (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. Access the Service Operations - General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

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

   The default is v1.

3. (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.

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

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

6. (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.

   • Click the Multi-Queues link to open the Queue List page and assign multiple queues to process the message.

     The Multi-Queue link appears only when you have enabled the multi-queue feature and when you are working with asynchronous service operations.

     See Assigning Multiple Queues to Process Service Operations.

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 the following about fault messages:

• You cannot add fault messages to asynchronous service operations.

• Fault messages must be nonrowset-based messages or container messages. Fault messages cannot be rowset-based messages.

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

Adding handlers to service operations is discussed elsewhere in this PeopleBook

See Managing Service Operation Handlers.

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.

See Creating Routing Definitions, Using Introspection to Create Routing Definitions, Adding and Configuring Nodes.

To add a routing to a service operation:

1. Access the Service Operations - Routings page (PeopleTools, Integration Broker, Integration Setup, Service Operations, click the Routings tab).

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.

See Also

Managing Service Operation Routing Definitions

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.

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 drop-down 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

Managing Service Operation Versions

This section discusses how to:

• Create service operation versions.

• Use non-default 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

PeopleCode processing for service operation handlers takes place on the default service operation version.

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 so that handler processing of the service operation can occur.

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.

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.

To access the FTP Attachment Upload page, select PeopleTools, Integration Broker, File Utilities, File Upload. 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;

Assigning Multiple Queues to Process Service Operations

This section discusses how to:

• Enable multi-queue service operation processing.

• Specifying multiple queues to process service operations.

Understanding Assigning Multiple Queues to Process Service Operations

You can assign a service operation to multiple queues for unordered processing.

The Service Operations page features a Multi-Queues link that enables you to specify multiple queues to handle inbound or outbound service operations. When you use the multi-queue option, the requests are split across multiple queues.

The Multi-Queues link is enabled only when a message is assigned to an unordered queue.

Before you can use this feature you must enable it in the Service Configuration page.

Enabling Multi-Queue Service Operation Processing

Before you can assign multiple queues to process a service operation, you must enable the multi-queue processing feature on the Service Configuration page.

To enable multi-queue service operation processing:

1. Access the Service Configuration page (PeopleTools, Integration Broker, Configuration, Service Configuration).

2. Select the Enable Multi-Queue box.

3. Click the Save button.

Specifying Multiple Queues to Process Service Operations

When a service operation contains a message assigned to an unordered queue, the Service Operations–General page displays a Multi-Queues. The Multi-Queues link displays in the Message Information section of the page, as shown in the following example:

When you click the Multi-Queues link, the Queues List page shown in the following example appears:

The Queues List page shows the queues assigned to process a service operation. Use Plus button (+) to add new rows and use the Lookup button to search for and specify additional queues to process the service operation. Note that when you use the Lookup button to search for a queue, only those queues that are active and unordered are available to select.

To assign multiple queues to process an inbound service operation:

1. Access the Service Operations–General page (PeopleTools, Integration Broker, Integration Setup, Service Operations).

2. In the Message Information section, click the Multi-Queues link. The Queue List page appears.

3. Click the Plus button (+) to add a new row. A new row appears.

4. Click the Lookup button to search for an select an unordered queue.

5. Repeat steps 3 and 4 to assign additional queues to process the service operation.

6. Click the OK button. The Service Operations–General page appears.

7. Click the Save button.

To remove a queue, click the Minus button (-) next to the queue name to remove. Click the OK button to return to the Service Operations–General page. Then, click the Save button.

Invoking Multiple Service Operations

You can invoke multiple service operations on the receiving system using a single inbound service operation. This process is sometimes referred to as service operation fanout.

Invoking multiple service operations using a single inbound service operation applies to asynchronous service operations only.

To invoke multiple service operations on the receiving system using one inbound service operation, you must specify the name of the inbound service operation in the External Alias field on the routing definition of each service operation on the receiving system that you want to invoke.

The service operations on the receiving system do not need to be assigned to the same queue; PeopleSoft Integration Broker will invoke service operations assigned to different queues.

If the sending system sends in a partition key (using the SubQueue HTTP listening connector or PeopleSoft services listening connector parameter), the receiving PeopleSoft system will honor it. If there is a transformation defined for the service operation, partitioning occurs after the transformation. If the sending system does not send in a partition key, the receiving PeopleSoft system applies partitioning according to the queue definition defined for the service operation.

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.

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.

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.

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

Note. If you delete the default version of a service operation, the system deletes all versions of the service operation.

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.