Setting Up the Transactions Connector

The transactions connector enables OIC to exchange transaction-related information with the Oracle Permitting and Licensing system.

Oracle provides a Solution Package with sample integration configurations. You can clone these samples and use them as starting points for your own connectors. The instructions in this procedure explain how to set up the transactions connector from scratch.

The procedures that follow are for entering the specific information that is required by the Oracle Permitting and Licensing system. For general instructions related to setting up integrations in OIC, refer to your OIC documentation at https://docs.oracle.com/en/cloud/paas/integration-cloud/user-processes/integrate-applications-and-services.html

Note: Before you set up connectors, you must create the Space and the Application for your workflow processes. See Workflow Basics.

Note: Currently, in the context of data object parameters, data association parameters, and REST resource attributes, the terms record, transaction, and permit are interchangeable. In some resource attributes, such as paths or parameters, trans is used in place of transaction for simplicity.

Procedure Overview for Setting Up the Transactions Connector

Setting up the Transactions Connector comprises multiple procedures with multiple steps. The following set of steps outline the high-level set of procedures involved with this task. Each item in the following list is explained in more detail in the following sections, in the listed sequence.

1. Download Required JSON Files for Workflow Integration Configuration

2. Create the Transactions Connector

3. Add the Transaction Resource

4. Add the PATCH Operation for Transaction Statuses

5. Add the GET Operation for Transaction Base Data

6. Add the GET Operation for Transaction Fields Data

7. Add the GET Operation for Transaction Data

8. Add the GET Operation for Transaction Assignee

9. Add the GET Operation for Transaction Type Resource

10. Add the Transaction Type Data

11. Add the POST Operation for the Business Rules Request.

Step 1: Download Required JSON Files for Workflow Integration Configuration

For creating integrations from scratch, Oracle provides a set of JSON files for defining the integration between OIC and the Oracle Permitting and Licensing system. Download all of the files first so that you can access them easily while completing the procedures documented in this topic.

To download the required JSON:

1. Sign on to My Oracle Support.

2. Access Doc ID 2449735.1, Public Sector Compliance and Regulation: JSON Files for Transaction Integration.

3. Download the following files to a local folder:

   • RequestTransStatusUpdate.json

   • ResponseTransStatusUpdate.json

   • ResponseTransBase.json

   • ResponseTransFields.json

   • ResponseTransData.json

   • ResponseTransAssignee.json

   • ResponseTransType.json

Step 2: Creating the Transaction Connector

Note: This procedure explains how to create the transaction connector. Additional procedures that follow this one explain how to set up the operations for this connector.

To set up the transactions connector:

1. Access the main console in OIC.

2. In the list of OIC applications, click the application for your workflow process.

3. Click the Integrations option in the left frame.

4. Click the Create button, then in the pop-up menu under the Create button, select External > REST

5. In the Create REST Connector window, enter the following:

   Page Element	Description
   Name	Enter a descriptive name, such as TransactionConnector. Note: The name TransactionConnector is suggested, however, you can choose your own name if needed. This documentation refers to TransactionConnector.
   Base URL	Enter the URL for your Oracle Public Sector Cloud REST API resources. The URL follows this pattern, where ServerName is the server name for your instance of the application: https://ServerName/fscmRestApi/resources/11.13.18.05
   Open Immediately	Select this check box if it is not already selected.

6. Click Create.

   The Rest Connector Editor opens.

7. If you want to set up security for this integration now, click the Edit link for the Configuration section.

   Note: If you prefer to set up security later when you activate the workflow application, you can skip the security-related steps in this procedure. Setting up security now simplifies the application activation steps.

8. Click the Security tab.

9. In the Security Type field, select APP Id - Basic Authentication.

