Registering Interfaces

This chapter provides an overview of the HCM interface registry and discusses how to:

• Manage the HCM interface registry.

• Register new interfaces.

• Implement registered interfaces.

• Consume registered interfaces.

• Maintain the registry folder structure.

• Test services.

• View and register transformation maps.

• Map HCM services to Integration Broker.

Understanding the HCM Interface Registry

The HCM interface registry holds all the interface specifications for available services in the Service Oriented Architecture (SOA). It stores contracts from service providers and provides those contracts to interested service consumers. The service provider registers the interface, the consumer locates the interface in the registry and uses the information to bind and execute the contract between the consumer and the provider, as shown in this diagram:

The service consumer finds an interface in the registry and the registry provides the information necessary to bind and execute the service

The service consumer is an application, service, or some other type of software module that requires a service. It is the entity that initiates the location of the service in the registry, binding to the service over a transport, and executing the service function. The service consumer executes the service by sending it a request formatted according to the contract.

The service provider is the service, the network-addressable entity that accepts and executes the requests from consumers. It can be a mainframe system, a component, or some other type of software system that executes the service request. The service provider publishes its contract in the registry for access by service consumers.

To set up and use an interface registry:

1. Set up the interface contract and register the interface using the Registration Wizard (Setup HRMS, System Administration, HCM Registry, Registry Wizard).

2. Implement the interface in the providing application.

3. Set up the consuming application to invoke registered interfaces.

Setting Up Interface Contracts

An interface contract specifies the way a consumer of a service will interact with the provider of the service, including the format of the request and response from the service. The HCM registry is populated with the existing interface contracts within HCM. To add new interfaces to the registry, you must first define the contract between the services.

To define an agreement between services, follow these steps:

1. Determine the interface details (such as signature, exceptions, and warnings).

2. Register the interface under the provider object identifier.

3. Set the interface status to Active.

Note. Register interfaces using the HCM registry's Registration Wizard.

Interfaces fall into one of the following categories:

• Services

  • Synchronous request/response (services)

    Services interfaces are procedural invocations and can be local and remote.

  • Asynchronous publish/subscribe (events)

    Events can be notifications (outbound) or consumption (inbound) and are based on messaging and integration points.

• sqlViews (views)

  Views are read only and are SQL-based.

• Types

  Types represent the complex data types used in service invocations. The following types are supported for service invocations in API:

  • Primitives (native PeopleCode data types), such as string, date, number, boolean, hexbinary, and arrays.

  • Complex types, as defined in the registry or arrays of any complex type.

  Note. While you can use all primitive types in service invocations natively, all complex types must be explicitly defined and registered in the registry.

• Exceptions

  Exceptions are fatal errors that can occur during service execution and require special handling by the PeopleCode program. Service providers must identify exceptions that they believe can occur so that the consumer code can manage the exception.

  Define exceptions and register them in the interface registry.

Managing the HCM Interface Registry

To mange the HCM interface registry entries, use the Service Registry component (HMCR_IFC_REGISTRY).

This section discusses how to:

• Register and maintain SOA interfaces.

• Use the HCM interface registry.

• View WSDL code for registry folders.

• Review registry folder audit results.

• Review registry and interface details.

• View WSDL or XSD code for registry entries.

• View RegistryDoc.

Pages Used to Manage the HCM Interface Registry

Using the HCM Interface Registry

Access the Service Registry page (Set Up HRMS, System Administration, HCM Registry, Service Registry, Service Registry).

The registry lists all the content owners and their interfaces in a tree format. Each tree leaf represents a registered interface. Registered interfaces are grouped by interface folders. Click a registered interface to review interface information on the Details page.

Searching the Registry

Use the Search capability to look up a registry when:

• You do not know the exact name for or the navigation to the service, sqlView, type, or exception.

• You want to search for the descriptions for a specific word or pattern of a word.

Viewing WSDL Code for Registry Folders

