The Grand Avenue Software Connector modules provide a set of web services that expose specific functionality in Grand Avenue modules. This is intended to allow customers to develop custom solutions that access information stored in Grand Avenue.
The Connector modules provide RESTful Web Services published using the Open Data Protocol (OData). If you use these resources, please keep in mind that any use of these APIs should be resilient as possible to changes made to the API. Try to be prepared for the following types of changes:
The following types of changes will be considered a "breaking" change to the API and packaged as a new "API version" (see Configure OData API for information on enabled/disabling API versions).
When a new version of the API is introduced due to breaking changes, the previous version of the API will be temporarily supported but marked as "Deprecated" to indicate that customers should migrate to the new version as soon as possible.
To use these resources, you must do the following:
All OData Resources are available beneath the OData Root URL.
<BaseURL>/<ApplicationName>/odata/<ApiVersion>
<BaseURL>/<ApplicationName>/odata/<ApiVersion>/<ResourceName>
The values for BaseURL and ApplicationName can be found by a System Administrator on the Configure Notification Settings page.
The values for ApiVersion can be found on the Configure OData API page, with a link to the corresponding OData Service Document for each version.
Grand Avenue OData Resources are implemented using version 4 of the OData specification and libraries. Each resource returns the items in the system, like doing an interactive search for items and then exporting that information to an Excel CSV file. In this case however the results are formatted in a JavaScript Object Notation (JSON) document. The description of JSON is readily available on the web and beyond the scope of this help.
Partial Resource Path | Resource Name | Description | Activated by Module | Supported HTTP Methods |
---|---|---|---|---|
.../odata/v2 | [Service Document] | Lists the currently enabled OData service resources for the specified API version for modules that have been activated. | GET | |
.../odata/v2/$metadata | $metadata | The OData metadata lists the data formats used by each of the service resources exposed by the specified API version. | GET | |
.../odata/v2/openapi.json | N/A | A JSON representation of the OpenAPI documentation for the specified API version. | GET | |
.../odata/v2/ActivityLogEntries | ActivityLogEntries | Activity Log Entries for CAPA Requests, Complaints and NCM Reports | CAPA, Complaint Handling, NCM | GET |
.../odata/v2/AssessmentResults | AssessmentResults | Assessment Results for Training Records | Training Assessment | GET |
.../odata/v2/AssociatedParts | AssociatedParts | Associated Parts for Issues and Complaints | Complaint Handling | GET |
.../odata/v2/AuditReports | AuditReports | Audit Reports | Audit Management | GET |
.../odata/v2/CapaActions | CapaActions | CAPA Actions | CAPA | GET |
.../odata/v2/CapaCorrections | CapaCorrections | CAPA Corrections | CAPA | GET |
.../odata/v2/CapaRequests | CapaRequests | CAPA Requests | CAPA | GET |
.../odata/v2/CapaRootCauses | CapaRootCauses | CAPA Root Causes | CAPA | GET |
.../odata/v2/ChangeRequests | ChangeRequests | Change Requests | Document Control | GET |
.../odata/v2/Complaints | Complaints | Complaints | Complaint Handling | GET |
.../odata/v2/Customers | Customers | Customers | Complaint Handling | GET, POST* |
.../odata/v2/DesignProjects | DesignProjects | Design Projects | Design Control | GET |
.../odata/v2/DeviationRequests | DeviationRequests | Deviation Requests | Document Control | GET |
.../odata/v2/Documents | Documents | Document Revisions | Document Control | GET |
.../odata/v2/Equipment | Equipment | Equipment | Equipment Management | GET |
.../odata/v2/EquipmentActivityRecords | EquipmentActivityRecord | Activity Records for Equipment | Equipment Management | GET |
.../odata/v2/Issues | Issues | Issues | Complaint Handling | GET |
.../odata/v2/NcmReportEntries | NcmReportEntries | Disposition entries for NCM Reports | NCM | GET |
.../odata/v2/NcmReports | NcmReports | NCM Reports | NCM | GET |
.../odata/v2/Parts | Parts | Parts | Complaint Handling, NCM, Supplier Management | GET, POST* |
.../odata/v2/ReportingZones | ReportingZones | Reporting Zones for Complaints | Complaint Handling | GET |
.../odata/v2/RiskAnalyses | RiskAnalyses | Risk Analyses for Risk Files | Risk Management | GET |
.../odata/v2/RiskAnalysisFailureModes | RiskAnalysisFailureModes | Failure Modes for Risk Analyses | Risk Management | GET |
.../odata/v2/SupplierCorrectiveActionRequests | SupplierCorrectiveActionRequests | SCARs | Supplier Management | GET |
.../odata/v2/SupplierEvaluations | SupplierEvaluations | Supplier Evaluations | Supplier Management | GET |
.../odata/v2/Suppliers | Suppliers | Suppliers | Audit Management, CAPA, NCM, Supplier Management | GET, POST* |
.../odata/v2/TaskAssignments | TaskAssignments | Task Assignments. NOTE: This endpoint will return all task assignments, not just the task assignments associated with other exposed resources. | GET | |
.../odata/v2/TrainingRecords | TrainingRecords | Training Records | Training Management | GET |
* POST operations are supported only when the Connector Write module is activated.
The Connector modules publish API documentation in a JSON format in compliance with the OpenAPI 3.0 standard. The documentation is available
<BaseURL>/<ApplicationName>/odata/<ApiVersion>/openapi.json
(e.g. https://myhost/GrandAvenue/odata/v2/openapi.json )Opening this URL in a browser should display the OpenAPI documentation for all activated services. The services displayed will depend upon your system configuration, but the JSON document will look something like this:
{
"openapi": "3.0.0",
"info": {
"title": "OData Service for namespace GrandAvenue.Api",
"version": "2.15.0",
"description": "This OData service is located at https://myhost/GrandAvenue/odata/v2"
},
"servers": [
{
"url": "https://myhost/GrandAvenue/odata/v2"
}
],
"tags": [
{
"name": "TaskAssignments"
}
],
"paths": {
"/TaskAssignments": {
"get": {
...
The OpenAPI documentation can also be viewed and exercised using third-party tools. Below is an example of using a Swagger API viewer with the OpenAPI spec:
The following table identifies which HTTP methods are supported:
HTTP Method | Description |
---|---|
GET | The Connector Read module supports GET operations for several Grand Avenue Process Items. |
POST | The Connector Write module supports POST operations for several Grand Avenue Process Items. |
PUT, PATCH, DELETE | Not implemented. |
Each item in Grand Avenue resources has a corresponding "ID" property. This is a unique 64-bit integer for that item in that resource. Note that any similarity from the ID to what is normally displayed in the system is coincidental. For example, a CAPA Request with a CAPA ID of "CAPA-00001" could have an any "ID". It might be 1 but it could just as easily be 3. The ID field value is the value that is used when referencing an individual item.
Each OData resource can be accessed directly from a web browser and other tools (for example, curl, Postman, Swagger UI, PowerShell). Requests through a web browser will automatically use the GET HTTP Method. Several of the following sections use a web browser as an example, but the information returned by these APIs will be the same whether using a browser or any other tool.
TIP: Extensions are available for some web browsers, such as Chrome, that will format the JSON response data to make it easier to read.
TIP: Third-party tools like Postman provide useful features for working with REST services like the GAS OData Resources. For example, it allows you to save requests, inspect and modify header data, etc.
For the examples below, the values for BaseURL and ApplicationName should be replaced by the corresponding values for the target GAS installation, and can be found by a System Administrator on the Configure Notification Settings page.
Enter the OData URL in the address bar of your web browser.
When prompted, sign in using the username and password for one of the configured Connector accounts (see Configure Connector Accounts):
The browser should then display the response for the request.
Enter <BaseURL>/<ApplicationName>/odata/<ApiVersion>
in the address bar of your web browser (e.g. https://myhost/GrandAvenue/odata/v2). You may be required to enter the username and password for one of the configured Connector accounts (see Configure Connector Accounts).
The browser should display the ODATA Service Document. The services displayed will depend upon your system configuration, but the JSON document will look something like this:
{
"@odata.context": "https://myhost/GrandAvenue/odata/v2/$metadata",
"value": [
{
"name": "CapaRequests",
"kind": "EntitySet",
"url": "CapaRequests"
},
{
"name": "TaskAssignments",
"kind": "EntitySet",
"url": "TaskAssignments"
}
]
}
Enter <BaseURL>/<ApplicationName>/odata/<ApiVersion>/$metadata
in the address bar of your web browser (e.g. https://myhost/GrandAvenue/odata/v2/$metadata). You may be required to enter the username and password for one of the configured Connector accounts (see Configure Connector Accounts).
The browser should display the ODATA Metadata. This contains information about all the fields available from services exposed in the OData API. The information displayed will depend upon your system configuration, but the XML document will look something like this:
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
<edmx:DataServices>
<Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="GrandAvenue.Api">
<EntityType Name="CapaRequest">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="CapaID" Type="Edm.String" MaxLength="100"/>
<Property Name="Status" Type="Edm.String" MaxLength="100"/>
...
<Property Name="ID" Type="Edm.Int64" Nullable="false"/>
<Property Name="CreatedDate" Type="Edm.Date"/>
</EntityType>
<EntityType Name="TaskAssignment">
<Key>
<PropertyRef Name="ID"/>
</Key>
<Property Name="ProcessName" Type="Edm.String" MaxLength="100"/>
<Property Name="TaskName" Type="Edm.String" MaxLength="100"/>
...
<Property Name="ID" Type="Edm.Int64" Nullable="false"/>
<Property Name="CreatedDate" Type="Edm.Date"/>
</EntityType>
<EntityContainer Name="Container">
<EntitySet Name="CapaRequests" EntityType="GrandAvenue.Api.CapaRequest"/>
<EntitySet Name="TaskAssignments" EntityType="GrandAvenue.Api.TaskAssignment"/>
</EntityContainer>
</Schema>
</edmx:DataServices>
</edmx:Edmx>
Enter /<BaseURL>/<ApplicationName>/odata/<ApiVersion>/<resourceName>
in the address bar of your web browser (e.g. https://myhost/GrandAvenue/odata/v2/CapaRequests). You may be required to enter the username and password for one of the configured Connector accounts (see Configure Connector Accounts).
The browser should display the ODATA JSON information for the items for that resource. The information displayed depends upon the resource and the items in your system, but it will look something like this (This is an example of CAPA Requests):
{
"@odata.context": "https://myhost/GrandAvenue/odata/v2/$metadata#CapaRequests",
"value": [
{
"CapaID": "CAPA-00001",
"Status": "Investigation",
"Description": "Example CAPA Request.",
...
"ID": 2,
"CreatedDate": "2014-01-03"
},
{
"CapaID": "CAPA-00002",
"Status": "Closed",
"Description": "An Example ",
...
"ID": 3,
"CreatedDate": "2015-10-22"
}
]
}
Enter <BaseURL>/<ApplicationName>/odata/<ApiVersion>/<resourceName>(<ID>)
in the address bar of your web browser (e.g. https://myhost/GrandAvenue/odata/v2/CapaRequests(2)
).
The ID is the internal 64-bit integer ID returned when querying all items.
The browser should display the ODATA JSON information for the item for that resource. The information displayed depends upon the resource and the items in your system, but it will look something like this (This is an example of a CAPA Request):
{
"@odata.context": "https://myhost/GrandAvenue/odata/v2/$metadata#CapaRequests$entity",
"CapaID": "CAPA-00001",
"Status": "Investigation",
"Description": "Example CAPA Request.",
...
"ID": 2,
"CreatedDate": "2014-01-03"
}
Endpoints for Grand Avenue entities that also store file content (e.g., Documents), provide a /FileContent property that will allow you to download the corresponding file.
Enter <BaseURL>/<ApplicationName>/odata/<ApiVersion>/<resourceName>(<ID>)/FileContent
in the address bar of your web browser, signing in with a configured Connector account if necessary.
Example: https://myhost/GrandAvenue/odata/v2/Documents(2)/FileContent
The browser will download the requested file associated with the item for that resource.
Send a POST request to the URL <BaseURL>/<ApplicationName>/odata/<ApiVersion>/<resourceName>
(e.g. https://myhost/GrandAvenue/odata/v2/Parts) with values for the corresponding fields required in the web application.
{
"Name": "Example Part",
"Number": "Part-7654",
"UnitOfMeasure": "EA"
}
The ODATA response to the example JSON above would look like this:
{
"@odata.context":"http://myhost/GrandAvenue/odata/v2/$metadata#Parts/$entity",
"Name":"Example Part",
"Number":"Part-7654",
"UnitOfMeasure":"EA",
"Active":"Yes",
"HasSuppliers":"No",
"ApiVersion": **2** ,
"ID":24,
"CreatedDate":"2020-11-17"
}
Excel 2016 supports reading OData v4 feeds. You can access Grand Avenue OData from Excel 2016 as follows:
<BaseURL>/<ApplicationName>/odata/<ApiVersion>
as the URL.
This data can be refreshed on demand and referenced in other formulas in the excel workbook.
NOTE: The examples in this section use the CapaRequests and Complaints service endpoints, but the basic principle is the same for all properties and service endpoints.
The following OData Query options are supported by the Grand Avenue OData API:
The first query option is placed at the end of the service URL after a '?'. Additional options are appended after a '&'. The following example would return the ID, CapaID and Created Date for the first two CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$top=2&$select=ID,CapaID,CreatedDate
The $filter OData query option is used to filter the items returned based upon the value of properties for each item. The $filter option is applied before any other OData query option such as $top, $skip or $count is applied.
Find all CAPA Requests with a CapaID of 'CAPA-00001':
https://myhost/GrandAvenue/odata/v2/CapaRequests?$filter=CapaID eq 'CAPA-00001'
Find all CAPA Requests created between July 1, 2016 and November 18, 2017:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$filter=CreatedDate gt 2016-07-01 and CreatedDate lt 2017-11-18
Find all CAPA Requests with a Status of Investigation or Implementation:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$filter=Status eq 'Investigation' or Status eq 'Implementation'
Find all CAPA Requests with the word quality in the description:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$filter=contains(Description, 'quality')
Find all CAPA Requests with an ID less than or equal to 3
https://myhost/GrandAvenue/odata/v2/CapaRequests?$filter=ID le 3
The $select OData query option is used to choose which properties will be returned for matching entities.
Return the CapaID and ID properties for all CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$select=CapaID,ID
Return the ID, CapaID and CreatedDate properties the CAPA Request with an ID of 2:
https://myhost/GrandAvenue/odata/v2/CapaRequests(2)?$select=ID,CapaID,CreatedDate
The $expand OData query option is used to choose which navigation properties will be expanded for matching entities.
Expand the TaskAssignments property for all CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$expand=TaskAssignments
Expand the TaskAssignments property for the CAPA Request with an ID of 2:
https://myhost/GrandAvenue/odata/v2/CapaRequests(2)?$expand=TaskAssignments
Expand the ResultingCapaRequest property for all Complaints in the system:
https://myhost/GrandAvenue/odata/v2/Complaints?$expand=ResultingCapaRequest
{
"@odata.context": "https://myhost/GrandAvenue/odata/v2/$metadata#Complaints",
"value": [
{
"ComplaintID": "COMPLAINT-00001",
"Status": "Processing",
"Description": "Example Complaint",
...
"ID": 2,
"CreatedDate": "2014-01-03",
"ResultingCapaRequest": {
"CapaID": "CAPA-00025",
"Status": "Investigation",
...
}
},
{
"ComplaintID": "COMPLAINT-00002",
"Status": "Closed",
"Description": "Another Complaint",
...
"ID": 3,
"CreatedDate": "2015-10-22",
"ResultingCapaRequest": null
}
]
}
The $top OData query option is used to specify how many of items to return starting from the first item.
Return the first 5 CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$top=5
The $skip OData query option is used to specify how many items to skip before returning items. $skip is applied before the $top option regardless of order.
Return all but the first 3 CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$skip=3
Return the fourth and fifth CAPA Requests in the system:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$skip=3&$top=2
The $orderby OData query option is used to sort the items before they are returned. This is applied before the $skip and $top options regardless of their order in the request URI.
Return all CAPA Requests in the system, most recently created first:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$orderby=CreatedDate desc
Return all CAPA Requests in the system sorted by Status then by CreatedDate:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$orderby=Status,CreatedDate
The $count OData query option is used to include the number of items returned. The count is done after the $filter option is applied. The $skip and $top options do not affect the value of the count.
When the $count option is applied the json results will add an @odata.count property at the top level as follows:
{
"@odata.context": "https://myhost/GrandAvenue/odata/v2/$metadata#CapaRequests",
"@odata.count": 2,
"value": [
{
"CapaID": "CAPA-00001",
"Status": "Investigation",
"Description": "Example CAPA Request.",
...
"ID": 2,
"CreatedDate": "2014-01-03"
},
{
"CapaID": "CAPA-00002",
"Status": "Closed",
"Description": "An Example ",
...
"ID": 3,
"CreatedDate": "2015-10-22"
}
]
}
Return all CAPA Requests in the system including the count:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$count=true
Return CAPA Requests including count with a Status of Investigation:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$count=true&$filter=Status eq 'Investigation'
Return the second and third CAPA Requests but include the count of all CAPA Requests:
https://myhost/GrandAvenue/odata/v2/CapaRequests?$count=true&$skip=1&$top=2
When an organization deploys the Grand Avenue Software Connector modules, there are configuration steps that should be performed. Each step has its own configuration screen to assist System Administrators in getting the system ready for production.
The links on this page allow a System Administrator to configure access to the web service APIs provided by the Connector modules.
This page allows a System Administrator to configure special reserved accounts that can be used to access the web services defined in the Connector modules. Connector Accounts are used to invoke the web services with their configured username and password.
Connector accounts have the following characteristics:
The accounts cannot sign in using the normal Sign In page.
The accounts cannot be assigned tasks or roles in Grand Avenue Software.
The accounts can be added to Access Lists (see Configure Access Lists) to control which modules they can access.
Passwords for the accounts do not expire and can only be changed on this configuration page.
The accounts do not appear on the Manage Users pages and can only be configured using this page.
Add Connector Account - Used to add a new Connector account to the system.
Edit Connector Account - Used to make changes to existing Connector accounts.
Click the "Save" button to apply your changes and return to the previous page.
Clicking the "Cancel" button will return you to the previous page without saving your changes.
Enter a unique Connector Account ID. The Connector Account ID and password are the credentials that will be used for accessing Connector APIs. Any changes to the Account ID will be recorded in a "User ID Change History" table and displayed on the "Info" page for the Connector account.
Use the Description field to explain the purpose/scope of the Connector account.
Indicate which modules or module permissions the account should be authorized to access by setting the fields to "Yes" or "No" for each access right. When adding an account, the values for these fields reflect the default settings for each module's access list.
Click the "Save" button to save changes and return to the previous page.
Click the "Cancel" button to discard your changes and return to the previous page.
A Connector account that is deactivated will no longer be able to access Connector APIs.
Click the "Deactivate" button to deactivate the Connector account.
Clicking the "Cancel" button will return you to the previous page without deactivating the Connector account.
This page allows you to reactivate a Connector account that was previously deactivated. Once activated, the Connector account can be used for accessing Connector APIs.
Click the "Activate" button to reactivate the Connector account.
Clicking the "Cancel" button will return you to the previous page without reactivating the Connector account.
The Connector modules include an OData web service API for accessing information in Grand Avenue.
To make the OData API available for use, set the "Enable OData API?" option to "Yes".
When an upgrade of Grand Avenue introduces API changes that are incompatible with the previous API, the incompatible changes are packaged as a new "version" of the API. The previous version of the API will be temporarily supported but marked as "Deprecated" to indicate that customers should migrate to the new version as soon as possible.
A table displays the list of all OData API versions supported by the system, with information about each version displayed in the following columns:
<BaseURL>/<ApplicationName>/odata/<ApiVersion>/<ResourceName>
https://server/GrandAvenue/odata/v2/$metadata
NOTE: The OData API and the corresponding API version must be enabled before any of the above URLs can be view. Each URL only includes resources for modules that have been activated.
The "Enable OData API vX?" fields indicate whether those versions are currently enabled. Setting a field to "No" will disable that version and prevent any access (returning a 404 "Not Found" error).
By default, all access to OData APIs must be encrypted by HTTPs. You can allow OData APIs to be accessed without encrypting the connection by setting the "Require HTTPs?" option to "No".
By default, all endpoints that can contain file content expose a "/FileContent" path that can be used to retrieve the corresponding file content for an entity. You can disable that access by setting the "Enable OData File Content Access?" field to "No". When disabled, the system will return a "(403) Forbidden" response for that path.
Click the "Save" button to apply your changes and return to the previous page.
Click the "Reload Application" button to save your changes and recycle the .NET Application Pool.
Clicking the "Cancel" button will return you to the previous page without saving your changes.
Copyright © 2003-2025, Grand Avenue Software, Inc.
All rights reserved.