Oracle Integration - Subscription Management Lab

Before You Begin

Some steps in this tutorial have a icon next to them. Click this icon to copy the snippet of text to your clipboard and then paste where needed.

Your instructor will provide you the information you need to access the environments used in this lab.

For this lab we will provide you the following:

• Oracle Integration
• Engagement Cloud

Get Your Oracle Integration (OIC) Environment

Select your OIC Environment and enter your User Number to get the information needed to access Oracle Integration.

Select your OIC environment: 

User Number:  OK

• OIC URL:

  Select your OIC Environment to get your OIC URL.

• OIC User Name:

  Select your OIC Environment to get your OIC Username.

  Enter your User Number to get your OIC Username.

• OIC Password: Your password will be provided by the instructor.

Sign In

1. Open your Oracle Integration instance.

   Select your OIC Environment to get your OIC URL.

2. Enter your user name and password.

   Select your OIC Environment to get your OIC Username.

   Enter your User Number to get your OIC Username.

   Your password will be provided by the instructor.

3. Click Sign In.

   The Home page appears.

   You are now logged in and ready to use Oracle Integration.

   

Create the Update Bill Lines Integration

We'll create an integration to update the Bill Lines for a Subscription Product in Oracle Engagement Cloud.

1. The Navigation menu provides access to the core capabilities within Oracle Integration such as Integration, Process Automation, Insight, B2B, and Visual Builder. We will explore some of these later.

   
   

   On the Home page, click Integrations, and then click Integrations.

2. The Integration page lists the integrations in your environment. These integrations can be in different stages of the development cycle. You can check the status column to see if an integration is activated (● Active) or under construction (● Configured).

   
   

   The first step in creating an integration is to create a Connection. Connections define the attributes, such as the hostname and security policies, used to connect to a specific type of application or technology.

   We have already created an Oracle Engagement Cloud connection for your use in this lab.

   
   

   On the Integrations page, click Create.

3. In the Select Integration Style dialog, select App Driven Orchestration.
   

   This style lets you run integrations on demand as opposed to Scheduled Orchestrations that are batch driven and run on a defined schedule. We also support other patterns such as publish and subscribe that let you distribute events to multiple integrations.

4. Click Select.
5. In the Create New Integration dialog, configure the integration:

   1. What do you want to call your integration?

      Enter Update Bill Lines

      Enter your User Number to specify your unique integration name.

   2. In the What does this integration do? field, enter:

      This integration will update the Subscription Product Bill Lines.

   The Identifier uniquely identifies your integration and is automatically generated from the name you entered. Since you are working on a shared environment, it is important to use the name assigned to you so you can easily find your integration and avoid conflicting with others who are also working on this lab.

6. Click Create.

   The Integration canvas appears.

Create the Update Bill Lines Trigger

Triggers define how your integration is exposed to to be invoked. In this case, we will define a trigger to expose your integration as a REST API.

1. Hover over START and click .
2. Begin typing REST Interface in the Search field to find the connection that exposes your integration as a REST API.

3. Select the connection named REST Interface.

   The Configure REST Endpoint wizard appears.

4. Name your endpoint UpdateBillLines.

5. In the What does this endpoint do? field, enter:

   This endpoint defines a REST interface to update the Bill Lines within a Subscription Product.

6. Click Next.
7. On the Resource Configuration page, configure the following properties:

   1. What is the endpoint's relative resource URI: /subscriptionProducts/billLines/{SubscriptionProductPuid}

      
      

      The relative URI is combined with the integration environment hostname and integration identifier to define the full REST API endpoint.

      The parts of the URI enclosed with curly braces are template parameters that will be supplied when the integration is called.

   2. What action do you want to perform on the endpoint?: select PATCH.
   3. Select Configure a request payload for this endpoint.
   4. Select Configure this endpoint to receive the response.
8. Click Next.

9. On the Request Parameters page, leave the default values, and click Next.

   If you needed to specify additional query parameters, you would define them here.

10. On the Request page, configure the following values:

    1. From the request payload format list, select JSON Sample.

       The JSON schema used by an integration can automatically be generated with a sample JSON payload.

    2. Click the <<<inline>>> link.
    3. Enter the following JSON sample:

       {
       	"BillLines" : [
       		{
       			"BillLinePUID" : "string",
       			"UsageQuantity" : 0
       		}
       	]
       }

       This payload specifies a collection of Bill Lines to be updated, each with a BillLinePUID and UsageQuantity element.

    4. Click OK.

       The JSON sample will be validated and a JSON schema will be generated.

    5. Click Next.
11. On the Response page, configure the following values:
    1. From the response payload format list, select JSON Sample.
    2. Click the <<<inline>>> link.
    3. Enter the following JSON sample:

       {
       	"BillLines" : [
       		{
       			"BillLinePUID" : "string",
       			"UsageQuantity" : 0
       		}
       	]
       }

       This integration will be defined to simply return the request payload.

    4. Click OK.
    5. Click Next.

12. On the Summary page, expand the Endpoint Summary to view the trigger for your integration. Check that everything looks right.

13. click Done.

    The canvas with the new trigger appears.

14. On the Integration canvas, from the Layout list, select Horizontal.

    
15. Click Save to save the integration.

