There are many times when you require information external to Aras Innovator. Whether it be some external system you wish to integrate, or you just need to use an external API for some data, it’s easy to accomplish from within Aras Innovator.
Our Example
Our example will go over using the Nager Date API which can return the national holidays for 101 different countries. We’ll be using the API to create business calendars with automatically generated exceptions, or holidays. This is a great example of how using an external API can simplify and improve some of our internal business processes.
The Nager API is very simple to use. There are two parameters we’ll have to append to the URL: the country we’re searching for and the calendar year. While this is a very simple example, most APIs have documentation which goes over how to properly use their system.
Labs just released this example on our GitHub page, so you can install it here and follow along. Note: Business calendars are part of the Program Management application. PM must be installed to follow along with this guide.
The Configuration
We’ve added an extra property to the business calendar ItemType, “country_code”, as well as an extra field on the business calendar form. The field is populated by a list which contains all 101 countries supported by the Nager API. This form can now supply all the data we need for our API call.
Now that we have all the data we need, we can create a server event to handle interacting with the API and adding the holidays to the newly created calendar. We’ll be adding a new onBeforeAdd server event to the business calendar ItemType. We’ll be using onBeforeAdd as opposed to onAfterAdd because we can cut down on the number of server calls we’ll be performing this way. If we were to add the item and then modify it in an onAfterAdd method, we’d have to perform a server call for both the addition and the modification. By using an onBeforeAdd, we can manipulate the context item before the addition, which will result in a single server call. We can add the necessary relationships to this, before handing it off to the standard add process.
Our method will query the newly created calendar to get the necessary information, year and country code, before handing them off to our external system. Our method will then build a URL which is accessible by REST requests and retrieve any response. Our response will be a list of holidays formatted within a JSON object.
The Code
To contact the API and retrieve that JSON object, we’ll be using the C# WebClient class. This class has tons of great tools for interacting with external systems. Since our needs are pretty basic, we can use the DownloadString function by passing it our complete URL. Since our response is formatted as JSON, we can use the Newtonsoft library, which is included with Aras Innovator by default, to make that data easier to work with. The whole method can be found in the gist below, with comments explaining each portion of the code.
Conclusion
There are many ways to utilize external APIs to enhance your Aras Innovator experience. The example above is available on the Aras Labs Github page, and you can find it here. This was a simple example. More complex examples will follow the same pattern, but could require more information be passed to the RESTful API, require credentials/validation, or could require more post-processing. Let us know what kind of examples you'd like to see in a blog covering a more advanced example!