Sunday, 30 July 2017

How to write files using ICS FTP adapter


In this blog we are going to show you, how to use Oracle Integration cloud service FTP adapter to write file on any  FTP location.

In my previous blog, we have explained how to configure FTP adapter in Oracle Integration Cloud Service.

After this blog, we have learned how to use FTP adapter to write files on FTP location.

Use Case: Develop REST service that exposes the below json, create a .csv file and post the same on FTP location.

{  
   
"employeeId":"ABC@123",
   
"firstName":"Ankur",
   
"lastName":"Jain",
   
"Qualification":"MCA",
   
"Designation":"Sr. Manager"
}

This Use case requires only simple 4 steps to complete:
  1. Create REST connection
  2. Create FTP connection
  3. Create an Integration
  4. Activate the Integration
Let's go step by step
  1. Create REST connection: The REST connection we are gonna to create will work as a Trigger point. We have already showcased the same in one of my blog. Please check it out before moving forward.
  2. Create FTP connection: FTP connection will work as a Target point. We have already showcased the same in one of my blog. Please check it out before moving forward.
  3. Create an Integration: Follow below steps to create an Integration
  • Login into ICS console
  • Click on the Integration tile from ICS home page

  • Click on Create button from upper right corner
  • Select Orchestration pattern from the dialog box

  • Enter Below information and click on Create button
    • Select Application event or business object radio button
    • Enter Integration Name in What do you want to call your integration text box
    • An Identifier would be picked up automatically from Integration name however you can edit it
    • Let the Version as it is
    • Enter the description in What does this integration do box
    • Leave the package box as it is

  • Integration pane will look like 
  • Drag the TEST_REST_Conn Connection on the canvas from REST connection 
  • Enter below information and Click Next
    • Name of the end point
    • Relative URI(must start with /)
    • Select HTTP verb
    • Select Configure a request payload for this endpoint checkbox- This option allows us to assign payload in the next step

  • Select Json Sample Radio button: This option allows us to take input in json format. Select inline link to give sample payload

  • Enter payload and click OK 
  • Click Next and Done button 
  • Click Invokes from right navigation, Select TEST_FTP_Conn, drag and drop the TEST_FTP_Conn below PostEmployee
  • Enter Name and optionally description. Click Next button
  • Enter below information and click Next button
      • Select Operation: In our case select Write File
      • Select a Transfer Mode: Select ASCII
      • Specify an Output Directory: Enter directory location where the file would be written
      • Specify a File Name Pattern: Either enter any hard coded file name or File Name pattern can be entered. In our case we have entered a File pattern test_%yyMMddHHmmss%.csv. So the file would be created in this format only
      • Append to Existing File: If this is check, data will be appended to the existing file if already exist with same name
  • Select the option as shown in below screen shot and click Next button
  • Enter below information and Click Next button
    • Select the Delimited Data File: Select the comma separated file from your local machine. Please download sample file from here
    • Enter the Record Name: Enter Employees
    • Enter the Recordset Name: Enter Employee
    • Select the Field Delimiter: Select Comma(,) as a delimiter
    • Character Set: This allows us to select character set
    • Optionally Enclosed By: Let it be "
    • This table allows us, to select which field would be optional and which would be mandatory
  • Review summary and click Done button
  • Click on Map to Write File mapper and click edit button
  • Map the source and target field as shown in the below scree shot. Click Validate and Close button

  • Select Action icon and click on Tracking. This is mandatory step and can’t activate integration without this step. Basically this allows us to track the Instance with configured parameter. In our case we will select employeeId field.

  • Drag & Drop the employeeId from left panel to first row in Tracking Field and click Done button
  • Click Save and Close button from upper right corner
Now our integration is completed and now turn to activate the integration.

      4. Activate Integration
  • Click on Activate button

  • Select Enable tracking and Include payload check boxes button. This option is useful if we want to see payload in the logs. Click Activate button

  • As soon as, integration will be activated, ICS will show you the service end point on the upper side as shown in the below screen shot. Alternatively, you can click on the info icon near to the activate button that will show you the service end point.

This completes our integration now. and this is the time to test the service and see the file should be created at mention location. We will use POSTMAN tool to test the REST service

      5. Test the REST service
  • Open postman tool
  • Enter service end point
  • We have to add Basic Auth as ICS service is automatically secured. We need to provide ICS console credentials.

  • Enter payload and hit Submit button
  • Open FTP location and found one file should be created there

That's done !

Send Email notification in Oracle Integration Cloud Service