10. Complete these additional fields that appear after you select the Security Type:

    Page Element	Description
    Keystore Credential	If you previously created a keystore credential, select it. Otherwise, leave this field set to [New Key] so that the system will create the keystore credential when you apply your changes.
    Key Name	If you selected [New Key] as the keystore credential, enter the name to give to the new keystore. If you selected an existing keystore credential, this field is read-only and displays the key name.
    Username	Enter the user name for the process cloud proxy user that you previously created. If you’re using an existing keystore credential, that credential supplies a default username.
    Password	Enter the password for the process cloud proxy user that you previously created. If you’re using an existing keystore credential, that credential supplies a default password.

11. Click Apply to save the security information and close the Configuration section.

12. Click Save

Step 3: Add the Transactions Resource

Note: Before starting this procedure, be sure to complete the procedure “Setting Up the Transactions Connector.”

1. Access the main console in OIC.

2. In the list of OIC applications, click the application for your workflow process.

3. Click the Integrations option in the left frame.

4. Click the TransactionConnector integration.

5. In the Resources section of the Rest Connector Editor, click Add.

6. Expand the new Resource section that appears, and enter TransactionResource in the Name field.

Step 4: Add the PATCH Operation for Transaction Statuses

Workflow in OIC uses the PATCH operation to update the status of a transaction.

To set up the PATCH operation:

1. In the Operations section of TransactionResource, click the Add button and then select PATCH operation from the drop-down menu.

2. Click the new PATCH operation.

3. Enter the following information:

   Page Element	Value
   Name	patchTransactionStatus
   Path	{transResource}/{transRecordKey} Although you can choose different names for the resource name and record key parameters, this procedure assumes that you use the given values.
   Documentation	Update transaction status.

4. Click Request

5. Click the + icon next to the Body field to open the Import Business Object from JSON window.

6. Enter RequestTransStatusUpdate in the Name field.

7. Click Schema.

8. Click the Import from File icon next to the Schema button.

9. Locate and upload the RequestTransStatusUpdate.json file that you downloaded from My Oracle Support.

   The imported JSON code appears in the Import Business Object from JSON window.

10. Click the Import button at the bottom of the window to save the code and close the window.

11. Ensure that the following values now appear for the PATCH operation request:

    Page Element	Value to Enter
    Body	BusinessData.RequestTransStatusUpdate
    Media Type	Custom
    Media Type details	application/vnd.oracle.adf.resourceitem+json

12. In each row of the Parameters list, click the Enter a description text and enter a description.

    These are example descriptions:

    Parameter	Description
    transResource	Transaction Resource Name
    transRecordKey	Transaction Record Key

13. Click Response.

14. Click the + icon next to the Body field to open the Import Business Object from JSON window.

15. Enter ResponseTransStatusUpdate in the Name field.

16. Click Schema.

17. Click the Import from File icon next to the Schema button.

18. Locate and upload the ResponseTransStatusUpdate.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

19. Click the Import button at the bottom of the window to save the code and close the window.

20. Ensure that the following values appear for the PATCH operation response:

    Field	Value
    Body	BusinessData.ResponseTransStatusUpdate
    Media Type	application/JSON

21. Click Apply.

22. Click Save.

Step 5: Add the GET Operation for Transaction Base Data

Note: Before starting this procedure, be sure to complete the procedure “Adding a PATCH Operation for Transaction Statuses.”

The getTransactionBaseData operation gets general transaction data that is found in all transactions, such as the permit type, the permit status, and the permit applicant for a permit transaction.

1. Expand the TransactionResource resource.

2. In the Operations section, click the Add button and then select GET operation from the drop-down menu.

3. Click the new GET operation.

4. Enter the following information:

   Field	Value
   Name	getTransactionBaseData
   Path	{transResource}/{transRecordKey} Although you can choose different names for the resource name and record key parameters, this procedure assumes that you use the given values.
   Description	Get base transaction data, such as applicant information

5. Click Request

6. In each row of the Parameters list, click the Enter a description text and enter a description.

   These are example descriptions:

   Parameter	Description
   transResource	Transaction Resource Name
   transRecordKey	Transaction Record Key

7. Click Response.

8. Click the + icon next to the Body field to open the Import Business Object from JSON window.