Access the <Registry Folder Label> page (click an interface folder on the Service Registry page).

Use the View WSDL group box to review the WSDL that the system generated for the selected registry folder. Click the Run Audit button to run an audit on the registry folder. The system displays the Audit - <Registry Folder Label> page for you to review the results of the registry folder audit.

Reviewing Registry Folder Audit Results

Access the Audit - <Registry Folder Label> page (click the Run Audit button on the <Registry Folder Label> page).

Reviewing Registry and Interface Details

Access the Interface Registry - Details page (click a link under the Services, sqlViews, Types, or Exceptions interface folders on the <Registry Folder Label> page).

Note. The Interface Registry - Details page is slightly different for each type of interface (services, sqlViews, types, and exceptions).

Registry Details

Interface Details

Interfaces are defined using an XSD schema. The schema for each interface type is stored in the registry. The system generates the schema during registration.

Note. The schema defines the details of sqlView interfaces, not the database view that implements the view interface. The database view must match the properties defined in the schema.

Service interface types have operations called DoServices. A DoService has one or more input, output, and outfault element and each element is defined by either one or more simple or complex type.

Exception Details

Review a service interface's exception details and the associated messages.

Implementation Details

In the Implementation Details group box, review the fully qualified application class path that implements class for this type or exception. The class path includes a branch indicating the version of this type. The version attribute of the registry entry must match the version in the class path of the type class.

Note. For sqlView interfaces, the Implementation Details box displays the database view implementing the interface view.

Note. All exceptions must extend the class baseException, which extends the PeopleTools built-in exception class.

Viewing WSDL and XSD Code for Registry Entries

Access the <Registry Entry Name> page (click an interface for a service on the <Registry Folder Label> page, and then click the Show WSDL button, or click an interface for a type or exception, and then click on the Show XSD button).

Viewing RegistryDoc

To view RegistryDoc, click the Generate Registry Doc button on the Service Registry page. The system generates the RegistryDoc and displays the View RegistryDoc link.

Click the View RegistryDoc link. The system opens a new browser window, which displays the registry API content in HTML format.

The page contains three frames. The upper left frame lists the root packages within the RegistryDoc. Click a link for a root package in the upper left frame to view for a list of all of the services, sqlViews, types, and exceptions that are associated with the selected root package. The system displays the details of the selected root package within the lower left frame. The right frame displays the services, sqlViews, types, and exceptions for all root packages.

Click a link in the lower left frame or the right frame to view service, sqlView, type, or exception details.

From a service details page, click on the View WSDL link to view WSDL code for the selected service.

If a service or type refers to another complex type or exception, click on the type link on the details page to view type or exception details.

Registering New Interfaces

To register new interfaces, use the Registration Wizard component (HMCR_WZ_REGSRV).

This section discusses how to:

• Enter interface information in the Registry Wizard.

• Enter interface specifications.

• Implement the interface.

Pages Used to Register New Interfaces Through the Registration Wizard

Entering Interface Information in the Registry Wizard

Access the Registry Information page (Set Up HRMS, System Administration, HCM Registry, Registration Wizard, Registry Information).

Type	Select the interface type. Note. The pages in this component and the information you enter can vary depending on the type of interface you select here.
Name	Enter a meaningful name for the interface using the following guidelines: One word (no spaces). Mixed case. In one of the following formats, depending on the interface type: in the format, <Noun>Exception, <Noun>Service, or <Noun>sqlView, depending on the type of interface you are registering. For Type interfaces: <Noun>Type. For Service interfaces: <Verb><Noun>. For Exception interfaces: <Noun>Exception. For Interface Views: <Noun><Noun>. Note. Users see the name you enter here on the registry tree so make sure that the name is clear and meaningful.
Version	Indicate the interface version using the format n.n. You can have multiple active versions of an interface.
Status	Select the status of this version of the interface: Requested The interface has been requested by a party but has not been implemented. In Work The interface is currently being defined. Active The interface is ready for use. Deprecated The interface has been replaced by a more current version, but is still supported. Retired The selected version of the interface has been retired.
Object owner identifier	Select the interface provider.
Scope	Indicate if the interface is Public (available to everyone) or Private (available only to the provider application).
Select parent folder	Click this link to access the registry folder structure and select the folder within which the new interface will reside. Group interfaces by feature.

