Does OnceSource Gateway have an API I can use to integrate with other systems?

In this article, get an in depth description of Idencia's available API calls

Overview

The Idencia Public API offers a robust set of GraphQL endpoints to perform various tasks efficiently. This article covers essential operations and configurations available through GraphQL calls:

Authentication

Configure and manage your Idencia account settings and API access.

Handling Errors

Retrieve Data

• • Get a List of Items: Fetch detailed information about items stored in Idencia.

  • Get a List of Projects: Retrieve comprehensive data regarding projects managed within Idencia.

Create Operations

• • Create a New Item Type: Define and add new item types to categorize items effectively.

  • Create a New Item: Initiate the creation of a new item within the Idencia system.

  • Create a New Project: Establish a new project framework within Idencia's project management system.

  • Create a New Custom Item Type: Customize item types within existing projects or independently without a predefined project structure.

  • Create a New Custom Property: Define and assign custom properties to items or projects for enhanced data management.

Update Operations

• • Update an Existing Item: Modify and update details of an item stored in Idencia associated with created organization.

  • Update an Item's Custom Property: Adjust specific custom properties associated with an item for accurate data representation.

  • Update an Existing Project: Modify and update existing project details and configurations.

  • Update an Item Type: Adjust and update the characteristics and attributes of predefined item types within Idencia.

  • Update a Custom Item Type: Modify and refine custom item types associated with ongoing projects or standalone configurations.

By leveraging Idencia's GraphQL API capabilities for these tasks, users can streamline their workflows, enhance data management practices, and maintain operational efficiency within their projects and inventory management processes.

Authentication

Idencia's API utilizes access tokens for authentication. To obtain an access token, you need to authenticate using Idencia's login REST API endpoint. Upon successful authentication, the login endpoint will provide you with an access token.

Access tokens serve as credentials for accessing Idencia's API resources securely. They are scoped to specific permissions based on the user or application making the request.

It is crucial to handle access tokens securely and avoid exposing them in publicly accessible areas like GitHub repositories or client-side code. Always transmit access tokens over HTTPS to protect them from interception.

All API requests to Idencia must be made over HTTPS. Requests made over plain HTTP will be rejected for security reasons. Additionally, API requests without valid access tokens will not be authorized.

By leveraging access tokens generated via Idencia's login REST API endpoint, you ensure secure and authenticated interactions with Idencia's API, maintaining the integrity and confidentiality of your data.

For accessing various API we need to get AccessToken which act as key to call all the available openAPI. Replace "yourusername@gmail.com" and "yoursecretpassword" with the actual credentials which created on Idencia portal and also replace Endpoint with actual Idencia endpoint.

 

Here is example curl for fetching AccessToken 

 

This call returns AccessToken attached with specific user requested through body

 

Response send by server

Breakdown of response received after calling login API

An access token is a compact digital artifact, typically in the form of a JSON Web Token (JWT), that grants permissions to a user (the resource owner) to access certain resources. These tokens act as an electronic key, ensuring that the user has the correct permissions to access the data they are requesting

A refresh token is a special token that is used to obtain more access tokens. This allows you to have short-lived access tokens without having to collect credentials every time one expires.

The ID token is a JSON Web Token (JWT) that contains claims about the identity of the authenticated user, such as name, email, and other details. You can use this identity information inside your application. The ID token can also be used to authenticate users to your resource servers or server applications.

Errors in Idencia APIs

Idencia GraphQL API follows standard HTTP response codes to indicate the success or failure of API requests. Here’s how errors are categorized:

• Success Codes (2xx): Requests that fall within the 2xx range indicate successful operations. These responses confirm that the requested action was completed successfully.

• Client Errors (4xx): Errors in the 4xx range indicate issues with the request made by the client. These errors can often be resolved by correcting the request parameters or configuration. Examples include:

  • 400 Bad Request: The request was invalid or malformed.

  • 401 Unauthorized: The request lacks valid authentication credentials.

  • 403 Forbidden: The server understood the request but refuses to authorize it.

  • 404 Not Found: The requested resource could not be found.

  • 422 Unprocessable Entity: The server understands the request but cannot process it due to semantic errors (e.g., validation errors).

  Additionally, some 4xx errors include error codes that provide brief explanations of the specific issue encountered, such as missing required parameters or invalid input data.

