Connecting to the Apply API

This section describes additional procedures so you can connect to the Apply API as well as troubleshooting information.

You need to set up these elements to ensure that you can connect to the Apply API.

Updating the REST Base URL

  1. Go to PeopleTools > Integration Broker > Integration Setup > Service Operations.

  2. In Service Operation, search for SAD_UC_DFE_APPL_GET.

  3. Click Search.

  4. In the results, click the service operation name.

  5. In REST Base URL, provide the new URL.

  6. Click Save.

  7. Repeat steps 2 to 6 for SAD_UC_DFE_APPL_POST and SAD_UC_DFE_APPL_V1_1_POST.

Configuring the Routing Definition

You must set up the routing to connect to the API.

  1. Go to PeopleTools > Integration Broker > Integration Setup > Routings.

  2. Click Add New Value.

  3. In Routing Name, enter SAD_UC_DFE_GET_APPL.

  4. Click Add.

  5. From the Routing Definitions page, provide these values:

    • Service Operation: SAD_UC_DFE_APPL_GET

    • Version: This field is automatically populated when you select the service operation.

    • Description: DFE Get Applications

    • Sender Node: Select the local node for the environment.

    • Receiver Node: WADL_NODE

    • Owner ID: Admissions — UK

  6. Click Parameters.

    1. In Outbound Request, Message.Ver into Transform 1, remove any value (if there’s any).

    2. In Inbound Response, Message.Ver out of Transforms, remove any value (if there’s any).

  7. Click Connector Properties.

    1. In Gateway ID, enter LOCAL.

    2. In Connector ID, enter HTTPTARGET.

    3. In Delivery Mode, select Guaranteed Delivery.

    4. In Connector Properties, delete any rows with values.

  8. Click Save.

  9. Repeat steps 3 to 7 for:

    • Routing Name: SAD_UC_DFE_GET_POST

    • Service Operation: SAD_UC_DFE_APPL_POST

    • Description: DFE Post Applications

  10. Repeat steps 3 to 7 for:

    • Routing Name: SAD_UC_DFE_APPL_V1_POST

    • Service Operation: SAD_UC_DFE_APPL_V1_1_POST

    • Description: DFE Post Applications v1.1

    In step 6, update External Alias to SAD_UC_DFE_APPL_V1_1_POST.v1.

Configuring the Gateway

  1. Go to PeopleTools > Integration Broker > Configuration > Gateways.

  2. In Integration Gateway ID begins with, enter LOCAL.

  3. Click Search.

  4. From the Gateways page, click Gateway Setup Properties.

  5. Enter your user ID and password.

  6. Click Advanced Properties Page.

  7. In Gateway Properties, scroll to the end of the box and look for UseDomainName.ExternalOperationNames.

    The line looks similar to this: #ig.UseDomainName.ExternalOperationNames=MYSOP1.v1,MYSOP2.v1.

  8. When you locate the line:

    • Remove the hashtag.

    • Replace MYSOP1.v1,MYSOP2.v1 with: SAD_UC_DFE_APPL_GET.v1,SAD_UC_DFE_APPL_POST.v1,SAD_UC_DFE_APPL_V1_1_POST.v1

    It should look like this: ig.UseDomainName.ExternalOperationNames=SAD_UC_DFE_APPL_GET.v1,SAD_UC_DFE_APPL_POST.v1,SAD_UC_DFE_APPL_V1_1_POST.v1

  9. Click OK.

  10. On the PeopleSoft Node Configuration page, click Save.

  11. On the Gateways page, click Save.

Testing Your Connection

  1. Go to PeopleTools > Integration Broker > Service Utilities > Service Operation Tester.

  2. In Service, enter SAD_UC_DFE_API.

  3. Click Search.

  4. From the results, click the service operation name.

  5. From the Service Operation page, click Populate Document Template.

  6. From the URI Template Builder page, click since.

  7. From the Set Value page, in Long, enter 2020-01-01T10:00:00Z.

  8. Click OK, then click Return.

  9. Click Invoke Operation.

    You may get a 401 unauthorized error message. This is okay; it means that a connection to the Apply API was successfully established.

Here’s what you can do when you see these errors.

HTTPS Hostname Wrong

To resolve the error logged as Integration Gateway - External System Contact Error (158,10721), update your gateway configuration. See Configuring the Integration Broker, “Configuring the Gateway.”

Untrusted Server Certificate Chain

To resolve this issue, you must upload the DFE API root certificate to your web server keystore.

Note: These steps assume you’re using Firefox as your browser. If you use another browser, you may have to determine the corresponding steps.

  1. On your browser, enter the REST base URL in the address field, then press Enter.

    This is the same URL you used in “Updating the REST Base URL.”

  2. In the URL field where you entered the REST base URL, click the lock icon. This icon is located on the left of the URL.

  3. In Connection, click the arrow to show connection details.

  4. Click More Information.

  5. From the window that appears, click View Certificate.

    The Certificate Viewer appears.

  6. Click Details.

  7. In Certificate Hierarchy, select the topmost certificate: GlobalSign Root CA - R3.

  8. Click Export, then save the certificate to a place in your hard drive.

    If necessary, save the certificate as GlobalSign Root CA - R3.crt.

  9. Using an FTP client, upload the certificate to your web server keystore folder. This is the path: /opt/oracle/psft/pt/cfghome/webserv/peoplesoft/piaconfig/keystore.

  10. Using PuTTY, import the certificate to your keystore folder. Enter this on the command line:

    keytool -import -v -alias "GlobalSignRootCA-R3" -keystore /opt/oracle/psft/pt/cfghome/webserv/peoplesoft/piaconfig/keystore/pskey -storepass Passw0rd -file /opt/oracle/psft/pt/cfghome/webserv/peoplesoft/piaconfig/keystore/GlobalSignRootCA-R3.crt -trustcacerts

  11. If the certificate already exists and you’re asked if you still want to add it or whether you trust this certificate, answer Yes.

    You should see this message: Certificate was added to keystore.

  12. Bounce the web server, application server, and process server.

  13. Log in to PIA, then go to PeopleTools > Security > Security Objects > Digital Certificats.

  14. Add a new row:

    • Type: RootCA

    • Alias: GlobalSignRootCA-R3

      This is the alias you used when you imported the certificate to your keystore folder.

  15. Click Add Root.

  16. Using a text editor, open the certificate you saved (step 8) and copy the entire content of the file.

  17. On the Add Root Certificate page, paste the certificate content in the text box.

  18. Click OK.

  19. Bounce the web server, application server, and process server.

  20. Test your connection to the API. See Configuring the Integration Broker, “Testing Your Connection.”