Entering Interface Specifications

Access the Interface Specification page (Set Up HRMS, System Administration, HCM Registry, Registration Wizard, Interface Specification).

Note. The system displays a different version of this page depending on what type of interface you're registering. See the Registering Services section for information on how to use this page to register service interfaces.

Registering Services

When you register a service, enter the follow information in the four group boxes:

• DoService Request

  When a service interface will be used to request information, use the fields in this grid to define the service's request parameters.

• DoService Response

  When a service interface will be used to respond to requests for information, use the fields in this grid to define the service's request parameters.

• Exceptions

  List all of the exceptions defined for the service interface. You can only select exceptions that have already be added to the registry.

• Warnings

  List all of the warnings and messages that could be logged during the execution of the service and that are meaningful to the consumer.

Implementing the Interface

Access the Implementation page (Set Up HRMS, System Administration, HCM Registry, Registration Wizard, Implementation).

Note. The system displays a different version of this page depending on what type of interface you're registering. See the Registering Interface Views section for information on how to use this page to register interface views.

Registering Interface Views

Implementing Registered Interfaces

After you have registered the interface, implement it in the providing application. The providing application must implement the interface accurately so that the consumer application does not encounter any unexpected behavior.

This section discusses how to:

• Implement types.

• Implement services.

• Implement exceptions.

• Implement SQLViews.

Implementing Types

To implement a registered type interface:

Note. Implement registered types as PeopleCode application classes.

1. In Application Designer, create an application package for each functional module using the naming convention <NAMESPACE_PREFIX>_TYPES.

   Use the first level sub-package to group implementation classes by function and the second level to group classes by versions.

2. Create the application class that is implementing the interface type.

   When you create the application class, you must ensure that it:

   • Extends the baseType class.

   • Imports the package with the baseType parent class definition.

   • Exposes a read-only property IUD with the type string.

   • Has a IUD property that contains the correct IUD of the corresponding registry entry.

   • Instantiates any array properties defined in the class as array properties with 0 elements.

   • Implements the following mandatory public methods: toXmlNode, toXmlNodeString, fromXmlNode, and truncateType.

3. Copy the stub code the system created when you clicked the Generate Class Code button on the Registry Wizard - Implementation page for this interface and paste it into the application class implementing the interface type.

   The generated type stub code includes the following mandatory methods:

   method toxmlNode(&parentNode As XmlNode);
                   
   method fromXmlNode(&parentNode As XmlNode);
                   
   method toXmlNodeString(&nodeName As string) Returns string;
                   
   method TruncateType();

   The system uses the XML mandatory methods to marshal and unmarshal the type to or from an xml representation, which is required in order to use this type in a remote service invocation. The truncateType mandatory method resents the value of all type elements.

4. Access the registry entry for the type interface in the Registry Wizard and add the application class to the type's implementation details.

Implementing Services

Consumer programs cannot directly instantiate service implementation classes. Due to late binding and remote procedure call support, the framework delays the resolution of the implementation class name until run-time so the only information available to service consumers during design is the interface name.

At run-time, the service manager resolves the interface name into the implementation class name using the registry lookup functionality. Depending on the implementation details defined in the registry, the service manager will return to the consumer either an instance of a local implementation class or a proxy class for the remote implementation.

Because of these considerations, the providing application needs to supply the following two application classes to fully implement a service:

• An interface that consumer applications can refer to during design.

• An implementation class that the service manager can bind to during run-time.

Note. Implement registered services as PeopleCode application classes.

To implement a registered service interface:

1. In Application Designer, create an application package for each functional module using the naming convention <NAMESPACE_PREFIX>_SERVICES.

   Use the first level sub-package to group implementation classes by function and the second level to group classes by versions. Use the third (application class) level to define an interface and an implementation for the service.

2. Create two application classes to implement the service, an interface and an implementation class.

3. Select the registry entry for this service and click the Generate provider Code button. The system displays a page with three group boxes containing code:

   • Interface peoplecode

     Copy and paste the interface PeopleCode into the interface application class.

   • Implementation peoplecode

     Copy and paste the implementation PeopleCode into the implementation application class. The implementation code generated is only a skeleton the actual logic for the application class. The development team must therefore modify the implementation class to meet the providing application's needs.

   • Proxy peoplecode

4. Confirm that the interface and implementation classes contain the necessary information.

   The two applications serve different functions. The interface class is an abstract definition and details what methods and properties the implementation class will have to have to comply with registered specifications, but it does not contain the implementation details. The implementation class actually implements the interface, providing the executable code for the abstract method definitions.

   The interface application class must:

   • Have names identical to the name of the registered service.

   • Extend the baseService class.

   • Imports the baseService parent class definition.

   • Contain a constructor method that creates an instance of the parent baseService class.

   • Define an abstract DoService method with the signature matching the signature of the registered service.

5. Confirm that the implementation of the service:

   • Implements the interface.

   • Provides a concrete implementation of the DoService method.

     When a development team decides to provide a service, they create an interface and implementation class that implements it.

   • Imports the interface that it implements, as well as the types and exceptions it is working with.

     This happens once you generate the provider code.

   • Throws exceptions in accordance with the registered interface contract in order to handle errors.

   • Can log warnings in accordance with the interface contract.

     The interface application class provides details of all warnings that were generated when the service was executed.

   • Uses the API2CI framework to abstract from the component interface specifics, if the implementation is component interface-based.

     Component interface-based services need to import the CI library (which is provided with the registry) using this code:

     import HMCR_API2CI

     If you are using a DoService method, you need to declare two local objects: ciHandler and ciIdent. ciHandler is the class managing all access to a component interface since you cannot directly manipulate a component interface. ciIdent defines the unique attributes of each ciHandler instance.

6. Access the registry entry for the service interface and add the implementation application class to the type's implementation details.

Note. You can use services to organize multiple other services to execute an business task. This is called aggregating services. The aggregating service is the service responsible for managing the business transaction, housekeeping, and performing the save professing so these processes are run only once, improving overall performance. When a service is running another service in aggregation mode, the calling service (the aggregating service) sets the RunAggregated flag on the called service, causing the called service to skip the housekeeping and save processing.

Implementing Exceptions

PeopleSoft delivers a baseException class providing the default exception handling, which is on the PeopleTools exception class. The baseException class constructor takes the following parameters:

• An instance of a service log.

• A message set number and message number.

• Default message text.

• Message parameters 1–5 or "Null" when none.

The base Exception class constructor executes the following logic:

• Adds PSMessages collection to the service log.

• Creates a PeopleTools exception for the provided message set and message number.

To implement a registered type interface:

Note. Implement registered exceptions as PeopleCode application classes.

1. In Application Designer, create an application package for each functional module using the naming convention <NAMESPACE_PREFIX>_EXCEPTIONS.

   Use the first level sub-package to group implementation classes by function and the second level to group classes by versions.

2. Copy the stub code the system created when you clicked the Generate Class Code button on the Registry Wizard - Implementation page for this interface and paste it into the application class implementing the exception.

3. Confirm that the exception implementation contains the following:

   • A link to an entry in the PeopleTools message catalog.

   • Default error processing.

   • Exception-specific error processing, where necessary.

   Note. The exception's registry entry defines the exception name, the fault message structure, and the exception semantics (description).