• Server Errors (5xx): Errors in the 5xx range indicate problems with Idencia’s servers and are relatively rare. These errors typically require no action from the client other than retrying the request after some time.

Handling Errors

To handle errors effectively when interacting with Idencia's GraphQL API:

• Programmatic Handling: Implement logic to interpret and handle specific error codes returned in the 4xx range programmatically. For instance, handle scenarios where a resource is not found or a request is unauthorized.

• Retry Mechanisms: Consider implementing retry mechanisms for 5xx errors, which may indicate temporary server issues.

By adhering to these error handling practices, developers can ensure robust and reliable integration with Idencia's GraphQL API, enhancing the overall stability and resilience of their applications.

Retrieve Data

Get a List of Items Types

Details of parameters in curl.

<ItemType> - Under this tag is all of the information about the Item Type of this Item.

• <Id> - The internal unique identifier for the item type.  This is a 16 byte GUID.

• <searchNumber> - The item type's Number field.

• <searchName> - The item type's Name field

• <defaultProcessId> - The internal unique identifier for the defaultProcess.  This is a 16 byte GUID.

• <Type> - The type of ItemType.

• <ProjectId> - The internal unique identifier for the Project.  This is a 16 byte GUID.

• <productSegment> -

• <isActive> - A flag to indicate if the itemType is active or not.  'true' if active, or 'false' if not active.

• <CreatedAt> - The UTC date/time stamp the item was created.

• <isDeleted> - A flag to indicate if the item has been deleted.  'true' if deleted, or 'false' if not deleted.

• <updatedAt> - The UTC date/time stamp the item type was last modified on the server.

• <QuantityRequired> - The value of the number of quantity required.

• <quantityProduced> - The value of the number of quantity produced.

• <organizationID> - The internal unique identifier for the respected organisation id where this itemtype belongs.  This is a 16 byte GUID.

• <ModifiedBy> - The first and last name of the user who recorded the step.

• <CustomProperties> - Under this tag are all of the Item Type Custom Properties that have values.

  • <CustomProperty> - (multiple) - Under this tag will be Name and Value pairs for each Item Type Custom property that has a value

    • <Name> - The name of the Custom Property

    • <CustomPropertyValue> - The value of the Custom Property
      
      

<Items> - Under this tag will be listed each item within the Item Type

