Master/Slave domains in Integration Broker.

When dealing within messaging, usually only one domain is configured and most of the time it is enough..

However, if you have to deal with a high number of messages, to process a maximum number of messages, you may want to create multiple domains to handle those messages.

We have to activate it to make this new domain processing messages. Go to Domain status page Change the status and click “update” button, so when you have 2 domains and trying to update both statuses to "ICT" -->

Here we go. An error is raised; we cannot have more than one master domain. And being master is set by default for a given domain.

What is that?

A master domain can be used to balance ingoing/outgoing messages between master and slave(s) domains. Particularly useful when dealing a very high number of messages in a short time.

We can handle it in two ways.

1. Static slave

In the configuration file appsrv.cfg, we can change a parameter value – Domain Slave Mode – from 0 to 1 to make the domain a slave domain.

Reload the application server domain, and coming back to the domain status’ page to make it active.

After updating the status, we can see the domain APPDOM2 activated and also that’s a slave domain. It is fixed, there’s no way to change but modify the configuration file manually and reload again the domain.

Without any failover set, it is probably the easiest way to achieve the goal: handle a high number of messages, you could make multiple slaves domains all managed by one and only master domain.

Using multiple slaves domains can also be useful, you could set a load balance in between all of them (click on “Master/Slave LoadBalance”) to configure all the priorities

2. Dynamic slave

Another way for handling a high number of messages and multiple domains would be to make slave domain dynamic. It is maybe a little bit more tricky, but also probably more reliable and scalable.

A dynamic slave domain can become a master domain in case of failure of the current master domain. Really nice features if the messages have to be processed asap or with a minimum of down-time.

So, consider the second domain APPDOM2 is inactive (it is not set as static slave in the configuration file):

Click on “SetUp Failover”, then check “enable Failover”, define a failover time (when the slave domain has to become master after original master failure, usually 5 minutes) and most importantly check “Dynamic Slave Option”. Finally set a failover priority (1, 2, 3…) and save.

It makes that second domain defined as dynamic slave as shown above in the failover setting as well.

From now, we have two domains which proceed with the messages, given the fact that if the first one fails, the second will become the master.

Hope you find this useful.

Cheers,
Mano

 

Integration Broker Issue Troubleshooting Tips:

1: Unable to Ping a Node 

Possible cause:
  1. the web server for the Gateway is down. 
  2. The Gateway is not configured properly. 
  3. The application server for the node is down. 
  4. The Gateway URL is incorrect; verify that the URL is correct. 
  5. Copy URL in browser address; you should see: \\

2: Message Instance stays in NEW status.
Possible cause: 
1. the pub/sub servers are not booted. 
2. The Item is not at the top of the queue. All messages with the same Channel/ Subchannel are in the same queue 
3. Run appmsgpurgeall.dms 
4. Restart PUBSUB processes 
5. Force clean-up from the monitor message -> domain status 
6. Test your message by routing it through another channel to make sure that it is not an issue with the channel. 

3: Message Instance stays in WORKING status.
Possible cause: 
1. Message Handler has crashed. 
2. The Message Handler processing the message is on another machine, and either the machine or the application server domain is down. The Message handler working on the message is "blocked". The service will timeout, and the Message Dispatcher will retry the message. 

 4: Cannot find message in Message Monitor
Possible causes: 
1. User does not have security for the message channel. 
2. The message monitor criteria have filtered out the message. 

5: Messages are being processed in an incorrect order
Possible cause: 
1. The Channel has been partitioned, and the resulting sub channels do not match what was assumed for the ordering of the messages. 

6: Message Instance not created
possible cause: 
1. Message is inactive. 

7: Publication Contract not created
possible cause: 
1. Channel routing rules not set up properly. 

8: Publication Contract stays in NEW status
possible cause: 
1. Message Channel paused. 
2. Node paused 
3. Previous message had a status of RETRY, ERROR, or TIMEOUT. 
4. The Publication Contract is not at the top of the queue. All Publication Contracts with the same Channel/ Subchannel and subscribing node are in the same queue 

9: Publication Contract stays in WORKING status
possible cause: 
1. The publication handler processing the contract is on another machine and either the machine or the domain is down. Processing should continue when the pub/sub system on the other machine comes back up. 

10: Subscription Contract not created.
Possible causes: 
1. Message Subscription is inactive. 
2. Channel routing rules not set up properly. 