Iterate Over Billing Lines

We defined our REST Interface trigger to accept a collection of Bill Lines to update. Oracle Engagement Cloud only provides an API to update a single Bill Line at a time. So we need to loop through the collection of Bill Lines passed to our integration and invoke the Engagement Cloud API for each.

We'll add a For Each construct to loop through our Bill Lines.

1. On the canvas, hover over the line coming out of our UpdateBillLines trigger, and click .

2. In the Search field, enter For Each.

   

3. From the Actions section, select For Each.

   The Create Action dialog appears.

4. In the Name field, enter ForEachBillLine.
5. Drag the BillLines element from the Source tree, and drop it on the Repeating Element field.

6. In the Current Element Name field, enter CurrentBillLine.

   

7. Click Create.

   The canvas now displays a loop.

   

8. Click Save to save the integration.

Update the Bill Line Quantity

Next we will add an activity inside our For Each loop to update each Bill Line in Oracle Engagement Cloud.

1. Hover over the line coming out of the ForEachBillLine action and click .
2. In the Search field, enter Engagement Cloud to find our Engagement Cloud connection.

3. From the Invokes section, select Engagement Cloud.

   The Configure Oracle Engagement Cloud Endpoint dialog appears.

   
   

   Connections created with our application adapters simplyfy the task of discovering and configuring access to application business objects and events.

4. Name the endpoint UpdateBillLine.
5. Click Next.

6. On the Operations page, configure the following:

   1. From the Browse by list, select Business (REST) Resources.
   2. From the Select a Service Application list, select crmRestApp.
   3. From the Select a Business Resource list, search for and select SubscriptionProducts.
   4. Click Browse and configure a child resource.
   5. From the Child Resources list, select SubscriptionProducts : billLines.
   6. From the Select the operation to perform list, select update.
7. Click Ok.
8. Click Next.

   A summary of the properties you configured appears.

9. Review the summary and click Done.

   That's all it takes to configured an action that will update a Bill Line.

10. Click Save to save the integration.

Add Request Mapping

Next we need to map the data sent to our integration to the activity we just created to update a Bill Line in Engagement Cloud. In this case, we want to map the current Bill Line in our For Each loop.

1. Click Map to UpdateBillLine, and then click .

   The Map to UpdateBillLine page appears.

   Notice a tooltip indicates available recommendations for this data mapping.

2. Click  Recommendations.

3. Click ✓ Apply Recommendations.

   A Confirmation message appears informing you that the recommended mappings were applied.

   Verify the following mappings and correct if necessary:

   • TemplateParameters.SubscriptionProductPuid ⟶ TemplateParameters.id0
   • CurrentBillLine.BillLines.BillLinePUID ⟶ TemplateParameters.id1
   • CurrentBillLine.BillLines.UsageQuantity ⟶ billLines.UsageQuantity

   Ensure you are not mapping data from the request-wrapper as this represents the collection of Bill Lines sent to your integration and you are updating only a single Bill Line for the current for loop iteration as defined in $CurrentBillLine.

   

4. Optionally, you can also map data manually by dragging the data elements from the Source tree, and dropping them on the Target tree.

5. Click Validate and then click Close.

   The Integration canvas appears.

6. Click Save to save the integration.

Add Response Mapping

Most integrations will need to return a response to the caller. This integration will be simply return the request payload.

We'll use the UpdateBillLines map to populate the response data.

1. Click Map to UpdateBillLines, and then click .

   The Map to UpdateBillLines page appears.

   Notice a tooltip indicates available recommendations for this data mapping.

2. Click  Recommendations.

3. Click ✓ Apply Recommendations.

   A Confirmation message appears informing you that the recommended mappings were applied.

4. Optionally, can also map data manually by dragging the data elements from the Source tree, and dropping them on the Target tree.

   Verify the following mappings:

   • request-wrapper.BillLines ⟶ response-wrapper.BillLines 
   • request-wrapper.BillLines.BillLinePUID ⟶ response-wrapper.BillLines.BillLinePUID
   • request-wrapper.BillLines.UsageQuantity ⟶ response-wrapper.BillLines.UsageQuantity

   

5. Click Validate and then click Close.

   The Integration canvas appears.

6. Click Save to save the integration.

Add Tracking Fields

Tracking fields let you identify and find specific integration instances. A tracking field associates an integration instance with a business identifier. You must define at least one tracking field per integration.

For example, for an integration that processes orders, you can track the integration by an order number. If for some reason the order is missing or delayed, you can search by the order number to locate the order and find out what caused the issue.

1. In the Integration canvas, click the error icon   next to the Last Saved field.

   Hover over the error to see the detailed error description. In this case, the error should indicate that you need to define a primary business identifier for tracking.

2. Click next to the Last Saved field.
3. Select Tracking.
4. In the Source tree, expand the execute node, and then expand the TemplateParameters node.

5. Drag the SubscriptionProductPuid to the first row of the Tracking Fields table.

   The first field in the list is the primary tracking field. It's used as the primary index to find an integration instance.

6. Click Save.

   The Integration canvas appears. Notice that there are no errors.

7. Click Save to save the integration.

8. Click Close.