Oracle ICS provides us an important activity that allows us to Trigger an Email- notification from ICS integration. This is called Notification Activity. This is very simple and straight forward to use.

For all available activities in ICS, please have a look at this blog.

Let's try to enable notification in already existing Scheduled Integration:

1) Open Action tab from right panel and Drag & Drop Notification activity on integration canvas:

Notification In ICS

2) Enter Name and optionally Description. Click  Create button


Notification In ICS

3) Notification configuration window will get open as shown in the below screen shot

Notification In ICS

4) Enter edit icon in front of From option. This allows from address to enter.



5) Enter From address in the expression input box. Or we can also drag and drop a variable from the left panel if any variable contains From address. Click Close button from the right upper corner.

Notification In ICS

As shown in the above image, we have configured ics.notifier@Oracle.com as a from address. ICS gives this from the address that can be used to send notifications.

6) Same ways we can configure To address. Enter comma separated addresses in the case to send the notification to multiple recipients.

Notification In ICS

7) Same ways we can add Email Subject


Notification In ICS

8) The body can be plain text and  HTML. Curly braces {} is being used to send any parameter value with the body.
Parameters can be created with table given under the Body input text.

Notification In ICS

9) Click + sign to create any variable. A row will be created on clicking + sign. Enter Parameter name and click the edit icon to assign any value to it.

Notification In ICS

10) Enter the email body. As shown in the below screen shot, we have used curly braces to send parameter value that is created in the previous step:

11) Let's Click on Validate and Close button from the upper right side.

This completes the notification activity in Oracle ICS.

Let's run the integration. As soon as we will run the integration an Email notification will be received to all configured recipients.





Saturday, 29 July 2017

Handle special character in Oracle ICS

Oracle Integration Cloud Service provides a header that enables us to handle special character during sending request to any service.

For instance:

Let's suppose we are calling Web Service that takes input in request parameter. It might be possible, special character may come in request parameter and we want to pass these special character as it is in the request parameter.

So to handle such type of request, Integration Cloud Service provides an useful custom header name x-ics-use-x-www-form-urlencoded that will help us to handle special character.

Simply add a customer header called x-ics-use-x-www-form-urlencoded and assign the value of this header as false.

x-ics-use-x-www-form-urlencoded


Set the value of x-ics-use-x-www-form-urlencoded to false in mapper.

x-ics-use-x-www-form-urlencoded


That's it !

Wednesday, 19 July 2017

Actions/Activities in Oracle ICS


This blog is very interesting and describes what all Actions/Activities are available in Oracle ICS.

Oracle ICS provides lots of Actions in Integration that we can add in our Integrations to make it flexible.

We have Oracle ICS with versions 17.2.5.0.2 as of now. I'm mentioning this because some Actions can be added/updated in the future release of ICS versions.

Following screenshot depicts all available Actions in Oracle ICS version  17.2.5.0.2


Let's describe all the Actions one by one:

  • Assign: Enables us to assign variables in Integrations.
  • Function Call: Enables us to call javascript functions in Integrations.
  • Logger: Enables us to put the logger in between of the integration to print some variables values in logs.
  • Map: Allows us to add some ad-hoc maps in Integrations.
  • Notification: Allows us to enable email notification in Integrations.
  • Scope: Enables you to manage a collection of child actions and invokes that can have their own fault handlers.
  • Stage File: Enables us to read/writes files in scheduled integration at some temporary location in ICS.
  • Switch: Enable us to add switch activity for defining routing expression branches in Integrations.
  • For Each: Enables you to loop over a repeating element and execute one or more actions within the scope of the for-each action. This blog shows, how to use For Each action.
  • While: Enables you to loop over actions or invoke connections as long as a specific condition is met.
  • Raise Error: Enables you to send failed messages to the error hospital for further analysis.
  • Fault Return: Enables you to return a fault.





Administering Oracle Integration Cloud Service

The Oracle Integration Cloud Service provide a rich dashboard with the information and tools to monitor and manage our integration in the runtime environment.

Monitoring Integration

Oracle ICS provide us the broad level  picture of how integrations are working/performing. Dashboard provides various views to check running integrations.
  • Viewing Dashboard
  • Viewing System Health
  • Viewing Design Time Metrics
  • Monitoring Integrations
  • Monitoring Agents
  • Track Instances
Viewing Dashboard: Dashboard provides us the information about how integrations are performing. The main page of the integration shows a snapshot of a state of all running integrations.
  • Login into ICS and click Dashboard from home page
Oracle ICS monitoring
  • Below screen shows the overall picture of all integrations that are running