11: Subscription Contract stays in NEW status.
Possible causes: 
1. Message Channel Node or System paused. 
2. Message Definition not Active. 
3. Previous message had a status of RETRY, ERROR, or TIMEOUT. 
4. The Subscription contract is not at the top of the queue. All Subscription Contracts with the same Channel/ Subchannel and subscription owner are in the same queue. 

12: All publication Contracts remain in a NEW status.
The queue was blocked from a Publication Contact that was in a status of ERROR from two weeks prior. User did not see the error on the message monitor because he was only looking at today. User entered xx day in and the ERROR publication appeared. Cancelled the error and all subsequent publication contracts processed successfully. 
Problem: Subscription Contract stays in STARTED status. 
Possible causes: 
1. The Subscription Handler has crashed or has been brought down. 

13: Subscription Contract stays in WORKING status.
Possible causes: 
1. The Subscription Handler has crashed or has been brought down. Check in Application Messaging Gateway Administrator 
2. Also look for any errors in App Serv Log 

14: Subscription Contract in ERROR status.
Possible causes: 
1. Subscription PeopleCode errors 
2. Application data errors. 

15: Subscription Contract in TIMEOUT status.
Possible causes: 
1. Subscription PeopleCode errors 
2. If the message works sometimes, and sometimes does not this may be a problem with the application server configuration. 

16: "Access denied. Target and source message node password's do not match." message even when no passwords are defined on target and source nodes.
Possible cause: 
1. Target application server has entry in Distinguished Name field in source node's message properties. 
2. Target URL must be defined with https:// on target node in source application server. 

17: Unable to ping a node.
Possible causes: 
1. The web server for the Gateway is down. 
2. The Gateway is not configured properly. 
3. The app server for the node is down. 
4. Verify url is correct. Copy url in browser address, should see "PeopleSoft <tools release> Application Messaging gateway".

Create a GET JSON REST API in PeopleSoft

These are the steps necessary to create a JSON REST API. To change from JSON to XML is easy, but I will focus on JSON.

• Create or identify the record that you will be using. I created four records. Three records that will be used for employee data. X_ERROR will be used to place error messages coming from the API.

• Create documents from the records. Each of the records created will be used to create a document.

These are the documents that were created based on records

• Create additional documents to be used in your http GET and POST requests. The documents created from records are not enough to get all the information that you need. In this case I want to retrieve the employee id, name, all her email addresses, and all her phone numbers. To accomplish that, I need create another document. This additional document will use the documents that were created from records.

• Create messages based on documents. I will only create two messages. One to be used as template and the other that will contain the employee data and error messages (if any)

• Create Service. One service needs to be created in which different Service Operations can be added

• Create Service Operation within Service. Once the Service has been saved, Service Operations can be added. In this case I am adding the GET Service Operation. A couple of things to note here. One is the URL that will be used to get the data and the other is the word "nothing" The template needs to have something there. "nothing" is there to identify that nothing will be passed on the template.

• Add Security to Service Operation. This security is a permission list that will access to this Service Operation. Since this is just a demo, I am granting access to PTPT1000 but on a production environment, this will be decided by your favorite security administrator.

• Create application package. The code below is used to populate the data into the message that will be sent to the user.

• Update Service Operation Handlers with the application package. The Service Operation needs to have a request handler.

• Test. Remember thing 1 from the Service Operation image, that is the URL that will be used for testing. In my PUM image, the URL is http://hostname:8000/PSIGW/RESTListeningConnector/PSFT_HR/X_GET_EMPLOYEE_DATA.v1/nothing

Final thoughts. If everything went well, you will have see a nice empty JSON result. If you want to see some data, you can do some insert statements on the three employee records and refresh your page. This URL with the security that was added will always return the PS data because that will be default user. If you scroll back to the Service Operation Image, you will see on the top right that there is a checkbox for User/Password Required. For this demo, that was left unchecked but in practice you should enable at least Basic Authentication and SSL. 

Thanks,

Manoranjan

Document Object in Peoplesoft

RESTful web service uses document type messages in service operations. We need to create message structure in document and then need to create a new message using this structure. Understanding the People Tools Document object is necessary to building REST based web services in People Soft so let's cover some of the basics.

Documents represent a hierarchical data structure a lot like a Rowset object.  They have a logical representation and a physical representation in the form of XML, HTML and JSON (from Tools 8.53).

Documents can be grouped together in a Package and like other Integration Broker object definitions can be versioned.

