Xytech Public Postman Collection

An extensive set of example API calls is available via the Platform’s REST API Postman Collection which you can your fork so that you can pull for future updates. This collection contains many example calls, including basic payload version to get you started.

Using cURL as a test client

cURL is a lightweight command line API client used for testing and troubleshooting.

Example curl to fetch job details (replace authorization string, baseURL and database name with your values)

curl --location 'https://baseURL/api/v2/database/DEMO/JmJob/job_no=342' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ***************' \

To avoid impacting user experience or other integrations, it is important to utilise the APIs efficiently:

1. Only fetch the fields you need - use the resultColumns parameter

2. Suppress null value fields - use the nullvaluehandling parameter

3. Disable alternate key handling - use the alternatekeyhandling parameter

4. Make use of Webhooks not polling - see the Webhooks guide.

5. Ensure the use of compression - include header Accept-Encoding: gzip or deflate

6. Always use pagination.

Licensing

The REST API is a licensed component.

Information You Will Need

To be able to connect with the REST API, you will need to know the instance details:

The API URL is constructed as follows:

{Site Base URLl}/api/v2/database/{dbname}/{endpoint}

e.g. https://example.com/mysite/api/v2/database/demo1/JmJob

For systems installed prior to mid 2023, you may also require the port number. All later systems are now setup with a proxy to avoid the need to know the port number.

If you do not have this information, please contact Xytech Technical Support.

An API user needs to have been created as a user in the Platform. The user, must be enabled for REST API access by flagging 'Allow API Login' on the user setup. As with all users, assign appropriate security roles (enable as a super user is not recommended).

Two methods are supported

• Client Credentials method (system to system access)

• SPA / browser sign-in method (interactive user authentication flow)

Pre-requisites Your auth provider has been configured and the Xytech app server has been configured. (Azure and Okta/Auth0)

Client-Credentials method, from auth provider you needs:

• Access token URL

• Client ID

• Client Secret

• Scope

For SPA method you need:

• Authorisation URL

• Access token URL

• Client ID

• Client Secret

Summary flow: - Obtain token from auth provider - Use token to make REST API calls until token expires.

For use case scenarios where database user accounts are employed, using the JWT Token may be the prefered method. Typical use might be for system to system authentication requirements.

Pre-requisite Xytech app server has been configured for JWT authentication

Summary flow: - Retrieve token passing login credentials in the POST body - Use token for all subsequent API calls, until token expires

Below are the URLs for login and token refresh.

{{baseURL}}/api/v2/database/{{dbName}}/orchestration/auth/login {{baseURL}}/api/v2/database/{{dbName}}/orchestration/auth/refresh

cURL Example:

Refresh example:

See additional authentication user guides for more details.

The REST API uses Basic Authentication and will require a login account. Always use HTTPS encrypted protocol when communicating with the REST API to ensure credentials are not passed in clear text.

The Xytech platform provides a REST API that enables you to create integrations and custom workflows with 3rd party systems.

You will need:

• Authentication credentials

• The base URL of the instance you wish to communicate with

External ID fields have now been added to layout and document customisation documents.

This is to enable the ability to import and export layouts via the REST API whilst storing an external identifier, 'external_key'.

Specific endpoints XeDocLayout, XeDocTemplate and XeDocField.

Note: Standard Xytech layouts should not not modified using the REST API, as any changes will be overwritten upon the next version update.

Work Order Transactions can be updated using the external_key field without having to know the order number (wo_no_seq).

i.e. previously to PATCH a transaction you needed to use:

/JmWoTransaction/wo_no_seq=1075735-1/jm_wo_transaction/external_key=PH20250103

Any custom fields you have defined through document customization are automatically included in REST API definition. There is specific naming convention that is a combination of the Custom Code you created via document customisation plus the internal field name concatenated with an underscore. i.e. {customization code}_{field name}

Document customization screen showing the user definable Customization Code

Document customization screen showing the internal field names:

Response from a GET call to fetch a Work Order that shows custom fields:

