Online Help for Connector




Module Overview

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.



Connector OData Resources

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:


Published OData Resources

All OData Resources are available beneath the OData Root URL.

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.


Using the OpenAPI Documentation

The Connector modules publish API documentation in a JSON format in compliance with the OpenAPI 3.0 standard. The documentation is available

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:

Swagger UI Example


OData HTTP Methods

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.

OData IDs

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.


Using the OData API

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.


Entering Basic Authentication

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):

Sign In Screen

The browser should then display the response for the request.


Accessing the OData Service Document

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"
        }
    ]
}

Accessing the OData Metadata

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>

Accessing an OData Resource

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"
        }
    ]
}

Accessing a single item by OData ID

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"
}

Downloading the associated file content for an item

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.


Adding a single item

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"
}

Using OData API in Microsoft Excel

Excel 2016 supports reading OData v4 feeds. You can access Grand Avenue OData from Excel 2016 as follows:

This data can be refreshed on demand and referenced in other formulas in the excel workbook.


Using OData Query Options

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


Using the $filter OData Query Option

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


Using the $select OData Query Option

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


Using the $expand OData Query Option

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
        }
    ]
}

Using the $top OData Query Option

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


Using the $skip OData Query Option

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


Using the $orderby OData Query Option

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


Using the $count OData Query Option

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



Configuration

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.


Configure Connector

The links on this page allow a System Administrator to configure access to the web service APIs provided by the Connector modules.


Configure Connector Accounts

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:

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.


Add/Edit Connector Account

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.


Deactivate Connector Account

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.


Activate 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.


Configure OData API

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".

OData API Versions

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:

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.