• <Item> (multiple) - a single item in the list of items that match the request parameters
  
  

  • <Id> - The internal unique identifier for the item.  This is a 16 byte GUID.

  • <IsDeleted> - A flag to indicate if the item has been deleted.  'true' if deleted, or 'false' if not deleted.

  • <updatedAt> - The UTC date/time stamp the item was last modified on the server.

  • <CreatedById> - The unique identifier of the user who created the item.

  • <CreatedBy> - The first and last name of the user who created the item.

  • <CreatedAt> - The UTC date/time stamp the item was created.

  • <CurrentPhase> - The name of the most recent Process Phase

  • <CustomProperties> - Under this tag are all of the Item Custom Properties that have values

    • <CustomProperty> - Under this tag will be Name and Value pairs for each Item Custom property that has a value

      • <Name> - The name of the Custom Property

      • <Value> - The value of the Custom Property

  • <HasFailedSteps> - A flag to indicate if the Item has Pass/Fail steps in the current process marked as Failed. 'true' if there are failed steps, 'false' if there are no failed steps.

  • <IsProcessComplete> - A flag to indicate if the Item is currently running a process or not.  'true' if no process is running, or 'false' if a process is running.

  • <SerialNumber> - The serial number assigned to the Item.

  • <searchNumber> - The search number assigned to the Item.

  • <createdAt> - The date/time the Item was created.

  • <itemTypeId> - The internal unique identifier for the itemTypeId.  This is a 16 byte GUID.

  • <projectId> - The internal unique identifier for the project.  This is a 16 byte GUID.

  • <shipmentId> - The internal unique identifier for the Shipment.  This is a 16 byte GUID.

  • <serialNumberType> - The type of Serial Number.

  • <latitude> –

  • <longitude> –

  • <sentToHicams> -

  • <forneyTestPending> -

  • <organizationID> - The internal unique identifier for the associated organization.  This is a 16 byte GUID.

  • <modifiedBy> The internal unique identifier for the associated user who modified.  This is a 16 byte GUID.

  • <deletedAt> The date/time the Item was deleted.

  • <Process> (multiple) - Under this tag is all of the information about a process.  If more than one process has been run on an item, this tag is used for each process.

    • <Name> - The name of the Process.

    • <ProcessPhases> (multiple) - Under this tag are all of the Process Phases

      • <Phase> (multiple) - Under this tag are the Phase properties

        • <Name> - The name of the Phase

        • <Steps> - Under this tag are all of the steps in the Phase

          • <Step> (multiple) - This tag indicates a step within this phase of the process.

            • <Name> - The name of the step.

            • <id> - The internal unique identifier for the associated step. This is a 16 byte GUID.

            • <description> - The description of the step.

            • <phaseID> - The identifier for the phase this step belongs to.

            • <order> - The order of the step within the phase.

            • <type> - The type of step. <isRequired> - Whether the step is required (boolean).

            • <allowFailedStep> - Whether the step can fail (boolean).

            • <hasNotApplicableOption> - Whether the step has a "Not Applicable" option (boolean).

            • <defaultOption> - The default option for the step. <customPassLabel> - Custom label for the "Pass" option.

            • <customPassLabel> Custom label for the "Pass" option.

            • <customFailLabel> - Custom label for the "Fail" option.

            • <customNALabel> - Custom label for the "Not Applicable" option.

            • <customPropertyId> - Identifier for the custom property associated with the step.

            • <defaultValueOfCustomProperty> - Default value for the custom property.

            • <isHidden> - Whether the step is hidden (boolean).

            • <propertyDropdownId> - Identifier for the property dropdown associated with the step.

            • <mask> - Mask applied to the step's input.

            • <isDefaultToCurrentDate> - Whether the step defaults to the current date (boolean).

            • <decimalPlace> - Decimal places allowed for the step's input. <lowerLimit> - Lower limit for the step's input.

            • <lowerLimit> - Lower limit for the step's input.

            • <upperLimit> - Upper limit for the step's input.

            • <isComputedLimits> - Whether the limits are computed (boolean).

            • <lowerLimitFormula> - Formula for computing the lower limit.

            • <upperLimitFormula> - Formula for computing the upper limit.

            • <allowValuesOutsideOfRange> - Whether values outside the range are allowed (boolean).

            • <tagName> - Tag name associated with the step.

            • <organizationID> - Identifier for the organization.

            • <isDeleted> - Whether the step is deleted (boolean).

            • <deletedAt> - The UTC date/time the step was deleted.

            • <createdAt> - The UTC date/time the step was created.

            • <updatedAt> - The UTC date/time stamp the step was last modified on the server.

            • <modifiedBy> - The internal unique identifier for the associated user who modified.  This is a 16 byte GUID.

Requires Parameters in Query

• organizationID

Here is example curl for fetching a list of Items

 

Response Example  

 

nextToken : It is defined as an identifier that was returned from the previous call to this operation, which can be used to return the next set of items in the list

In response we will receive array of all item according to limit which was applied by us.

Get a List of Projects

Requires Parameters in Query

• organizationID

  Here is example curl for fetching list of Projects

 

Response Example 

In response we will receive array of all item according to limit which was applied by us.

Mutations

Create a New Item Types

This call will create a new Item Type (not Process specific)

Requires Parameters in Mutations

• isActive

• name

• number

• type: 10

• searchNumber

• searchName

• organizationID

• productSegment

Here is example curl for fetching list of Projects

 

Response Example 

Create a New Item

This call will create a new Item with the specified properties.

Requires Parameters in Mutations

• itemTypeId

• organizationID

• searchNumber

• serialNumber

Here is example curl for fetching list of Projects

 

Response Example 

Create a New Project

This call will create new project

Requires Parameters in Mutations

• name

• organizationID

• Number

 

Response Example 

Create a Item custom properties

This call will insert a new item custom properties without Process.

Requires Parameters in Mutations

• customPropertyId

• itemsId

• organizationID

• Number

Create new Item Type Custom Properties

This call will insert a new item type custom properties without Process.

Requires Parameters in Mutations

• customPropertyId

• itemTypeId

• organizationID

• requiredProperty

Create new Shipments

This call will insert a new Shipments.

Requires Parameters in Mutations

• name

• organizationID

• Number

• scheduleDate

Create new Property Dropdown

This call will insert a new Property Dropdown

Requires Parameters in Mutations

• customPropertyId

• name

• options

Updating