4. Confirm that the implementation of the exception class:

   • Name is identical to the registry entry name.

   • Extends the baseException and import the baseException class definition.

   • Contains a constructor that:

     — Takes an instance of a LogType as a single parameter and imports the LogType class definition.

     — Facilitates the default error processing by wan of an instance of a parent class.

     — Assigns the correct IUD of the corresponding registry entry to its IUD property.

   • Exposes a read-only property IUD with a type of string.

Implementing SQLViews

To implement a registered sqlView interface:

Note. Implement registered sqlView interfaces as PeopleSoft record definitions with a type of view.

1. Create fields on the record definition to correspond to each field in the registered sqlView interface.

2. Run SQL Create to create the view in the database.

3. Open the sqlView registry entry and add the implementation record name to the registry entry.

   When you are creating a new interface view, you must use the Registry Wizard component. When you are updating an existing view, you must use access the registry and click the Update button. The system then displays the Registry Wizard component.

   See Registering New Interfaces.

Consuming Registered Interfaces

This section provides an overview of registered interface consumption and discusses how to:

• Invoke service interfaces.

• Set up stale data checks in service calls.

• Pool component interfaces.

• Consume collection-sized interfaces.

• Bind complex types to and from portal pages.

• Consume SQLViews.

Understanding Registered Interface Consumption

If there is an interface in the registry that your application needs to use, you must create code in PeopleCode events in the consuming application to invoke the interface.

Note. You can click the Generate Consumer Code button on the Registry Details page for the registered service to generate all the code the consuming application needs. Cut and paste the code into the consuming application's PeopleCode Event (for example, SavePostChange PeopleCode). Confirm that the generated code meets the criteria set out in these steps and make any necessary modifications.

Note. You can only place the code for manipulative services such as Set, Add, or Delete in the SavePostChange PeopleCode of a single field in a component. You cannot spread out manipulative service calls over several PeopleCode events. You must also not place manipulative service calls in FieldChange PeopleCode.

Invoking Service Interfaces

Consuming applications invoke service interfaces in four steps:

1. Import, declare, and create framework classes, service classes, and type classes.

2. Bind to the service implementation using the Service Manager's LocateService method.

   At runtime, the Service Manager determines the appropriate implemented interface application class and returns an instance of it to the consuming application for invocation as follows:

   1. The import statement in the consumer code indicates which registered interface is required.

   2. The registered interface contains information about which implemented interface class is required.

   3. The Service Manager's LocateService method returns an instance of the implementation class.

      Note. The LocateService method requires the service name and the service version in order to bind to the appropriate service.

   The consumer code only needs to know which registered interface it is using. The provider application specifies which implemented class should be returned to the consumer. This enables the provider to make changes to the implemented interface without impacting the consumer.

3. If you are invoking a type interface, the consumer application needs to set the properties of the type class in the input parameters prior to passing it to the DoService call.

   The type interface registry entry describes the properties of the type class. The consumer can map properties individually from the consuming application to the type class properties.

4. Invoke the DoService method of the service implementation class, passing the parameters as defined in the service signature.

   The service signature defines the zero or more input and output parameters that need to be passed to the service. Parameters can be simple types (such as string, number, date, or boolean) or complex types defined and registered as types in the interface registry:

   • When the service requires complex types as parameters, the consumer needs to import the type class, declare it as a local variable and instantiate it using the Create instruction.

   • When the service requires simple types, the simple types only need to be declared by the consumer.

5. Catch and manage exceptions.

   The consumer code must invoke all services within a try-catch block. All code executed in between the try and the catch statement is in a protected area so that any exceptions thrown during service execution will immediately return control to the catch statement in the consumer code. The consuming application can then react to the exception.

   The consumer code can catch specific exceptions or the baseException, which is the parent class to all registered exceptions.

   Note. The consuming code should always catch for baseException to catch exceptions not specific to the service.