9. Enter ResponseTransBase in the Name field.

10. Click Schema.

11. Click the Import from File icon next to the Schema button.

12. Locate and upload the ResponseTransBase.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

13. Click the Import button at the bottom of the window to save the code and close the window.

14. Ensure that the following values appear for the GET operation response:

    Page Element	Value to Enter
    Body	BusinessData.ResponseTransBase
    Media Type	application/JSON

15. Click Apply.

Step 6: Add the GET Operation for Transaction Fields Data

The getTransactionFieldsData gets field data from the application intake form configured using the Intake Form Designer.

1. In the Operations section of the Transactions Resource, click the Add button and then select GET operation from the drop-down menu.

2. Click the new GET operation.

   The new GET operation has the default name of GetTransactionResources.

3. Enter the following information:

   Field	Value
   Name	getTransactionFieldsData
   Path	{transResource}/{transRecordKey}/child/FieldGroups Although you can choose different names for the resource name and record key parameters, this procedure assumes that you use the given values.
   Description	Get specific transaction data, such as job cost.

4. Click Request.

5. In each row of the Parameters list, click the Enter a description text and enter a description.

   These are example descriptions:

   Parameter	Description
   transResource	Transaction Resource Name
   transRecordKey	Transaction Record Key

6. Click Response.

7. Click the + icon next to the Body field to open the Import Business Object from JSON window.

8. Enter ResponseTransFields in the Name field.

9. Click Schema.

10. Click the Import from File icon next to the Schema button.

11. Locate and upload the ResponseTransFields.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

12. Click the Import button at the bottom of the window to save the code and close the window.

13. Ensure that the following values appear for the GET operation response:

    Page Element	Value to Enter
    Body	BusinessData.ResponseTransFields
    Media Type	application/JSON

14. Click Apply.

15. Click Save.

Step 7: Add the GET Operation for Transaction Data

The getTransactionData combines getTransactionBaseData and getTransactionFieldsData into a single operation, which you can use instead of using getTransactionBaseData and getTransactionFieldsData separately.

1. In the Operations section, click the Add button and then select GET operation from the drop-down menu.

2. Click the new GET operation.

   The new GET operation has the default name of GetTransactionResources.

3. Enter the following information:

   Field	Value
   Name	getTransactionData
   Path	{transResource}/{transRecordKey} Although you can choose different names for the resource name and record key parameters, this procedure assumes that you use the given values.
   Description	Combines getTransactionBaseData and getTransactionFieldsData into a single operation.

4. Click Request.

5. In each row of the Parameters list, click the Enter a description text and enter a description.

   These are example descriptions:

   Parameter	Description
   transResource	Transaction Resource Name
   transRecordKey	Transaction Record Key

6. Click Response.

7. Click the + icon next to the Body field to open the Import Business Object from JSON window.

8. Enter ResponseTransactionData in the Name field.

9. Click Schema.

10. Click the Import from File icon next to the Schema button.

11. Locate and upload the ResponseTransactionData.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

12. Click the Import button at the bottom of the window to save the code and close the window.

13. Ensure that the following values appear for the GET operation response:

    Page Element	Value to Enter
    Body	BusinessData.ResponseTransactionData
    Media Type	application/JSON

14. Click Apply.

15. Click Save.

Step 8: Add the GET Operation for Transaction Assignee

The getTransactionAssignee operation gets the assigned planner for transactions within the Planning and Zoning offering. You can configure subsequent tasks in the workflow process to reference the retrieved and stored getTransactionAssignee value.

1. In the Operations section, click the Add button and then select GET operation from the drop-down menu.

2. Click the new GET operation.

   The new GET operation has the default name of GetTransactionResources.

3. Enter the following information:

   Field	Value
   Name	getTransactionAssignee
   Path	publicSectorTransactionLatestAssignees/{transRecordKey} Although you can choose different names for the resource name and record key parameters, this procedure assumes that you use the given values.
   Description	Get specific transaction data, such as job cost.