A document is a tree structure representing data.  As such, every document has ROOT element that is the name of the Document. 

There a four basic data types
*Primitive.  An element that has one of the simple data types of integer, string, character, date, time, etc.

*Compound.  An element that contains 1 or more primitives (think Record definition)

*Complex Primitive Compound.  A primitive element that has attributes. (think XML attributes ElementValue )

*Collection.  An element that is a repeating group of Compound and/or Primitives. (think Rowsets)

A Document is required to collect the inbound URI parameters from a REST web service call.  This is done by mapping the URI parameters to document element names.  This is called the Document Template.

Thanks,
Mano

Ways to access PeopleSoft RESTful Web Services

Well, People soft allows RESTful web services fully starting 8.53. I will post steps to create web services in my next blogs. Today we will see the ways to access Restful web services.

1. SOAP tester Tool
2. Advance REST client
3. CURL command 

Lets focus on CURL command which allows accessing web services from command prompt.

1. Download the CURL.exe from below site(download based on your OS) and place in one working directory.   https://curl.haxx.se/download.html

2. After creating Service Operation, You can get a uri(unique resource identifier) which looks like below.

http://<hostname>:<portname>/PSIGW/RESTListeningConnector/<node>/<service operation>/employee/{EmployeeID}/profile

3. In case you want to add custom header to your request, use -H to add the heaer value.

Curl Command for GET verb with Header: 

curl -i -H "Content-Type: application/json" -X GET http://<hostname>:portname>/PSIGW/RESTListeningConnector/<node>/<serviceoperation>/employee/{EmployeeID}/profile

Curl command for POST verb with header:

curl -i -H "Content-Type: application/json" -X POST -d "{\"myRequestID\": 0,\"myPayType\": \"XXX\",\"myPaySubType\": \"YYY\"}" http://<hostname>:portname>/PSIGW/RESTListeningConnector/<node>/<serviceoperation>/employee/{EmployeeID}/payPost

4. Go to Command prompt, Navigate to the folder where curl.exe is placed. Paste this command and fire. You will get the response with http status code.

This was you can access your webs services if autorization token is not enabled in service operations. If enabled, you need to pass the authorization token in header parameter.

Hope this helps!

Thanks,
Manoranjan

Custom Header in RESTful webservice Peoplesoft

If you are using Restful web services in Peoplesoft, you can set your custom header in response message. Below piece of code helps to set header for response message.

In addition you need to make sure below change to service operation routing tab to read the header from request message IBInfo class and populate the same in response message.

There is a bug with People toolset (8.54.12 or below), for incoming GET request has the capability of capturing the header details in IBInfo class where for POST and PUT, the details are not captured.
As a workaround, you need to modify the RestListeningConnector.class file to capture the header details for POST and PUT as well.

Otherwise ORACLE has already included this fix with next patch (8.54.21). Hope this helps!

Thanks,
Manoranjan

Basic Authorization between PeopleSoft and Third Party Systems

Today, I am going to share few important points on security in case you are integrating Peoplesoft with other system via Web services. (Which I experienced in my recent work)

Let you are integrating Peoplesoft with a third party via Restful/SOAP synchronous web services, we can authenticate the incoming Request to Peoplesoft via basic authentication/PS Token/SSL/None. Below are the steps mentioned in People book for securing your application.

1. Attach Permission list(who has access to Integration Broker) to Service Operation.

2. Set Service Operation page 'Required Verification' to desired one. If you will set the value to  NONE, any of the validation at peoplesoft end will be triggered for incoming request(This was my assumption with Tool version 8.54.12)

So when we set the value to 'Basic Authorization', Incoming message should contain a header with basic Authorization value as 64bit encoded NodeUser:Password

Peoplesoft Node user is validated for each incoming request from third party.

There is a bug with People Tool set that if you will set the value to NONE, still it validates the node user and the request will fail if message does not contain basic authorization header or contain wrong values. You need to do below as a workaround,

1. Customization needed to RESTListeningConnector.class file on web server until Oracle puts a fix in next patch level(those who are in 8.54.12 or below)

2. This connector class searches for string 'BASIC' in incoming message and does validation without checking whether the validation flag is set to NONE or Basic Authorization on service operation page. Either you need to comment this or make conditional check for flag.

After modification to class file, place it in same path and restart the services. Hope this will help people who have faced such issue in their implementation. Good luck !

Thanks,
Manoranjan