6. Analyze the service execution log for relevant information.

   During service execution, the registry framework collects all warnings and messages issued by the provider and exposes them to the consumer as a service execution log. The consumer can query the execution log and take action based on the warnings and messages, if necessary.

   Each service has a property called ExecutionLog. The property has an array of LogType called Log. The LogType has the following attributes:

   • DEFAULT_TEXT

   • MESSAGE_SET_NBR

   • MESSAGE_NBR

   • MESSAGE_SEVERITY

   The service's Log class has a generic method ShowLog() to display the content of the execution log.

Note. All consumer PeopleCode runs within the scope of a consumer component session. Any services that the system invokes during the component runtime will also run within this transaction scope. If the service execution encounters fatal errors, the system will roll back the entire component transaction unless the errors are specifically caught as exceptions. For example, if the a component in the consumer application uses two services invoked by the SavePostChange PeopleCode and one executes successfully while the other throws a fatal error, the system will not save any data to the component from either service.

Setting Up Stale Data Checks in Service Calls

If the service call is updating the component in the consumer application with an action of Add, you do not need to set up a check for stale data and you can invoke the service in Component.SavePostChange PeopleCode..

However, if the service is to update prior selected data, you need to set up a stale data check to ensure that the underlying data has not been modified during user interaction on the consumer side. To do this, create a Get service in the Component.PostBuild PeopleCode and a Set service in the Component.SavePostChange PeopleCode.

If the registry detects a discrepancy in the data, it will cause an error, which can be caught using baseException.

Pooling Component Interfaces

Several services may use the same instance of a component interface in their implementations. To improve performance, you can pool component interfaces. Component interfaces must be scoped to one local PeopleCode event, but within that event the code can send several calls to services using the same open component interface.

The system then passes the component interface pool to the Service Manager's LocateService method. If a requestor is only issuing one service call in a Peoplecode Event, the system passes NULL as a component interface pool.

Consuming Collection-Sized Services

You can set up services to operate on items or on collections (row sets). If the consuming application is working with a collection of rows, you must set up the consuming application to pass the entire collection to the service. The service removes any items that are not passed into the service in the collection. If consumer passes an empty collection, it will effectively remove all the data rows in the provider implementation.

Use a collection-sized Get service to populate the collection type class, manipulate it, and pass it back to the Set service.

Binding Complex Types To and From the Portal Pages

All services work with simple or complex types as parameters. Simple types are available as PeopleCode data types. The provider application implements complex types as application classes. It is not possible to view application class properties directly on a page so it is necessary for the consumer application to create pages based on Rowset.Row.Record.Field objects and map the type class properties to the fields.

In the consumer code, set up a call to the helper method PopulateToRowset to bring all data from the type class instance to the user interface of the consumer component. Set up a call to the helper method PopulateFromRowset to bring all values from the rowset used in the user interface of the type class.

Note. Not all type classes provide helper methods and not all helper methods will work in all consumer components. In these cases, you will need to write your own logic to bind the type class values to the consumer user interface.

Consuming SQLViews

Consuming applications can use registered sqlViews directly without binding. Use registered sqlViews for the following:

• Search views.

• Prompting.

• Related display.

Maintaining the Registry Folder Structure

To administer the HCM interface registry, use the Administer Service Registry component (HMCR_CONTENT_ADMIN).

This section discusses how to maintain the registry folder structure.

Page Used to Maintain the Registry Folder Structure

Maintaining the Registry Folder Structure

Access the Administer Service Registry page (Set Up HRMS, System Administration, HCM Registry, Administer Service Registry, Administer Service Registry).

Create Folders

To create a new folder, select Create Folder in the Operation field and enter the folder's registry details.

Delete Folders

To delete a folder, select Delete Folder in the Operation field. Expand the registry tree, locate the folder you want to delete, and click on it. You cannot delete a folder that contains registered interfaces within one if it's child folders.

Testing Services

To test newly created services, use the Service Tester component (HMCR_SRV_TESTER).

This section discusses how to test services.

Page Used to Test Services

Testing Services

Access the Service Tester page (Set Up HRMS, System Administration, HCM Registry, Service Tester, Service Tester).