4. Click Request.

5. In each row of the Parameters list, click the Enter a description text and enter a description.

   These are example descriptions:

   Parameter	Description
   transRecordKey	Transaction Record Key

6. Click Response.

7. Click the + icon next to the Body field to open the Import Business Object from JSON window.

8. Enter ResponseTransactionFields in the Name field.

9. Click Schema.

10. Click the Import from File icon next to the Schema button.

11. Locate and upload the ResponseTransAssignee.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

12. Click the Import button at the bottom of the window to save the code and close the window.

13. Ensure that the following values appear for the GET operation response:

    Page Element	Value to Enter
    Body	BusinessData.ResponseTransAssignee
    Media Type	application/JSON

14. Click Apply.

15. Click Save.

Step 9: Add the Transaction Type Resource

Note: Before starting this procedure, be sure to complete the previous procedures.

1. Access the main console in OIC.

2. In the list of OIC applications, click the application for your workflow process.

3. Click the Integrations option in the left frame.

4. Click the TransactionsConnector integration.

5. In the header of the Resources section, click Add to create a new transaction type resource.

6. Expand the new Resource section that appears, and enter the following information:

   Field	Value
   Name	TransactionTypeResource
   Path	publicSectorRecordTypes

Step 10: Add the GET Operation for Transaction Type Data

The GetTransactionTypeData operation gets data that is associated with the transaction type definition rather than with an individual transaction. For example, this operation can get the overall fee structure for a permit definition, because the fee structure is associated with the permit type.

To set up the GET operations for transaction type data:

1. In the Operations section of the Transaction Type Resource, click the Add button and then select GET operation from the drop-down menu.

2. Click the new GET operation.

3. Enter the following information:

   Page Element	Value
   Name	getTransactionTypeData
   Path	{transResource}
   Documentation	Get transaction type setup data.

4. Click Request

5. In the Parameters list, click the Enter a description text and enter a description.

   Here is an example description:

   Parameter	Description
   transResource	Transaction Resource Name

6. Click Response.

7. Click the + icon next to the Body field to open the Import Business Object from JSON window.

8. Enter ResponseTransTypeData in the Name field.

9. Click Schema.

10. Click the Import from File icon next to the Schema button.

11. Locate and upload the ResponseTransType.json file that you downloaded from My Oracle Support.

    The imported JSON code appears in the Import Business Object from JSON window.

12. Click the Import button at the bottom of the window to save the code and close the window.

13. Ensure that the following values appear for the GET operation response:

    Page Element	Value to Enter
    Body	BusinessData.ResponseTransTypeData
    Media Type	application/JSON

14. Click Apply.

15. Click Save.

Step 11: Add the POST Operation for the Business Rules Request

This step describes how to configure integration with Oracle Permitting and Licensing by calling REST resources directly from workflow process definitions.

Generally, any REST API can be called from your workflow process definition. There are multiple REST API’s provided with the Public Sector Licensing and Permitting offerings. The sample workflow models provided to get you started include only a handful of the integrations that could be configured, depending on your business requirements.

Each process definition has a set of connectors that you can view on the Integrations tab. In the sample workflow process definitions and documentation the each connector is separated to make it easier to view and describe. However, you may choose to combine all the individual connectors into a single connector.

This procedure outlines how you can configure additional integrations within process definitions to call Oracle Permitting and Licensing REST APIs to incorporate more data to drive your workflow process. This example demonstrates how to configure an integration with a Business Rules Framework API.

For more information on the Business Rules Framework, see Business Rules Framework Overview.

To set up an integration:

1. Open the Transaction Connector.

2. In the Resources box, click Add.

3. Expand the added resource and enter these values:

   Page Element	Description	Value
   Name	The name of the integration or connector. You can enter a custom name as needed.	BusinessRules
   Path	The name of the REST resource you intend to call.	publicSectorBusinessRulesFrameworkRequests

   This example illustrates adding a Business Rules resource.

   