Oracle ICS monitoring
    1. Success Rate: Shows the success ratio of running integration.
    2. Total Message: Shows the total no of messages received of integrations that are activated.
    3. Success: Shows the total no of successful messages.
    4. Failures: Shows the total no of fail messages.
    5. Connections: Shows how many connections are currently in use in the integrations.
    6. Integrations: Shows how many integrations are activated out of developed integrations.
    7. Scheduled Integrations: Shows how many integrations are scheduled integrations.
    8. This section allows us to download the logs.
Viewing System Health: This allows us to view information about the system health of Oracle Integration Cloud Service components. To view System Health click on the drop down from left corner and click on System Health
Oracle ICS monitoring
Viewing Design Time Metrics: This allows us to view the design-time metrics of Oracle Integration Cloud Service, including details about packages, integrations, connections, lookups, and agents.
Oracle ICS monitoring
  1. Integrations: This sections shows the total no of Integrations we have so far with some extra information(Draft, Configured, Active, Failed)
  2. Connections: This sections shows the total no of Connections we have so far with some extra information(Draft, Configured, In-Use)
  3. Lookups: This sections shows the total no of Lookup we have so far with some extra information(In-Use)
  4. Packages: This sections shows the total no of Packages we have so far with some extra information(Developed, Prebuilt)
  5. Agents: This sections shows the total no of Agents we have configures so far.
  6. Adapters: Shows the total no of adapters available out of the box
Monitoring Integrations: On the ICS dashboard, we can see how Integrations are processing messages. For example: How many messages have been received and processed , how many successful and errors have occurred.
Oracle ICS monitoring
Monitoring Agents: Monitor the agent groups and their associated on-premises agents in Oracle Integration Cloud Service.
Oracle ICS monitoring

Track Instances: Oracle ICS allows us to track instances of the integrations. 

Thursday, 13 July 2017

Oracle Integration Cloud Service Lookups

ICS  Lookups

We use lookups in the integrations to create reusable tables that map the different terms used to describe the same item across your applications. Lookups are exact same as Data Value Map(DVM) in SOA

A lookup associates values used by one application for a specific item to the values used by other applications for the same item. For example, one application uses a specific set of codes to describe countries, while another application uses a different set of codes to describe the same countries.

Lookups can be used for items such as mapping gender codes, nationality codes, currency codes—any type of information that our applications must share with each other but that they represent differently. We may have several lookups for one integration, depending on the number of fields that require mapping. Lookups are also reusable, and can be used by multiple integrations. Lookups are based on a static definition, meaning we create and populate them during design time, and are not changed by runtime activities. These tables are used for looking up values only.




Lookup Function:

ICS proivdes a lookupValue function that we can use to call in mapper to specify when to reference a lookup table. We use this function to lookup values at run time based on the data coming as part of the response. This way, our integration knows how to map data coming in from one application to data being sent to another application.


In the next blog, you will learn how to use lookups in integration.


Use Lookup in Oracle Integration Cloud Service

In the previous blog, I have explained about lookup in Oracle Integration Cloud Service. This blog shows how to create and use a lookup in any integration.

Follow below steps to create and use the lookup in the integration

Create Lookup
  • Click on the Lookups tile from ICS home page
  • Click Create button from the upper corner
  • Enter Lookup Name & Description and click Create button
  • Edit domain names by clicking on the Domain_name_1 and select Edit Domain Name
  • Enter domain name as per choice. Same ways we can edit the name of Domain_name_2
  • Enter Values as shown in the below screenshot and click + sign to add more values
  • Click Save and Close button
With the above steps, we have seen how to create the lookup in ICS. Now let's see how to use lookups in integration.

Use Lookups
  • Open any existing Integration
  • Drag and Drop Assign Activity from Actions on the Integration canvas
  • Enter Name and click Create button
  • Click + Sign to add variable and enter Name of the variable

  • Click on Edit button to open expression builder from the right side below Value column
  • Seach Lookup and Drag & Drop lookupValue function on Expression
  • Select CountryLookup and click Next button
  • Click Select Source Column and select Country Code
  • Same ways, click on Select Target Column and select CountryName and click Next button
  • Enter any default value. This allows lookupValue function to set the default value if none of the CountryCode is found from the lookup. Click Next button and Done
  • srcValue value needs to replace with any variable or set any hardcoded value as of now. This will allow lookup to search entered value in lookup against CountryCode and return corresponding Country Name. If Country Code is not found then it returns the default value(in our case default value is Not Found)