Use this page to test newly created services through a generic component. For example, if you create a new service using the Registration Wizard component and the corresponding implementation code, you can use this page to test the service and ensure that service you are committing works as designed. The system returns the results of the service test in a new window as XML.

Viewing and Registering Transformation Maps

To view transformation maps, use the Transformation Registry component (HMTF_TRF_REGISTRY). To register transformation maps, use the Register Transformation Map component (HMTF_WZ_TRF).

This section discusses now to:

• View transformation maps.

• Register transformation maps.

Pages used to View and Register Transformation Maps

Viewing Transformation Maps

Access the Transformation Registry page (Set Up HRMS, System Administration, HCM Registry, Transformation Registry, Transformation Registry).

Use this page to view details of transformation maps, which instruct the system to convert incoming messages (From) into (To) a specific format. Primarily this is done because, between release, the record definitions may have undergone a change.

Registering Transformation Maps

Access the Register Transformation Map page (Set Up HRMS, System Administration, HCM Registry, Register Transformation Map, Register Transformation Map).

When you need to exchange information between two different release of a PeopleSoft Enterprise product you must perform transformations. With each release record definitions sometimes undergo changes. Transformations enable you to scale these problems by transforming messages from one release to another. Use this page to create transformation maps for messages from one release to another and from one version to another.

Mapping HCM Services to Integration Broker

This section provides an overview of HCM service mapping to Integration Broker and discusses how to:

• Map HCM services to Integration Broker.

• Delete mapped services.

• Use Integration Broker to provide web services.

Understanding HCM Service Mapping to Integration Broker

You can invoke HCM services from remote (non-PeopleSoft) systems. The SOA framework contains built-in functionality to process an incoming requests (services) and return the required response. This built in functionality gives you the ability to:

• Generate a web service automatically.

• Publish WSDL to the PeopleSoft repository.

• Publish WSDL to UDDI.

• Synchronize Integration Broker services with the Integration Services Repository (ISR) automatically.

PeopleTools Integration Broker serves as the transport mechanism for services. By mapping your HCM services to Integration Broker, you ensure that your Service Registry conforms to industry standards.

Mapping HCM Services to Integration Broker

This section discusses how to:

• Map an HCM Interface Registry folder to an Integration Broker service.

• Map an HCM service to an Integration Broker service operation.

• Map interface details.

• View service operation security.

• View service operation handlers.

• View service operation routings.

Mapping an HCM Interface Registry Folder to an Integration Broker Service

Initiate the mapping of HCM services to Integration Broker through the HCM Interface Registry. The system permits mapping at only third level folders, which are the lowest sub-categorization of HCM services for products.

To map the HCM Interface Registry metadata for a particular folder to an Integration Broker service:

1. Click the folder name link on the Service Registry page for a third level folder.

   The system displays the WSDL for that registry folder.

2. Click the Add to service repository button to add to the service repository.

   Provided that you have set up Integration Broker, the system displays details of the service.

   Note. The Delete from service repository button is available only when you have mapped the registry folder to the Integration Broker service repository, at which time the Add to service repository button becomes unavailable. This ensures that you can only perform the correct action.

The system automatically generates an Integration Broker service name for the folder. This service name is the IUD for the folder, which is unique string within the HCM Interface Registry and thus guarantees that each service has a unique name. Optionally, you can rename the Integration Broker service to give it a more meaningful name through the Service Administration component (PeopleTools, Integration Broker, Service Utilities, Service Administration). If you rename the service, the system still guarantees a unique name because the Service Alias field contains a copy of the IUD service name. This ensures that the delete process has a means of correlating the service with the HCM Interface Registry.

Note. Do not change the Service Alias field under any circumstances because it is critical to service delete processing.

Mapping an HCM Service to an Integration Broker Service Operation