4. On the new resource, click Add, and select the appropriate operation.

   In this case, select POST operation.

5. Click the newly added operation.

6. (Optional) Add a different name or additional path.

7. Configure the JSON Request.

   1. In the Response and Request section, select the Request tab, and click Create business object under the Body field to open the Import Business Object from JSON dialog box.

   2. For Name enter a recognizable name for the request, such as RequestBusinessRules.

   3. In the Enter the JSON edit box, select Schema.

   4. Copy and paste the following JSON.

      {
        "type" : "object",
        "properties" : {
          "EventCode" : {
            "type" : "string"
          },
          "RecordFirstKeyName" : {
            "type" : "string"
          },
          "RecordFirstKeyValue" : {
            "type" : "string"
          }
        }
      }

      This example illustrates the request JSON.

      

   5. Click Import.

   6. Close the Import Business Object from JSON dialog box.

8. Configure the JSON Response.

   1. In the Response and Request section, select the Request tab, and click Create business object under the Body field to open the Import Business Object from JSON dialog box.

   2. For Name enter a recognizable name for the response, such as ResponseBusinessRules.

   3. In the Enter the JSON edit box, select Schema.

   4. Copy and paste the following JSON.

      {
        "type" : "object",
        "properties" : {
          "CreationDate" : {
            "type" : "string"
          },
          "EventCode" : {
            "type" : "string"
          },
          "EventId" : {
            "format" : "long",
            "type" : "number"
          },
          "ExecutionId" : {
            "type" : "string"
          },
          "LastUpdateDate" : {
            "type" : "string"
          },
          "LogId" : {
            "format" : "long",
            "type" : "number"
          },
          "NoRules" : {
            "type" : "string"
          },
          "RecordFifthKeyName" : {
            "type" : null
          },
          "RecordFifthKeyValue" : {
            "type" : null
          },
          "RecordFirstKeyName" : {
            "type" : "string"
          },
          "RecordFirstKeyValue" : {
            "type" : "string"
          },
          "RecordFourthKeyName" : {
            "type" : null
          },
          "RecordFourthKeyValue" : {
            "type" : null
          },
          "RecordIdentifier" : {
            "type" : null
          },
          "RecordSecondKeyName" : {
            "type" : null
          },
          "RecordSecondKeyValue" : {
            "type" : null
          },
          "RecordSubIdentifier" : {
            "type" : null
          },
          "RecordThirdKeyName" : {
            "type" : null
          },
          "RecordThirdKeyValue" : {
            "type" : null
          },
          "ResourceId" : {
            "format" : "long",
            "type" : "number"
          },
          "StopProcess" : {
            "type" : "string"
          }
        }

      This example illustrates the response JSON.

      

   5. Click Import.

   6. Close the Import Business Object from JSON dialog box.

9. Click Apply and Save.

10. Add a task to the process definition to incorporate the integration.

    1. Open the process definition.

    2. In the BPMN palette, expand the Integrations section, and drag your integration onto the process definition in the desired location and update the connectors as needed.

    This example illustrates adding the Business Rules integration to a process definition.

    

11. Confirm the integration is referencing the correct operation.

    1. Select the task and click Open Properties.

    2. Select Implementation, General and then click Configure for the Service Call.

       This example illustrates the integration step referencing the REST operation.

       

12. Configure data associations.

    1. Select your integration task and select Open Data Association.

    2. On the Data Association page, select the Input tab.

    3. Map the following process definition data attributes to your Business Rules integration attributes, and click Apply and Save.

    Data Object	Integration
    "LNP-PERMT-UPDATE" or "PZ-PLANNING-UPDATE" Enter these values manually, depending on whether this process definition is being used for Permits or Planning and Zoning.	body.EventCode
    "LnpRecordKey" Enter this value manually.	body.RecordFirstKeyName
    transaction.transactionKey	body.RecordFirstKeyValue

    This example illustrates that data associations between the transaction and the business rules integration.