In previous blog posts, we have covered topics regarding the use of the REST API to request tokens for authentication and querying simple/more complex data. In this blog post, we will dive into server methods as OData actions through a POST request.
We will walk through a simple example that will demonstrate both how to call a static server method as well as how to call a server method with additional parameters. Our first example covers getting the parts that are owned by Administrators, followed by an example with another ItemType (Documents) also owned by Administrators.
If you would like to follow our steps, we’d recommend using a REST client such as PostMan or Insomnia to make calls to the server.
Setting Up the Call
In our first blog post, we showed how to authenticate by passing the username and a hashed password directly through the headers for every request. Part of the focus during the development of Aras Innovator 12.0 was on security, so this kind of authentication is no longer supported. Instead, we recommend reading over the token authentication blog post before continuing on.
Creating our Method to Call
First, we need to create a method that we can test our POST calls on. If you are following along, we recommend creating some test parts and setting some of the assigned creators as Administrators and the rest as another identity. Let’s use a custom method called postExample; all this will do for now is query parts that have the identity set to Administrators.
1. Calling Our Method
Now that we have a method to call, let’s create a simple POST calling postExample. Once we send the request, all parts with owned_by_id set to the Administrators Identity will be returned in JSON form. The link should be as follows:
POST {base url}/method.postExample
If you scroll down the response, you will see that owned_by_id is in fact the Administrators Identity for each part returned.
"owned_by_id": {
"@aras.keyed_name": "Administrators",
"@aras.type": "Identity",
"#text": "2618D6F5A90949BAA7E920D1B04C7EE1"
}
If we go to the parts we created within Aras Innovator or run a quick AML query, we can see that they will match the returned results.
2. Adding More Parameters
Within the body of the request we can specify more parameters or properties to incorporate into our method. Let’s modify the code a bit more and include a new value called owner. This variable will contain the string we pass from our POST call and allow us to specify any Identity we want. Note our default is Administrators so our POST will return the Administrators parts if we do not include the body as part of our request.
We have modified the following lines to allow us to insert an owner string into our method:
string owner = this.getProperty("owner", "Administrators");
identity.setProperty("keyed_name", owner);
Before running this method, ensure that at least one part has the owned_by_id property set to another identity (we are using Mike Miller for our example). This will allow us to verify that the method is performing the intended modification. Going back to PostMan our link should be as follows:
POST {base url}/method.postExample
Now within the body we include our new property “owner” and set it to “Mike Miller”. Once you send the POST there will be the returned JSON containing only parts owned by Mike Miller.
{
"owner": "Mike Miller"
}
3. Specifying the Method ItemType
Using a slightly modified postExample method we can return another ItemType with the same assigned creator property as Mike Miller. In order to test this let’s create some test documents and assign them to Mike Miller. The code below has been modified to take in a string called itmType that gets the attribute type.
The following lines contain modifications to our initial method that accept the string we pass in within the POST request:
string itmType = this.getType();
Item itm = inn.newItem(itmType, "get");
This allows us to pass in any ItemType that has the assigned creator property, in this case we will be focusing on documents. The link below is what your URL should look like:
POST {base url}/method.postExample
The body JSON should be as follows, the bolded text is where you actually specify the ItemType:
{
"@odata.type": "{base url}/$metadata#Document,
"owner" : "Mike Miller"
}
The response should contain the JSON with the owned_by_id as Mike Miller and the documents with their following properties.
In Conclusion
This tutorial should give you a good understanding of how REST calls are made to the Aras Innovator Server and how one can leverage this tool to extend their data into other applications. The ability to call your own custom methods, and hand in any parameters offers an incredible level of flexibility when developing external applications.