Each HCM service that is in a registry folder on the Service Registry page is mapped to an Integration Broker service operation and can be found in the service that you have generated for the folder on the Services page (PeopleTools, Integration Broker, Integration Setup, Services). The system uses the name of the HCM service as the name for the service operation, unless that service operation already exists. If the service operation does already exist, an algorithm works within the length constraints of the Service Operation Name field (30 characters). The algorithm replaces the endmost characters with digits until it generates a unique name. The system retrieves the version for the service operation from the HCM Interface Registry.

Mapping Interface Details

The system maps each input and output interface to an integration Broker non-rowset based message, complete with generated schema. The system also assigns the version from the HCM Interface Registry. The base name for the messages is the HCM service name plus the suffix _IM or _OM to designate input or output interfaces, respectively (for example, ADDPOITYPE_IM) .

The system maps outfault interfaces to Integration Broker non-rowset based part messages. This is due to the limitation of Integration Broker having only one fault message per service operation. Therefore, the system creates all outfaults that are associated with a mapped HCM service within an Integration Broker container message. The system indicates outfault messages by using the suffix _FM (for example, ADDPOITYPE_FM).

Viewing Service Operation Security

The system assigns each service operation that you generate the standard HCSPSERVICE permission list. Access the permission list details for the web service on the Web Service Access page (PeopleTools, Integration Broker, Service Operations, General, click the Service Operation Security link).

Viewing Service Operation Handlers

The system assigns a handler to each service operation that you generate. The assigned handler references a generic handler class that is processing the incoming request, and generates the required response. The generic handler is HMCR_FRAMEWORK:IB_Framework:Handlers:IB_SyncRequestHandler. Access handlers for service operations on the Handlers page of the Service Operations component (PeopleTools, Integration Broker, Integration Setup, Service Operations).

Viewing Service Operation Routings

Within the HCM Registry there is no indication of consumers for a given service, so the system does not generate routings during the mapping process. It is up to the development teams to create the necessary routings.

Deleting Mapped Services

Use the Service Registry to delete HCM services that you have mapped to Integration Broker. The system makes available the Delete from service repository button in the Service Registry only for folders that you have already added to the Integration Broker metadata.

The delete process removes the following objects from the Integration Broker metadata:

• WSDL

• Services

• Service operations

• Service operation security

• Service operation handlers

• Service operation routings

• Messages (input, output, fault container, and part)

• Message schemas

Using Integration Broker to Provide Web Services

One main reason for mapping HCM services to Integration Broker is to use Integration Broker's capability of providing web services. You can provide a web service only for service operations that you define as having any-to-local routing. You create these service operations, along with their handlers and routings, in the Service Operations component.

To set up any-to-local routings for service operations:

1. Access the Service Operations component (PeopleTools, Integration Broker, Integration Setup, Service Operations).

2. Select the Generate Any-to-Local check box in the Routing Actions Upon Save area of the General page.

3. Save the component.

   The system updates the Any-to-Local value of the Routing Status area to Exists.

   The system also generates the routing and displays it on the Routings page of the component.

You can publish as a web service any service that has at least one service operation defined as any-to-local.

To publish a qualifying service as a web service:

1. Access the Provide Web Service component (PeopleTools, Integration Broker, Web Services, Provide Web Service) to launch the Provide Web Service Wizard.

   The system displays the Select Services page.

2. Search for the service that you wish to publish as a web service.

3. Select that service in the returned search results, and then click the Next button.

   The system displays the Select Service Operations page.

4. Select the service operation for the service that you want to publish as a web service, and then click the Next button.

   The system displays the View WSDL page.

5. Click the View WSDL link for a service to view the WSDL that the system generated for the service.

6. Return to the View WSDL page and click the Next button.

   The system displays the Specify Publishing Options page.

7. Define where to publish the selected services.

   Select the Publish to UDDI check box or the WSDL Repository check box to publish the services to the corresponding location.

   The system displays the Provide Web Service - Results page.

8. View the WSDL generation log to confirm the results of the wizard.