Note - In updating only id is required of associated mutation

Update a Existing Item Types

This call will Update a Existing Item Type

Here is example curl for fetching list of Projects

 

Response Example 

Update a Existing Item

This call will Update a Existing item with the specified properties.

Here is example curl for fetching list of Projects

 

Response Example 

 

Update a Existing Project

This call will Update Existing project

 

Response Example 

Update a Existing Item custom properties

This call will Update Existing item custom properties without Process.

 

Update Existing Item Type Custom Properties

This call will Update Existing item type custom properties without Process.

Update Existing Shipments

This call will Update a Existing new Shipments.

Update Existing Property Dropdown

This call will Update Existing Property Dropdown

 

Filtering read results

GraphQL allows clients to request exactly the data they need, and nothing more. filtering is common requirements for many applications. This documentation will guide you through implementing filtering for reading results in GraphQL.

Query Example

Here are some example queries to demonstrate sorting and filtering.

<anyFields> : We can replace this with any available field associated with that Query we have to filter.

Fields in Response

We can also specify which fields we want in the response in <all the avilable fields>. For example, in the query below, we can request only the hasFailedStep field without retrieving all unnecessary data. This approach is applicable to all queries.

We have lots of filtering options in graphQL like

attributeExists: false

• This filter checks if a specific attribute does not exist in the item.

• Example: attributeExists: false for the attribute shipDateActual would return items where the shipDateActual attribute is not present.

attributeType: binary

• This filter checks if an attribute is of a specific type, in this case, binary.

• Example: attributeType: binary for an attribute would ensure that the attribute is of binary type.

beginsWith: ""

• This filter checks if the value of an attribute begins with a specific substring.

• Example: beginsWith: "Item" for the attribute name would return items where the name attribute starts with "Item".

between: ""

• This filter checks if the value of an attribute is between two specified values.

• Example: between: ["2023-01-01", "2023-12-31"] for the attribute createDate would return items where the createDate is between January 1, 2023, and December 31, 2023.

contains: ""

• This filter checks if the value of an attribute contains a specific substring.

• Example: contains: "urgent" for the attribute description would return items where the description attribute contains the word "urgent".

eq: "" ---

• This filter checks if the value of an attribute is equal to a specific value.

• Example: eq: "completed" for the attribute status would return items where the status attribute is "completed".

ge: ""

• This filter checks if the value of an attribute is greater than or equal to a specific value.

• Example: ge: "2023-01-01" for the attribute createDate would return items where the createDate is on or after January 1, 2023.

gt: ""

• This filter checks if the value of an attribute is greater than a specific value.

• Example: gt: "2023-01-01" for the attribute createDate would return items where the createDate is after January 1, 2023.

le: ""

• This filter checks if the value of an attribute is less than or equal to a specific value.

• Example: le: "2023-12-31" for the attribute createDate would return items where the createDate is on or before December 31, 2023.

lt: ""

• This filter checks if the value of an attribute is less than a specific value.

• Example: lt: "2023-12-31" for the attribute createDate would return items where the createDate is before December 31, 2023.

ne: ""

• This filter checks if the value of an attribute is not equal to a specific value.

• Example: ne: "canceled" for the attribute status would return items where the status attribute is not "canceled".

notContains: ""

• This filter checks if the value of an attribute does not contain a specific substring.

• Example: notContains: "urgent" for the attribute description would return items where the description attribute does not contain the word "urgent".

Pagination in results

Pagination in GraphQL is typically handled using arguments in your query that specify how many results to fetch (limit) and where to start fetching (nextToken ). Here’s a basic example of how pagination can be implemented in a GraphQL query:

Usage in cURL

If you were to use this in a cURL command, it would look something like this (assuming the GraphQL endpoint supports pagination):

Explanation

• Pagination Mechanism:

  • limit: Specifies how many items to fetch per page.

  • nextToken: Specifies where to start fetching the next page of results. It could be a cursor value indicating the end of the current page.

• GraphQL Variables:

  • limit and nextToken are GraphQL variables used to pass pagination parameters dynamically to the query.

• Response:

  • The response from GraphQL will include items, an array of Item objects, and nextToken, a cursor to fetch the next page of results.

This setup allows you to implement basic pagination in GraphQL queries, providing control over the number of items per page and navigation through result sets efficiently. Adjust the limit and nextToken variables as per your specific pagination needs.