The Alliant User Applications include the Alliant API application, which is a Representational State Transfer (REST) Application Programming Interface (API) feature that allows you to interact with the Alliant system programmatically. You can use Alliant API to perform the following:

• Create data in the Alliant system.
• Read data from the Alliant system.
• Update data in the Alliant system.
• Delete data from the Alliant system.
• Use an Alliant Tool on an Item (for example, set a Contract to Complete).

Alliant API is based on REST principles. All interactions with Alliant API are made using standard Hypertext Transfer Protocol (HTTP) or Hypertext Transfer Protocol Secure (HTTPS) requests to a set of predefined endpoints (resources). Alliant API endpoints accept and return data in JavaScript Object Notation (JSON) format.

Alliant API has the same hardware and software requirements as Alliant UI, and is installed and configured during the Alliant UI installation. When Alliant UI and Alliant API are installed, a Help Page is available from the Alliant Instance on the Web Server at {base address}/{AlliantInstance}/api/help (for example, http://WebServer/AlliantWebServerInstance/api/help).

The following Alliant terms and concepts are related to Alliant API:

Adjustments on Tab are Adjustments that are added to an Item directly from a User-Defined Tab (UD Tabs) on the Item window in Alliant Administration or Alliant UI. Adjustments on Tab must be associated with an Adjustment Type that is configured to use only one Detail Type. The Status for an Adjustment on Tab generally corresponds to the Status of the Item with which it is associated.

In Alliant API, when you submit or receive data that includes Adjustments on Tab data, the Adjustments on Tab names include the a_ prefix and are based on the name of the tab to which they are attached (for example, when the Adjustments are on a tab called Advance Schedule, the Adjustments on Tab name is a_Advance Schedule).

Adjustments on Tab include Adjustment Details and Adjustment Control Totals subproperties:

"a_{AdjustmentOnTabName}":{
    "adjustmentDetails": [{}, {}, ... ],
    "adjustmentTotals": [{}, {}, ... ]
}

The adjustmentDetails property contains Adjustment Details data Items. Each Adjustment Details Item contains properties that represent the fields defined for the Adjustments on Tab. Some of these properties represent Reference fields. It is required that the _action subproperty is present for each Adjustment Details Item included in a request body for a Create or Update request. The value of the _action subproperty specifies the Action to perform on the Adjustment Details data Item. The following Actions are available for Adjustment Details data Items:

• add -- specify this action when you want to add an Adjustment Item.

• update -- specify this action when you want to update data for an Adjustment Item.

• delete -- specify this action when you want to delete an Adjustment Item.

The adjustmentTotals property contains Adjustment Control Total data Items for the Adjustments on Tab. Adjustment Control Totals are not present in a response and are not valid in a request body when the Entry Format for the corresponding Adjustment Type is not configured to use Adjustment Control Totals. Adjustment Control Totals have either one or two Items based on the associated Entry Format.

When you submit Adjustment data in a create or update request, include all of the properties that are applicable based on the associated Adjustment Type or Entry Format.

Set of Data Items that are directly associated with a main (parent) Data Item of a resource. Child Collection Data Items include specific sets of properties that define each Item. For example, a Contact Item contains the Physical Addresses Child Collection, which defines the Physical Addresses that are related to a Contact. Additionally, each Physical Address includes multiple properties that are used to identify the Address (address1, city, postalCode, and so forth). Child Collection Data Items are accessed only from the parent resource (for example, you can only change a Physical Address by accessing the specific Contact and editing the information for the Physical Address for that Contact).

Set of Data Items that can exist independently in the Alliant system and can also be associated with other Alliant Data Items (for example, Adjustments in the Contract module). Unlike Child Collection, Cross-Reference Items can be accessed from their own specific resource (except for delete) or from a parent resource.

Reference properties are properties that refer to existing Items in the Alliant system (for example, a Contact includes the Contact Type reference property). The names of reference properties are always suffixed with Reference. Reference properties are objects that include subproperties that identify the referenced Item. In a request, reference properties can identity Items using one of the subproperties below:

• _objectRef -- identifies the Item by a positive integer value that corresponds to an _objectId value for an Item in the same request. Specifying an _objectRef value for a corresponding _objectId value sets the Reference property value to the Item identified by the _objectId value.

• _fromContext -- identifies the Item from the context when the value is true (for example, when you submit a request for a specific Contract, the context is the Contract specified in the request resource).

• _useLicensor -- identifies the Item from the licensorContactReference field value when the value is true. This property is only valid for the actualStartDateItemReference, actualEndDateItemReference, estimatedStartDateItemReference, and estimatedEndDateItemReference reference properties available on the IP Rights and IP Rights Template Rights data items.

• _useLicensee -- identifies the Item from the licenseeContactReference field value when the value is true. This property is only valid for the actualStartDateItemReference, actualEndDateItemReference, estimatedStartDateItemReference, and estimatedEndDateItemReference reference properties available on the IP Rights and IP Rights Template Rights data items.

• guid -- identifies the Item from the GUID (or Unique Identity) value that you specify.

• sid -- identifies the Item from the System ID value that you specify.

• id -- identifies the Item from the Alliant ID field value that you specify.

• name -- identifies the Item from the Alliant Name field value that you specify.

• description -- identifies the Item from the Alliant Description field value that you specify.

• displayName -- identifies the Item from the Display Name value for the Item.

When you specify more than one of the above subproperties in the request body, the value is taken from the first property that is available in the following order: _objectRef, _fromContext, _useLicensor, _useLicensee, guid, sid, id, name, description, displayName

Reference properties include the following subproperties when returned in a response:

• _type -- identifies the Alliant Datatype for the Item Type (for example, Contract, Contact, Period, and so forth). Types correspond to the names of resources accessible from the API endpoints (for example, api/data/period).

• displayName -- specifies the Display Name value for the Item.

and one of the subproperties below:

• guid -- specifies the GUID (or Unique Identity) value for the Item.

• _fromContext -- specifies when the Item is identified from the context. The value for this property is always true when returned in a response. When an Item is identified from the context, the guid property is not returned in the response.

• _useLicensor -- specifies when the Item is identified from the licensorContactReference value. The value for this property is always true when returned in a response. This property is only valid for the actualStartDateItemReference, actualEndDateItemReference, estimatedStartDateItemReference, and estimatedEndDateItemReference reference properties available on the IP Rights and IP Rights Template Rights data items. When this property is included in the response, the guid, fromContext, and useLicensee properties are not returned in the response.

• _useLicensee -- specifies when the Item is identified from the licenseeContactReference value. The value for this property is always true when returned in a response. This property is only valid for the actualStartDateItemReference, actualEndDateItemReference, estimatedStartDateItemReference, and estimatedEndDateItemReference reference properties available on the IP Rights and IP Rights Template Rights data items. When this property is included in the response, the guid, fromContext, and useLicensor properties are not returned in the response.

The level of detail for Items returned in a response is determined by the Verbosity parameters. You specify the Verbosity for Items in a response using the following request query parameters: minimal, verbose, default, include, and exclude.

Datatypes defined in Alliant to specify the valid values for a User-Defined Field (UD Fields).

User-Defined Fields (UD Fields) are fields that are defined in Alliant for customizing Transaction Characteristics. The names of properties representing UD Fields are prefixed by ud_ or by udLookup_ (for UD Fields configured to use Lookup values) followed by the name of a UD Field (for example, ud_field1 or udLookup_field1). When the Datatype for a UD Field is one of the Alliant Transaction Characteristics or a User-Defined Datatype, the API property representing the UD Field is a Reference property (for example, ud_field1Reference or udLookup_field1Reference). When a UD Field is configured to use Lookup values, the API property representing the UD Field is an object with the udLookupItems array subproperty. Entry format and lookup type of UD Field determine properties of each object in udLookupItems array.

Your Alliant System Administrator must configure User Group permissions in Alliant Security to allow Users access to data in the Alliant system. The permissions necessary for Alliant API depend on the modules that you want to access and the Actions that you want to perform.

Note: When a User submits a Multiple-Item Read request for a module other than Contracts for which they do not have the View Action assigned, the request succeeds but the response contains data in Minimal verbosity format. When a User submits a Multiple-Item Read request for Contracts and they do not have the View Action assigned for Contracts, the request succeeds but the response contains data in Minimal verbosity format, excluding Contracts for which the User does not have access based on the values in the Owner Group and View Access Group fields for each Contract. This restriction applies only when your Alliant system is configured to use the Contract Access by User Group feature.

Alliant API returns responses in JSON format. The property names in a response are in camel case notation starting with a lowercase letter. Every response from Alliant API has the following format:

 {
   "result": {},
   "errors": [],
   "warnings": [],
   "hasErrors": false,
   "hasWarnings": false
 }

The response properties are as follows:

• result -- this property is an object. This property contains the data for a request, when applicable, or returns null when no data is returned. When you request an Item or Items, the Item data returns in this property. When you create or update an Item, the data for the new or updated Item returns in this property.
• errors -- this property is an array. This property contains any Errors that occur while processing the request.
• warnings -- this property is an array. This property contains any Warnings related to the request.
• hasErrors -- this property is a boolean. This property contains true when there are Errors in the errors property. This property contains false when there are no Errors in the errors property.
• hasWarnings -- this property is a boolean. This property contains true when there are Warnings in the warnings property. This property contains false when there are no Warnings in the warnings property.

Alliant API returns responses in JSON format. The property names in a response are in camel case notation starting with a lowercase letter. When you use Alliant API to request data for multiple Items, the data is returned in the following format:

{
"result": {
    "previousPageUrl": null,
    "nextPageUrl": null,
    "itemCount": X,
    "totalItemCount": X,
    "items": []
},
"errors": [],
"warnings": [],
"hasErrors": false,
"hasWarnings": false
}

The response properties are as follows:

• result -- this property is an object. This property contains the data for a request, when applicable, or returns null when no data is returned. When you request an Item or Items, the Item data returns in this property. When you create or update an Item, the data for the new or updated Item returns in this property.
  • previousPageUrl -- this property is a string. This property contains a URL for the previous set of results when there are more Items found than the request specifies to return. When you are currently accessing the first page, this property has a null value.
  • nextPageUrl -- this property is a string. This property contains a URL for the next set of results when there are more Items found than the request specifies to return. When you are currently accessing the last page, this property has a null value.
  • itemCount -- this property is an integer. This property specifies the number of Items returned for the request.
  • totalItemCount -- this property is an integer. This property specifies the total number of Items in the Alliant system that match the request criteria.
  • items -- this property is an array. This property displays the Item data for each Item returned in the request.
• errors -- this property is an array. This property contains any Errors that occur while processing the request.
• warnings -- this property is an array. This property contains any Warnings related to the request.
• hasErrors -- this property is a boolean. This property contains true when there are Errors in the errors property. This property contains false when there are no Errors in the errors property.
• hasWarnings -- this property is a boolean. This property contains true when there are Warnings in the warnings property. This property contains false when there are no Warnings in the warnings property.

Each object in errors or warnings array has the following format:

{
  "message":"value",
  "type":"value",
  "subType":"value",
  "itemType":"value",
  "itemKey":"value",
  "field":"value",
  "guid":"value",
  "sid":1001,
  "sequenceNumber":1001,
  "largeSequenceNumber":1001,
  "id":"value",
  "description":"value",
  "name":"value",
  "value":"value",
  "LogId":123456,
  "dateTime":"value"
}

The properties are as follows:

• message -- contains text describing the Error or Warning. This property is always present.

• type -- specifies the type of the Error or Warning. This property is always present. The following Error Types are possible:

  • General -- indicates a general Error or Warning.
  • Usage -- indicates a usage Error or Warning.
  • Serialization -- indicates a serialization Error or Warning.
  • NotApplicable -- indicates a not applicable Error or Warning.
  • NotAvailable -- indicates a not available Error or Warning.
  • Lock -- indicates an Error related to Alliant locking. This error can be retried.
  • Concurrency -- indicates a concurrency Error or failed Timestamp check. Concurrency errors can be retried.
  • Security -- indicates an authentication or authorization Error.
  • DatabaseDeadlock -- indicates a Database deadlock Error. This error can be retried.

• subType -- contains the System ID value for the Validation Rule that caused the Error or Warning when the Error or Warning relates to failing a validation check. This property returns only for Validation Error Types.

• itemType -- contains the Item Type value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• itemKey -- contains the Item Key value in a string for the Item that caused the Error or Warning. This property does not return for every Error Type. Values are separated by commas when more than one value returns in the response.

• field -- contains the field name for the Item that caused the Error or Warning. This property does not return for every Error Type.

• guid -- contains the Unique Identity value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• sid -- contains the System ID value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• sequenceNumber -- contains the Sequence Number of a Child, Cross-Reference, or UD Field Lookup Item that caused the Error or Warning. This property does not return for every Error Type.

• largeSequenceNumber -- contains the Large Sequence Number of a Child, Cross-Reference, or UD Field Lookup Item that caused the Error or Warning. This property does not return for every Error Type.

• id -- contains the ID value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• description -- contains the Description value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• name -- contains the Name value for the Item that caused the Error or Warning. This property does not return for every Error Type.

• value -- contains the ID of the Reference Item that was not found and caused the Error or Warning when a referenced Item in a request was not found in the Alliant system. This property does not return for every Error Type.

• logId -- contains the Log ID for the Error message when an Error or Warning is logged to the Alliant Database. This property does not return for every Error Type.

• dateTime -- contains the Date and Time for the Error message when an Error or Warning is logged to the Alliant Database. This property does not return for every Error Type.

  Note: When the request fails with the 500 status code, a single message field is returned.