Aras InnovatorEdge offers an exciting new opportunity to make your PLM data available wherever it's needed. In this blog, we'll cover the entire process of setting up your first InnovatorEdge endpoint. This will cover configuring your OAuthServer to allow requests, all the way to defining the schema of your API and testing it.

Note: InnovatorEdge is a SaaS service that requires a user and credentials provided by Aras. Learn how to get access.

Setting up your Aras Innovator instance

When we first log in to Aras InnovatorEdge, you’ll see two tabs at the top of the screen. By selecting Aras Instances, you will see a list of all the instances you currently own connected to InnovatorEdge. To add a new one, you will click the + icon and enter a few pieces of information.

• Name: An identifier for this instance
• Type: The type of instance this is (Dev, QA, Prod).
• Http Alias: How this instance will be identified in the URL of your InnovatorEdge endpoint
• Database: The database you want to connect to in your Aras Innovator instance
• Server URL: The base server URL of your Innovator instance
• Auth URL: In most cases, this is the same as your base server URL
• Service User: You can set this to admin in most cases

With that, you can hit save to add this Innovator instance to InnovatorEdge. The last thing we'll need to do is configure our OAuth server to allow calls from Edge. There are two ways we can register the Edge API service with Innovator’s OAuth server: manually configure the OAuth.config file or use the OAuth Registry platform component.

Option 1: Manual configuration

1. Click the Download certificate button to get a .cer file
2. Navigate to the /OAuthServer/ folder of your Innovator instance
3. Move the certificate into the /App_Data/Certificates/ folder
4. In the OAuth.config file, add the following section to the  block

<clientregistry id="AmsService" enabled="true">
    <secrets>
        <secret type="JwtBearerAssertionServerSecret">
            <certificate filepath="App_Data/Certificates/AmsService.cer"></certificate>
        </secret>
    </secrets>
    <allowedscopes>
        <scope name="Innovator"></scope>
    </allowedscopes>
    <allowedgranttypes>
        <granttype name="impersonate"></granttype>
    </allowedgranttypes>
    <tokenlifetime accesstokenlifetime="3600"></tokenlifetime>
</clientregistry>

After that, the connection should be complete, and you can move on to actually building your InnovatorEdge endpoint.

Option 2: OAuth Registry

The Aras OAuth Registry is a platform component that admins can install to easily manage their OAuth clients without leaving the Aras Innovator web client. This is especially helpful for SaaS environments where admins don't have direct access to the OAuth.config code tree file. If you're using the OAuth Registry to manage your external clients, here are the steps to add a client for InnovatorEdge:

1. Click the Download certificate button to get a .pem file
2. Log in to your Aras Innovator instance as an admin
3. From the Table of Contents, expand Administration > External Access
4. Select OAuth Clients and click the Add New button

5. Set the Client ID to AmsService
6. Select the Impersonate Grant Type
7. Click Choose File under Certificate Secrets to upload the .pem file you downloaded from Edge
8. Save the client, and you're ready to build your API!

Run into an error uploading your certificate? Make sure you've downloaded a .pem file from InnovatorEdge, not a .cer file.

Setting up your API

Back in InnovatorEdge, we can now navigate to the Available APIs tab. By clicking the Create Configurable API button in the top right, we can start configuring our new endpoint. We'll go through this tab by tab.

Configure API

Here, we just need to set some general information about the endpoint we're building.

• Alias: An identifier for this API that will be used in the URL of the endpoint
• Name: A human-readable name that we will see when you view the full list of APIs in the Available APIs tab

Connect Instances

Here, you will select which Aras Innovator instances this endpoint can connect to.

1. Click the Add Instance button in the bottom right
2. From the dropdown, select the name of the instance that you created earlier, and then click the Add button

Schema

Here's the most important part of building your new API: selecting the data that will be available through this endpoint. The standard Innovator permission model will still apply, so a user without permission to see a particular ItemType won't be able to query that data through InnovatorEdge. Defining your schema here is simply an added layer of security. The schema you'll build for this example will be very simple, but it can be as complex as you need.

1. Click the Add Item Type or Global Method button
2. Search for and add the Part ItemType

3. Set the Alias to Part. This will also be used in the URL that's generated. Note: Setting an Alias lets you simplify or obfuscate the ItemType names in your Innovator instance.
4. In the Actions dropdown, select Get and Get List to enable users to retrieve Parts by id (Get) or via general query (Get List) through this endpoint.

5. In the Properties tab, click the Add button and select item_number, name, generation, and state. Note that you can also change the alias for each of these properties if you want them to be called something different in the response from the endpoint.

6. In the Relationships tab, click the Add button and select the Part BOM relationship. You'll see that Part BOM is automatically added to the full list of ItemTypes on the left. 

7. If you have discussions enabled on Parts in Aras Innovator, you can include them in your API. In the Extensions tab, turn on Discussion comments (Secure Social). This will enable you to also query for any messages that have been written on Parts through this endpoint

8. In the ItemType list, click Part BOM and add the quantity property to the Properties tab.

9. Click Save in the bottom right to save the changes to your schema

Access

With your endpoint built, you just need a way to authenticate so that you can begin testing. In this blog post, you'll add an API Key. However, InnovatorEdge also supports individual user auth through CIAM.

1. Click the Add button to add a new API Key
2. In the resulting dialog, fill in a name for the key and a user for the key.

3. Click the Save button in the bottom right, and you should see an API Key appear in the Key column. Copy this and save it in a secure location. It will not be shown again after navigating away from this screen.

Note: All operations performed with an API key will be executed as the user assigned to the key. We're using admin in this example, but you should consider using a dedicated service user with limited permissions for production scenarios using an API key.

Publish

We won't cover publishing in this blog, but this is a way to move entire APIs that you've created between Aras instances. The intended flow is that APIs are built and tested against Dev or QA instances, then published here to Production instances after testing is complete.

Testing our API

Now that you've finished creating your InnovatorEdge API, let's test to ensure we can retrieve the data we expect. If you go to the Part ItemType in your schema, you can copy the URL from the Execution endpoint link field. With this, you can open a client like Postman and run some test queries.

After pasting the URL into a new query in Postman, you can add our API key under the Authorization tab in the format apikey {YOUR_API_KEY}. Now we can simply click Send and make sure the data we expect is returned.

You can use all of the same syntax from the standard Aras Innovator REST API in your InnovatorEdge queries.

Wrapping up

InnovatorEdge provides a powerful new way to securely use your Aras Innovator data across a wide range of applications. Let us know if you are already using InnovatorEdge or if there are any use cases you'd like to see covered in more detail, such as using an InnovatorEdge API to populate a web app.