Users can enable custom dropdown fields (through enabling a document customisation flag 'Additional API details', so that when called by the REST API will return the additional attributes stored with the dropdown record such as external_key.

Xytech is, at a fundamental level, a system that deals with creating, updating, and utilizing a particular type of data object referred to as a document.

• Each Xytech document is a representation of a database table or collection of database tables and has an API endpoint.

  • Each endpoint has a primary table and may have one or more sub-tables.

Upsert provides the ability to create records if they don't already exist, or update them if they do.

Upsert functionality is provided using the PUT method and is available on all maintenance document types. (v11.0+)

PUT payload concepts

The most common use of the PUT method will be where a 3rd party identifier is known and you wish to create or update a Xytech record.

The external identifier is likely to be stored in the "external_key" field of the record.

What is important, is to supply the external_key field in multiple places:

1. In the URL

2. As a payload field within the key field object (this is for lookup of existing record)

3. Within the root body of the payload (this is for inserting the value)

This will ensure correct insert or update functionality.

Example to upsert a Job:

You will receive the ID of the created record if one does not already exist matching the external_key.

If you send the same payload again, you will receive a 2xx success code, no new ID as the record already exists (any changes would update the record).

See the OpenAPI definition on endpoint details and the Postman collection for examples.

When performing an upsert, you may wish to clear any existing sub-table records before adding new ones. This can be done in a single API call by adding a header.

Syntax: rowAction : {"deleteAll":["<sub-table>"]} Example: endpoint /LibMaster rowAction value: {"deleteAll":["lib_master_audio"]} This will delete all existing audio records of the library asset (and add new ones if defined in the payload)

Optionally, you can delete multiple sub-tables by including separating comma: Syntax: rowAction : {"DeleteAll":["<sub table name>","<sub table name>"]}

Full example: In this example we're creating or updating a library asset with a barcode identifier, if the record already exists the system will delete any existing audio and title records and create new audio and title records.

RESTful services utilize HTTP methods to differentiate between different types of API calls.

Methods

The REST service generates HTTP response codes. In many cases, the HTTP response code will be accompanied by additional information in the body or the header of the message. In some cases, the HTTP response code may be the only response.

For more information refer to the or a developer resource for HTTP status codes, such as the

There are differences in the payload structure between POST & GET calls when filtering by sub-table.

When using GET to fetch a payload filtered by a sub-table, the payload is missing the sub-table wrapper. The Swagger definition reports the correct payload structure that includes the sub-table wrapper, but that is not what works today.

A fix would mean a breaking change, so we shall not be correcting this until API v3.

Example of how Swagger defines the GET response payload for a sub-table of /XmTransmissionOrder endpoint, which includes the wrapper in this case mo_service_row.

Below is how the the endpoint actually responds that excludes the wrapper.

When using a POST call that includes creating sub-table records, some endpoints respond with invalid sub-table record IDs that are negative values. This has been resolved in v11.1 onwards.

There is an issue with a few endpoints when sending a JSON payload. The order the fields submitted within the payload can cause an error response when placed in an in an order the endpoint does not expect.

Some basic examples of API calls

GET

Retrieve Work Order header details returning specific fields and not null values:

curl --location --globoff 'http://{APIbaseURL}/JmWorkOrder/wo_no_seq=2627-1?resultColumns={"jm_work_order":["wo_no_seq","wo_desc","wo_begin_dt","wo_end_dt","phase_desc","sched_by_name"]}&nullvaluehandling=ignore' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic *************' \
--data '@'

Response:

{
    "jm_work_order": [
        {
            "wo_no_seq": {
                "wo_no_seq": "2627-1"
            },
            "wo_desc": "Dscription2",
            "wo_begin_dt": "2000-03-31T02:30:00-08:00",
            "wo_end_dt": "2000-03-31T05:30:00-08:00",
            "wo_type_no": {
                "wo_type_no": 3275,
                "wo_type_desc": "Production"
            }
        }
    ]
}

POST method

Create a new Work Order with minimal fields:

curl --location 'http://{APIbaseURL}/JmWorkOrder' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ********' \
--data '{
    "jm_work_order": [
        {
            "wo_desc": "Match20",
            "wo_begin_dt": "2023-08-22T10:00:00.000Z",
            "wo_end_dt": "2023-08-22T16:00:00.000Z",
            "wo_type_no": 17,
            "phase_code": "Bid",
            "rate_card_no": 1,
            "cust_id": 19
        }
    ]
}'

Response:

{
    "message": null,
    "tables": [
        "jm_work_order"
    ],
    "jm_work_order": {
        "record_identifiers": [
            "wo_no_seq"
        ],
        "records": [
            {
                "wo_no_seq": "8250-1"
            }
        ]
    }
}

PATCH

curl --location --request PATCH 'http://{APIbaseURL}/JmJob/job_no=67981' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic **********' \
--data '[
    {
        "op": "replace",
        "path": "job_desc",
        "value": "Hello World"
    },
    {
        "op": "replace",
        "path": "external_key",
        "value": 15411
    }
]'

Response: Status Code 204

PATCH Using POST Payload

There are two PATCH methods, one where you define the field and the operation, the other is to use the full POST JSON payload. To use the PATCH with the full JSON payload, you must include the header parameter: 'Content-Type: application/json-patch+json'

Example Work Order update using PATCH and the POST payload structure:

Response 200 status code

Notes: The payload must include the existing primary key as a URL parameter as well as in the body payload. The expected response status code for a successful PATCH can be 200 or ‘204’ where no response is returned.

List endpoints also support the PATCH method so that you can update multiple records using a query (see ‘Parameters’ section above for details on available query parameters). This method is the equilivent API functionality of the Grid Update feature in the UI.

Example to update multiple Work Orders using the $range query parameter:

Response Status Code 204.

As with GET, wildcards ‘%’ are supported such as: PATCH {base_url}__/ JmJobList?Query={"job_desc": "Sport%"}

See many other basic payload examples in the public .

REST API v1 was the first Xytech REST API product. It had limitations that required breaking changes to improve so v2 was made available from Xytech v9.4 with improved functionality.

REST API v1 is no longer supported in version 11.0 and beyond.

All new integrations should use API v2 and existing integrations should port to v2 as soon as possible.

To use v2 API, change the base URL version number from ../v1/.. to ../v2/..

Changes in v2 API

Payload structure changes

The payload structure has been enhanced to be more robust and scalable. The primary data object name is now always added as the root element of the payload with an array containing the details. v2 handles sub tables more gracefully and respects the hierarchy of the tables. With v1, the sub tables were often added to the bottom of the payload at the root level, which made it difficult to determine the relationship between tables and their sub items. With v2, the table names are included in the payload and the sub tables are added as children to maintain the relationships.

Example showing the root element for JmJob

All sub-tables are offset from the root object. See the OpenAPI documentation for details of the JSON structure for each endpoint.

In addition, v2 has many enhancements as detailed in this document.

To assist, below are main steps needed to migrate to API v2:

1. Change your URL to use the v2 path.

2. Adapt to the new and improved payload structure.

3. Utilise new parameters

API v1 base URL http://domain/api/v1/database/XYT_MAIN_V

API v2 base URL http://domain/api/v2/database/XYT_MAIN_V

The main difference is that v2 handles sub tables more gracefully and respects the hierarchy of the tables especially when making POST calls. See the examples below:

GET Jm_Job v1:

GET Jm_Job v2:

POST XmTransmissionOrder v1:

POST XmTransmissionOrder v2:

To improve responsiveness and design efficient integrations. The following additional URL parameters were added for GET requests:

NullValueHandling : ignore

This parameter removes all the fields with null values from the result set.

AlternateKeyHandling : ignore

This parameter instructs the API to not resolve the alternate keys in the payload for GET requests. In the example below, the highlighted items are removed from the result set when using the AlternateKeyHandling=ignore parameter:

Best practice:

ResultColumns

Always filter a GET call using resultColumns parameter so that you only return the fields you need.

Avoids making additional calls to check whether a record already exists before creating/updating it.

POST XmTransmissionOrder response payload with record IDs

Each payload contains a nested sub-section of key fields which are used for the lookup of records by a key field. This sub-subsection is identified by the primary key field name.

The nested sub-section of fields are not used for writing values to the database, values that need to be stored should be contained in the main root of the payload.

The sub-group always contains the primary key field and the 'external_key' field.

Additionally, there are sub-sections of related tables with their key fields. Lookups (using GET query parameters) can only filter sub-tables using the sub-table primary key and not their alternate keys, unless sub-table fields exist in the main body of the payload.

As a general rule, if you are creating or updating file values, the fields you need to write values to should be included in the root of the payload

Using POST, you have two options for creating and setting key values of sub-tables. Below is an example to create a JmJob that generates the primary key value (using -1) and assigns the Division, Customer and Job Type sub-table IDs. This structure follows the same structure you will receive from a GET call.

From Xytech version v10.2, an OpenAPI (previously referred to as Swagger) index page has been introduced to assist in the navigation and generation of OpenAPI definitions. The index page can be found by entering the base URL of your site (you use for accessing the Xytech UI) and adding “/ApiDocs” to the end (e.g. www.xytechexample.com/XYT_TEST/ApiDocs). The Xytech API Index page is displayed.

API Index Page

The index page displays groups of endpoints called modules for the selected database. Clicking on a module will reveal the endpoints within that module. Click on an endpoint, and the OpenAPI definition will be generated using the Swagger UI.

The Index is comprised of the following areas:

In some cases, you must also add a header to trigger the app server to perform a function as part of an API call. For example, when creating a Work Order, to load a Work Order Template you must provide the SaveArgument header parameter as well as including the wo_template_no value in the payload.

Below is a list of Save Arguments

Load a Template to an order

Applicable endpoints: JmWorkOrder, MoMediaOrder, XmTransmissionOrder

Loads Work Order Template to an order.

This replaces LoadTemplate as an improved method that includes the option to append or replace existing transactions. (Available from release 26.1)

saveArgument : {"LoadTemplateOption":1}

//option to load child templates
saveArgument : {"LoadTemplateOption":1,"LoadChildTemplates":"Y"}

Options:

• 1 = append template transactions to existing order transactions

• 0 = replace any existing order transactions with the template transactions

Applies to POST, PATCH and PUT methods. Requires the wo_template_no to exist in the payload.

Example:

POST - create Work Order and load template

Where the number represents the number of the template to load.

To load child templates (available from release 11.3), add an additional parameter called 'LoadChildTemplates'

Example when creating an order using a POST call. The template number must be provided in both the header and the payload.

For transmission orders, you can load a Service Template

And populate the XmTransmissionOrder payload with service_template_no value

Multiple Service Templates can be loaded by including comma separated values:

In this scenario you can leave the "service_template_no" in the body as null.

Function to void an Order.

Where the number represents the Work Order number sequence.

Example using a PATCH call:

Provides the ability to un-void an Order.

Example using a PATCH call with the header Content-Type : application/json-patch+json

v11.1

To actualize selected or all transactions. This save argument will update the transaction and order phase, effectively posting the actuals.

Variations:

Intended to be used in conjunction with the POST of actual actions. This save argument then performs the action of actualization.

Example single transaction actualization without times:

v11.1

Replicates the action UI menu item to 'Post' the batch.

Example PATCH payload:

Function to set the default Group of a scheduling resource. The Group must already be assigned to the Resource in the Group list.

Example using a PATCH call with the header Content-Type : application/json-patch+json

Changes the bid approval state of a Bid using number that represents the approval type.

Approval number types:

Example using a PATCH call to set the 'approved' value and the header save argument.

Where applicable, multiple save arguments can be used as an array separated by a comma.

Example:

Query Parameter

GET and PATCH List endpoints require query parameters.

This section describes the syntax and options used for the query parameter. This is a mandatory parameter for List documents.

The standard format for a “query” parameter is to add the parameter as query={} to the end of a GET request for a List document after the parameter delimiter (“?”), where the value of query= is a JSON object:

http://{APIbase_url}/documentList?query={key: value}

Such as:

http://{APIbase_url}/jmJobList?query={"job_no": "12345"}

Note: The query parameter is supported with GET and PATCH requests of List type documents and is not supported by GET requests for Setup or Maintenance documents.

In the simplest form, the value is a single piece of information, such as a string or integer. In more complex forms, the value is a JSON object containing specific formats as described below.

See section regarding URL encoding requirements:

To return items that match a specified string. The string can either be letters or numbers. Wildcard ‘%’ can be used. Remember to URL encode the % sign.

To return items that fall between a specified minimum and maximum numeric value.

To return items that match one of the values provided in a given set of values. See section below on wildcards

To return items that have NULL values. Note: Put pipe characters around NULL to differentiate it from the literal string “NULL”.

To return items that do not match the specified number, string, or NULL.

To return items where values are greater than or less than a given value.

Full GET example for greater than

(11.1) Ability to query where a field's value does not match an array of supplied values. Usage example: {{server}}/PmProjectList?query={"project_desc":{"$notin":["test", "Sarah"]}} Applies to GET queries.

(11.1) Ability to define an array of matching values that all have to match regardless of the order defined. {{server}}/LibMasterList?{"master_desc":{"$LIKEAND":["%Genesis%","%XHD%"]} Applies to GET queries.

The Null parameter returns any record that has a null value for the specified key, which indicates that no value has ever been set. This differentiates it from an empty string for text-based or date-based properties, a 0 value for numbers, and true or false values for Boolean properties.

Note: Not all fields support null values. If possible, check the OpenAPI definition whether the field allows nulls.

Values

• String values are not case-sensitive.

• DateTime values should be provided in a valid ISO date format.

When using HTML special characters as part of the query value, they must be URL encoded.

Example: to use a wildcard query such as "%dave%", the % needs substituting with %25. Once URL encoded will look like this %25dave%25

Example GET query with URL encoded wildcard : {{server}}/MoMediaOrderList?query={"wo_desc":"%25dave%25"}&resultcolumns={"L": ["wo_no", "wo_desc"]}

(The reason why %dave% fails to return valid results it that %da is the encoding for the Ú character)

This also applies to datetime values that use the offset attribute with the + sign.

To include a value of "2023-06-01T09:00+5:00" in a URL query parameter, substitute + with %2b

Example: query={"wo_begin_dt":{"$range":["2023-06-01T09:00%2b5:00","2023-06-01T17:00%2b5:00"]}}

If you wanted to search for multiple wildcard values contained within a single field that all need to exist, then you can include a list of wildcard values.

For example, if you wanted to search for media assets that have "Tale" AND "Dark" in their "master_desc" field, you can use the following query parameter:

{"master_desc":{$in:["%Tale%Dark%","%Tale%Dark%"]}}

Note you may need to use encode the % symbol (for instance if using Postman) you will need:

{"master_desc":{$in:["%25Tale%25Dark%25","%25Tale%25Dark%25"]}}

Used by the GET method on List and Maintenance endpoints.

resultColumns parameter is used to define the fields you wish to return in the response. Without this parameter, the response will contain all document fields which is not recommended for performance reasons.

For example: {APIbaseurl}/JmJobList?Query={"job_no":2}&resultColumns={"L":["job_no","job_desc"]}

Job No. and Job Description fields will be included in the response. Important to include the “L” as the top-level element.

Sub-Table columns

Many endpoints include related sub-tables in their responses. Example syntax to include specific sub-table columns.

Below example fetches a transmission order description and all it's service row numbers:

{APIbase_url}/XmTransmissionOrder/wo_no_seq=7655-1?resultColumns={"jm_work_order":["wo_desc"],"mo_service_row":["service_row_no"]}

Response:

API Pagination is available for the GET Query on List endpoints.

Sort parameters: Syntax: sort=[field1 sort, field2 sort] Example: sort=["job_desc desc", "job_no desc"]

Note: If you don’t specify pageSize, the ‘page’ and ‘sort’ options are ignored. If you do specify a pageSize and do not pass a page, page will default to 1.

Example: To return the first 10 records on page 1 sorted by product_no:

Full example:

The above example queries for jobs that have job numbers in the range of 1 to 67982, returns job number and job description fields but only the 7th page with 5 jobs sorted first by description (descending) then by job number (descending).

The response header will include a parameter called 'Pagination-Count' which is the count of all records as a result of the query.

This will allows you to call for data in manageable payloads without exceeding memory limitations.

This optional parameter suppresses all null value fields from the response payload. Using this parameter reduces the payload size dramatically, especially for larger queries. (v10.6+)

Applicable for all GET calls with List, Maintenance & Report endpoints. Values are ‘ignore’ or ‘include’ (default). 'include' means that all null values are included in the response.

Examples: URL Parameter:- nullvaluehandling=include (default)

URL Parameter:- nullvaluehandling=ignore (recommended)

Notice how all null value fields are omitted.

This optional parameter suppresses additional key fields from the responses. If you do not need to work with key fields other than the primary key, use this parameter to keep the API call performant and reduce the processing overhead when not working with alternate key fields. (v10.6+)

Applicable for all GET calls with List, Maintenance endpoints.

Values are ‘ignore’ or ‘include’ (default). ‘include’ includes alternate keys in the response.

Example: URL Parameter:- alternatekeyhandling=include (default)

URL Parameter:- alternatekeyhandling=ignore (recomended)

Notice how the additional key fields barcode, external_key & umid are omitted.

The REST API uses Date time formats in ISO format with an optional offset value.

e.g. 2014-11-03T22:20:00+00:00

If you omit the offset value when using POST to create a record, you can use a header parameter to set the time zone your dates are using. The advantage of using this header approach, is that it will respect any daylight savings offset applicable to the date given.

e.g. header: Source-Time-Zone-Name: Pacific Standard Time

This example will will create records in the time zone of Pacific Standard Time. Remember to omit the offset values in your time formats.

See link for list of

(11.1)

REST API calls support the ability to pass the Division as an override to the API API user's default Division.

An optional header called "Division-Code" exists where you can include the Division code. This will ensure the correct results are returned for the API users when using Divisions.

The API user account must have been given user access to the division to be able to successfully pass it in the API call. If not, you will receive an error message.

e.g. Division-Code : GS

Using Postman:

This capability replicates the functionality when a user accesses the webapp with their default division, who will see data filtered by their default Division.

Applicable only to sites that use the Division feature.