The Xillio API provides a platform with which developers can effortlessly build integrations with all popular content repositories, making content stored in both cloud content systems and legacy systems accessible from any application.

The core functionality of the Xillio API is to create, retrieve, manipulate and delete content no matter where it is stored. This is done by defining a set of operations which can be performed on every repository agnostically.

1. REST API

This section describes the second version of the official Xillio API. It defines the different endpoints of the API and the URL schema used. The way errors are handled and returned is also explained in this section.

1.1. Overview

The root endpoint of this API is https://{tenant}.xill.io/v2. This URL denotes that this API is currently in version 2 (v2) and works over HTTPS. Every tenant uses their own endpoint. This means {tenant} should be substituted by your tenant name. For example, if your tenant name is demo-tenant then your base URL would be https://demo-tenant.xill.io/v2.

To locate documents in a repository, an internal protocol called XDIP is used. The request URL is based on this XDIP. The XDIP and the request URLs are connector-specific. Therefore the request URLs should not be hand-crafted, but instead obtained by browsing the target repository through the API. This can be done by starting at the root entities endpoint and requesting a relation scope (e.g. path_children_reference).

The id field of an entity can be used to request that entity. This id field looks like this: https://{tenant}.xill.io/v2/entities/{configurationId}/{path}.

In this document, the id of an entity can also be referred to as its URL.

When the API returns an id, it always points to the latest version of an entity. Therefore, when a newer version of that entity is created, the previously used id will point to the new version, despite being similar. Only when explicitly requesting a version, using the version relation scope), is the id guaranteed to point to that specific version.

All request and response bodies are represented as JSON objects except for the /contents endpoints. These endpoints contain an entity’s contents in the request and response bodies. When making a request to the API which has a body, please note that the Content-Type header must be specified (e.g. Content-Type: application/json).

1.1.1. Pagination

The API supports pagination via the HTTP query parameters offset and limit with integer values.

Although the API itself supports pagination, it is up to the connector to actually implement it: this is clearly listed in each connector feature list as pagination.

If a connector does not support pagination or the request does not include pagination fields, then the result set is returned as a whole without pagination.

When pagination is specified, the result set is returned to the requestor by first skipping offset records and then taking the following limit records. An offset of 0 will not skip any record. A limit of 1 will return 1 record.

If at any time while applying the offset the result set is exhausted (the end is reached) then an empty result will be returned. If at any time applying the limit the result set is exhausted (the end is reached) then the records collected so far are returned.

Example: retrieve entities from the 3rd to the 10th
GET https://xillio.xill.io/v2/entities/59e4b5a6857/aba0005a28227?offset=2&limit=7
Computing offset and limit for the Nth page of M elements

If every page contains M elements, then the Nth page starts at the element ordinal (N - 1) * M + 1. For example, the first page starts at (1 - 1) * M + 1 = 1, so the offset is 0 (no elements to skip). The second page starts at ordinal M + 1, so the offset is M. The number of elements to skip is therefore one less than the ordinal of the first element on the given page. The size of the page is straightforward, since it is given by the M parameter, thus yielding:

offset = (N - 1) * M
limit = M

1.2. Authorization and Authentication

The Xillio API uses OAuth2 with the password flow for authentication. To use the API it is generally required to have a valid OAuth2 token as an Authorization header with a Bearer access token, and a sufficient level of privilege for the corresponding user. The authorization logic relies on the OAuth2 scopes mechanics, as documented here.

Getting a token requires a username and password.

Using this authentication method requires to specify client_id=app. Don’t forget to add this to each requests like shown below.

1.2.1. Retrieve a JWT token

Get a JWT token in exchange for a client id, client secret, username and password.

POST /oauth/token
------
HTTP/1.1 200 OK
Example Using curl
$ curl 'https://demo-tenant.xill.io/oauth/token' -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1' \
    -d 'grant_type=password&client_id=app&username=demo-user&password=demo-password'
Response Fields
Path Type Description

access_token

String

The bearer token to provide on subsequent API calls.

token_type

String

The type of the JWT token.

expires_in

Number

The number of seconds before this token expires.

scope

String

Space-separated list of scopes for this token.

jti

String

Identifier of this token.

tenant

String

Name of the tenant, for which this token is authorized.
Example Response
HTTP/1.1 200 OK

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsieGlsbGlvX2FwaSJdLCJ1c2VyX25hbWUiOiJkZW1vLXVzZXIiLCJzY29wZSI6WyJ1c2VyIiwidXNlcnMiLCJjb25maWd1cmF0aW9ucyIsImNvbnRlbnRzY3JpcHRzIiwicXVlcnk6Y29uZmlndXJlIiwicXVlcnk6ZXhlY3V0ZSIsInR5cGVzIiwidGVtcGxhdGVzIiwiZW50aXRpZXMiLCJjb250ZW50cyIsInRlbmFudCIsInJwYyIsInNlYXJjaCJdLCJleHAiOjE3MzAyNjI0NjIsImF1dGhvcml0aWVzIjpbIlJPTEVfQ09ORklHX0FETUlOIiwiUk9MRV9SUENfVVNFUiIsIlJPTEVfVVNFUl9BRE1JTiIsIlJPTEVfQ09OVEVOVFNDUklQVF9BRE1JTiIsIlJPTEVfU0VBUkNIIiwiUk9MRV9FTlRJVFlfQURNSU4iLCJST0xFX0VOVElUWV9VU0VSIiwiUk9MRV9RVUVSWV9BRE1JTiJdLCJqdGkiOiI4OWQ0MTg0YS1jOTgyLTQxZWItYTgxNi1mNjJlMmY1ZGI2ODciLCJ0ZW5hbnQiOiJkZW1vLXRlbmFudCIsImNsaWVudF9pZCI6ImFwcCJ9.1-jRbfGRaSLnhz-iC6gJNSyCEpYsdBOzEkGihXiOD6k",
  "token_type" : "bearer",
  "expires_in" : 43199,
  "scope" : "user users configurations contentscripts query:configure query:execute types templates entities contents tenant rpc search",
  "tenant" : "demo-tenant",
  "jti" : "89d4184a-c982-41eb-a816-f62e2f5db687"
}
Nearly all endpoints require an Authorization header with a Bearer access token. See the relevant endpoint documentation for details about the necessary OAuth2 scopes for your user.

1.2.2. Authorization Scopes and Roles

The access_token must be provided in other API calls as a Bearer token in the Authorization header. Such headers are commonly omitted in code snippets for brevity, but endpoints do list their requirements in term of OAuth2 user scopes.

Tokens granted in exchange for a user/password combination are valid for a list of "scopes". This is an overview of possible scopes:

Scopes Overview
Scope name Description

entities

Allows access to the /entities endpoint.

contents

Allows access to the /contents endpoint.

types

Allows access to the /types endpoint.

templates

Allows access to the /templates endpoint.

tenant

Allows access to the /tenant endpoint.

configurations

Allows access to the /configurations endpoint.

contentscripts

Allows access to the /configurations/contentScripts endpoint.

query:configure

Allows access to the /configurations/queries configuration endpoint.

query:execute

Allows access to the /queries endpoint.

users

Allows access to the /users endpoint.

user

Allows access to the /user endpoint.

rpc

Allows access to the /rpc endpoint.

search

Allows access to the /search endpoint.

These scopes give access to specific endpoints. Users have limited permissions on those endpoints, which is expressed using roles:

User Roles Overview
Role Description

USER_ADMIN

Allows administration of users.

CONFIG_ADMIN

Allows administration of configurations.

CONTENTSCRIPT_ADMIN

Allows administration of content scripts.

QUERY_ADMIN

Allows administration of named query configurations.

ENTITY_ADMIN

Allows modification, deletion and write access to content stored in repositories.

ENTITY_USER

Allows read access to content stored in repositories.

1.2.3. Passthrough Authorization

Normally a configuration for a repository will contain enough information to authenticate to the target repository transparently from the API user. When that is not possible, advisable or the target repository uses an unsupported authentication protocol, you can create a configuration using the passthroughAuthorization option set to true. The Passthrough-Authorization header is then required when making requests using that configuration. Failure to provide the header results in an Authorization Failed error.

Two types of Passthrough-Authorization are supported: Basic and Bearer. When you specify the Basic authentication header the username and password fields from your configuration are overridden. When you specify the Bearer authentication header the token field is overridden.

This should not be confused with the authentication required to access the Xillio API: passthrough authorization deals with authenticating towards the target repository.

1.3. Entities

The Xillio API format describes entities from many different content repositories, and allows to deal with content without in-depth knowledge of the underlying content repository.

Entities are designed to be declarative. This means that entities can be created or updated without having to know anything about the operations required to change their state in the target system. For example, to update an entity: retrieve it using the get entity endpoint, adjust the modified decorators where necessary, and post it to the update entity endpoint.

Entities are always represented in JSON, and contain several fields:

Entity Fields
Field Type Description

id

URL

A URL that points to the entity.

xdip

URL

A URL that is used internally to point to the entity. This value can be found in error messages and entity results.

kind

String

A simple content type string that describes the best match for the entity.

original

Object

An object containing all decorators as they were found in the content repository. This field is used by the create entity endpoint.

modified

Object

An object containing all decorators as they will be represented in the content repository. This field is identical to original on all entities that are retrieved from the api. It is used by the update entity endpoint.
An Example Entity
{
  "entity" : {
    "id" : "https://xillio.xill.io/v2/entities/59e4b5a6857aba0005a28227",
    "xdip" : "xdip://59e4b5a6857aba0005a28227/",
    "kind" : "Folder",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "created" : {
        "date" : "2017-08-22T14:24:50.000Z"
      },
      "modified" : {
        "date" : "2017-08-22T14:24:50.000Z"
      },
      "name" : {
        "systemName" : "root",
        "displayName" : "root"
      },
      "fileSystem" : {
        "path" : "/"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "created" : {
        "date" : "2017-08-22T14:24:50.000Z"
      },
      "modified" : {
        "date" : "2017-08-22T14:24:50.000Z"
      },
      "name" : {
        "systemName" : "root",
        "displayName" : "root"
      },
      "fileSystem" : {
        "path" : "/"
      }
    }
  }
}

1.3.1. Decorators

Within an entity, the 'original' and 'modified' sections contain decorators. Decorators are named sets of closely related fields. A collection of decorators is provided to represent most common metadata fields. Fields must be of one of the following types:

Supported field types
Type Description

BOOLEAN

Either true or false.

NUMBER

An integer or decimal number.

STRING

A textual value. A blank string value means: "intentionally left blank".

URL

A URL formatted string value.

DATE

An ISO date formatted string value. Format: yyyy-MM-ddTHH:mm:ss.sssTZD. The date format complies with https://www.w3.org/TR/NOTE-datetime.

ENUM

A STRING with limited possible values.

OBJECT

A nested object containing key-value pairs.

For each field an indicator is given whether the field is required or optional. Required fields cannot be omitted and cannot have value 'null'. Optional fields can be set to null or may be omitted entirely.

Container

The container decorator signifies an entity that can have children. If the decorator is not present on an entity, the entity cannot have children. For example, this decorator is not present on an entity representing a file in a file system.

When the container decorator is present, the entity can have children. For example, this decorator is present on an entity representing a folder in a file system.

The Container Decorator
{
  "container": {
    "hasChildren": true
  }
}
Container Decorator Fields
Field Name Description Type Required

hasChildren

Set to true if this entity might have children. Set to false if it is certain that the object does not have any children.

BOOLEAN

ContentType

The contentType decorator contains the content type used by the target system. The exact value differs for every connector.

The ContentType Decorator
{
  "contentType": {
    "systemName": "86797349759843867824",
    "displayName": "FileMetadata"
  }
}
ContentType Decorator Fields
Field Name Description Type Required

displayName

The human readable name of the content type.

STRING

name

Deprecated (see notes). The name of the content type.

STRING

systemName

The technical name of the content type. Can also be a system specific unique id or name.

STRING

Notes

The use of contentType.name has been deprecated. This field has been changed to contentType.systemName in order to distinguish a system-specific technical name of a content type from a human readable one.

Some systems might not have a human readable content type name. In that case the contentType.displayName field should be equal to the contentType.systemName field.

Created

The created decorator signifies when an entity was created.

The Created Decorator
{
  "created": {
    "date": "2017-08-22T14:29:53.000+02:00",
    "by": {
      "systemName": "5508584",
      "displayName": "Ernst van Rheenen",
      "email": "ernst.rheenen@example.com"
    }
  }
}
Created Decorator Fields
Field Name Description Type Required

date

The creation date of the entity. Has millisecond accuracy. The time zone is formatted as Z for UTC or +02:00 otherwise.

DATE

by

An object specifying the user that created this entity.

OBJECT

Object(User) Fields
Field Name Description Type Required

systemName

The technical name of the user. Can also be a system specific unique id or name.

STRING

displayName

The human readable name of the user.

STRING

email

The email address associated with the user.

STRING

Description

The description decorator provides a small excerpt or description for an entity. This is generally used as a preview message or subtitle.

The Description Decorator
{
  "description": {
    "short": "Code because you can!"
  }
}
Description Decorator Fields
Field Name Description Type Required

short

A short extract or subtitle of the entity.

STRING

File

The file decorator contains various pieces of information related to files on a file system.

The File Decorator
{
  "file": {
    "extension": "jpg",
    "rawExtension": "JPG",
    "size": 12697
  }
}
File Decorator Fields
Field Name Description Type Required

extension

The (optionally cleaned) extension of the file. Not present when the file does not have an extension.

STRING

rawExtension

The extension of the file as found on the filesystem. Contains the empty string ("") when the file does not have an extension.

STRING

size

The size of the file in bytes.

NUMBER

Notes

The extension field is automatically computed from an internal extension database. It contains a normalized version of the rawExtension field. For instance, if the rawExtension field contains PNG, the extension field contains png.

FileSystem

The fileSystem decorator contains the absolute path of a file or folder on the configured repository.

The FileSystem Decorator
{
  "fileSystem": {
    "path": "/home/dave/Pictures"
  }
}
FileSystem Decorator Fields
Field Name Description Type Required

path

The absolute path of the folder from the 'root' of the configured repository.

STRING

Hash

The hash decorator contains one or more types of hashes corresponding to the entity.

The Hash Decorator
{
  "hash": {
    "md5": "75f12bf60fd789722416e8feec3f4e83",
    "sha1": "de60ab502c20cd0cfb18c80f823e6d1dac94aa7a",
    "sha256": "3b9deece7e58947079d8a73d88ad0694e296b40d507a7ff9c25f4a4eb1974ec2"
  }
}
Hash Decorator Fields
Field Name Description Type Required

md5

The md5 hash of the entity’s contents.

STRING

sha1

The sha1 hash of the entity’s contents.

STRING

sha256

The sha256 hash of the entity’s contents.

STRING

Language

The language decorator contains information about the language of the entity’s content and (optionally) the base entity of which this is a translation. Whenever a language tag is mentioned, we refer to strings compliant with BCP-47.

The Language Decorator
{
  "tag": "it-IT",
  "translationOf": "https://demo-tenant.xill.io/v2/entities/5a27e7d82ab79c00076a78bd/document.txt?language=0"
}
Language Decorator Fields
Field Name Description Type Required

tag

The language tag for this entity.

STRING

translationOf

A reference to the entity that is the master from which this one was translated.

STRING

Notes

System specific language tags are converted into BCP-47 compliant tags. Custom language tags defined in target systems are required to be BCP-47 compliant.

MimeType

The mimeType decorator contains a reference to the type of media that is contained by the entity. A list of types can be found on http://www.freeformatter.com/mime-types-list.html.

The MimeType Decorator
{
  "mimeType": {
    "type": "text/plain"
  }
}
MimeType Decorator Fields
Field Name Description Type Required

type

The MIME Type of the entity’s contents.

STRING

Modified

The modified decorator signifies when an entity was last modified.

The Modified Decorator
{
  "modified": {
    "date": "2017-08-22T14:29:53.000+02:00",
    "by": {
      "systemName": "13",
      "displayName": "Thomas Biesaart",
      "email": "thomas.biesaart@example.com"
    }
  }
}
Modified Decorator Fields
Field Name Description Type Required

date

The last modification date of the entity. Has millisecond accuracy. The time zone is formatted as Z for UTC or +02:00 otherwise.

DATE

by

An object specifying the user that last modified this entity.

OBJECT

Object(User) Fields
Field Name Description Type Required

systemName

The technical name of the user. Can also be a system specific unique id or name.

STRING

displayName

The human readable name of the user.

STRING

email

The email address associated with the user.

STRING

Name

The name decorator represents both a technical name and a human readable name for an entity. This could be anything from the title of a web page to the filename of a document.

The Name Decorator
{
  "name": {
    "displayName": "Three Basic Personas",
    "systemName": "personas.docx"
  }
}
Name Decorator Fields
Field Name Description Type Required

displayName

The human readable name of the entity.

STRING

systemName

The technical name of the entity. Can also be a system specific unique id or name.

STRING

Notes

Some systems might not have a human readable name. In that case the name.displayName field should be equal to the name.systemName field.

Parent

The parent decorator contains a reference to the entity’s parent.

The Parent Decorator
{
  "parent": {
    "id": "https://demo-tenant.xill.io/v2/entities/59e4b5a6857aba0005a28228/images/2017"
  }
}
Parent Decorator Fields
Field Name Description Type Required

id

The URL that points to the entity’s parent.

STRING

Update

An entity can be moved in the path relation scope by changing the parent decorator in an update entity call. Afterwards the entity will be contained in the entity specified in the modified parent decorator and removed from its original container.

If the parent decorator is set to a non-existing entity the update will return a No Such Entity error.
If the parent decorator is set to an entity that cannot contain other entities update will return an Operation Not Allowed error.
Preview

The preview decorator provides a location for previews of an entity that the underlying system provides. For instance, if the entity is a piece of source code from GitHub, the preview.html field contains a URL to the GitHub view of that code.

This can also be a system specific URL to a resource.

The Preview Decorator
{
  "preview": {
    "html": "https://github.com/ChappIO/loud/blob/master/README.md"
  }
}
Preview Decorator Fields
Field Name Description Type Required

html

A web view that can be opened in a browser.

STRING

Notes

Note that the URL must not point to the Xillio API contents endpoint for this entity.

Version

The version decorator contains the version number of the entity.

The Version Decorator
{
  "version": {
    "tag": "36354-436"
  }
}
Version Decorator Fields
Field Name Description Type Required

tag

The version number or tag of this entity.

STRING

Notes

This decorator is read-only. It cannot be used to update the version of an entity.

Workflow

The workflow decorator signifies the state of the entity in the workflow of the target system.

The Workflow Decorator
{
  "workflow": {
    "status": {
      "systemName": "5508585",
      "displayName": "publish",
      "normalized": "PUBLISHED"
    },
    "date": "2017-08-22T14:29:53.000+02:00",
    "by": {
      "systemName": "5508584",
      "displayName": "Ernst van Rheenen",
      "email": "ernst.rheenen@example.com"
    }
  }
}
Workflow Decorator Fields
Field Name Description Type Required

status

An object specifying the status within the workflow for this entity.

OBJECT

date

The date at which this status is set. Has millisecond accuracy. The time zone is formatted as Z for UTC or +02:00 otherwise.

DATE

by

An object specifying the user that set this status.

OBJECT

Object(User) Fields
Field Name Description Type Required

systemName

The technical name of the user. Can also be a system specific unique id or name.

STRING

displayName

The human readable name of the user.

STRING

email

The email address associated with the user.

STRING

Object(Status) Fields
Field Name Description Type Required

systemName

The technical name of the status. Can also be a system specific unique id or name. Should always be present when reading entities if the workflow decorator is present.

STRING

displayName

The human readable name of the status.

STRING

normalized

The normalized interpretation of the status to provide unification among target systems. Any of: "DRAFT", "PUBLISHED", "ARCHIVED".

ENUM

Notes

For read operations entities always provide at least status.systemName

For write operations with workflow decorator:

  • If not present, the connectors will default to target system’s least impactful status. For example, in web content management systems, an entity would rather be created in draft state than published.

  • If present, either status.systemName or status.normalizedStatus must always be filled, however the status.normalizedStatus takes precedence if filled. If neither is filled or if the system is not able to work with either field, an error will be thrown.

The number of normalized statuses is likely to grow in the future as more unification possibilities have been identified amongst systems.

1.4. Downloading Files

The Xillio API allows to download files that are stored in any content repository. Files can be downloaded from a configured content repository using the /contents endpoint. For example:

$ curl 'https://demo-tenant.xill.io/v2/contents/59e0b361a7b11b000586ebea/images/logo.png' --output logo.png

Downloading a file is only possible if the target entity contains contents. If the target entity is not capable of containing contents, the response will be a No Binary Content error.

When updating or downloading an entity’s contents, it is necessary to supply respectively a Content-Type or Accept header. The values from these headers are used to determine which content script should be run to transform the content. If these headers are not specified they will default to application/octet-stream, which indicates that the content should remain unchanged. See the Content Scripts section for more information on how to write such a script.

1.5. Updating Entities

The Xillio API allows to retrieve and update entities in configured content repositories. For example:

let request = require('request');
const baseUrl = 'https://demo-tenant.xill.io/v2';

// Get the entity
request({
    url: baseUrl + '/entities/59faf4f2a7b11b0005a8c264/SANDBOX.md',
    json: true
}, function(error, response, body) {

    // Update the name
    body.entity.modified.name.systemName = "RENAMED.md";

    // Send it back
    request({
        method: 'put',
        url: body.entity.id,
        json: body.entity
    }, function(error, response, body) {
        console.log("Updated Name: ", body.entity.original.name.displayName);
    });

});

1.6. Scopes for Entities

When the target of a request to the Xillio API is an entity or a collection of entities, it is possible to use the scopes for entities as an expressive way to retrieve different aspects of an entity, such as additional metadata or other related entities. All /entities endpoints support scopes, except for the DELETE requests.

To specify a scope for a request, add a scope query parameter with a comma-separated list of scope names. The response json will contain an element for each requested scope. Using a scope that does not exist will raise a No Such Scope error.

There are two broad categories of scopes: those that retrieve a different representation for an entity (return type scope), and those that retrieve other entities in relation with an entity (relation scope).

It is not always required to specify a scope. The default one is the entity return type.

1.6.1. Return Type Scopes

These scopes provide a way to extract different kinds of information from an entity. They can be used alone, or as the last part of a relation scope.

Return types:
Value Description

entity

All entity metadata that is mapped to the Xillio API standard entity format.

metadata

All metadata that is not mapped to the Xillio API standard entity format. See the section User-defined Metadata

1.6.2. Relation Scopes

Relation scopes allow retrieving entities related to the entity that is the subject of the current request. It consists of three parts separated by underscores (_):

  • the relation type,

  • the direction,

  • the return type.

The combination of those three components represent a valid scope, although the availability of a specific scope is connector dependent, and specified in every "Feature and limitations" sections.

Relation type

The relation type denotes the type of related information to retrieve, or in other words, the relation to navigate. Currently, the following are defined:

Relation types:
Value Description

path

Containment relation as in file systems and the internet.

version

Relation between realizations of the same entity at different times.

translation

Relation between different translations of the same entity, i.e. same content, different language. This applies to both content and metadata.
Direction

The direction of the scope represents the kind of navigation strategy to be performed on the relation. In general, relations give rise to trees or graphs, in some cases we view the relation simply as a set (a complete, undirected graph).

Directions:
Value Description

parents

The direct ancestors, i.e. the first level of entities reachable by ascending (going against) the relation arrows

children

The direct descendants, i.e. the first level of entities reachable by descending (going along) the relation arrows

all

All entities recursively reachable following all arrows in both directions, including the target. For set-like relations, this is the same as getting any other direction plus the target. If requested from an entity in a tree-like relationship, this will retrieve the whole tree.
Example with the path relation:

For instance, if the entity "myFolder" contains the entity "myFile", then the path relation can be navigated:

  • in the children direction from "myFolder", yielding "myfile",

  • in the parents direction from "myFile", yielding "myFolder".

Example with the translation relation:

If the entity "document.EN", written in English, has translations "document.IT" and "document.DE" for Italian and German. By requesting the all direction targeting any of the mentioned entities it is possible to retrieve the list of all translations, obtaining in every case "document.EN", "document.IT", "document.DE".

If the parents direction from "document.IT" is requested, the result depends on the target repository support for translations:

  • if it has a concept of a "source" document, reflected in the translationOf field of the language decorator, then only the original document is returned (in this case "document.EN").

  • if however the target repository does not have such support thus representing the translation relation as a set, all translations are returned, with the exception of the target of the request (the result will be "document.DE" and "document.EN").

Return type

The return type determines the format of the data returned by a relationship scoped request, much in a similar way to the case of a return type scoped request, but applied to all entities reached by the navigation strategy.

Return types:
Value Description

entity

All entity metadata that is mapped to the Xillio API standard entity format

reference

The URL (id) of the entities
Examples
Get a folder and the entities it contains:
Request:
GET /v2/entities/{configurationId}/{path}?scope=entity,path_children_entity
Response:
{
    "entity" : { ... },
    "path_children_entity" : [
        { ... },
        { ... },
        ...
    ]
}
Get the references to all versions and translations of an entity:
Request:
GET /v2/entities/{configurationId}/{path}?scope=version_all_reference,translation_all_reference
Response:
{
    "version_all_reference" : [
        {"id" : "<version1-url>", "versionTag" : "1"},
        {"id" : "<version2-url>", "versionTag" : "2"},
        ....
    ],
    "translation_all_reference" : [
        {"id" : "<translation-Italian-url>", "languageTag" : "IT_it"},
        {"id" : "<translation-French-url>", "languageTag" : "FR_fr"},
                ....
    ]
}
Get the previous versions of an entity:
Request:
GET /v2/entities/{configurationId}/{path}?scope=version_parents_entity
Response:
{
    "version_parents_entity" : [
        { ... },
        { ... }
    ]
}
See Entities for more detailed examples.

1.6.3. Legacy Scopes

For backward compatibility, "legacy" scopes are still usable. Their use is deprecated and should be replaced by the new scope system whenever possible. Their description here is provided as an aid for code migration.

Those scopes consist of a single value, and cannot be combined.

Legacy scopes:
Value Equivalent Description

childList

path_children_reference

The list of references to the children of the entity

children

path_children_entity

The children of the entity

translationList

translation_all_reference

The list of references to the translations of the entity

translations

translation_all_entity

The translations of the entity

versionList

version_all_reference

The list or references to the versions of the entity

versions

version_all_entity

The versions of the entity

1.6.4. Scopes for the Entity Endpoint

As a reference, this section presents a summary of the rules governing the use of the scopes, as well as an exhaustive list of all the available scopes with their semantics.

General Scope Rules

  • The default scope is always entity

  • Any number of scopes can be specified for a request, as a comma-separated list

  • Scopes which do not apply to an endpoint as specified by its documentation will raise an exception in the HTTP 400 range

  • Scopes which are not natively available on the target repository or not supported by a connector will result in an empty list in the response ([])

  • For each requested scope, the response will contain an element named after the scope name.

  • Duplicate scopes will be ignored

Scope List

In this list, "the subject" refers to the entity to which the scope will be applied, for example the entity referred by the URL used to issue the request.

The * in the scope denotes the part that has to be completed with one of the scope return types, and which will format the elements of the response as URLs or as JSON structures following the Xillio API standard entity format.

Scopes:
Scope Description Comments

entity

All metadata mapped to the standard Xillio API format

See Entities for more information

metadata

All metadata not mapped to the standard Xillio API format

See User-defined Metadata for more information

path_parents_*

All entities containing the subject

In most cases, returns a list containing the parent folder(s)

path_children_*

All entities contained in the subject

path_all_*

All entities reachable from the subject with any number of steps along the path containment relation

In a simple file system, returns all files and folders

translation_parents_*

The entity from which the subject was translated

One document only is expected as result for repositories that have a master document concept for translations, while most systems will return all translations for the target instead

translation_children_*

The entities which are translations of the subject

The direct translations of the target are expected as result for repositories that have a master document concept for translations, while most systems will instead return all translations for the target, direct or not

translation_all_*

All translations for the subject

version_parents_*

The predecessors of the subject

In most cases, returns the previous version. See the Notes on versions

version_children_*

The entities derived from the subject

In most cases, returns the next version. See the Notes on versions

version_all_*

All versions of the subject

Returns the whole version history for the target, including next versions
Notes on versions

In most repositories the version history is linear, i.e. every document has at most one previous version and at most one next version. As with translation, some repositories do not record the previous version as such, but rely on the version tag to infer their sequence. In this case, when asking for any version scope, the behaviour is connector-specific.

1.6.5. User-defined Metadata

The metadata scope allows to retrieve all user-defined metadata of an entity. This returns all properties from the target system in a unified structure. Most properties are grouped in templates, but some properties are part of the content type definition. Templates are reusable groups of strongly related properties that can be applied to an entity.

Metadata Properties
Property Example Description

contentType.systemName

"FileData"

The unique identifier for the content type.

contentType.displayName (optional)

"Generic File"

The human-readable name for the content type.

contentType.description (optional)

"A file uploaded through the sync client."

The description for the content type.

contentType.properties.<propertyName>.value

true

The value of this property. This can be a string, number, boolean or a list of strings.

templates.<systemName>.displayName (optional)

"Offshore Project"

The human-readable name for the template.

templates.<systemName>.description (optional)

"A project executed by an external partner."

The description for the template.

templates.<systemName>.properties.<propertyName>.value

"Acme Inc."

The value of this property. This can be a string, number, boolean or a list of strings.

 
{
    "contentType": {
        "systemName": "c6f334cc708c",
        "properties": {
            "size": {
                "displayName": "File Size",
                "description": "The size in bytes.",
                "value": 9786
            }
        }
    },
    "templates": {
        "ca266bbfea62": {
            "displayName": "Offshore Project",
            "description": "A project executed by an external partner.",
            "properties": {
                "partner": {
                    "displayName": "Executing Partner",
                    "value": "Acme Inc."
                },
                "customer": {
                    "displayName": "Customer",
                    "value": "L. Cartoons Ltd."
                },
                "status": {
                    "displayName": "Project Status",
                    "description": "Planned, in progress, canceled, finished.",
                    "value": "in progress"
                }
            }
        }
    }
}

1.7. Content Scripts

Content scripts are Node.js scripts that export a transformation function. This function should return the mapped content: this can be a string, an object or a Buffer. When the script is used this function will be invoked with an object containing the unmapped content. If the passEntity flag is set to true on the content script, the input will also contain the entity object.

Content Script Input
Property Description

content

A Buffer object containing the unmapped content.

entity

An optional JSON object containing the entity.

The simplest content script is one that directly returns the content: the identity script.

The Identity Script
module.exports = function(input) {
    return input.content;
};

Any errors that occur in the script are directly translated to errors on the API.

Content scripts have a runtime limit of 10 seconds. If a script runs for too long it will be aborted and an error will be returned.

1.8. Named Queries

Named queries (aka query configurations) are string templates written for a specific repository’s query language and identified by a unique name in the repository configuration.

The query templates have to be written for a target system that supports querying. They use the ${…​} syntax for their variables, and the variable names have to be prefixed by q_.

Query example:

Suppose the target repository accepts this type of queries:

https://www.xill.io/content/search?type=pdf

then the corresponding named query configuration will be:

{
  "name": "type_query"
  "template": "type=${q_type}"
}

and calling /queries endpoint will be done with the following parameters:

/type_query?q_type=pdf
Malformed, missing or superfluous template variables will cause errors when calling the endpoints.

2. API Endpoints

Here is an exhaustive list of all the endpoints provided by the API.

2.1. /entities

2.1.1. List Available Repositories

List all available repositories as entities. When requesting the root entity (/entities) with the scope path_children_entity, all available repositories will be returned. The configurationId of each configuration can be found in the name.systemName decorator field, and this can be used in other calls to the API where a configurationId is required.

This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities?scope=path_children_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities?scope=path_children_entity' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "path_children_entity" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/bb3a7fbc82b94d939df5cd1cb6db16ba",
    "xdip" : "xdip://bb3a7fbc82b94d939df5cd1cb6db16ba/",
    "kind" : "FileSystem",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "name" : {
        "systemName" : "bb3a7fbc82b94d939df5cd1cb6db16ba",
        "displayName" : "My filesystem configuration"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "name" : {
        "systemName" : "bb3a7fbc82b94d939df5cd1cb6db16ba",
        "displayName" : "My filesystem configuration"
      }
    }
  } ]
}
Possible Errors

Unauthorized

Access Denied

Connector Operation Failed

2.1.2. Get an Entity or its Relations

Get a set of decorators containing metadata about the requested entity and, based on the given scopes, about related entities, such as its contained documents, its versions or translations.

The default scope is entity.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/cc2d6a58c390407a8b71ea8b0919c32b/Documents?scope=entity&include=name,file' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/cc2d6a58c390407a8b71ea8b0919c32b/Documents",
    "xdip" : "xdip://cc2d6a58c390407a8b71ea8b0919c32b/Documents",
    "kind" : "Folder",
    "original" : {
      "name" : {
        "systemName" : "Documents",
        "displayName" : "Documents"
      }
    },
    "modified" : {
      "name" : {
        "systemName" : "Documents",
        "displayName" : "Documents"
      }
    }
  }
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.3. Get the Metadata of an Entity

Get the user-defined metadata from the target system. These are metadata fields which are created by a user or application to enhance content.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=metadata
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/e53251631d8e458196e88b959103ce30/Documents/Resume.docx?scope=metadata' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "metadata" : {
    "contentType" : {
      "displayName" : "FileData",
      "systemName" : "FileData",
      "properties" : {
        "lastAccessTime" : {
          "value" : "2024-10-29T16:27:26.36354Z"
        },
        "lastModifiedTime" : {
          "value" : "2024-10-29T16:27:26.36354Z"
        },
        "size" : {
          "value" : "360"
        },
        "creationTime" : {
          "value" : "2024-10-29T16:27:26.36354Z"
        },
        "isSymbolicLink" : {
          "value" : "false"
        },
        "isRegularFile" : {
          "value" : "true"
        },
        "fileKey" : {
          "value" : "(dev=46,ino=25977806)"
        },
        "isOther" : {
          "value" : "false"
        },
        "isDirectory" : {
          "value" : "false"
        }
      }
    },
    "templates" : { }
  }
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.4. List References to the Contained Documents of an Entity

Get a reference to the documents contained in the requested entity, i.e. the `id`s or URLs of the documents contained in the document referenced by the URL of this request.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all the data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=path_children_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/d7e30f62cf664c6782311f9b1cb7d91a/path/to/folder?scope=path_children_reference' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "path_children_reference" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/d7e30f62cf664c6782311f9b1cb7d91a/path/to/folder/avatar.jpg"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/d7e30f62cf664c6782311f9b1cb7d91a/path/to/folder/README.md"
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.5. List the Documents Contained in an Entity

Get all the entity’s contained documents as full entity objects. Note that this is an expensive operation. Only request this scope if you need the details of the children. If you are just looking for their id instead, use the path_children_reference request scope.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=path_children_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory?scope=path_children_entity' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "path_children_entity" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory/config.json",
    "xdip" : "xdip://afe79618452643bc9b1613e852325e13/subdirectory/config.json",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "file" : {
        "rawExtension" : "json",
        "extension" : "json",
        "size" : 15
      },
      "hash" : {
        "md5" : "e73e607ac7da9724987cbba6e47d954d",
        "sha1" : "e2f1bf02ed9117442a00627e121a4f3393768e3f",
        "sha256" : "bf955f306034e20bf403b8df4dce1e90adc7e9ee104312942b2f9fd988df025b"
      },
      "mimeType" : {
        "type" : "application/json"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "name" : {
        "systemName" : "config.json",
        "displayName" : "config.json"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory"
      },
      "fileSystem" : {
        "path" : "/subdirectory/config.json"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "file" : {
        "rawExtension" : "json",
        "extension" : "json",
        "size" : 15
      },
      "hash" : {
        "md5" : "e73e607ac7da9724987cbba6e47d954d",
        "sha1" : "e2f1bf02ed9117442a00627e121a4f3393768e3f",
        "sha256" : "bf955f306034e20bf403b8df4dce1e90adc7e9ee104312942b2f9fd988df025b"
      },
      "mimeType" : {
        "type" : "application/json"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "name" : {
        "systemName" : "config.json",
        "displayName" : "config.json"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory"
      },
      "fileSystem" : {
        "path" : "/subdirectory/config.json"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory/notes.docx",
    "xdip" : "xdip://afe79618452643bc9b1613e852325e13/subdirectory/notes.docx",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx",
        "size" : 360
      },
      "hash" : {
        "md5" : "12479eed8c4db56da287a0e790fee4c8",
        "sha1" : "c1840749b4a81d99e5164e51cced3ed7bc6c1c97",
        "sha256" : "c156c43acda9fc45d22c2508becfcd230a2f8b0376a1eaf6ce2656a68913ddd6"
      },
      "mimeType" : {
        "type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "name" : {
        "systemName" : "notes.docx",
        "displayName" : "notes.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory"
      },
      "fileSystem" : {
        "path" : "/subdirectory/notes.docx"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx",
        "size" : 360
      },
      "hash" : {
        "md5" : "12479eed8c4db56da287a0e790fee4c8",
        "sha1" : "c1840749b4a81d99e5164e51cced3ed7bc6c1c97",
        "sha256" : "c156c43acda9fc45d22c2508becfcd230a2f8b0376a1eaf6ce2656a68913ddd6"
      },
      "mimeType" : {
        "type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:25.883Z"
      },
      "name" : {
        "systemName" : "notes.docx",
        "displayName" : "notes.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/afe79618452643bc9b1613e852325e13/subdirectory"
      },
      "fileSystem" : {
        "path" : "/subdirectory/notes.docx"
      }
    }
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.6. List References to the Translations of an Entity

Get a list of references to the known translations of the requested entity.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=translation_all_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/78d6954f9d794e7bb15a3f7187112fa9/biography.pdf?scope=translation_all_reference' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "translationList" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/78d6954f9d794e7bb15a3f7187112fa9/biography.pdf?language=cs-CZ",
    "tag" : "cs-CZ"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/78d6954f9d794e7bb15a3f7187112fa9/biography.pdf?language=es-ES",
    "tag" : "es-ES"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/78d6954f9d794e7bb15a3f7187112fa9/biography.pdf?language=es-MX",
    "tag" : "es-MX"
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.7. Get the Translations of an Entity

Get all of the translations of the entity as full entity objects. Note that this is an expensive operation. Only request this scope if you need the translation’s details. If you are just looking for their id instead, use the translation_all_reference request scope.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=translation_all_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?scope=translation_all_entity' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "translations" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=cs-CZ",
    "xdip" : "xdip://43f1cadad688469284a0b1d25729cb43/appointments.docx?language=cs-CZ",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=cs-CZ"
      },
      "language" : {
        "tag" : "cs-CZ",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=cs-CZ"
      },
      "language" : {
        "tag" : "cs-CZ",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=es-ES",
    "xdip" : "xdip://43f1cadad688469284a0b1d25729cb43/appointments.docx?language=es-ES",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=es-ES"
      },
      "language" : {
        "tag" : "es-ES",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=es-ES"
      },
      "language" : {
        "tag" : "es-ES",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=es-MX",
    "xdip" : "xdip://43f1cadad688469284a0b1d25729cb43/appointments.docx?language=es-MX",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=es-MX"
      },
      "language" : {
        "tag" : "es-MX",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43?language=es-MX"
      },
      "language" : {
        "tag" : "es-MX",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/43f1cadad688469284a0b1d25729cb43/appointments.docx?language=fr-FR"
      }
    }
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.8. List References to All Versions of an Entity

Get a list of references to the known versions of the requested entity.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=version_all_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/27cd402b17fb436da442ad84ca03ff76/biography.pdf?scope=version_all_reference' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "versionList" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/27cd402b17fb436da442ad84ca03ff76/biography.pdf?version=1.0",
    "tag" : "1.0"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/27cd402b17fb436da442ad84ca03ff76/biography.pdf?version=1.1",
    "tag" : "1.1"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/27cd402b17fb436da442ad84ca03ff76/biography.pdf?version=2.0",
    "tag" : "2.0"
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.9. Get the Versions of an Entity

Get all of the entity’s versions as full entity objects. Note that this is an expensive operation. Only request this scope if you need the version’s details. If you are just looking for their id instead, use the version_all_reference request scope.

You can set the 'scope' parameter on all requests that return an entity. This is merely an example.
It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER. 
GET /v2/entities/{configurationId}/{path}?scope=version_all_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?scope=version_all_entity' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "versions" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=1.0",
    "xdip" : "xdip://bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=1.0",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=1.0"
      },
      "version" : {
        "tag" : "1.0"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=1.0"
      },
      "version" : {
        "tag" : "1.0"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=1.1",
    "xdip" : "xdip://bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=1.1",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=1.1"
      },
      "version" : {
        "tag" : "1.1"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=1.1"
      },
      "version" : {
        "tag" : "1.1"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=2.0",
    "xdip" : "xdip://bb1679e67e2f4787bd10bd2ca34c28d8/appointments.docx?version=2.0",
    "kind" : "File",
    "original" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=2.0"
      },
      "version" : {
        "tag" : "2.0"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "file" : {
        "rawExtension" : "docx",
        "extension" : "docx"
      },
      "name" : {
        "systemName" : "/appointments.docx",
        "displayName" : "/appointments.docx"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/bb1679e67e2f4787bd10bd2ca34c28d8?version=2.0"
      },
      "version" : {
        "tag" : "2.0"
      }
    }
  } ]
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.10. Create a New Entity

Create an entity with the given metadata. Of this entity, only the original section will be used, the modified section will be ignored. To create an entity with contents, use the Create a New Entity With Contents endpoint.

The parent path of the new entity is given by the request URL. If this happens to be a configuration path, the parent is assumed to be the "root" in the context of the given configuration and target repository. This is because a Xillio API connector configuration always points to a concrete starting folder that might not be the logical root of the file hierarchy in the target repository. For example, the "object store" for Filenet and the "site" for Sharepoint point to a specific part of the repository which constitute the "root" for all connector operations.

Translations

This endpoint can be used to create a translation of an already existing document. This is done by setting the Language decorator to a language that does not already exist for the target entity.

Versions

This endpoint can be used to create a new version of an already existing document. This can be done by updating the metadata or content of an entity and setting the Version.

Some systems will implicitly create a new version even if the version decorator is not set, please check the specific connector documentation for details.
Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN. 
POST /v2/entities/{configurationId}/{path}
------
HTTP/1.1 201 Created
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/e3dc7372313f43ceaf4ae9608e61fb55/' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "kind" : "File",
  "original" : {
    "name" : {
      "systemName" : "a-new-file.txt",
      "displayName" : "a-new-file.txt"
    }
  },
  "modified" : {
    "name" : {
      "systemName" : "a-new-file.txt",
      "displayName" : "a-new-file.txt"
    }
  }
}'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 201 Created

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/e3dc7372313f43ceaf4ae9608e61fb55/a-new-file.txt",
    "xdip" : "xdip://e3dc7372313f43ceaf4ae9608e61fb55/a-new-file.txt",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:24.659Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 0
      },
      "hash" : {
        "md5" : "d41d8cd98f00b204e9800998ecf8427e",
        "sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:24.659Z"
      },
      "name" : {
        "systemName" : "a-new-file.txt",
        "displayName" : "a-new-file.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/e3dc7372313f43ceaf4ae9608e61fb55"
      },
      "fileSystem" : {
        "path" : "/a-new-file.txt"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:24.659Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 0
      },
      "hash" : {
        "md5" : "d41d8cd98f00b204e9800998ecf8427e",
        "sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:24.659Z"
      },
      "name" : {
        "systemName" : "a-new-file.txt",
        "displayName" : "a-new-file.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/e3dc7372313f43ceaf4ae9608e61fb55"
      },
      "fileSystem" : {
        "path" : "/a-new-file.txt"
      }
    }
  }
}
Possible Errors

No Such Configuration

Invalid XDIP

Entity Already Exists

Missing Decorator

Operation Not Allowed

Authorization Failed

Host Not Reached

Unsupported Content Type

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.11. Create a New Entity With Contents

Create an entity with the given metadata and contents. This endpoint requires the request to be sent as multipart/form-data.

The request must at least have an entity part which contains the entity object, this part must be of type application/json. Of this entity, only the original section will be used, the modified section will be ignored.

A contents part can optionally be supplied, this can either be a stream or a file containing the contents of the entity to be created. To create an entity without contents, use the Create a New Entity endpoint.

The parent path of the new entity is given by the request URL. If this happens to be a configuration path, the parent is assumed to be the "root" in the context of the given configuration and target repository. This is because a Xillio API connector configuration always points to a concrete starting folder that might not be the logical root of the file hierarchy in the target repository. For example, the "object store" for Filenet and the "site" for Sharepoint point to a specific part of the repository which constitute the "root" for all connector operations.

This endpoint can also be used to create a translation or version of an existing document. Please see Create a New Entity for further info on creating translations or versions.
We support creating files up to 1 gigabyte using this endpoint. To upload larger files see the Update an Entity's Contents endpoint.
Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN. 
POST /v2/entities/{configurationId}/{path}
------
HTTP/1.1 201 Created
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Request Parts
Part Description

entity

The JSON formatted entity.

contents

The contents of the entity.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/b0060b80f92a4312ae362185c8323a4d/' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: multipart/form-data' \
    -F 'entity={
  "kind" : "File",
  "original" : {
    "name" : {
      "systemName" : "a-new-file-with-contents.txt",
      "displayName" : "a-new-file-with-contents.txt"
    }
  },
  "modified" : {
    "name" : {
      "systemName" : "a-new-file-with-contents.txt",
      "displayName" : "a-new-file-with-contents.txt"
    }
  }
};type=application/json;charset=UTF-8' \
    -F 'contents=This file was newly created!'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 201 Created

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/b0060b80f92a4312ae362185c8323a4d/a-new-file-with-contents.txt",
    "xdip" : "xdip://b0060b80f92a4312ae362185c8323a4d/a-new-file-with-contents.txt",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:24.787Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 28
      },
      "hash" : {
        "md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
        "sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
        "sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:24.787Z"
      },
      "name" : {
        "systemName" : "a-new-file-with-contents.txt",
        "displayName" : "a-new-file-with-contents.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/b0060b80f92a4312ae362185c8323a4d"
      },
      "fileSystem" : {
        "path" : "/a-new-file-with-contents.txt"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2024-10-29T16:27:24.787Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 28
      },
      "hash" : {
        "md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
        "sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
        "sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2024-10-29T16:27:24.787Z"
      },
      "name" : {
        "systemName" : "a-new-file-with-contents.txt",
        "displayName" : "a-new-file-with-contents.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/b0060b80f92a4312ae362185c8323a4d"
      },
      "fileSystem" : {
        "path" : "/a-new-file-with-contents.txt"
      }
    }
  }
}
Possible Errors

No Such Configuration

Invalid XDIP

Entity Already Exists

Missing Decorator

Operation Not Allowed

Authorization Failed

Host Not Reached

Unsupported Content Type

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.12. Update an Existing Entity

Update an entity based on the differences between the original and modified sections.

When trying to change unmodifiable information, the change is ignored and not reflected in the target system or response body. The returned entity can be used to validate which updates were executed and which were not.

This behaviour is by design and ensures the greatest consistency between different underlying connectors.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN. 
PUT /v2/entities/{configurationId}/{path}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are entity and metadata, as well as the relation scopes for path, translation and version. (default: entity).
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/9c6ae4e23ba241929579551951102621/existing-file.xml?include=name' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "kind" : "File",
  "original" : {
    "name" : {
      "systemName" : "existing-file.xml",
      "displayName" : "existing-file.xml"
    }
  },
  "modified" : {
    "name" : {
      "systemName" : "updated-entity.xml",
      "displayName" : "updated-entity.xml"
    }
  }
}'
Response Fields

The response fields depend on the requested scopes.

Example Response
HTTP/1.1 200 OK

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/9c6ae4e23ba241929579551951102621/updated-entity.xml",
    "xdip" : "xdip://9c6ae4e23ba241929579551951102621/updated-entity.xml",
    "kind" : "File",
    "original" : {
      "name" : {
        "systemName" : "updated-entity.xml",
        "displayName" : "updated-entity.xml"
      }
    },
    "modified" : {
      "name" : {
        "systemName" : "updated-entity.xml",
        "displayName" : "updated-entity.xml"
      }
    }
  }
}
Possible Errors

No Such Entity

No Such Configuration

Invalid XDIP

Entity Already Exists

Operation Not Allowed

Authorization Failed

Host Not Reached

Unsupported Content Type

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.1.13. Delete an Entity

Delete an entity, its contents, and, if any, its path children. Special rules apply when deleting a version from the middle of the version history: different repositories have different rules, but in general it is possible to delete the last version on all repositories that support versioning.

If the entity does not exist, nothing happens.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN. 
DELETE /v2/entities/{configurationId}/{path}
------
HTTP/1.1 204 No Content
/v2/entities/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/bba6136117a04776868553012054256f/old-file.txt' -i -X DELETE \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

No Such Configuration

Invalid XDIP

Operation Not Allowed

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.2.1. Search by Content

Search through the target repository by textual content.

This endpoint uses the native search engine of the target repository. As such, the results of the search are dependent on the target repository type.

For instance, on some repository the search will be done on content only, while on another the results will include matches based on metadata.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope search for a user with role ENTITY_USER. 
POST /v2/search/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/search/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Query Parameters
Parameter Description

scope

A comma-separated list of scopes. The available scopes are: entities, entityList. (default: entityList)
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/search/e6c1340019524953b7493fccf94c90ae' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{"contents": "Sales Department"}'
Response Fields
Path Type Description

entities

Entity[]

This field contains entities' metadata if the 'scope' contains 'entities'.

entityList

Array

This field contains an array of references to entities if the 'scope' parameter contains 'entityList'.
Example Response
HTTP/1.1 200 OK

{
  "entityList" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/e6c1340019524953b7493fccf94c90ae/message.xml"
  } ]
}
Possible Errors

Unauthorized

Access Denied

No Such Configuration

No Such Query Configuration

2.3. /queries

2.3.1. List Your Named Queries for a Repository

List all your named queries for a specific configuration. To create a named query see Create a named query configuration.

This endpoint requires an access_token for scope entities:query for a user with role ENTITY_USER. 
GET /v2/queries/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/queries/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/queries/4e6d17127bdd49e49a215612f0bc37e2' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all your named queries for this configuration.

[].name

String

The name of the query configuration.

[].template

String

The template of the query, written for the target system.
Example Response
HTTP/1.1 200 OK

[ {
  "name" : "my_query",
  "template" : "parameter=${q_variable}"
} ]
Possible Errors

Unauthorized

Access Denied

No Such Configuration

2.3.2. Query Entities

Execute a named query using the supplied template variable values.

The query must be present in the referenced configuration and all template variables must be supplied as request parameters. Specifying variables that are not used in the template also leads to an error.

URL parameter names must match the corresponding template variables names exactly and must conform to the standard specified in Named Queries.

The template variable values input to this endpoint are escaped using a method appropriate to the target system.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope query:execute for a user with role ENTITY_USER. 
GET /v2/queries/{configurationId}/{queryName}?q_variable=33&scope=entities
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/queries/{configurationId}/{queryName}
Parameter Description

configurationId

The id of a configured repository.

queryName

The name of this query configuration.
Query Parameters
Parameter Description

include

A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included.

exclude

A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored.

scope

A comma-separated list of scopes. The available scopes are: entities, entityList. (default: entityList)

q_variable

Query template variable value, for each variable defined in the query template
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/queries/2a187efb9bfc44669f8efb47af1c0b54/my_query?scope=entities&q_variable=value' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entities

Entity[]

This field contains entities' metadata if the 'scope' contains 'entities'.

entityList

Array

This field contains an array of references to entities if the 'scope' parameter contains 'entityList'.
Example Response
HTTP/1.1 200 OK

{
  "entities" : [ ]
}
Possible Errors

No Such Entity

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Invalid Query Variable

No Such Query Configuration

Invalid Query

Connector Operation Failed

2.4. /contents

2.4.1. Download an Entity's Contents

Get the contents of an entity.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope contents for a user with role ENTITY_USER. 
GET /v2/contents/{configurationId}/{path}
------
HTTP/1.1 200 OK
/v2/contents/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Headers
Name Description

Accept

Which content script to apply, or application/octet-stream for none.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/contents/c5379df07d024b8fbb8963443b61c947/note.xml' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Accept: application/octet-stream'
Example Response
HTTP/1.1 200 OK

<items>
  <item>
    <title>Hello World</title>
    <text>This is a simple note</text>
  </item>
</items>
Possible Errors

No Such Entity

No Such Configuration

No Binary Content

Invalid XDIP

Operation Not Allowed

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.4.2. Update an Entity's Contents

Overwrite the contents of the entity with the contents of the request body. When calling this endpoint the version of the entity is incremented.

Currently, we support updating files with up to 10 gigabyte using this endpoint.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope contents for a user with role ENTITY_ADMIN. 
PUT /v2/contents/{configurationId}/{path}
------
HTTP/1.1 204 No Content
/v2/contents/{configurationId}/{path}
Parameter Description

configurationId

The id of a configured repository.

path

The XDIP path to the entity.
Headers
Name Description

Content-Type

Which content script to apply, or application/octet-stream for none.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/contents/2d22a1cab94f4e68af3fd36500f48b80/manifest.txt' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/octet-stream' \
    -d 'This will be the new content!'
Example Response
HTTP/1.1 204 No Content
Possible Errors

No Such Entity

No Such Configuration

No Binary Content

Invalid XDIP

Operation Not Allowed

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.5. /types

2.5.1. List All Content Types

List all known content types of the target repository.

This endpoint requires an access_token for scope types for a user with role ENTITY_USER. 
GET /v2/types/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/types/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/types/0035561c61a24140b2bd8e78075feea5' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all content types of the target repository.

[].id

String

The URL that points to this content type.

[].systemName

String

The technical name of the content type.

[].displayName

String

The human readable name of the content type. If none is given, systemName is used instead.

[].description

String

A small excerpt or description of the content type.
Example Response
HTTP/1.1 200 OK

[ {
  "systemName" : "FileData",
  "displayName" : "File or Folder",
  "description" : "A file or folder stored on the file system",
  "id" : "https://demo-tenant.xill.io/v2/types/0035561c61a24140b2bd8e78075feea5/FileData"
} ]
Possible Errors

No Such Configuration

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.6. /templates

2.6.1. List All Templates

List all known metadata templates, also known as mixins, of the target repository.

This endpoint requires an access_token for scope templates for a user with role ENTITY_USER. 
GET /v2/templates/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/templates/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/templates/a328d9664a684598bf71319c23a0f2bf' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all metadata templates, also known as mixins, of the target repository.

[].id

String

The URL that points to this template.

[].systemName

String

The technical name of the template.

[].displayName

String

The human readable name of the template. If none is given, systemName is used instead.

[].description

String

A small excerpt or description of the template.
Example Response
HTTP/1.1 200 OK

[ {
  "systemName" : "contact",
  "displayName" : "Contact",
  "description" : "A person who can offer help in achieving goals",
  "id" : "https://demo-tenant.xill.io/v2/templates/a328d9664a684598bf71319c23a0f2bf/contact"
}, {
  "systemName" : "employer",
  "displayName" : "Employer",
  "description" : "A person conducting a business or undertaking",
  "id" : "https://demo-tenant.xill.io/v2/templates/a328d9664a684598bf71319c23a0f2bf/employer"
}, {
  "systemName" : "employee",
  "displayName" : "Employee",
  "description" : "A contributor of labor and expertise to an endeavor of an employer",
  "id" : "https://demo-tenant.xill.io/v2/templates/a328d9664a684598bf71319c23a0f2bf/employee"
} ]
Possible Errors

No Such Configuration

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.7. /tenant

2.7.1. Get your tenant

Retrieve information about your tenant.

This endpoint requires an access_token for scope tenant for a user with role CONFIG_ADMIN. 
GET /v2/tenant
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/tenant/' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

id

String

The id of this tenant

name

String

Technical name e.g. for usage in URLs

displayName

String

Human-readable name for displaying e.g. in a GUI

description

String

Free form description of this tenant

availableConnectors

Array

List of connectors that are enabled for this tenant
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91a64dd007f",
  "name" : "demo-tenant",
  "displayName" : "demo-tenant",
  "description" : "Free form description of the demo-tenant tenant.",
  "availableConnectors" : [ "FileSystem" ]
}
Possible Errors

Unauthorized

Access Denied

2.8. /configurations

2.8.1. List All Your Configurations

List all your configurations.

This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
GET /v2/configurations
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all configurations that are accessible to you.
Example Response
HTTP/1.1 200 OK

[ {
  "id" : "f9e5410873bb404995d1e65ab16b20fc",
  "name" : "My filesystem configuration",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT202859415874992619/"
  }
} ]
Possible Errors

Unauthorized

Access Denied

2.8.2. Get a Configuration

Get one of your configurations.

This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
GET /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/299bb0ec99f040feab50ff2acdd4068f' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

id

String

The id of this configuration.

name

String

The display name of this configuration.

configurationType

String

The underlying type of the configuration.

config

Object

The properties which are passed to the connector.

passthroughAuthorization

Boolean

Set this to true to enable passthrough authorization (default: false).
Example Response
HTTP/1.1 200 OK

{
  "id" : "299bb0ec99f040feab50ff2acdd4068f",
  "name" : "My filesystem configuration",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT8425269191185369657/"
  }
}
Possible Errors

No Such Configuration

Unauthorized

Access Denied

2.8.3. Create a New Configuration

Create a configuration with the given name, configurationType and config fields and an optional id field. This returns the created configuration, of which the id can be used in other requests.

If set, the chosen id must be unique, can only contain alphanumerics and dashes, and cannot start nor end with a dash. Additionally, its length must be between 2 to 255 characters. If the id was not set, it will be automatically generated.

Some values in config are required, in which case a value must be assigned. Some can also have a default, which can be overwritten by providing a value for the field. The connectors endpoint provides extensive information about each connector configuration field.

Passthrough-Authorization

By default you can create configurations which work using a fixed username and password or token. However, if you require access to a specific user’s content only a few times, it can be quite excessive to create configurations for every individual user.

By specifying the Passthrough-Authorization header, you can override the credentials from a configuration for the scope of a single request. There are two supported types of passthrough authorization:

Basic authorization allows you to override the username and password fields of a configuration. To use Basic authorization you specify the following header: Passthrough-Authorization: Basic {AUTHORIZATION_STRING}. The AUTHORIZATION_STRING is created by base64 encoding the string {USERNAME}:{PASSWORD}. For example, if your username is mrclarke and your password is deborah94, you can create your AUTHORIZATION_STRING by base64 encoding the string mrclarke:deborah94 to bXJjbGFya2U6ZGVib3JhaDk0. This means the header will be: Passthrough-Authorization: Basic bXJjbGFya2U6ZGVib3JhaDk0.

Bearer authorization allows you to override the token field of a configuration. To use Bearer authorization you specify the following header: Passthrough-Authorization: Bearer {TOKEN} where {TOKEN} is substituted by the desired token. For example, if your token is 6gHrnAjJPvQAAAAAAAAMfg43gc, your header will be: Passthrough-Authorization: Bearer 6gHrnAjJPvQAAAAAAAAMfg43gc.

This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
POST /v2/configurations
------
HTTP/1.1 201 Created
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "optional-id",
  "name" : "A Temporary Folder",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT10251666518990608010/"
  }
}'
Response Fields
Path Type Description

id

String

The id of this configuration.

name

String

The display name of this configuration.

configurationType

String

The underlying type of the configuration.

config

Object

The properties which are passed to the connector.

passthroughAuthorization

Boolean

Set this to true to enable passthrough authorization (default: false).
Example Response
HTTP/1.1 201 Created

{
  "id" : "optional-id",
  "name" : "A Temporary Folder",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT10251666518990608010/"
  }
}
Possible Errors

Invalid Configuration

Deprecated

Unauthorized Configuration Type

Unauthorized

Access Denied

Configuration Already Exists

2.8.4. Replace a Configuration

Replace one of your configurations, overwriting all fields with the given values. Missing fields are interpreted as having the value null.

See the connectors endpoint for more information about connector configuration fields.

The id cannot be changed using this method. The only way to achieve a similar result is to create a new configuration and delete the old one.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
PUT /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/cd388a30ff774975b104ea84ee06d831' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : null,
  "name" : "\"New Name\"",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT11669230971777510233/"
  }
}'
Response Fields
Path Type Description

id

String

The id of this configuration.

name

String

The display name of this configuration.

configurationType

String

The underlying type of the configuration.

config

Object

The properties which are passed to the connector.

passthroughAuthorization

Boolean

Set this to true to enable passthrough authorization (default: false).
Example Response
HTTP/1.1 200 OK

{
  "id" : "cd388a30ff774975b104ea84ee06d831",
  "name" : "\"New Name\"",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT11669230971777510233/"
  }
}
Possible Errors

No Such Configuration

Unauthorized Configuration Type

Invalid Configuration

Deprecated

Unauthorized

Access Denied

2.8.5. Update a Configuration

Update (or patch) one of your configurations, overwriting only the included fields with the given values.

See the connectors endpoint for more information about connector configuration fields.

The config part of both configurations will be merged, with the new values taking precedence in case of field collisions
The id cannot be changed using this method. The only way to achieve a similar result is to create a new configuration and delete the old one.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
PATCH /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/5b897c2af7df4e92a2dfb00002b2ee8b' -i -X PATCH \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{"config":{"rootPath":"file:///tmp/ApiDocumentationIT6713763177405635522/"}}'
Response Fields
Path Type Description

id

String

The id of this configuration.

name

String

The display name of this configuration.

configurationType

String

The underlying type of the configuration.

config

Object

The properties which are passed to the connector.

passthroughAuthorization

Boolean

Set this to true to enable passthrough authorization (default: false).
Example Response
HTTP/1.1 200 OK

{
  "id" : "5b897c2af7df4e92a2dfb00002b2ee8b",
  "name" : "My filesystem configuration",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT6713763177405635522/"
  }
}
Possible Errors

No Such Configuration

Unauthorized Configuration Type

Invalid Configuration

Deprecated

Unauthorized

Access Denied

2.8.6. Delete a Configuration

Delete one of your configurations.

This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN. 
DELETE /v2/configurations/{configurationId}
------
HTTP/1.1 204 No Content
/v2/configurations/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/1ad10429ad374e9d9904eae8d3daa0fd' -i -X DELETE \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

2.9. /configurations/contentScripts

2.9.1. List All Your Content Scripts

List all your content scripts.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
GET /v2/configurations/{configurationId}/contentScripts
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/contentScripts
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/088a76ab467a4cbeb088fdb818136a4b/contentScripts' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 200 OK

[ {
  "id" : "2c91808292d91a180192d91a7f9b00bf",
  "type" : "read",
  "mimeType" : "application/FileData",
  "description" : "This is the description of an example content script",
  "passEntity" : false
} ]
Possible Errors

Unauthorized

Access Denied

2.9.2. Get a Content Script

Get a content script.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
GET /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/contentScripts/{contentScriptId}
Parameter Description

configurationId

The id of a configured repository.

contentScriptId

The id of a configured content script.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/d5395d016f1340ee91bbfaae857d94ce/contentScripts/2c91808292d91a180192d91a820600cb' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91a820600cb",
  "type" : "read",
  "mimeType" : "application/FileData",
  "description" : "This is the description of an example content script",
  "passEntity" : false
}
Possible Errors

No Such Content Script

Unauthorized

Access Denied

2.9.3. Create a New Content Script

Create a content script with the given code, type, mimeType, description and passEntity fields. The code, description and passEntity field are optional. If no code is supplied, an identity script will be used. This returns the created content script, with the id which can be used in other requests. The script code is not returned, this can be requested via the code endpoint.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
POST /v2/configurations/{configurationId}/contentScripts
------
HTTP/1.1 201 Created
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/4c9ee43cd552409682970fab999e2fce/contentScripts' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "2c91808292d91a180192d91a7b2200ad",
  "type" : "read",
  "mimeType" : "application/FileData",
  "description" : "This is the description of an example content script",
  "passEntity" : false
}'
Response Fields
Path Type Description

id

String

The id of a content script.

type

String

How the content script is used, READ scripts are for retrieving and WRITE scripts are for updating content.

mimeType

String

The mime type associated with this content script.

description

String

The description of the content script.

passEntity

Boolean

Whether to pass the entity object along with the content to the content script.
Example Response
HTTP/1.1 201 Created

{
  "id" : "2c91808292d91a180192d91a7b2200ad",
  "type" : "read",
  "mimeType" : "application/filedata",
  "description" : "This is the description of an example content script",
  "passEntity" : false
}
Possible Errors

Unauthorized

Access Denied

Invalid Configuration

2.9.4. Update a Content Script

Update one of your content scripts, overwriting all fields with the given values. If a field is not given, the old value will be used.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
PUT /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/contentScripts/{contentScriptId}
Parameter Description

configurationId

The id of a configured repository.

contentScriptId

The id of a configured content script.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/82bd39888b8049718ac73bad6779b707/contentScripts/2c91808292d91a180192d91a878f00eb' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "id" : "2c91808292d91a180192d91a878f00eb",
  "type" : "read",
  "mimeType" : "application/FileData",
  "description" : "This description has been updated",
  "passEntity" : false
}'
Response Fields
Path Type Description

id

String

The id of a content script.

type

String

How the content script is used, READ scripts are for retrieving and WRITE scripts are for updating content.

mimeType

String

The mime type associated with this content script.

description

String

The description of the content script.

passEntity

Boolean

Whether to pass the entity object along with the content to the content script.
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91a878f00eb",
  "type" : "read",
  "mimeType" : "application/filedata",
  "description" : "This description has been updated",
  "passEntity" : false
}
Possible Errors

No Such Content Script

Unauthorized

Access Denied

2.9.5. Delete a Content Script

Delete one of your content scripts.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
DELETE /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 204 No Content
/v2/configurations/{configurationId}/contentScripts/{contentScriptId}
Parameter Description

configurationId

The id of a configured repository.

contentScriptId

The id of a configured content script.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/fcf09eae8402451f90c112180f9a10ad/contentScripts/2c91808292d91a180192d91a7db500b5' -i -X DELETE \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

2.9.6. Get the Code of a Content Script

Get the code of a content script.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
GET /v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
------
HTTP/1.1 200 OK
Content-Type: application/javascript
/v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
Parameter Description

configurationId

The id of a configured repository.

contentScriptId

The id of a configured content script.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/7dedf319476746cda11338bcf457f412/contentScripts/2c91808292d91a180192d91a826600cd/code' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 200 OK

//This is an example script
Possible Errors

No Such Content Script

Unauthorized

Access Denied

2.9.7. Update the Code of a Content Script

Update the code of a content script.

This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN. 
PUT /v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
------
HTTP/1.1 204 No Content
Content-Type: application/javascript
/v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
Parameter Description

configurationId

The id of a configured repository.

contentScriptId

The id of a configured content script.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/03dd3f46f0ef483386ea0140f216caa8/contentScripts/2c91808292d91a180192d91a87ef00ed/code' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/javascript' \
    -d 'module.exports = function(input) {
	return input.content;
};'
Example Response
HTTP/1.1 204 No Content
Possible Errors

No Such Content Script

Unauthorized

Access Denied

2.10. /configurations/queries

2.10.1. List All Your Named Queries

List all your named queries for a specific configuration.

This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN. 
GET /v2/configurations/{configurationId}/queries
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/queries
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/cfa98db9426f4f22a477c5173379d8db/queries' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all your named query for this configuration.

[].name

String

The name of the query configuration.

[].template

String

The template of the query, written for the target system.
Example Response
HTTP/1.1 200 OK

[ {
  "name" : "my_query",
  "template" : "parameter=${q_variable}"
} ]
Possible Errors

Unauthorized

Access Denied

No Such Configuration

2.10.2. Get a Named Query

Get a named query.

This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN. 
GET /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/queries/{queryName}
Parameter Description

configurationId

The id of a configured repository.

queryName

The name of this query configuration.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/087c647f88ef404f93b181cf65adde61/queries/my_query' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

name

String

The name of the query configuration.

template

String

The template of the query, written for the target system.
Example Response
HTTP/1.1 200 OK

{
  "name" : "my_query",
  "template" : "parameter=${q_variable}"
}
Possible Errors

Unauthorized

Access Denied

No Such Configuration

No Such Query Configuration

2.10.3. Create a New Named Query

Create a named query with the given mandatory name and query fields. To execute a query see Execute a named query.

The name of the query has to be unique per configuration.

This returns the created named query configuration object, which can be referenced by its name in other requests.

This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN. 
POST /v2/configurations/{configurationId}/queries/
------
HTTP/1.1 201 Created
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/bae3e05959e6448da652480a66134643/queries' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "my_query",
  "template" : "parameter=${q_variable}"
}'
Response Fields
Path Type Description

name

String

The name of the query configuration.

template

String

The template of the query, written for the target system.
Example Response
HTTP/1.1 201 Created

{
  "name" : "my_query",
  "template" : "parameter=${q_variable}"
}
Possible Errors

Unauthorized

Access Denied

No Such Configuration

Query Configuration Already Exists

Invalid Template Variable

Invalid Query

2.10.4. Update a Named Query

Update one of your named query, overwriting the query field.

The name field will be ignored. To update it, you have to delete the faulty query and create a new one.
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN. 
PUT /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/configurations/{configurationId}/queries/{queryName}
Parameter Description

configurationId

The id of a configured repository.

queryName

The name of this query configuration.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/3e4d9f8d87a34cc7ade9830b399d99f2/queries/my_query' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "my_query",
  "template" : "new_query"
}'
Response Fields
Path Type Description

name

String

The name of the query configuration.

template

String

The template of the query, written for the target system.
Example Response
HTTP/1.1 200 OK

{
  "name" : "my_query",
  "template" : "new_query"
}
Possible Errors

Unauthorized

Access Denied

No Such Configuration

No Such Query Configuration

Invalid Template Variable

Invalid Query

2.10.5. Delete a Named Query

Delete one of your named queries.

This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN. 
DELETE /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 204 No Content
Content-Type: application/json
/v2/configurations/{configurationId}/queries/{queryName}
Parameter Description

configurationId

The id of a configured repository.

queryName

The name of this query configuration.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/configurations/412c25c9d8fd458ba5a6e7891874458d/queries/my_query' -i -X DELETE \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

No Such Configuration

No Such Query Configuration

2.11. /users

2.11.1. List All Your Users

List all your users.

This endpoint requires an access_token for scope users for a user with role USER_ADMIN. 
GET /v2/users
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/users' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all users.
Example Response
HTTP/1.1 200 OK

[ {
  "id" : "2c91808292d91a180192d91a3ad9001f",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "USER_ADMIN", "ENTITY_USER", "RPC_USER", "QUERY_ADMIN", "CONFIG_ADMIN", "ENTITY_ADMIN", "SEARCH", "CONTENTSCRIPT_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3b190020",
  "username" : "USER_ADMIN",
  "displayName" : "USER_ADMIN",
  "roles" : [ "USER_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3b570021",
  "username" : "CONFIG_ADMIN",
  "displayName" : "CONFIG_ADMIN",
  "roles" : [ "CONFIG_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3b950022",
  "username" : "ENTITY_ADMIN",
  "displayName" : "ENTITY_ADMIN",
  "roles" : [ "ENTITY_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3bd20023",
  "username" : "ENTITY_USER",
  "displayName" : "ENTITY_USER",
  "roles" : [ "ENTITY_USER" ]
}, {
  "id" : "2c91808292d91a180192d91a3c0f0024",
  "username" : "CONTENTSCRIPT_ADMIN",
  "displayName" : "CONTENTSCRIPT_ADMIN",
  "roles" : [ "CONTENTSCRIPT_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3c4d0025",
  "username" : "QUERY_ADMIN",
  "displayName" : "QUERY_ADMIN",
  "roles" : [ "QUERY_ADMIN" ]
}, {
  "id" : "2c91808292d91a180192d91a3c8a0026",
  "username" : "RPC_USER",
  "displayName" : "RPC_USER",
  "roles" : [ "RPC_USER" ]
}, {
  "id" : "2c91808292d91a180192d91a3cc70027",
  "username" : "SEARCH",
  "displayName" : "SEARCH",
  "roles" : [ "SEARCH" ]
}, {
  "id" : "2c91808292d91a180192d91a4174002a",
  "username" : "new-user",
  "displayName" : "New user",
  "email" : "new-user@example.com",
  "roles" : [ "ENTITY_USER", "ENTITY_ADMIN" ]
} ]
Possible Errors

Unauthorized

Access Denied

2.11.2. Get a User

Get one of your users.

This endpoint requires an access_token for scope users for a user with role USER_ADMIN. 
GET /v2/users/{username}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/users/{username}
Parameter Description

username

The name of the user.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/users/demo-user' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

id

String

The unique id for the user.

username

String

The name of the user.

displayName

String

The display name of the user.

email

String

The e-mail address of the user.

roles

String[]

The authorities of the user.
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91a3ad9001f",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "USER_ADMIN", "ENTITY_USER", "RPC_USER", "QUERY_ADMIN", "CONFIG_ADMIN", "ENTITY_ADMIN", "SEARCH", "CONTENTSCRIPT_ADMIN" ]
}
Possible Errors

No Such User

Unauthorized

Access Denied

2.11.3. Create a New User

Create a user with the given username, password, displayName and email. This returns the created user.

The password has to be at least 10 characters long, and the lowercased password cannot contain the lowercased username.
If the roles field is omitted, the user will be granted all roles.
This endpoint requires an access_token for scope users for a user with role USER_ADMIN. 
POST /v2/users
------
HTTP/1.1 201 Created
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/users' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "password" : "U2VjcmV0cyE=",
  "displayName" : "New user",
  "roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ],
  "email" : "new-user@example.com",
  "username" : "new-user"
}'
Response Fields
Path Type Description

id

String

The unique id for the user.

username

String

The name of the user.

displayName

String

The display name of the user.

email

String

The e-mail address of the user.

roles

String[]

The authorities of the user.
Example Response
HTTP/1.1 201 Created

{
  "id" : "2c91808292d91a180192d91a4174002a",
  "username" : "new-user",
  "displayName" : "New user",
  "email" : "new-user@example.com",
  "roles" : [ "ENTITY_USER", "ENTITY_ADMIN" ]
}
Possible Errors

Invalid User

Unauthorized

Access Denied

Connector Operation Failed

2.11.4. Update a User

Update one of your users, overwriting all fields with the given values. If a field is not given, the old value will be used.

This endpoint requires an access_token for scope users for a user with role USER_ADMIN. 
PUT /v2/users/{username}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/users/{username}
Parameter Description

username

The name of the user.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/users/demo-user' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "password" : "Z2lwaHkuY29tL2VtYmVkLzdwdDloQlhRUjlJMmM=",
  "displayName" : "Demo user",
  "roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ],
  "email" : "demo-user@example.com",
  "username" : "demo-user"
}'
Response Fields
Path Type Description

id

String

The unique id for the user.

username

String

The name of the user.

displayName

String

The display name of the user.

email

String

The e-mail address of the user.

roles

String[]

The authorities of the user.
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91a3ad9001f",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "ENTITY_USER", "ENTITY_ADMIN" ]
}
Possible Errors

No Such User

Invalid User

Unauthorized

Access Denied

Connector Operation Failed

2.11.5. Delete a User

Delete one of your users.

This endpoint requires an access_token for scope users for a user with role USER_ADMIN. 
DELETE /v2/users/{username}
------
HTTP/1.1 204 No Content
/v2/users/{username}
Parameter Description

username

The name of the user.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/users/delete-me' -i -X DELETE \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

2.12. /user

2.12.1. Get Your Current User

Get your user profile.

This endpoint requires an access_token for scope user. 
GET /v2/user
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/user' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

id

String

The unique id for the user.

username

String

The name of the user.

displayName

String

The display name of the user.

email

String

The e-mail address of the user.

roles

String[]

The authorities of the user.
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91adc6101ae",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "USER_ADMIN", "ENTITY_USER", "RPC_USER", "QUERY_ADMIN", "CONFIG_ADMIN", "ENTITY_ADMIN", "SEARCH", "CONTENTSCRIPT_ADMIN" ]
}
Possible Errors

Unauthorized

Access Denied

2.12.2. Update Your Current User

Update your user profile, overwriting all fields with the given values. If a field is not given, the old value will be used. Note that the username and roles fields cannot be updated, that can be done with the /users endpoint.

This endpoint requires an access_token for scope user. 
PUT /v2/user
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/user' -i -X PUT \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "password" : "updated-demo-password",
  "displayName" : "Updated Demo User",
  "email" : "updated-demo-user@example.com"
}'
Response Fields
Path Type Description

id

String

The unique id for the user.

username

String

The name of the user.

displayName

String

The display name of the user.

email

String

The e-mail address of the user.

roles

String[]

The authorities of the user.
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808292d91a180192d91adc6101ae",
  "username" : "demo-user",
  "displayName" : "Updated Demo User",
  "email" : "updated-demo-user@example.com",
  "roles" : [ "USER_ADMIN", "ENTITY_USER", "RPC_USER", "QUERY_ADMIN", "CONFIG_ADMIN", "ENTITY_ADMIN", "SEARCH", "CONTENTSCRIPT_ADMIN" ]
}
Possible Errors

Invalid User

Unauthorized

Access Denied

2.13. /connectors

2.13.1. Retrieve the Connector Information

Get information about all available connectors. The configurationType is the type of configuration that can be created, and the config contains each configurable element for that connector.

Some connector configuration fields have a default value, for which relevant information is available in the default field.
Some connector configuration fields contain sensitive information. For those fields, the secret property is set to true, and their values are obfuscated.
All default values for which mustDefaultWith is not empty must be specified or omitted together. 
GET /v2/connectors
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/connectors' -i -X GET
Response Fields
Path Type Description

[]

Array

An array of information of all configurations in the connectors.
Example Response
HTTP/1.1 200 OK

[ {
  "configurationType" : "Aem",
  "description" : "Adobe Experience Manager brings your content management system (CMS) and digital asset management (DAM) together — in one place.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the AEM host.",
    "longDescription" : "The base URL of the AEM host.",
    "example" : "https://aem.xillio.com:4502",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account with permissions to access CRX.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of an account with permissions to access CRX.",
    "example" : "password",
    "secret" : false
  }, {
    "name" : "workspace",
    "type" : "STRING",
    "required" : false,
    "description" : "The JCR workspace to access.",
    "longDescription" : "The JCR workspace to access.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "crx.default"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "NOT_IMPLEMENTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_IMPLEMENTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "SUPPORTED"
  }
}, {
  "configurationType" : "Bitbucket",
  "description" : "Bitbucket is a web-based version control repository hosting service for source code and development projects.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Bitbucket API.",
    "longDescription" : "The base URL of the Bitbucket v2 cloud service.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://api.bitbucket.org/2.0"
    }
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on Bitbucket (not the email address).",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "owner",
    "type" : "STRING",
    "required" : false,
    "description" : "The owner of the repositories. If this is not provided, the username is used as owner.",
    "longDescription" : "The owner for which to select repositories. When not provided, the connector will use the `username` as owner.\n\nThe repositories shown with this setting are only the ones owned by the owner, not the repositories to which the user has access to.",
    "example" : "repository-owner",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Box",
  "description" : "Box Drive is the incredibly simple way to stream all of your files — even millions of files — right to your desktop, taking up very little hard drive space.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Box API.",
    "longDescription" : "The base URL of the Box API.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://api.box.com/2.0"
    }
  }, {
    "name" : "uploadUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Box API upload endpoint.",
    "longDescription" : "The URL of the Box API upload endpoint.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://upload.box.com/api/2.0"
    }
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The client secret of the Box Application.",
    "longDescription" : "The Box application secret. Required when `refreshToken` is set.",
    "example" : "kHsek3Jpji8tgFTcwcnqosfYnxO4unQA",
    "secret" : true
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The client id of the Box Application.",
    "longDescription" : "The Box application client id. Required when `refreshToken` is set.",
    "example" : "m1rvfFhvTCe2a5n7u4eElmOfvvE6WumL",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "A Box OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "A refresh token.",
    "longDescription" : "An OAuth2 refresh token.",
    "example" : "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "SUPPORTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "ContentStore",
  "description" : "Content Store is the Xillio database concept for storing any type of content.",
  "config" : [ {
    "name" : "connectionType",
    "type" : "STRING",
    "required" : true,
    "description" : "Identifies the type of the MongoDB connection. Use 'mongodb' for standard connection or 'mongodb+srv' for SRV connection.",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nIdentifies the type of the MongoDB connection, 'mongodb' for standard connection or 'mongodb+srv' for SRV connection",
    "example" : "mongodb+srv",
    "secret" : false
  }, {
    "name" : "host",
    "type" : "STRING",
    "required" : true,
    "description" : "The Content Store host. Including the port if necessary.",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nThe Content Store host, including the port if necessary",
    "example" : "localhost:27017",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : false,
    "description" : "Optional. Username to use to authenticate with the Content Store",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nUsername to use when authenticating with the Content Store",
    "example" : "user",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : false,
    "description" : "Optional. Password to use to authenticate with the Content Store",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nPassword to use when authenticating with the Content Store",
    "example" : "goodpassword",
    "secret" : false
  }, {
    "name" : "connectionOptions",
    "type" : "STRING",
    "required" : false,
    "description" : "Optional. Options of the MongoDB connection as pairs <name>=<value>. Separate options by the ampersand character.",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nOptions of the MongoDB connection as pairs <name>=<value> separated by ampersand",
    "example" : "tls=true&connectTimeoutMS=30000",
    "secret" : false
  }, {
    "name" : "dbName",
    "type" : "STRING",
    "required" : true,
    "description" : "Name of the Content Store database",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nName of the Content Store database",
    "example" : "contentstore",
    "secret" : false
  }, {
    "name" : "collectionName",
    "type" : "STRING",
    "required" : false,
    "description" : "Name of the documents collection of the Content Store",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nName of the documents collection of the Content Store",
    "example" : "documents",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "documents"
    }
  }, {
    "name" : "bucketName",
    "type" : "STRING",
    "required" : false,
    "description" : "Name of the GridFS bucket for the Content Store binaries",
    "longDescription" : "//\n//  XILLIO CONFIDENTIAL\n//  __________________\n//\n//  [2017] XILLIO NEDERLAND B.V.\n//  All Rights Reserved.\n//\n//  NOTICE:  All information contained herein is, and remains\n//  the property of Xillio Nederland B.V. and its suppliers,\n//  if any.  The intellectual and technical concepts contained\n//  herein are proprietary to Xillio Nederland B.V. and its suppliers\n//  and are protected by trade secret or copyright law.\n//  Dissemination of this information or reproduction of this material\n//  is strictly forbidden unless prior written permission is obtained\n//  from Xillio Nederland B.V.\n//\n\nName of the GridFS bucket for the Content Store binaries",
    "example" : "binaries",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "binaries"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "NOT_IMPLEMENTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Contentful",
  "description" : "Contentful is the API-first content management platform to create, manage and publish content on any digital channel.",
  "config" : [ {
    "name" : "token",
    "type" : "STRING",
    "required" : true,
    "description" : "The personal access token of your Contentful Management API",
    "longDescription" : "The Content management access token.",
    "example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
    "secret" : true
  }, {
    "name" : "spaceId",
    "type" : "STRING",
    "required" : false,
    "description" : "The space id of your Contentful Management API",
    "longDescription" : "The ID of the Contentful space you want to access. This value is optional. When not provided the connector will expose all the spaces that the tokens allows accessing.",
    "example" : "43bhs4uagphk",
    "secret" : false
  }, {
    "name" : "environmentId",
    "type" : "STRING",
    "required" : false,
    "description" : "The environment id of your Contentful Management API",
    "longDescription" : "The environment id of your Contentful Management API. It is necessary to add spaceId if you add environmentId.",
    "example" : "master",
    "secret" : false
  }, {
    "name" : "sourceLanguageCode",
    "type" : "STRING",
    "required" : true,
    "description" : "To provide source language for download entry data for translation",
    "longDescription" : "Configure the code of the language you consider a source language for the translations. This defines what values the connector exports as content that needs to be translated.",
    "example" : "en-US",
    "secret" : false
  }, {
    "name" : "getOnlyTranslationFields",
    "type" : "BOOLEAN",
    "required" : false,
    "description" : "Setting this value to true, the connector will extract only fields of your models that are enabled for translation.",
    "longDescription" : "Setting this value to true, the connector will extract only fields of your models that are enabled for translation.",
    "example" : "false",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : false
    }
  }, {
    "name" : "exposeLinkedEntitiesAsChildren",
    "type" : "BOOLEAN",
    "required" : false,
    "description" : "Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry.",
    "longDescription" : "Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry. Setting it to false or leaving it out, there will be no children of Entries.",
    "example" : "false",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : false
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_IMPLEMENTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "NOT_IMPLEMENTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Dropbox",
  "description" : "Dropbox is a modern workspace designed to reduce busywork—so you can focus on the things that matter.",
  "config" : [ {
    "name" : "token",
    "type" : "STRING",
    "required" : true,
    "description" : "The access token from the Xillio app in Dropbox.",
    "longDescription" : "A Dropbox API token.",
    "example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "SUPPORTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Drupal",
  "description" : "Drupal is an open source platform for building amazing digital experiences. It's made by a dedicated community. Anyone can use it, and it will always be free.",
  "config" : [ {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on Drupal.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the Drupal instance including the path to the JSON:API module.",
    "longDescription" : "The URL to the JSON:API module of Drupal.",
    "example" : "https://my-drupal-website:8084/jsonapi",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "SUPPORTED"
  }
}, {
  "configurationType" : "Egnyte",
  "description" : "Egnyte CONNECT: Secure File Sharing & Collaboration.",
  "config" : [ {
    "name" : "address",
    "type" : "STRING",
    "required" : true,
    "description" : "The URL of the Egnyte instance.",
    "longDescription" : "The base URL of the Egnyte instance.",
    "example" : "https://example.egnyte.com",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : true,
    "description" : "An access token.",
    "longDescription" : "An Egnyte OAuth2 token.",
    "example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Episerver10",
  "description" : "Episerver is a global software company offering web content management (WCM) (or CMS), digital commerce, and digital marketing, through the Episerver Digital Experience Cloud software platform.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the Episerver api extension.",
    "longDescription" : "The URL of the Episerver instance.",
    "example" : "http://my-domain.com:49700/episerverapi",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on Episerver.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "An Episerver OAuth2 token.\n\nA token lasts 5 minutes after which a new one will be requested.\n\nOptional if supplying a `username` and `password`.",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Filenet",
  "description" : "IBM FileNet Content Manager is document management engine with enterprise content, security and storage features plus process management capabilities.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the FileNet server API extension.",
    "longDescription" : "The URL of the FileNet server API extension.",
    "example" : "http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on Filenet.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "objectstore",
    "type" : "STRING",
    "required" : true,
    "description" : "The name of the object store to which to connect.",
    "longDescription" : "The name of the object store to which to connect.",
    "example" : "objectstore",
    "secret" : false
  }, {
    "name" : "stanza",
    "type" : "STRING",
    "required" : false,
    "description" : "The communication protocol to use.",
    "longDescription" : "The communication protocol to use.\n\nIf not sure about what value to use for stanza, leave empty, the Web Service Interface will be used by default.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "FileNetP8WSI"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "SUPPORTED"
  }
}, {
  "configurationType" : "GitLab",
  "description" : "GitLab is a web-based Git-repository manager providing wiki, issue-tracking and CI/CD pipeline features.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the GitLab instance.",
    "longDescription" : "The base URL to the GitLab instance.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://gitlab.com"
    }
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The application id.",
    "longDescription" : "The GitLab application client id. Required when `refreshToken` is set.",
    "example" : "client-id",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The application secret.",
    "longDescription" : "The GitLab application secret. Required when `refreshToken` is set.",
    "example" : "client-secret",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "A GitLab personal access token or an OAuth2 token",
    "longDescription" : "A GitLab personal access token, or a GitLab OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required.",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "A refresh token.",
    "longDescription" : "An OAuth2 refresh token.\n\nSee <<gitlab-credentials>> for information on acquiring a refresh token.",
    "example" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
    "secret" : true
  }, {
    "name" : "projectId",
    "type" : "STRING",
    "required" : true,
    "description" : "The id or path of the git repository.",
    "longDescription" : "The id of the GitLab project.\n\nIt can be specified either by name (e.g. `MyUser/MyProject` or `MyOrganization/MyProject`) or by a numeric identifier (e.g. `10262206`), which can be found on the main page of the project.",
    "example" : "MyGroup/MyProject",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "GoogleDrive",
  "description" : "A safe place for all your files.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Google Drive API.",
    "longDescription" : "The base URL of the Google Drive API.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://www.googleapis.com"
    }
  }, {
    "name" : "oauthUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The token URL of the Google authorization server.",
    "longDescription" : "The token URL of the Google authorization server.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://www.googleapis.com/oauth2/v4/token"
    }
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The client id of your Google API application.",
    "longDescription" : "The Google Drive application client id. Required when `refreshToken` is set.",
    "example" : "826514876365-m4hltubt3d3tvu7iu2875m5pvum0fm8l.apps.googleusercontent.com",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The client secret of your Google API application.",
    "longDescription" : "The Google Drive application secret. Required when `refreshToken` is set.",
    "example" : "BAHEfQjVAN-GVZ9IV9EPbPg_",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "A Google Drive OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "A refresh token.",
    "longDescription" : "An OAuth2 refresh token.\n\nSee <<googledrive-refresh-token>> for information on acquiring a refresh token.",
    "example" : "1/CWEaui3J_4X5sQlYGP0S4lwZ6er59YsWx6jiPrflAiA",
    "secret" : true
  }, {
    "name" : "mimeTypeMapping",
    "type" : "MAP",
    "required" : false,
    "description" : "The mapping of Google mimeTypes to an exportable mimeTypes.",
    "longDescription" : "It is not possible to download the Google Docs format via Xillio API directly.\n\nThe `mimeTypeMapping` field is required to make the downloading and exporting the content of the Google Docs format files possible by converting it into any other compatible format.\n\nThe `mimeTypeMapping` field is an another JSON object. So, it can be either `null` or have the standard JSON structure like:\n\n[source]\n----\n{\n    \"application/vnd.google-apps.document\": \"text/plain\",\n    \"application/vnd.google-apps.spreadsheet\": \"text/csv\"\n}\n----\nThe key must be a `googleMimeType` and value is an `exportMimeType`\n\nIf the `googleMimeType` will not be compatible with `exportMimeType`, e.g.\n[source]\n----\n{\n    \"application/vnd.google-apps.document\": \"image/jpeg\",\n    ...\n}\n----\nwhat means you are trying to export a document format as a `JPG image`, you will get an error\n[source]\n----\n{\n    \"errorId\": \"27d9e2d0-0336-4ead-ad8f-a5348532426e\",\n    \"message\": \"Export Mime Type [image/jpeg] not supported by [application/vnd.google-apps.document]\",\n    \"error\": \"Bad Request\",\n    \"status\": 400,\n    \"timestamp\": \"2021-11-25T14:19:36.891+01:00\",\n    \"errorType\": \"InvalidConfiguration\",\n    \"path\": \"/v2/configurations\",\n    \"parameters\": {}\n}\n----\nPlease refer to the https://developers.google.com/drive/api/v3/ref-export-formats[official Google documentation] to find everything out about different mimeTypes and their compatibility.\n\nEach Google doc format can be exported only into one format in each distinct mimeTypeMapping. If you enter several export formats for the same Google Docs format e.g.\n[source]\n----\n{\n    \"application/vnd.google-apps.document\": \"text/plain\",\n    \"application/vnd.google-apps.document\": \"application/rtf\",\n    \"application/vnd.google-apps.spreadsheet\": \"text/csv\"\n}\n----\nonly the last one will be used.\n\nAs were said, the `mimeTypeMapping` field is a JSON object but you must provide map only. You can you neither arrays nor nested objects.\n\n\nIf you don't set up the `mimeTypeMapping` field or miss a desired format and try to download a Google Doc, you will get an error\n[source]\n----\n{\n    \"errorId\": \"b2811db5-21fe-4cb7-9213-edd39c56725b\",\n    \"message\": \"Configuration for googleMimeType [<missing mimeType>] not added\",\n    \"error\": \"Method Not Allowed\",\n    \"status\": 405,\n    \"timestamp\": \"2021-11-25T13:52:04.415+01:00\",\n    \"errorType\": \"OperationNotAllowed\",\n    \"path\": \"/v2/contents/googledrive/<file-id>\",\n    \"parameters\": {}\n}\n----",
    "example" : "{ \"application/vnd.google-apps.document\": \"text/plain\", \"application/vnd.google-apps.spreadsheet\":\"text/csv\" }",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "SUPPORTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "JsonRpc",
  "description" : "Configuration for an external connector that exposes the JSON RPC API.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the connector jsonrpc endpoint",
    "longDescription" : "The URL of the remote JSON RPC connector endpoint that is going to execute the requests for this configuration.",
    "example" : "http://custom-connector:8887/json-rpc",
    "secret" : false
  }, {
    "name" : "skipSslValidation",
    "type" : "BOOLEAN",
    "required" : false,
    "description" : "Ignore SSL trust chain verification for the external connector",
    "longDescription" : "When set to `true`, the connector will skip validation of the trust chain when connecting to the external connector with the `HTTPS` protocol, allowing to use self-signed certificates.\n\nWARNING: _Only for testing_: should be left to `false` in production as it will not prevent spoofing and man in the middle attacks.",
    "example" : "false",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : false
    }
  }, {
    "name" : "configuration",
    "type" : "MAP",
    "required" : true,
    "description" : "The external connector configuration",
    "longDescription" : "The external JSON RPC connector configuration fields in the form a JSON object with field names as keys and field values as values.\n\nNOTE: Arrays, nested objects and null values are not supported in this configuration object.\n\nFor example, if the external JSON RPC connector needs a `baseUrl` and a `token` field, the `configuration` map would look as follows:\n\n```\n{\n    \"baseUrl\" : \"https://myhost.com/myCms\",\n    \"token\" : \"mytokenforauthenticationandauthorization\"\n}\n```\n\nNOTE: It is important not to confuse the `baseUrl` of the JSON RPC connector configuration, that points to the external _connector_, with the `baseUrl` field of the external connector configuration that points to the _target system_.",
    "example" : "{ \"baseUrl\": \"https://mycms/store\", \"token\":\"ljdadn234wqnadnn4\" }",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "SUPPORTED",
    "pagination" : "SUPPORTED"
  }
}, {
  "configurationType" : "OneDrive",
  "description" : "OneDrive is Microsoft's service for hosting files in the \"cloud\", that's available for free to all the owners of a Microsoft account and offers users a simple way to store, sync and share all kinds of files, with other people and devices.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the OneDrive API.",
    "longDescription" : "The base URL of the OneDrive API.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://graph.microsoft.com/v1.0/me/drive/root"
    }
  }, {
    "name" : "redirectUri",
    "type" : "STRING",
    "required" : false,
    "description" : "The OAuth redirect URI.",
    "longDescription" : "The URI where the user is redirected to after authorization is completed.",
    "example" : "https://xillio.com/callback",
    "secret" : false
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The client id of your application registered with OneDrive.",
    "longDescription" : "The OneDrive application client id. Required when `refreshToken` is set.",
    "example" : "client-id",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The client secret of your application registered with OneDrive.",
    "longDescription" : "The OneDrive application secret. Required when `refreshToken` is set.",
    "example" : "client-secret",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "A OneDrive OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "A refresh token.",
    "longDescription" : "An OAuth2 refresh token.",
    "example" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_AVAILABLE",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Opentext",
  "description" : "OpenText Content Server provides the core set of tools you need to capture, process and manage unstructured content across your organization including document management, workflow, search and information retrieval services, all tightly integrated into a platform that is easily customized and extended.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the OpenText Content Server.",
    "longDescription" : "The full URL of the OpenText Content Server API extension: server, port and the path to the API root.",
    "example" : "http://otcs.xillio.com:8080/otcs/cs.exe",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on OpenText.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "rootNode",
    "type" : "NUMBER",
    "required" : false,
    "description" : "The id of the root node.",
    "longDescription" : "The id of the root node.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : 2000
    }
  }, {
    "name" : "maxAuthAttempts",
    "type" : "NUMBER",
    "required" : false,
    "description" : "The number of attempts to get an authentication ticket from Opentext Content Server.",
    "longDescription" : "The number of attempts to get an authentication ticket from Opentext Content Server.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : 3
    }
  }, {
    "name" : "retryAuthAfter",
    "type" : "NUMBER",
    "required" : false,
    "description" : "Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt.",
    "longDescription" : "Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : 2
    }
  }, {
    "name" : "ticket",
    "type" : "STRING",
    "required" : false,
    "description" : "OpenText Content Server authentication ticket. Can be left empty when creating or updating a configuration.",
    "longDescription" : "OpenText Content Server authentication ticket.",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "SUPPORTED",
    "pagination" : "SUPPORTED"
  }
}, {
  "configurationType" : "S3",
  "description" : "S3 is a storage service offered by Amazon and other vendors. It stands for simple storage service and provides cloud storage for various types of web development applications.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the S3 API. This includes the bucket as sub-domain.",
    "longDescription" : "The base URL to the target bucket. It _must_ include the bucket name.",
    "example" : "https://mybucket.s3.amazonaws.com",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The Access Key id to sign the S3 requests.",
    "longDescription" : "The access key id to use for authentication.",
    "example" : "AKIAIOSFODNN7EXAMPLE",
    "secret" : true
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The Secret Access Key to sign the S3 requests.",
    "longDescription" : "The secret access key to use for authentication.",
    "example" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "secret" : true
  }, {
    "name" : "region",
    "type" : "STRING",
    "required" : false,
    "description" : "The region of the S3 instance.",
    "longDescription" : "The region in which this bucket resides. Required for AWS S3 instances.",
    "example" : "eu-central-1",
    "secret" : false
  }, {
    "name" : "delimiter",
    "type" : "STRING",
    "required" : false,
    "description" : "The delimiter used in your S3 bucket.",
    "longDescription" : "The delimiter for traversing the bucket. See <<s3-hierarchy>>.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "/"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "NOT_IMPLEMENTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Salesforce",
  "description" : "Salesforce Knowledge is part of complex cloud-based CRM solution.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The address of your Salesforce server.",
    "longDescription" : "The base URL of the Salesforce API.",
    "example" : "https://eu26.salesforce.com",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://eu26.salesforce.com"
    }
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "A refresh token to obtain access tokens with.",
    "longDescription" : "An OAuth2 refresh token.",
    "example" : "5Axc861F1.ndOFuBX057HR38ot4A7419...",
    "secret" : true
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "Application identifier for refresh token authorization flow.",
    "longDescription" : "The client id. Required when `refreshToken` is set.",
    "example" : "3MFG96_7YM2sI9wTgZjGhoQXR6WBX35X...",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "Application secret for refresh token authorization flow.",
    "longDescription" : "The client secret. Required when `refreshToken` is set.",
    "example" : "FB5AE94E81B62A80692F4D9CUR63M890...",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "The token that is used for authenticating requests with Salesforce.",
    "longDescription" : "An OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
    "example" : "00A4p000000OtwS!AQNEPJgHxpEq9YXP...",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_AVAILABLE",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "SharePoint",
  "description" : "SharePoint is web-based, collaborative platform that integrates with Microsoft Office.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the SharePoint Online site.",
    "longDescription" : "The base URL of the SharePoint instance.",
    "example" : "https://your-company.sharepoint.com",
    "secret" : false
  }, {
    "name" : "authUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Microsoft authentication endpoint for the SharePoint REST API.",
    "longDescription" : "The URL of the Microsoft authentication endpoint.",
    "example" : "https://login.microsoftonline.com/extSTS.srf",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://login.microsoftonline.com/extSTS.srf"
    }
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on SharePoint.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "domain",
    "type" : "STRING",
    "required" : false,
    "description" : "The MS Windows Domain for SharePoint On-Premises only.",
    "longDescription" : "Windows NT Domain name, for SharePoint On-Premises only.",
    "secret" : false
  }, {
    "name" : "site",
    "type" : "STRING",
    "required" : true,
    "description" : "The site to which to connect.",
    "longDescription" : "Site URL part which usually takes one of 2 forms:\n\"sites/MySite\" or just \"MySite\"",
    "example" : "MySite",
    "secret" : false
  }, {
    "name" : "version",
    "type" : "STRING",
    "required" : false,
    "description" : "The version of Sharepoint On-Premise to connect to.",
    "longDescription" : "The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.",
    "example" : "2016",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "2016"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "SharePointV2",
  "description" : "SharePoint is web-based, collaborative platform that integrates with Microsoft Office.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the SharePoint Online site",
    "longDescription" : "The base URL of the SharePoint instance.",
    "example" : "https://your-company.sharepoint.com",
    "secret" : false
  }, {
    "name" : "authUrl",
    "type" : "URL",
    "required" : false,
    "description" : "The URL of the Microsoft authentication endpoint for the SharePoint REST API",
    "longDescription" : "The URL of the Microsoft authentication endpoint.",
    "example" : "https://accounts.accesscontrol.windows.net",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "https://accounts.accesscontrol.windows.net"
    }
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : true,
    "description" : "Client Id of registered SharePoint Add-In",
    "longDescription" : "The SharePoint app client-id to access the API.",
    "example" : "91391ad5-f8b4-4007-8e98-e2e695c0bcb2",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : true,
    "description" : "Client Secret registered SharePoint Add-In",
    "longDescription" : "The SharePoint app client secret to access the API.",
    "example" : "mQ1eApeD251QJkNBodWRGYCES2PnEhaq1+YoM0DHrw8=",
    "secret" : true
  }, {
    "name" : "tenantId",
    "type" : "STRING",
    "required" : true,
    "description" : "Id of your SharePoint tenant",
    "longDescription" : "ID of the SharePoint tenant.",
    "example" : "f15805d7-484f-456f-b28d-5f3afae0f44b",
    "secret" : false
  }, {
    "name" : "site",
    "type" : "STRING",
    "required" : true,
    "description" : "The site to which to connect",
    "longDescription" : "Site URL part which usually takes one of 2 forms:\n\"sites/MySite\" or just \"MySite\"",
    "example" : "MySite",
    "secret" : false
  }, {
    "name" : "version",
    "type" : "STRING",
    "required" : false,
    "description" : "The version of Sharepoint to connect to",
    "longDescription" : "The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.",
    "example" : "2016",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "online"
    }
  }, {
    "name" : "resourceId",
    "type" : "STRING",
    "required" : true,
    "description" : "Resource information identifying Microsoft application. For SharePoint Online, use the default value",
    "longDescription" : "Resource information identifying Microsoft application.",
    "example" : "00000003-0000-0ff1-ce00-000000000000",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "00000003-0000-0ff1-ce00-000000000000"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Sitecore",
  "description" : "Sitecore is a CMS with additional marketing functionality that analyses customer data from multiple sources and makes it possible to show custom content.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the Sitecore target system.",
    "longDescription" : "The base URL of the Sitecore instance.",
    "example" : "https://sitecore.mydomain.com",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on Sitecore.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "database",
    "type" : "STRING",
    "required" : true,
    "description" : "The database of the Sitecore target system.",
    "longDescription" : "Database on the Sitecore target system.\n\nValid values are `core`, `master` or `web`.",
    "example" : "master",
    "secret" : false
  }, {
    "name" : "domain",
    "type" : "STRING",
    "required" : true,
    "description" : "The domain to which to connect.",
    "longDescription" : "The domain to which to connect.",
    "example" : "sitecore",
    "secret" : false
  }, {
    "name" : "ignoreExpiryDateOnCookies",
    "type" : "BOOLEAN",
    "required" : false,
    "description" : "Ignore the expiry date on cookies.",
    "longDescription" : "Enable this setting to ignore the expiry date on cookies.\n\nWARNING: For development only. Omit in a production environment.",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : false
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Trim",
  "description" : "Automate secure content and records management, from creation to disposal, to regain control of your assets and mitigate risk. Previously known as HP Content Manager and HP Trim.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the TRIM system Service API.",
    "longDescription" : "The absolute URL to the TRIM Service API.",
    "example" : "http://trim.xillio.com/HPECMServiceAPI/",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on TRIM.",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "rootQuery",
    "type" : "STRING",
    "required" : false,
    "description" : "Defines the set of records in the root for this connector.",
    "longDescription" : "A TRIM query string, see <<Root Query>>.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "*"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "NOT_IMPLEMENTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "WordPress",
  "description" : "WordPress is a free and open-source content management system (CMS). Features include a plugin architecture and a template system.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the WordPress site.",
    "longDescription" : "The URL of the WordPress site.",
    "example" : "https://demo.wp-api.org/",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of an account.",
    "longDescription" : "The username of an account on WordPress (with Administrator privileges).",
    "example" : "username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the account.",
    "longDescription" : "The password of the account, or the generated application password, depending on the authentication type.",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "A WordPress OAuth2 token.\n\nOptional if logging in with a `username` and `password` combination.",
    "secret" : true
  }, {
    "name" : "authenticationType",
    "type" : "STRING",
    "required" : true,
    "description" : "The authentication type to use.",
    "longDescription" : "Specifies which authentication type the connector should use. Valid options are `basic` and `jwt`.",
    "example" : "NO_EXAMPLE",
    "secret" : false,
    "default" : {
      "mustDefaultWith" : [ ],
      "value" : "jwt"
    }
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Zendesk",
  "description" : "Zendesk Guide is a smart knowledge base system for better self-service and empowered agents.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "URL",
    "required" : true,
    "description" : "The URL of the Zendesk server.",
    "longDescription" : "The URL of the target Zendesk site.",
    "example" : "https://yoursite.zendesk.com",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : false,
    "description" : "The username of an account, or the username and \"/token\".",
    "longDescription" : "Depending on your authentication method, either of:\n\n - The email you are using to log in to the Zendesk web interface\n - The concatenation of your username and `/token`",
    "example" : "your@email.com",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : false,
    "description" : "The password of the account, or the API token.",
    "longDescription" : "Depending on your authentication method, either of:\n\n - The password you are using to log in to the Zendesk web interface\n - The API token assigned to the selected user",
    "example" : "password",
    "secret" : true
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "An access token.",
    "longDescription" : "A Zendesk OAuth2 token.\n\nShould not be provided if `username` and `password` are provided.",
    "secret" : true
  }, {
    "name" : "permissionGroupId",
    "type" : "NUMBER",
    "required" : false,
    "description" : "The id of the permission group that is used when creating articles.",
    "longDescription" : "_Optional._ +\nThe id of the management permission group that is used when creating articles.",
    "example" : "2102353",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_AVAILABLE",
    "metadataScope" : "NOT_IMPLEMENTED",
    "rpc" : "SUPPORTED",
    "search" : "NOT_IMPLEMENTED",
    "pagination" : "NOT_IMPLEMENTED"
  }
} ]

2.14. /system

2.14.1. Ping

Ping the Xillio API. This can be used to check the health of the system and your tenant. If the tenant could not be found, a 404 response is returned.

GET /v2/system/ping
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/system/ping' -i -X GET
Response Fields
Path Type Description

tenant

String

The name of the current tenant.

serverTime

String

The current server time.
Example Response
HTTP/1.1 200 OK

{
  "tenant" : "demo-tenant",
  "serverTime" : "2024-10-29T16:27:46.323Z"
}
Possible Errors

No Such Tenant

2.14.2. Version

Receive the version information of the Xillio API.

GET /v2/system/version
------
HTTP/1.1 200 OK
Content-Type: application/json
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/system/version' -i -X GET
Response Fields
Path Type Description

softwareName

String

The name of the software.

softwareVersion

String

The current software version.
Example Response
HTTP/1.1 200 OK

{
  "softwareName" : "Xillio API",
  "softwareVersion" : "testing"
}
Possible Errors

No Such Tenant

2.15. /rpc

For documentation of the specific RPC methods, see the RPC section of the connector documentation.
New RPC methods can be created on request. Please contact support to be informed about the possibilities.

2.15.1. Get all RPC methods

List all RPC methods for the given configuration.

This endpoint requires an access_token for scope rpc for a user with role RPC_USER. 
GET /v2/rpc/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/rpc/{configurationId}
Parameter Description

configurationId

The id of a configured repository.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/rpc/5583aaf876824ea2a4a64f2ed54d7b89' -i -X GET \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

configurationType

String

The type of the configuration exposing the RPC methods

handlers

Array

An array of all the RPC methods.

handlers[].namespace

String

The namespace of the RPC method.

handlers[].method

String

The name of the RPC method.

handlers[].url

String

The URL on which the RPC method can be invoked.
Example Response
HTTP/1.1 200 OK

{
  "configurationType" : "FileSystem",
  "handlers" : [ {
    "namespace" : "files",
    "method" : "attributes",
    "url" : "https://demo-tenant.xill.io/v2/rpc/5583aaf876824ea2a4a64f2ed54d7b89/files/attributes"
  } ]
}
Possible Errors

No Such Configuration

Unauthorized

Access Denied

2.15.2. Invoke an RPC method

RPC methods can be invoked using either a GET or a POST request. The input for an RPC method can be supplied either through query parameters or the request body. When using a request body, the body should be a JSON object containing fields for each input parameter, e.g.: { "path": "/some/path" }. When using query parameters, the parameter key must match an argument name of the RPC method, e.g.: path=%2Fsome%2Fpath. Query parameter values have precedence over values in the request body.

RPC methods can have optional and mandatory parameters. If no value is supplied for an optional parameter, a default value is used. If a mandatory value is not supplied, an error will be returned.

The response body is the result of the invoked method serialized to JSON. This is a non-unified value. If no result is returned, the response code will be 204 - No Content without a response body.

Passthrough Authorization

This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.

This endpoint requires an access_token for scope rpc for a user with role RPC_USER. 
POST /v2/rpc/{configurationId}/{namespace}/{method}
------
HTTP/1.1 200 OK
Content-Type: application/json
/v2/rpc/{configurationId}/{namespace}/{method}
Parameter Description

configurationId

The id of a configured repository.

namespace

The namespace of the to be invoked RPC method.

method

The name of the method to invoke.
Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/rpc/4b29ae987665455f80673c737475bae0/files/attributes' -i -X POST \
    -H 'Authorization: Bearer <<YOUR_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  "path" : "./file.txt"
}'
Example Response
HTTP/1.1 200 OK

{
  "attributes" : {
    "lastAccessTime" : "2024-10-29T16:27:27.087549Z",
    "lastModifiedTime" : "2024-10-29T16:27:27.087549Z",
    "size" : "12",
    "creationTime" : "2024-10-29T16:27:27.087549Z",
    "isSymbolicLink" : "false",
    "isRegularFile" : "true",
    "fileKey" : "(dev=46,ino=25977806)",
    "isOther" : "false",
    "isDirectory" : "false"
  }
}
Possible Errors

No Such Handler

No Such Configuration

No Such Entity

Entity Already Exists

Operation Not Allowed

No Binary Content

Authorization Failed

Insufficient Storage

Misconfigured System

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

2.16. Possible Endpoints Errors

If an error occurs while handling a request, it will be returned as the response instead. All errors adhere to the following structure:

Path Type Description

errorId

String

The id of the error. This id can be used in support requests.

message

String

A contextual message that describes the cause of this error.

error

String

A more general error message.

status

Number

The http status code.

timestamp

String

The date this exception occurred.

errorType

String

The type of error that occurred in the backend.

path

String

The request URI that caused this error.

parameters

Object

The parameters that were passed to this request.

The most common errors with their respective responses are:

2.16.1. No Such Entity

This error occurs when the requested entity could not be found. This error also occurs when the URL does not match the format a connector expected, for example with an nonexistent collection in a REST based system.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "8a237533-b8e3-4831-ad5d-896e3ac0a6da",
  "message" : "No entity was found at xdip://59e4b5a7857aba0005a2822a/non/existing/entity",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.447Z",
  "errorType" : "NoSuchEntity",
  "parameters" : { }
}

2.16.2. No Such Configuration

This error occurs when the requested configuration could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "862961c7-32c5-46ba-9768-81d88403e07b",
  "message" : "No configuration was found for '59e4b5a7857aba0005a28228'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.444Z",
  "errorType" : "NoSuchConfiguration",
  "parameters" : { }
}

2.16.3. No Such Content Script

This error occurs when the requested content script could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "2a036d0f-fab9-4081-a067-27cff88f4bdc",
  "message" : "No content script was found for '59e4b5a7853aba0005a2822a'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.445Z",
  "errorType" : "NoSuchContentScript",
  "parameters" : { }
}

2.16.4. Content Script Already Exists

This error occurs when a content script is manipulated or created which conflicts with an existing content script on the configuration. A configuration cannot have two content scripts that share the same mimetype and type.

Example response
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "09b7e27f-3921-49bb-8b88-1600471632b3",
  "message" : "Supplied content script already exists: A content script with the mimeType 'application/xml' and type 'READ' on configuration with id '59e4b5a7353aba0005a2822a' already exists.",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2024-10-29T16:27:32.407Z",
  "errorType" : "ContentScriptAlreadyExists",
  "parameters" : { }
}

2.16.5. No Such Query Configuration

This error occurs when the requested named query configuration could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "24e2f5ab-ccf6-4251-a09a-36f9d49b8d08",
  "message" : "No named query was found for 'queryName' on configuration '59e4b5a7353aba0005a2822a'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.450Z",
  "errorType" : "NoSuchQueryConfiguration",
  "parameters" : { }
}

2.16.6. No Such Handler

This error occurs when the requested RPC method could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "cf692c2d-c8fa-4ab8-b9fc-70a1d1c80c9a",
  "message" : "No method was found for namespace/non-existing-method",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.449Z",
  "errorType" : "NoSuchHandler",
  "parameters" : { }
}

2.16.7. Query Configuration Already Exists

This error occurs when creating a named query with a name which is already used by another query in the same configuration. A configuration cannot have two named queries sharing the same name.

Example response
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "61dbb7e0-b86b-4979-90be-eb994de4982f",
  "message" : "The named query configuration 'queryName' on configuration with id '59e4b5a7353aba0005a2822a' already exists.",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2024-10-29T16:27:32.460Z",
  "errorType" : "QueryConfigurationAlreadyExists",
  "parameters" : { }
}

2.16.8. Invalid Template Variable

This error occurs when a named query template uses a variable name which is not prefixed correctly or is empty.

See Named Queries.

Example response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "65d0fde1-84e2-4188-bdbf-ebfbf999fa99",
  "message" : "All template variables must be not empty and prefixed with 'q_'. Invalid variable names: variable",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.427Z",
  "errorType" : "InvalidTemplateVariable",
  "parameters" : { }
}

2.16.9. Invalid Query Variable

This error occurs when executing a query and is caused by a violation of any of the following constraints:

  • When executing a query without specifying all template variables as URL parameters (missing variable)

  • When executing a query specifying more URL parameters than the template contains (unused variable)

  • When a query variable is assigned more than one value

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "ca43fc41-c54b-4dbd-a06e-6322cdff4195",
  "message" : "Invalid query variables. Missing: [q_my-missing-variable]. Unused: [q_my-unused-variable]",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.425Z",
  "errorType" : "InvalidQueryVariable",
  "parameters" : { }
}

2.16.10. Invalid Query

This error occurs when the query template, or the query template after the substitution of variables, is not a valid query for the target system, either syntactically or semantically.

Example Reponse
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "c4587d72-1550-4ee5-84b4-5ebd3fdefca4",
  "message" : "The query could not be parsed by the target system: The query is not valid",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.423Z",
  "errorType" : "InvalidQuery",
  "parameters" : { }
}

2.16.11. Invalid Configuration

This error occurs when creating or updating a configuration and the input is invalid.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "1c1917fb-85ba-4c0e-bb89-378ef7b04ae3",
  "message" : "Missing required field 'rootPath'",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.421Z",
  "errorType" : "InvalidConfiguration",
  "parameters" : { }
}

2.16.12. Configuration Already Exists

This error occurs when creating a configuration with an id that already exists

Example Response
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "d5847c84-8600-4e76-93b1-9493f560762c",
  "message" : "The configuration id 'customConfigurationId' already exists",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2024-10-29T16:27:32.404Z",
  "errorType" : "ConfigurationAlreadyExists",
  "parameters" : { }
}

2.16.13. No Such User

This error occurs when the requested user could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "2d311a1f-f2aa-4dee-9073-d10d917bf9ce",
  "message" : "No user with id 'myUsername' was found in tenant 'myTenant'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.456Z",
  "errorType" : "NoSuchUser",
  "parameters" : { }
}

2.16.14. Invalid User

This error occurs when creating or updating a user and the input is invalid.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "35212f03-7d39-40cb-95bc-a6fd734a5aa2",
  "message" : "Supplied user was not valid: A user with the username 'myUsername' already exists.",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.431Z",
  "errorType" : "InvalidUserArgument",
  "parameters" : { }
}

2.16.15. Entity Already Exists

This error occurs when doing a manipulative operation on a specific entity where this operation conflicts with the underlying system since there is already something in that place. For example, when moving an existing entity to a location where another entity already exists.

Example Response
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "9179b1ed-3a45-4a61-b5a7-44c035b230f1",
  "message" : "'xdip://59e4b5a6857aba0005a28227/existing/entity' already exists.",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2024-10-29T16:27:32.417Z",
  "errorType" : "EntityAlreadyExists",
  "parameters" : { }
}

2.16.16. Missing Decorator

This error occurs when performing an operation which requires a certain decorator and the decorator is not present. For example, during an attempt to create a new entity but do not provide the name decorator.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "1b58454c-0728-4743-af43-cd433f2d1347",
  "message" : "Missing required decorator: parent",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.441Z",
  "errorType" : "MissingDecorator",
  "parameters" : { }
}

2.16.17. No Binary Content

This error occurs when requesting or updating the contents of an entity which is not capable of containing contents. If an entity is capable of containing contents but it does not, this error does not occur.

Example Response
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "3fd86f38-165c-48b8-8659-bd1d495145d4",
  "message" : "No content found at xdip://59e4b5a6857aba0005a28227/New%20Folder",
  "error" : "Method Not Allowed",
  "status" : 405,
  "timestamp" : "2024-10-29T16:27:32.443Z",
  "errorType" : "NoBinaryContent",
  "parameters" : { }
}

2.16.18. Content Script Failed

This error occurs when the content script has reached a timeout or has encountered a compile, runtime or user thrown error.

Example Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "436731f3-f58b-4f33-855e-defec744d024",
  "message" : "Something went wrong while running the content script.",
  "error" : "Unprocessable Entity",
  "status" : 422,
  "timestamp" : "2024-10-29T16:27:32.408Z",
  "errorType" : "ContentScriptFailed",
  "parameters" : { }
}

2.16.19. Operation Not Allowed

This error occurs when performing an operation that cannot complete due to limitations. For example, moving an entity into another entity which cannot have children (and does not have the container decorator).

Example Response
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "890bf6a5-afc4-4f04-8085-55666c223382",
  "message" : "Files cannot contain other files",
  "error" : "Method Not Allowed",
  "status" : 405,
  "timestamp" : "2024-10-29T16:27:32.458Z",
  "errorType" : "OperationNotAllowed",
  "parameters" : { }
}

2.16.20. Authorization Failed

This error occurs when performing an action for which you are not authorized by the target system, or when the configuration contains invalid credentials.

Example Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "0184605d-1b56-462e-a066-26d60404adac",
  "message" : "You are not allowed to create files in this folder",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2024-10-29T16:27:32.402Z",
  "errorType" : "AuthorizationFailed",
  "parameters" : { }
}

2.16.21. Host Not Reached

This error occurs when the API is not able to communicate with the host which was set in the configuration.

Example Response
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "45fe6a80-436d-440d-b59a-f9cdbf8ff302",
  "message" : "Could not find host at https://hostisnotfound.com",
  "error" : "Service Unavailable",
  "status" : 503,
  "timestamp" : "2024-10-29T16:27:32.418Z",
  "errorType" : "HostNotReached",
  "parameters" : { }
}

2.16.22. Unauthorized Configuration Type

This error occurs when performing a create or update on a configuration with an unauthorized configuration type. All the allowed configuration types of a tenant can be checked by calling the /v2/tenant endpoint.

Example Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "d4a90ac6-75eb-4599-8f65-68bb52176df3",
  "message" : "Configuration type 'BitBucket' is not available for your tenant.",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2024-10-29T16:27:32.464Z",
  "errorType" : "UnauthorizedConfigurationType",
  "parameters" : { }
}

2.16.23. Unsupported Content Type

This error occurs when performing a create or update operation using an unsupported value in the kind or contentType.systemName fields.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "6b39d729-10d5-4ae1-b679-2d45ffe5c5c9",
  "message" : "application/vnd.google-apps.folder is not supported by Episerver",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.465Z",
  "errorType" : "UnsupportedContentType",
  "parameters" : { }
}

2.16.24. Quota Exceeded

This error occurs when the quota or usage limit of the target system has been exceeded. Most systems impose flood prevention mechanisms such as api rate-limits.

This error does not occur when the Xillio API usage limits are exceeded as it only applies to the target systems.

If supported by the target system, this error will include the Retry-After header to indicate the time after which this request can be retried.

Example Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "23a7c8ba-094b-4cf5-a8f7-0c44d6ff694b",
  "message" : "Rate Limit exceeded Please retry after 42 seconds.",
  "error" : "Too Many Requests",
  "status" : 429,
  "timestamp" : "2024-10-29T16:27:32.462Z",
  "errorType" : "QuotaExceeded",
  "parameters" : { }
}

2.16.25. Insufficient Storage

This error occurs when the storage limit on the target system is exceeded and no more space is available to perform a requested operation. This error is only thrown when supported by the target system.

Example Response
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "fac5e30d-e01f-4f69-aecf-b6b9500ae734",
  "message" : "The maximum storage quota has been reached.",
  "error" : "Internal Server Error",
  "status" : 500,
  "timestamp" : "2024-10-29T16:27:32.420Z",
  "errorType" : "InsufficientStorage",
  "parameters" : { }
}

2.16.26. Unauthorized

This error occurs when no valid authorization was done while accessing the API.

This error does not occur when Xillio API could not connect to a target system due to authentication issues.

Example Response
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "882620e5-6bc3-4bbf-a808-67c37bb06f6a",
  "message" : "You are not authenticated",
  "error" : "Unauthorized",
  "status" : 401,
  "timestamp" : "2024-10-29T16:27:32.463Z",
  "errorType" : "Unauthorized",
  "parameters" : { }
}

2.16.27. Access Denied

This error occurs when the scope of the current authentication does not match the allowed scopes of the called endpoint of this API.

Example Response
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "c1e71b9d-578d-4460-86b0-11dee92d4fed",
  "message" : "Access is denied",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2024-10-29T16:27:32.331Z",
  "errorType" : "AccessDenied",
  "parameters" : { }
}

2.16.28. Misconfigured System

The target system has unmet preconditions, meaning the API cannot connect to it. Solve the problem in the error message and try again.

Example Response
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "4ebd1f80-3331-4695-94cb-26c8f18971a3",
  "message" : "The target system has disabled the 'integrations api'. Please enable the 'integrations api' feature to connect.",
  "error" : "Service Unavailable",
  "status" : 503,
  "timestamp" : "2024-10-29T16:27:32.439Z",
  "errorType" : "MisconfiguredSystem",
  "parameters" : { }
}

2.16.29. Connector Operation Failed

This error occurs when an unknown error occurred while attempting to perform the requested operation.

Example Response
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "5fd788fc-346e-4a55-8653-de46f126d775",
  "message" : "An internal server error occurred, please contact an administrator.",
  "error" : "Internal Server Error",
  "status" : 500,
  "timestamp" : "2024-10-29T16:27:32.405Z",
  "errorType" : "ConnectorOperationFailed",
  "parameters" : { }
}

2.16.30. No Such Tenant

This error occurs when the tenant you are using could not be found.

Example Response
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "2f3e471f-cbad-4570-8f81-76e572e67514",
  "message" : "No tenant with name 'my-tenant' was found",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2024-10-29T16:27:32.455Z",
  "errorType" : "NoSuchTenant",
  "parameters" : { }
}

2.16.31. Invalid XDIP

This error occurs when a request URL or reference URL does not match the XDIP constraints:

XDIP URLs must match the URL protocol with the following additions:

  • They must use the XDIP scheme

  • They cannot use fragment parameters

  • They cannot use user information

  • They cannot use port specifications

  • The first component (or configuration id) can only contain alphanumerics and dashes, but the id cannot start or end with a dash. The minimum length is 2.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "85a82804-7a59-4275-99ea-44407fdb892c",
  "message" : "Invalid XDIP URL 'xdip://3/'. Configuration ids can only contain alphanumerics and dashes, but the id cannot start or end with a dash. The minimum length is two.",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.433Z",
  "errorType" : "InvalidXDIP",
  "parameters" : { }
}

2.16.32. Deprecated

This error occurs when creating configurations and other entities that have a preferred implementation somewhere else in the API.

Example Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "c66770ff-6ce3-4efe-96e4-951691d2e5d9",
  "message" : "The connector 'DeprecatedConnector' is deprecated. Please use 'NotDeprecatedConnector'",
  "error" : "Unprocessable Entity",
  "status" : 422,
  "timestamp" : "2024-10-29T16:27:32.415Z",
  "errorType" : "Deprecated",
  "parameters" : { }
}

2.16.33. No Such Scope

This error occurs when one of the provided scope names is invalid.

Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errorId" : "afd84b89-54a5-4a49-8045-2a032895b0d5",
  "message" : "Scope 'my:scope' is not valid. Valid scopes are: entity, reference, metadata. Valid relationship names in the 3-part form of <relationship>_<navigation>_<return type> are: path, version, translation",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2024-10-29T16:27:32.453Z",
  "errorType" : "NoSuchScope",
  "parameters" : { }
}

3. Connectors

An overview of the current capabilities of the connectors can be found on: https://api.xill.io/connectors

Connector Descriptions

Connector descriptions start with the name of the connector, general information on the target system of the connector, and a short overview of supported target system versions.

Connectors might work with unsupported target system versions, but their behavior could be unpredictable.

Configuration

The Configuration section describes what needs to be done to configure the connector to work with your system.

This section includes at least a description of the configuration parameters and a minimal configuration example. In the table describing the fields, bold indicates that a field is mandatory, and italic indicates that the parameter has a default value, and can therefore be omitted.

Features and Limitations

The Features and Limitations section describes what can be expected from the connector. The connectors are intended to be as complete as possible, but in some cases the system just doesn’t support certain functionality or behaves slightly differently from what is expected.

Mappings

The Mappings section describes how data in the system is mapped to data in our internal model and potentially in which way it is converted. This section will have a table that looks like this, potentially with extra columns where needed:

Decorator Used By Field in System Description

Decorator name

Content types that use this decorator

Field in the system

Information on the mapping and/or conversion.

3.1. AEM

Adobe Experience Manager brings your content management system (CMS) and digital asset management (DAM) together — in one place.

Version(s): we support AEM 6.4 and newer.

3.1.1. Configuration

The AEM connector connects to the AEM Content Repository Extreme (CRX) repository. The CRX repository can be viewed inside AEM through CRXDE Lite.

When configuring the AEM connector, the user referenced in the configuration needs at least jcr:read privileges on JCR nodes that should be exposed. For more information on AEM permissions and on how to set them up, please refer to the AEM documentation.

Configuration parameters:
Parameter Description

baseUrl

The base URL of the AEM host.

username

The username of an account with permissions to access CRX.

password

The password of an account with permissions to access CRX.

workspace

The JCR workspace to access.

Default: crx.default
Example Configuration:
{
  "configurationType": "Aem",
  "config" : {
    "baseUrl" : "https://aem.xillio.com:4502",
    "username" : "username",
    "password" : "password"
  }
}

3.1.2. Features and Limitations

  • This connector is read-only.

  • Only JCR nodes of type nt:file, nt:folder, cq:Page and dam:Asset are exposed.

  • Both content fragments and regular assets are supported for nodes of type dam:Asset.

  • Only nodes of type nt:folder and cq:Page support the path relation.

  • Contents of nodes of type nt:folder, cq:Page and content fragments (dam:Asset) are exposed as the JCR system view XML of their jcr:content child node.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

3.1.3. Mappings

AEM mappings
Decorator Used By Field in AEM Description

container.hasChildren

cq:Page, nt:Folder

Whether the entity can have children according to the path relation.

contentType.systemName

All entities

jcr:primaryType

The primary JCR type of the JCR node corresponding to the entity.

created.date

All entities

jcr:created

The date and time at which the JCR node corresponding to the entity was created.

created.by

All entities

jcr:createdBy

The username of the account used to create the JCR node corresponding to the entity.

description.short

dam:Asset (media), dam:Asset (content fragment)

dam:Asset (media): jcr:content/metadata/dc:description, dam:Asset (content fragment): jcr:content/jcr:description

The asset description.

file.rawExtension

dam:Asset (media), nt:File

Extracted from the JCR node name

The file extension of the asset.

file.extension

dam:Asset (media), nt:File

Extracted from the JCR node name

The file extension of the asset.

file.size

dam:Asset (media), nt:File

dam:Asset (media): jcr:content/metadata/dam:size if present otherwise derived from jcr:content/renditions/original/jcr:content/jcr:data, nt:File: derived from jcr:content/jcr:data

The file size of the original rendition of the asset or the file.

fileSystem.path

All entities

JCR node path

The path of the JCR node corresponding to the entity.

hash.sha1

dam:Asset (media)

jcr:content/metadata/dam:sha1

The sha1 hash of the original rendition of the asset.

language.tag

All entities

jcr:content/jcr:language if present or extracted from the JCR node path according to the rules for AEM Language Roots

The language of the JCR node corresponding to the entity.

mimeType.type

All entities

dam:Asset (media): jcr:content/metadata/dam:MIMEtype if present otherwise jcr:content/renditions/original/jcr:content/jcr:mimeType, other entities: application/xml

The mime type of the original rendition of the asset. The XML mime type for all other entities, since their contents is returned as JCR system view XML.

modified.date

dam:Asset, cq:Page, nt:File

cq:Page: jcr:content/cq:lastModified, nt:File and dam:Asset: jcr:content/jcr:lastModified

The date and time at which the JCR node corresponding to the entity was last modified.

modified.by

dam:Asset, cq:Page, nt:File

cq:Page: jcr:content/cq:lastModifiedBy, nt:File and dam:Asset: jcr:content/jcr:lastModifiedBy

The username of the account used to last modify the JCR node corresponding to the entity.

name.systemName

All entities

JCR node name

The name of the JCR node corresponding to the entity.

name.displayName

All entities

jcr:content/jcr:title

The title of the JCR node corresponding to the entity.

parent.id

All entities

The id of the entity corresponding to the parent JCR node.

3.2. Bitbucket

This is the connector for the Bitbucket Cloud Service API. This system will be referred to as Bitbucket in the remainder of the documentation.

Version(s): version 2 of the API.

3.2.1. Configuration

The configuration for this connector consists of a URL to Bitbucket, user credentials and (optionally) an owner to define the children (repositories) of the root entity.

The connector currently only supports HTTP basic authentication.
Configuration parameters:
Parameter Description

baseUrl

The base URL of the Bitbucket v2 cloud service.

Default: https://api.bitbucket.org/2.0

username

The username of an account on Bitbucket (not the email address).

password

The password of the account.

owner

The owner for which to select repositories. When not provided, the connector will use the username as owner.

The repositories shown with this setting are only the ones owned by the owner, not the repositories to which the user has access to.
Example Configuration:
{
  "configurationType": "Bitbucket",
  "config" : {
    "username" : "username",
    "password" : "password",
    "owner" : "repository-owner"
  }
}

3.2.2. Features and Limitations

The children of the root elements are always of type Repository. The children of a Repository are always of type Branch. The children of a Branch are of type Folder or File. The children of Folder are of type Folder or File.

This connector has the following limitations:

  • Only basic authentication is supported using this connector.

  • Only read operations are allowed on repositories and branches.

  • Only read operations are allowed on the metadata of files and folders.

  • Due to the specific nature of the underlying git system, it is not possible to delete folders. In fact: in Bitbucket a folder does not exist, it only manifests itself when a file is created with a path pointing to that folder. Recursively deleting a folder would have huge impact on the performance of the connector, as it would result in a lot of calls to Bitbucket, which could voilate the fair use policy of Bitbucket regarding rate limits. This does not apply to branches and repositories, as these are read-only.

  • For the same reason we simulate the creation of folders by creating a placeholder (.xillio-api) file in the folder. This file is deleted once another file is created in the same folder.

  • Files can be deleted.

  • Files and folders cannot be moved to a different parent.

  • File and folder names cannot contain double quotes (") or slashes (/).

  • When a request for an entity on this connector (a folder or a file) results in a 404, there is no real guarantee that the entity does not exist. The bitbucket API responds with a 500 status on an entity that cannot be found. Therefore we cannot distinguish between a simple file not found or a serious incident with Bitbucket. We do feel that the serious incident is far less likely to happen than that an entity is not found. If it would happen that Bitbucket does have serious problems, there will be other calls that would report the 500 status anyway.

  • The Bitbucket API is rate limited at 30 calls per minute. The connector obeys this limit, however keep in mind that a single endpoint of the Bitbucket connector may result in multiple calls to the Bitbucket API. In case a rate limit is hit, the connector will respond with http status 429 too many requests.

  • The Bitbucket API also has hourly and daily rate limits; see https://confluence.atlassian.com/bitbucket/rate-limits-668173227.html for details.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.2.3. Mappings

These are the decorators that are set for certain types in Bitbucket. The connector uses the Repository, Branch, Folder and File types. The repository and branch types are read-only and cannot be updated.

Bitbucket mappings
Decorator Used By Field in Bitbucket Description

container.hasChildren

Repository, Branch, Folder

For these types, hasChildren is always true.

contentType

created

Repository

created_on

Other types do not have a creation date.

description

Repository

description

The description of a repository when available.

file.rawExtension

File

Computed from path.

The extension of the file, or an empty string if it has none.

file.extension

File

Computed from path.

The sanitized extension of the file.

file.size

File

size

The size in bytes of the file.

fileSystem.path

Branch, File, Folder

path

The path to the file or folder relative to the branch. For a branch this value is always "/".

hash

language

mimeType.type

File

Computed from extension.

The mime type of the requested file, based on the extension. If the extension is unknown this is set to application/octet-stream.

modified.date

Repository, Branch, Folder, File

For Repository: updated_on. For Branch, Folder and File: commit.date.

Contains the last modified date of the requested entity, converted to the current time zone.

modified.by.displayName

Branch, Folder, File

Computed from commit.author.raw.

The (full) name of the user that modified this entity, when available.

modified.by.systemName

Branch, Folder, File

commit.author.user.username

The username of the user that modified this entity.

modified.by.email

Branch, Folder, File

Computed from commit.author.raw

The email address of the user that modified this entity, when available.

name.displayName

Repository, Branch, Folder, File

For Branch, the system name is the same as the name of the branch. Any slash ('/') in the name of the branch is replaced with a space (' '). For File and Folder: computed from path. For Repository: name.

The name of the entity.

name.systemName

Repository, Branch, Folder, File

For Branch and Repository: name. For File and Folder: computed from path.

The name of the file or folder. When a branch contains slashes, the system name shows the slashes replaced with (encoded) spaces.

parent.id

Repository, Branch, Folder, File

For Branch: target.repository. Target points to the latest commit. For Repository: Repository is root. Parent is the configurationId of the current configuration. For File and Folder: the parent directory path.

The XDIP of the parent entity.

preview.html

Repository, Branch, Folder, File

links.html.href

Link to the content on the Bitbucket Web UI.

version

File

commit.hash

The version of file - its commit id.

3.3. Box

Box offers simple, secure file sharing and collaboration from anywhere.

Version(s): we support the latest version of Box.

3.3.1. Configuration

The Box connector uses the OAuth2 web flow for authentication. For more information refer to Get a Box OAuth2 Refresh Token or the Box Documentation.

Create a Box application

This section describes creating a Box application for the Xillio API. This step only has to be done once, even if multiple Box configurations are created.

Before you can start using the Box connector with your application, you will need to setup Box and provide information about your application:

  1. Navigate to the developer console.

  2. Create a new app.

  3. Select the Custom App option.

  4. Select Standard OAuth 2.0 (User Authentication) as authentication method.

  5. Give your app a name and continue by pressing View Your App.

  6. Take note of your Client ID and Client Secret under Configuration at the section OAuth 2.0 Credentials.

  7. Set the Redirect URI under OAuth 2.0 Redirect URI. Users will be redirected here after authorizing this app.

  8. Select scopes under Application Scopes. See Box Application Scopes for more information.

Box Application Scopes

The Box connector requires enabling either of the following scopes in the Box application:

Input values for configuration
Scope name Description

Read all files and folders stored in Box

This scope is needed to expose entities' metadata, content and user-defined metadata.

Read and write all files and folders stored in Box

This scope is needed to perform write operations such as creating, updating and deleting entities and their content.
Get a Box OAuth2 Refresh Token

This section describes getting an OAuth2 refresh token to create a Box connector configuration. This step has to be repeated for each Box connector configuration created. Do not share the refreshToken outside of one configuration as Box will invalidate the token.

Authorize the Box Application

Direct the Box user with access to the files and folders that need to be accessed by the Xillio API to the following URL where they will have to enter their Box credentials:

 https://account.box.com/api/oauth2/authorize?
    response_type=code&
    client_id=<your-client-id>&                 (1)
    redirect_uri=<your-redirect-uri>            (2)
1 Set client_id to the Box client ID from Create a Box application.
2 Set redirect_uri to the redirect URI specified in Create a Box application.

After the user authenticates and authorizes the app to access their content, Box will redirect them to the specified redirect URI. The code request parameter contains the authorization code. If the redirect URI points to your own application, handle this request and continue with the following step. Otherwise, copy the authorization code and use it in the following step.

The code is only valid for a short amount of time. Therefore, perform this step and the next request quickly after each other in order to retrieve a refresh token successfully.

Request a Refresh Token

With the authorization code we can now request a Box refresh token:

curl -X POST https://api.box.com/oauth2/token \
    -d grant_type=authorization_code \
    -d client_id="<your-client-id>" \                   (1)
    -d client_secret="<your-client-secret>" \           (2)
    -d redirect_uri="<your-redirect-uri>" \             (3)
    -d code="<your-code>"                               (4)
1 Set client_id to the Box client ID from Create a Box application.
2 Set client_secret to the Box client secret from Create a Box application.
3 Set redirect_uri to the redirect URI specified in Create a Box application.
4 Set code to the authorization code from the previous request.

Box will return a JSON response with the refresh_token is everything is successful:

{
    "access_token": "gc1q8a1pYSxL7VHXsB1CGLOX9E7OjyOq",
    "expires_in": 3874,
    "restricted_to": [],
    "refresh_token": "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS",
    "token_type": "bearer"
}

Box can respond with an error if the authorization code is expired:

{
    "error": "invalid_grant",
    "error_description": "The authorization code has expired"
}
Box connector configuration

The Box connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the Box API.

Default: https://api.box.com/2.0

uploadUrl

The URL of the Box API upload endpoint.

Default: https://upload.box.com/api/2.0

clientSecret

The Box application secret. Required when refreshToken is set.

clientId

The Box application client id. Required when refreshToken is set.

token

A Box OAuth2 token.

When set, refreshToken, clientId and clientSecret are not required. It can be useful for testing, or if your application handles refreshing tokens.

refreshToken

An OAuth2 refresh token.
Either token is a required field, or all of refreshToken, clientId and clientSecret are required fields. By only providing a token, you can use a developer token which is valid for 60 minutes, or handle the process of refreshing tokens yourself.
Example Configuration:
{
  "configurationType": "Box",
  "config" : {
    "clientSecret" : "kHsek3Jpji8tgFTcwcnqosfYnxO4unQA",
    "clientId" : "m1rvfFhvTCe2a5n7u4eElmOfvvE6WumL",
    "refreshToken" : "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS"
  }
}

3.3.2. Features and Limitations

Currently, this connector supports operations on files, folders and weblinks. This also includes special files, such as Box Notes.

User-defined Metadata

Box allows you to define your keys in your enterprise metadata templates and custom metadata. These keys do not have to be unique. However, when retrieving the metadata, these identical keys are suffixed with an incremental number.

Furthermore, special characters in keys of enterprise templates will be truncated when retrieving metadata. Any conflict with another key is then resolved by using an incremental number as a suffix to the key. If the key only contained special characters, the key will be called field.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

3.3.3. Mappings

Entities retrieved through Box can be of kind File, Folder or WebLink. A WebLink is also known as a Bookmark in Box’s UI.

Box Mappings
Decorator Used By Field in Box Description

container.hasChildren

Folder

Whether the entity has children.

contentType.systemName

All entities

type

The type of the Box entity.

contentType.displayName

All entities

The human readable type name.

created.date

All entities

created_at

The date and time the entity was created. This decorator won’t be present if the information is not available.

created.by

All entities

created_by

The user who created the entity.

description.short

All entities

description

The description of the entity.

file.rawExtension

File

extension

The extension of the file.

file.extension

File

extension

The extension of the file.

file.size

File

size

The size of the file in bytes.

fileSystem.path

File and Folder

path_collection

Computed from the path_collection.

hash.md5

hash.sha1

File

sha1

The sha1 hash of the file.

hash.sha256

language

mimeType.type

File

The mime type of the requested file, based on the extension. If the extension is unknown, this is set to application/octet-stream.

modified.date

All entities

modified_at

The time the entity was last modified.

modified.by

All entities

modified_by

The user who last modified the entity.

name

All entities

name

The name of the entity as used in Box.

parent.id

All entities

path_collection

The XDIP of the parent entity, as computed using the 'path_collection'.

preview.html

WebLink

url

The URL of the Bookmark.

version

File

version_number

The version number as shown in Box.

3.4. Content Store

The Content Store is the Xill4 database concept for storing any type of content targeting migrations. It uses a Mongo database and a combination of schemas.

Version(s): we support the latest version of Content Store.

Official Content Store documentation

3.4.1. Configuration

To configure a connection to a Content Store you need to provide several configuration values.

Configuration parameters:
Parameter Description

connectionType

Identifies the type of the MongoDB connection, 'mongodb' for standard connection or 'mongodb+srv' for SRV connection

host

The Content Store host, including the port if necessary

username

Username to use when authenticating with the Content Store

password

Password to use when authenticating with the Content Store

connectionOptions

Options of the MongoDB connection as pairs <name>=<value> separated by ampersand

dbName

Name of the Content Store database

collectionName

Name of the documents collection of the Content Store

Default: documents

bucketName

Name of the GridFS bucket for the Content Store binaries

Default: binaries
Example Configuration:
{
  "configurationType": "ContentStore",
  "config" : {
    "connectionType" : "mongodb+srv",
    "host" : "localhost:27017",
    "username" : "user",
    "password" : "goodpassword",
    "connectionOptions" : "tls=true&connectTimeoutMS=30000",
    "dbName" : "contentstore"
  }
}

3.4.2. Features and Limitations

This connector was created exclusively for use with LocHub and for translating content.

The connector exposes Content Store RECORDs and CONTAINERs. Only RECORDs can be translated. CONTAINERs are only exposed to create the tree structure to navigate the Content Store. As a children entites of the root the connector exposes all RECORDs and CONTAINERs without a parent.

When a Content Store RECORD is translated for the first time, the connector creates a new RECORD, sets a reference to the original master language RECORD, sets the language of the translation, and marks the origin of the RECORD as LocHub.

When the RECORD is translated again later, the connector creates a new BINARY entity with the new translated content, and links this new BINARY to the existing translation RECORD. The former BINARY is deleted.

All the translation RECORDs are created as children of a special CONTAINER called "LocHub Translations". The connector creates such a CONTAINER if it doesn’t exist.

3.5. Contentful

Contentful is content infrastructure. The platform lets you create, manage and distribute content to any platform. Unlike a CMS, Contentful gives you total freedom to create your content model so you can decide which content you want to manage.

With our connector, you can access and translate content stored in Contentful.

3.5.1. Configuration

The most important part of the configuration is the Content management access token. You need to provide this token to allow our connector to navigate and update content created in your apps. This token represents the desired account of your user, and this token will have the same rights as the owner of the account.

There are two types of Content management tokens which you can use:

  • OAuth tokens - they are issued by OAuth applications and represent the user who granted access through this application. These tokens have the same rights as the owner of the account. You can learn more about OAuth applications in Contentful documentation.

  • Personal access tokens - As an alternative to OAuth applications, you can also leverage Personal Access Tokens to use the Content Management API. These tokens are always bound to your individual account, with the same permissions you have on all of your spaces and organizations.

Getting a Content management token

You can create personal access tokens using the Contentful web app. Navigate to the master branch of a space you want to access with the connector. Select Settings/API keys and switch to Content management tokens. Here you can create a token of your choice.

Contentful connector configuration

The Contentful connector configuration consists of the following values:

Configuration parameters:
Parameter Description

token

The Content management access token.

spaceId

The ID of the Contentful space you want to access. This value is optional. When not provided the connector will expose all the spaces that the tokens allows accessing.

environmentId

The environment id of your Contentful Management API. It is necessary to add spaceId if you add environmentId.

sourceLanguageCode

Configure the code of the language you consider a source language for the translations. This defines what values the connector exports as content that needs to be translated.

getOnlyTranslationFields

Setting this value to true, the connector will extract only fields of your models that are enabled for translation.

Default: false

exposeLinkedEntitiesAsChildren

Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry. Setting it to false or leaving it out, there will be no children of Entries.

Default: false
Example Configuration:
{
  "configurationType": "Contentful",
  "config" : {
    "token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
    "spaceId" : "43bhs4uagphk",
    "environmentId" : "master",
    "sourceLanguageCode" : "en-US"
  }
}

3.5.2. Features and Limitations

Connector does not support updating the binary content of the entities as a connector operation. To update the translation of an asset or entry, request creating a new entity. Creating a completely new asset or entry is not possible with the current version of the connector.

Connector does not support entity deletion.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

3.5.3. Mappings

These are the decorators that are set for certain kinds of entities in Contentful. Entities retrieved via Contentful connector can be of kind Space or Environment or ContentModel or Assets or Entry or AssetFile.

Contentful mappings
Decorator Used By Read-only Field in Contentful Description

container.hasChildren

All entities

True

When the entity has children.

contentType.displayName

All entities

True

The human-readable name of the content type associated with the requested Contentful entity.

contentType.systemName

All entities

True

Computed from ContentType

The name of the content type associated with the requested Contentful entity.

created.date

All entities

True

CreatedAt

Date and time when the requested entity was created.

file.rawExtension

Entries and Assets

True

json for all entries, actual extension of a file for assets

file.size

Entries and Assets

True

1 for all entries, actual file size for assets

modified.date

All entities

True

UpdatedAt

Last modified date and time of the requested entity.

name.displayName

All entities

True

Name

The name of the requested entity.

name.systemName

All entities

False (update this decorator to rename entity or change file’s extension)

Id

The id of the requested entity.

parent.id

All entities

True

The XDIP of the parent entity.

3.6. Dropbox

Dropbox is a modern workspace designed to reduce busywork—so you can focus on the things that matter.

Version(s): we support the latest version of Dropbox.

3.6.1. Configuration

The configuration for the Dropbox connector consists only of an API token.

Configuration parameters:
Parameter Description

token

A Dropbox API token.

To generate a token, visit https://www.dropbox.com/developers/apps and click Create app.

Select the Dropbox API (the Dropbox Business API is not supported by this connector), the type of access, enter a name and click Create app.

You can now get a token by clicking Generate under "Generated access token".

Example Configuration:
{
  "configurationType": "Dropbox",
  "config" : {
    "token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw=="
  }
}

3.6.2. Named Queries

This connector supports Named Queries.

Due to the underlying Dropbox query API, the expected format for the template field in a named query configuration consists of the serialized version of a JSON structure. Furthermore, the format of the structure depends on whether searching for file names and content, or metadata properties.

Searching for file names and content

When searching over file names and content, the following format should be used:

Example Filename and Content Dropbox Query
{
  "path" : "/targetFolder",
  "query" : "${q_file_name}",
  "mode" : "filename"
}
Filename and Content Dropbox Query fields
Field Description

path

The root of the search operation, omit, leave empty or null for full repo search

query

The text to search for in the context given by mode

mode

The contexts of this search as a comma separated list: filename, filename_and_content, deleted_filename
the filename_and_content mode option is only available to business accounts.

The resulting query configuration for the Dropbox query above is therefore:

Example Dropbox Named Query Configuration
{
  "name" : "myQuery",
  "template" : "{\"path\":\"/targetFolder\",\"query\":\"${q_file_name}\",\"mode\":\"filename\"}"
}
Searching for metadata properties

When searching over custom metadata properties, the following format should be used:

Example Metadata Properties Dropbox Query
{
  "queries" : [ {
    "query" : "${q_property_value}",
    "mode" : {
      "field_name" : "myProperty",
      ".tag" : "field_name"
    },
    "logical_operator" : "or_operator"
  } ],
  "mode" : "properties",
  "template_filter" : "filter_none"
}
Metadata Properties Dropbox Query fields
Field Description

template_filter

List of template ids to restrict the search.

queries

List of matchers for a given property, see next table.

mode

The contexts of this search: the constant properties
Dropbox Property Matcher fields
Field Description

query

Term to search for in the property value.

logical_operator

The logical way this predicate is joined with other condition to determine the match.

mode

Describes the match: currently the .tag field must be "field_name", and the field_name field contains the metadata property name to match.

The resulting query configuration for the metadata properties query above is therefore:

Example Dropbox Named Query Configuration
{
  "name" : "myQuery",
  "template" : "{\"queries\":[{\"query\":\"${q_property_value}\",\"mode\":{\"field_name\":\"myProperty\",\".tag\":\"field_name\"},\"logical_operator\":\"or_operator\"}],\"mode\":\"properties\",\"template_filter\":\"filter_none\"}"
}

For an extended explanation of the options and limitations of the Dropbox query (aka "search") API, please consult the official documentation at https://www.dropbox.com/developers/documentation/http/documentation.

3.6.3. Features and Limitations

This connector has the following limitations:

  • The Dropbox Business API is not supported by this connector.

  • The maximum number of file versions that can be returned is 100.

  • Some endpoints, like /entities with metadata scope, are unavailable when using a Dropbox App with permission/access type "App Folder". Dropbox unfortunately does not give access to the necessary endpoints for these kind of apps.

  • Querying for " (double quotes) never yields results.

  • Querying for metadata properties only returns files which are not deleted.

  • Full text search on the /search endpoint is only supported for Dropbox Business accounts. For other accounts it will only search the file names.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.6.4. Mappings

These are the decorators set for certain types in Dropbox. Like on a regular filesystem, an entity can be of kind File or Folder.

Dropbox mappings
Decorator Used By Field in Dropbox Description

container.hasChildren

Folder

This decorator is only set for folders, and hasChildren is always true.

contentType.displayName

File, Folder

This value is set to FolderMetadata for folders and to FileMetadata for files.

contentType.systemName

File, Folder

This value is set to FolderMetadata for folders and to FileMetadata for files.

created

description

file.rawExtension

File

name

The extension of the file, or an empty string if it has none. Computed from the file name.

file.extension

File

name

The sanitized extension of the file. Computed from the file name.

file.size

File

size

The size in bytes of the file.

fileSystem.path

File, Folder

path_display

The path to the file or folder relative to the Dropbox root.

hash.md5

hash.sha1

hash.sha256

File

content_hash

The sha256 hash of the requested file.

language

mimeType.type

File

The mime type of the requested file, based on the extension. If the extension is unknown this is set to application/octet-stream.

modified.date

File

server_modified

Contains the last modified date of the requested file, converted to the current time zone.

modified.by

name.displayName

File, Folder

name

The name of the file or folder.

name.systemName

File, Folder

name

The name of the file or folder.

parent.id

File, Folder

path_display

The XDIP of the parent entity. Computed from the display path of the entity.

preview

version

File

rev

The revision number of the file.

3.7. Drupal

Drupal is an open source platform for building amazing digital experiences. It’s made by a dedicated community. Anyone can use it, and it will always be free.

Version(s): we support version 9 of Drupal.

3.7.1. Preqrequisites in Drupal system configuration

In order to enable translation support for Drupal, the next steps have to be followed:

To connect to Drupal, we need to have the following modules installed. You can install these under Manage → Extend.

  • Http Basic Authentication Module

  • JSON:API Module

  • Serialization Module

In addition, permissions for users will have to be modified. You can find the user permissions under Manage → People → Permissions.

  • To use the connector, your user must have the View published content permission. To also see unpublished content authored by your own user, you also need the View own unpublished content permission. To see any unpublished content by any user, you need either the Administrator role or the Bypass content access control permission.

  • If the user does not have the correct permission to retrieve the information of a Node, it could be that no data is returned with an HTTP OK 200 response.

Furthermore, to support write-operation, you need to configure the JSON API to allow such operations. You can configure this at Manage → Configuration → Web Services → JSON:API and then check Accept all JSON:API create, read, update, and delete operations.

Translation prerequisites

In order to enable the translation support with drupal the next steps have to be followed.

  • Install JSON:API Translation module under Manage → Extend → Core(Experimental).

  • To support the translation relation type, you need to have set up Drupal for translation management as well. This requires the content translation and language modules. Furthermore, the supported languages in Drupal needs to be configured at configuration → languages.

  • The types of content supporting translation need to be configured as well at configuration → content language and translation. In order to translate articles and web-pages, the box content needs to be ticked in this window.

Making use of the translation features when the JSON:API Translation module has not been successfully installed can result in undesired effects. This module allows recognizing the translations of a node, without it, any modifications might be applied to the default node as an undesired result. That is why it is advised thoroughly to follow all the steps described above.

3.7.2. Configuration

The Drupal connector uses basic authentication as supported by Drupal’s 'HTTP Basic Authentication module'. If you would rather configure this connector to use JWT tokens issues by your JWT module, please contact us to provide support for this in the connector.

The Drupal connector configuration consists of the following values:

Configuration parameters:
Parameter Description

username

The username of an account on Drupal.

password

The password of the account.

baseUrl

The URL to the JSON:API module of Drupal.

An example configuration for the Drupal connector would be:

Example Configuration:
{
  "configurationType": "Drupal",
  "config" : {
    "username" : "username",
    "password" : "password",
    "baseUrl" : "https://my-drupal-website:8084/jsonapi"
  }
}

3.7.3. Features and Limitations

  • On the contents endpoint, we expose a JSON structure of the body field and fields starting with the system name field_. A custom field might contain only system information, such as for a custom field of type comment. See at the bottom of this section an example of these contents. The same JSON structure can be used to update content. If a value of a field in this JSON structure is set to null, it will be ignored by Drupal.

  • Currently, the connector does not expose attachments nor images yet.

  • The maximum limit used in pagination is 50.

  • The workflow.status.normalized decorator field will expose PUBLISHED if there is at least one revision of the node that is published, even when there is a newer DRAFT revision. This is a limitation of the Drupal API.

Translation support for this connector is limited due to a number of bugs in Drupal. The following limitations have been recorded:

  • Currently, it is only possible to create translations on published nodes. Creating translations of a draft node is not supported by Drupal at this moment.

  • Currently, it is only possible to update translation nodes when they and their original node are published.

  • Currently, only the title, status and contents of translation nodes can be updated. For original nodes, the title, status, language and contents can be updated. Changing the language of an original node will result in not being able to alter it again as the node can not be reached anymore due to a bug in the Drupal core API.

  • Currently, you can not yet delete an existing translation due to a bug in Drupal translation API.

  • For original languages, the API currently only exposes the latest published version of that node. If there is no latest published version, it will show the latest draft version instead. For non-original translations of a node, the API will also only expose the latest published version of that translation. If there is no latest published version of a translation, it will not expose the translation at all using the translation_all_* on the original node. Furthermore, direct retrieval of the translation using the language query parameter will result in the original language node being returned. Therefore it might seem that your entity is already published, but a previous version or other translation of that entity is shown instead. Be extra careful by looking at which language and what status of the entity is returned.

Example contents of a 'recipe'
{
    "body": {
        "value": "<p>Pita bread with shawarma and optional ingredients.</p>\r\n",
        "format": "basic_html",
        "processed": "<p>Pita bread with shawarma and optional ingredients.</p>",
        "summary": ""
    },
    "field_subtitle": "Middle-eastern meat dish",
    "field_duration": 15,
    "field_instructions": {
        "value": "<ul>\r\n\t<li>Cook shawarma</li>\r\n\t<li>Heat pita bread</li>\r\n\t<li>Put cooked shawarma in pita bread with optional ingredients (lettuce, garlic sauce, cheese)</li>\r\n</ul>\r\n",
        "format": "basic_html",
        "processed": "<ul><li>Cook shawarma</li>\n\t<li>Heat pita bread</li>\n\t<li>Put cooked shawarma in pita bread with optional ingredients (lettuce, garlic sauce, cheese)</li>\n</ul>"
    },
    "field_recipe_comments": {
        "status": 2,
        "cid": 4,
        "last_comment_timestamp": 1601458996,
        "last_comment_name": "",
        "last_comment_uid": 1,
        "comment_count": 1
    }
}
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

translation_all_entity translation_all_reference

3.7.4. Mappings

Drupal mappings
Decorator Used By Field in Drupal Description

container.hasChildren

NodeType

Whether the entity can have path relation children. Always true for NodeType. Never present for any other Node.

contentType.systemName

Node

type

The type of the node.

contentType.systemName

NodeType

attributes.drupal_internal__type

The internal name for the node type.

created.date

Node

attributes.created

Contains the creation date of the requested node.

created.by.systemName

Node

relationships.uid.data.id

The ID of the user that created this node.

description.short

NodeType

attributes.description

The description of the node type.

file.size

Node

attributes.body.processed

Contains the amount of bytes that would be returned in the contents call.

language.tag

All entities

attributes.language

The language of the node (type).

name.displayName

Node

attributes.title

The title of the node.

name.displayName

NodeType

attributes.name

The name of the node type.

name.systemName

Node

id

The ID of the node.

name.systemName

NodeType

attributes.drupal_internal__type

The internal name of the node type.

mimeType.type

Node

Present when the node contains content (a attributes.body field and/or fields starting with attributes.field_). This will always be application/json.

modified.date

Node

attributes.changed

Contains the last modified date of the requested node.

modified.by.systemName

Node

relationships.revision_uid.data.id

The ID of the user that last modified this node.

parent.id

All entities

The parent XDIP. In the case of a Node, this will be the node’s NodeType. In the case of nodeType, this will be root.

workflow

All entities

attributes.moderation_state

Whether the node (type) is published/visible.

3.8. Egnyte

Go beyond secure file sharing with a solution that helps businesses work better and safer on any device, from anywhere, and with any app they choose.

Version(s): we support the latest online version of Egnyte.

3.8.1. Configuration

Before you can start using the Egnyte connector, you will need to setup an Egnyte domain and request an API token for that domain:

  1. Register an Egnyte account if you don’t have one yet.

  2. Register an Egnyte developer account here if you don’t have one yet (use the domain from the step 1 and set your application as "Internal").

  3. Once the API key has been approved by Egnyte, authenticate it with the domain from step 1. The approval may take some time as they approve the API keys manually.

The configuration consists of both an Egnyte access token and the URL of your domain.

Configuration parameters:
Parameter Description

address

The base URL of the Egnyte instance.

token

An Egnyte OAuth2 token.
Example Configuration:
{
  "configurationType": "Egnyte",
  "config" : {
    "address" : "https://example.egnyte.com",
    "token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw=="
  }
}
Getting your token

To get your access token you make a curl request like this:

curl -X POST \
    -d grant_type=password  \
    -d username="<your-egnyte-username>" \                                        (1)
    -d password="<your-egnyte-password>" \                                        (2)
    -d client_id="<your-client-id>" \                                             (3)
    https://<your-domain>.egnyte.com/puboauth/token                               (4)
1 Set username of an administrator account of your Egnyte domain
2 Set password of the administrator account that you use
3 Set client_id to the API key that was approved by Egnyte
4 Set domain to the domain name that you use for your Egnyte service

On success, this returns:

{
  "access_token": "68zc95e3xv954u6k3hbnma3q",
  "token_type": "bearer",
  "expires_in": -1
}

The access_token can now be used in the connector configuration.

For more information and possible errors see Egnyte’s manual.

3.8.2. Features and Limitations

  • Note that by default all API keys are set to 2 queries per second and a 1000 call daily limit. This is a per user per domain limit that Egnyte imposes.

  • A 403 - FORBIDDEN HTTP response code can be caused by either a wrong access token or a wrong domain name that does exist.

  • When deleting a file or folder it will be moved to the "Trash" from where it will be permanently deleted after one month.

Rate Limiting

Egnyte has an aggressive rate limit where you can only do two requests per token per second. Xillio API retries the request after one second when encountering rate limit errors for a maximum of five times. We do this for all operations except for operations containing binary data (Create a New Entity With Contents and Update an Entity's Contents).

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_parents_entity version_parents_reference

version_children_entity version_children_reference

version_all_entity version_all_reference

translation

3.8.3. Mappings

Egnyte Mappings
Decorator Used By Field in Egnyte Description

container.hasChildren

Folder

Whether the entity has children.

contentType

created.date

created.by

description

file.rawExtension

File

Computed from name

file.extension

File

Computed from name

file.size

File

size

The size of the file in bytes.

fileSystem.path

All entities

path

The path in the Egnyte domain that the entity can be found at.

hash.md5

hash.sha1

hash.sha256

language

mimeType.type

File

The mime type of the requested file, based on the extension. If the extension is unknown, this is set to application/octet-stream.

modified.date

All entities

last_modified / lastModified

The date and time the file or folder was last modified.

modified.by

All entities

uploaded_by

The user who last modified the entity.

name

All entities

name

The name of the entity as used in Egnyte.

parent.id

All entities

Computed from path

preview

version

File

entry_id

The version id of the file.

3.9. Episerver10

Episerver is a solution that enables you to manage content and campaigns in one screen.

Version(s): we support version 10 of Episerver.

3.9.1. Configuration

To configure Episerver you need the following:

Configuration parameters:
Parameter Description

baseUrl

The URL of the Episerver instance.

username

The username of an account on Episerver.

password

The password of the account.

token

An Episerver OAuth2 token.

A token lasts 5 minutes after which a new one will be requested.

Optional if supplying a username and password.
The baseUrl value needs to end with /episerverapi.
Example Configuration:
{
  "configurationType": "Episerver10",
  "config" : {
    "baseUrl" : "http://my-domain.com:49700/episerverapi",
    "username" : "username",
    "password" : "password"
  }
}
Episerver Service Extension

To allow communication with your Episerver instance, a Xillio API service extension is required. In the next section you are guided through the installation of that extension.

Setup
Prerequisites

In order for the Xillio Episerver extension to work some conditions need to be met:

  1. A working Episerver instance must be available.

  2. The EPiServer.ServiceApi NuGet package should be installed from the Episerver NuGet feed. For more infomation visit: Adding the Episerver NuGet feed.

  3. The command update-epidatabase should be ran in the Package Manager console.

Installing the extension by adding the source

The extension can be added to the Episerver by creating a new reference to the extension source code. By completing the following steps you can add this reference.

  1. Clone/Download the extension source code, which can be found at https://github.com/xillio/ServiceAPIExtensions, to your system.

  2. Open the solution for your Episerver site in Visual Studio.

  3. Right-click the Episerver site and select 'Add > Existing Item…​'.

  4. In the file browser dialog, search for the source code. Add the ContentApiController.cs file.

  5. Add app.UseServiceApiIdentityTokenAuthorization<ApplicationUserManager<ApplicationUser>, ApplicationUser>(); to the Startup.cs.

  6. Build the solution ([Ctrl+Shift+B]). Once the build succeeds the Episerver can be started. Go to {episerver-address}/episerver to verify that it is running.

  7. Once logged in with your admin credentials you can go to CMS > Admin > Config > Permissions for functions. In here you have to allow users to use the EpiserverServiceApi and all of its functions. (Not permitting a user means that some functionality can’t be accessed).

  8. Now the extension is ready to be used with the Xillio API.

3.9.2. Features and Limitations

Data Hierarchy

The data hierarchy of the Episerver CMS is as follows:

  • Pages have pages as parent.

  • Files have folders or pages as parents.

  • Folders have other folders or pages as parent.

  • Blocks have folders as parents.

  • The children of a page contain child pages, referenced blocks and content.

  • The children of a folder contain the folders, files and blocks that are inside the folder.

  • Blocks and files have no children.

  • Pages and Blocks can exist in multiple languages.

Content Type Children Parent Translations

Block

Folder

File

Folder, Page

Folder

Block, File, Folder

Folder, Page

Page

Block, File, Folder, Page

Page

Supported Content Types

The only types that are supported are types that fall into the following categories.

Pages

All kinds of page types. For more info on pages visit Episerver documentation.
When a request is made for the content of a page. The response will return all fields of the page as a JSON.

Example Response
{
  "Name": "Whitepaper",
  "ParentLink": "9",
  "ContentGuid": "ee643f9d-a5c4-4013-a76f-dbfd73190121",
  "ContentLink": "12",
  "ContentTypeID": 23,
  "__EpiserverContentType": "StandardPage",
  "__EpiserverBaseContentType": "Page",
  "__EpiserverAvailableLanguages": [
    "en",
    "nl-NL"
  ],
  "__EpiserverDefaultLanguage": "en",
  "__EpiserverCurrentLanguage": "nl-NL",
  "PageLink": "12",
  "PageTypeID": 23,
  "PageParentLink": "9",
  "PagePendingPublish": false,
  "PageWorkStatus": 4,
  "PageDeleted": false,
  "PageSaved": "2017-08-25T16:38:12+02:00",
  "PageTypeName": "StandardPage",
  "PageChanged": "2017-08-25T16:38:12+02:00",
  "PageCreatedBy": "",
  "PageChangedBy": "",
  "PageMasterLanguageBranch": "en",
  "PageLanguageBranch": "en",
  "PageGUID": "ee643f9d-a5c4-4013-a76f-dbfd73190121",
  "PageContentAssetsID": "2d1dca96-2f80-4576-82f1-fe403379f654",
  "PageName": "Whitepaper",
  "PageVisibleInMenu": true,
  "PageURLSegment": "download-whitepaper-alloy-track",
  "PageChildOrderRule": 1,
  "PagePeerOrder": 4,
  "PageChangedOnPublish": false,
  "PageCategory": "Track",
  "PageStartPublish": "2012-09-13T16:04:17+02:00",
  "PageCreated": "2012-09-13T16:04:17+02:00",
  "PageShortcutType": 0,
  "PageLinkURL": "/link/ee643f9da5c44013a76fdbfd73190121.aspx",
  "MetaTitle": "Alloy Track Whitepaper",
  "PageImage": "83",
  "MetaKeywords": [
    "Alloy Track Whitepaper",
    "Online project tracking"
  ],
  "TeaserText": "Explore the opportunities that exist for keeping your projects on track.",
  "MetaDescription": "Making sure that your project is on-track.",
  "MainBody": "<p><img style=\"float: left;\" src=\"/link/3864e90c32b642f6bd523992a49c9f30.png\" alt=\"Download Whitepaper Alloy Track\" width=\"300\" height=\"205\" />Learn from the experiences of our many customers who have contributed to this whitepaper.</p>\n<p>Projects have a natural lifecycle with well-defined stages. Progress  monitoring is a critical part of making sure that your project is  on-track and capable of delivering in the end.</p>\n<p>From start-up meetings to final sign-off, we have the solutions for  today's market-driven needs. Leverage your assets to the fullest through  the combination of Alloy Plan, Alloy Meet and Alloy Track.</p>",
  "MainContentArea": [
    85
  ]
}

The same applies for creating and updating content on a page.

Blocks

All kinds of block types. For more info on blocks visit Episerver documentation.
When a request is made for the content of a block. The response will return all fields in the block as a JSON object.

Example Response
{
  "Name": "Alloy Meet jumbotron",
  "ParentLink": "50",
  "ContentGuid": "18d75471-54fc-462f-9114-e745a8ea6127",
  "ContentLink": "51",
  "ContentTypeID": 12,
  "__EpiserverContentType": "JumbotronBlock",
  "__EpiserverBaseContentType": "Block",
  "__EpiserverAvailableLanguages": [
    "en"
  ],
  "__EpiserverDefaultLanguage": "en",
  "__EpiserverCurrentLanguage": "en",
  "Image": "150",
  "ImageDescription": "Some happy people cheering",
  "Heading": "Wherever you meet!",
  "SubHeading": "Alloy solves the two most pressing problems in long distance collaboration – better communication and better project management ",
  "ButtonText": "Read more",
  "ButtonLink": "/link/33b0aa1ca429426c8d05d97d6cbd7f7a.aspx"
}

The same applies for creating and updating content in a block.

Folders

Only the basic CMS folder is supported.

Files

All file and media types are supported.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

translation_all_entity translation_all_reference

3.9.3. Mappings

These are the decorators that are set for Episerver.

Episerver Mappings
Decorator Used By Episerver property Description

container.hasChildren

All entities

Page, Folder

Whether the entity has children or not.

contentType.displayName

All entities

ContentType

The content type returned by Episerver.

contentType.systemName

All entities

ContentType

The content type returned by Episerver.

created.date

Page

PageCreated

The time the page was created in ISO UTC format.

created.by

Page

PageCreatedBy

The user that created the page.

description

Page

MetaDescription

The description of a page.

file.rawExtension

File

Computed from the name of the file.

The extension of the file.

file.extension

File

Computed from the rawExtension.

The sanitized extension of the file.

file.size

File

FileSize

The size of the file in bytes.

fileSystem.path

hash.md5

hash.sha1

hash.sha256

File

sha256

The sha256 hash of the file.

language.tag

Page, Block

The language tag of the requested page or block.

language.translationOf

Page, Block

The master language of the page or block.

mimeType.type

File

MimeType

The mime type of the requested file, based on the extension. If the extension is unknown this is set to application/octet-stream.

modified.date

Page

PageSaved

The time the page was last modified in ISO UTC format.

modified.by

Page

PageChangedBy

The user that last modified the page.

name.displayName

All entities

Page: The "MetaTitle" of the page. Folder, Block and File: The "Name" of the object.

The human readable name of the entity.

name.systemName

All entities

Name

The name of the object as used in the Episerver backend.

parent.id

All entities

Computed using ParentLink

The XDIP of the parent entity.

preview

version

3.10. IBM FileNet

IBM FileNet Content Manager is a document management engine for enterprise content, security and storage features plus process management capabilities.

The FileNet connector allows connecting to an object store of the FileNet Content Engine and manipulate its folders and documents.

Version(s): we support version 5.2.X of FileNet.

3.10.1. Configuration

The FileNet connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The URL of the FileNet server API extension.

username

The username of an account on Filenet.

password

The password of the account.

objectstore

The name of the object store to which to connect.

stanza

The communication protocol to use.

If not sure about what value to use for stanza, leave empty, the Web Service Interface will be used by default.

Default: FileNetP8WSI

A configuration allows access to a single object store only.

Example Configuration:
{
  "configurationType": "Filenet",
  "config" : {
    "baseUrl" : "http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM",
    "username" : "username",
    "password" : "password",
    "objectstore" : "objectstore"
  }
}

3.10.2. Features and Limitations

The FileNet connector supports two types of content: documents and folders.

Multiple parents of a document

FileNet supports documents (not folders) to have multiple parents at the same time. The Xillio API entity endpoint is not capable of this at the moment and our FileNet connector will always return only one parent of the document. This will be always the parent with lowest FileNet

Although the FileNet connector cannot deliver multiple parents of a document, it allows to add or remove additional parents. The following table shows how to add, remove or update parent reference of the document with FileNet connector.

The complete document parent list can be accessed using the metadata scope.

FileNet connector parent reference updates
Action Parent in "original" section Parent in "modified" section

Move document

Add new parent link

Remove parent link

You can remove all the parent links of a document in this way.

There is no support for multiple parents for folders in FileNet. So in case of a folder the parent in the "original" section of the update entity request is ignored and the folder can only be moved to the new folder defined by the parent.id in the "modified" section of the update entity request.

ID-based identification of the entities

Our FileNet connector is using FileNet internal IDs as a part of the entity’s XDIP. This allows multiple documents in the same folder to have the same name just like in FileNet itself. Similarly the names of subfolders of a certain folder need to be unique as this is a limitation of FileNet.

Be aware that Filenet assigns different IDs to different versions of a document and that uploading new content for a document with the Xillio API creates a new version of that document. Therefore we recommend that you get the ID of the latest version of a document after uploading new content before you continue working with it. To get the ID of the latest version you might request the versions or list of versions of that entity and get the latest version from there including its ID.

Keep in mind that deleting a specific version of an entity will use the ID in the xdip to remove it.

You can still use the parameter in an XDIP to reference other versions of the document. Assume for example that AAA is the ID of version 1.0 of a document and BBB is the ID of version 2.0 of that document. You can request an entity xdip://{configuration ID}/AAA?version=2.0 and you will get the metadata of version 2.0 as if you would request xdip://{configuration ID}/BBB. Also requesting xdip://{configuration ID}/AAA?scope=versions returns the same result as a request for xdip://{configuration ID}/BBB?scope=versions.

Documents with no parent folder

FileNet allows documents to have no parent folder. Such a document is not shown using IBM Filenet Navigator UI, but it can still be found through the "Search" function. Similarly, with our connector if you know the ID of the document you can do all the common operations on the document using its ID, but you will never get this document iterating over the files and folders in the object store.

Metadata of such a document won’t contain the parent decorator to indicate that there is no parent folder assigned to this document in FileNet.

Documents in the root of the object store

Though the IBM Filenet Navigator UI is not showing any documents in the root of the object store it is possible to create, update and delete such documents and our FileNet connector allows these operations.

Querying documents and folders

This connector supports Named Queries.

The Content Engine supports an SQL-92-like query language. Check IBM Filenet Documentation

For example, the following query will return documents added in the last three days:

{
	"name" : "created_in_3_days",
	"template" : "SELECT * FROM Document WHERE DateCreated > Now() - TimeSpan(3, 'Days')"
}

It is possible to query for documents by the values of their properties, as defined in the templates assigned to them. Use the Symbolic name of the property in query predicates.

Let’s assume TestNumber is the Symbolic name of a property inherited by your documents, then the following query will find documents with a specific value for it:

{
	"name" : "test_number",
	"template" : "SELECT * FROM Document WHERE TestNumber = ${q_myvariable}"
}
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.10.3. Mappings

The FileNet connector supports two types of entities: documents and folders. This connector does not specify which fields from FileNet are mapped to the decorators since the FileNet API extension defines these fields itself.

FileNet connector mappings
Decorator Used By Description

container.hasChildren

Folder

This decorator is only set for folders and hasChildren is always true for them.

contentType.displayName

Document, Folder

This value is set to FilenetFolder for folders and to FilenetDocument for documents.

contentType.systemName

Document, Folder

This value is set to FilenetFolder for folders and to FilenetDocument for documents.

created.date

Document, Folder

Date and time when the requested entity was created.

created.by

Document, Folder

Name of the user that created the requested entity.

file.rawExtension

Document

The extension of the document or an empty string if it has none.

file.extension

Document

The sanitized extension of the document.

file.size

Document

The size in bytes of the document.

fileSystem.path

Document, Folder

The path through the entity’s parent to this resource.

mimeType.type

Document

The mime type as supplied by FileNet.

modified.date

Document, Folder

Last modified date and time of the requested entity.

modified.by

Document, Folder

Name of the user that modified the requested entity last.

name.displayName

Document, Folder

The name of the requested entity. Always the same as name.systemName.

name.systemName

Document, Folder

The name of the requested entity.

parent.id

Document, Folder

The XDIP of the parent entity. See the Multiple parents of a document section for more details.

version

Document

The version number of the document.

3.11. GitLab

GitLab provides a Git-like experience while providing CI and many more perks to developer teams.

Version(s): we support version 4 of the GitLab API on GitLab 11.1.0 and newer.

3.11.1. Configuration

The GitLab connector gives access to a single GitLab git repository per configuration. A repository is identified by its GitLab project ID. The GitLab connector uses Personal Access Tokens or the OAuth2 web flow for authentication. For more information refer to Get a GitLab OAuth2 Refresh Token or the GitLab Documentation.

Using a Personal Access Token

  1. Navigate to the GitLab user settings

  2. Click Access Tokens

  3. Enter a name for your token

  4. Select the api scope

  5. Click Create personal access token

  6. Copy the personal access token to your Xillio API configuration’s token field

Using OAuth
Create a GitLab application

This section describes creating a GitLab application for the Xillio API. This step only has to be done once, even if multiple GitLab configurations are created.

  1. Navigate to the GitLab user settings

  2. Open the Applications tab

  3. Add a new application with a redirect URI that can handle OAuth code callbacks (this could be your own web application or https://localhost for testing purposes) and the api scope only

When requesting an OAuth2 authorization code, GitLab will return a redirect to the redirect URI with the code request parameter containing the authorization code. This should normally be handled by your own web application. However, using https://localhost as a redirect URI can be helpful for testing since the authorization code can simply be copied from the browser manually and used to request a refresh token.
Get a GitLab OAuth2 Refresh Token

This section describes getting an OAuth2 refresh token to create a GitLab connector configuration. This step has to be repeated for each GitLab connector configuration created.

Direct the GitLab user with access to the GitLab projects that need to be exposed by the Xillio API to the following URL where they will have to enter their GitLab credentials:

 https://gitlab.com/oauth/authorize? (1)
    response_type=code
    client_id=<your-application-id>& (2)
    redirect_uri=<your-redirect-uri> (3)
1 This endpoint handles authorization code requests. Replace gitlab.com with the hostname of your GitLab instance, if not using the GitLab cloud solution.
2 Set client_id to the GitLab application ID from Create a GitLab application.
3 Set redirect_uri to the redirect URI specified in Create a GitLab application.

GitLab will respond with a redirect to the specified redirect URI. The code request parameter contains the authorization code. If the redirect URI points to your own application, handle this request and continue with the following step. Otherwise, copy the authorization code and use it in the following step.

Request a refresh token:

curl -X POST https://gitlab.com/oauth/token \      (1)
    -d grant_type=authorization_code \
    -d client_id="<your-application-id>" \         (2)
    -d client_secret="<your-application-secret>" \ (3)
    -d redirect_uri="<your-redirect-uri>" \        (4)
    -d code="<your-code>"                          (5)
1 This endpoint handles OAuth2 token requests. Replace gitlab.com with the hostname of your GitLab instance, if not using the GitLab cloud solution.
2 Set client_id to the GitLab application ID from Create a GitLab application.
3 Set client_secret to the GitLab application secret from Create a GitLab application.
4 Set redirect_uri to the redirect URI specified in Create a GitLab application.
5 Set code to the authorization code from the previous request.
Connector Configuration

The GitLab connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL to the GitLab instance.

Default: https://gitlab.com

clientId

The GitLab application client id. Required when refreshToken is set.

clientSecret

The GitLab application secret. Required when refreshToken is set.

token

A GitLab personal access token, or a GitLab OAuth2 token.

When set, refreshToken, clientId and clientSecret are not required.

refreshToken

An OAuth2 refresh token.

See Get a GitLab OAuth2 Refresh Token for information on acquiring a refresh token.

projectId

The id of the GitLab project.

It can be specified either by name (e.g. MyUser/MyProject or MyOrganization/MyProject) or by a numeric identifier (e.g. 10262206), which can be found on the main page of the project.
Example Configuration:
{
  "configurationType": "GitLab",
  "config" : {
    "clientId" : "client-id",
    "clientSecret" : "client-secret",
    "refreshToken" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
    "projectId" : "MyGroup/MyProject"
  }
}

3.11.2. Features and Limitations

  • This connector supports read and write operations on folders and files.

  • This connector supports only read operations on branches.

  • The path relation of this connector returns different kinds of entities depending on the level of children:

    • branches for the children of the root,

    • files and folders on subsequent levels.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

3.11.3. Mappings

GitLab mappings
Decorator Used By Field in GitLab Description

container.hasChildren

Branch, Folder

Whether the entity can have path relation children. Always true for branches and folders.

file.rawExtension

File

Computed from file_name

The extension of the file.

file.extension

File

Computed from file_name

The extension of the file.

file.size

File

size

The size of the file in bytes.

fileSystem

Folder, File

file_path

The absolute path from the root of the repository to the entity.

hash.sha256

File

content_sha256

The sha256 hash of the file.

mimeType.type

File

The mime type of the requested file, based on the extension. If the extension is unknown, this is set to application/octet-stream.

modified.date

Branch, File

committed_date

The date of the last modifying commit for files. The date of the last commit for branches.

modified.by

Branch, File

author_name and author_email

The name and e-mail of the author. Git also has a concept of committer, which is not represented by the GitLab connector.

name.displayName

Branch, Folder, File

file_name

The file name, including extension.

name.systemName

Branch, Folder, File

file_name

The file name, including extension.

parent.id

Branch, Folder, File

The ID of the connector configuration for branches, the ID of the branch for root level files and folders, the ID of the parent folder otherwise.

version

Branch, Folder, File

commit_id

The commitId of the HEAD of the requested branch.

3.12. Google Drive

Google Drive provides cloud storage and file backup.

Version(s): we support the latest version of Google Drive.

3.12.1. Configuration

Google Drive uses OAuth2 to secure the web api. This means you will need an app which you can use to generate access tokens.

Create an API app

To set up the Google Drive connector you need a Google API app.

  1. If you don’t have a google developer project, create one.

  2. Search for 'Google Drive API' in the API-Library.

  3. Enable 'Google Drive API'.

  4. Open the OAuth Consent screen.

  5. Set a 'Product name'. This is the name that shows up when you try to authenticate a user.

  6. Open the Credentials overview.

  7. Create a new 'OAuth Client ID' and select 'Other client'.

Get a Refresh Token

The refresh token allows Xillio API to receive a new access token automatically after the current one has expired. To get your initial refresh token, you have to go through the OAuth code flow of Google. You will need the details of the API app you created in the previous step.

Enter the following URL in your browser:

https://accounts.google.com/o/oauth2/v2/auth                        (1)
    ?response_type=code                                             (2)
    &redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob               (3)
    &client_id=<your-client-id>                                     (4)
    &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive          (5)
    &access_type=offline                                            (6)
If you decide to use any outer redirect_uri, you should add it to your application first. Otherwise, an attempt of receiving a refresh token will fail. To add your custom redirect_uri, go to Credentials screen, select your application and add your uri to the Authorized redirect URIs
1 https://accounts.google.com/o/oauth2/v2/auth is the main authentication endpoint
2 The response_type can be set to either code, which provides a code that can be used to get a new token, or token, which will return a short-lived token. As you need a refresh token, use the value code.
3 Set the redirect_uri to the uri to which the user should return after authorization. If you don’t have a redirect uri you can use, use urn:ietf:wg:oauth:2.0:oob to prompt the user to manually copy the code.
4 Enter here the client ID of your registered app. You can find your client_id in Credentials overview.
5 The https://www.googleapis.com/auth/drive scope is required to manipulate and inspect files in the user’s drive.
6 The access_type value offline is required to make Google API return you a refresh token. With refresh token Xillio API can later renew access tokens automatically for you. If you omit this parameter, you will receive only access token. Access token is typically only for 1 hour and you will have to renew it later manually.

The browser will ask you to select a Google account that you want to connect to and to authorize the access to your data. After approving the access you will be redirected to redirect_uri you have specified and the URL. It doesn’t matter if there is no content on that URL. You only need to check the URL you were redirected to. It will contain a query parameter code. You need to get that code. You will exchange it for token during the next step.

Make a Google OAuth endpoint POST request like this one

curl -X POST https://www.googleapis.com/oauth2/v4/token \
    -d grant_type=authorization_code \
    -d redirect_uri="urn:ietf:wg:oauth:2.0:oob" \         (1)
    -d client_id="<your-client-id>" \                     (2)
    -d client_secret="<your-client-secret>" \             (3)
    -d code="<your-code>"                                 (4)
1 The redirect_uri must be set to the same URI as you used earlier to request the code.
2 You can find your client_id in your Credentials overview.
3 You can find your client_secret in your Credentials overview.
4 Insert the code you got from the URL at the end of the previous step.

You should get a response like this:

{
    "access_token": "<< ACCESS_TOKEN >>",
    "expires_in": 3599,
    "refresh_token": "<< REFRESH_TOKEN >>",
    "scope": "https://www.googleapis.com/auth/drive",
    "token_type": "Bearer"
}

The value refresh_token is what you will need later when setting up a configuration to access the Google Drive you have selected during this flow.

Connector Configuration

The connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the Google Drive API.

Default: https://www.googleapis.com

oauthUrl

The token URL of the Google authorization server.

Default: https://www.googleapis.com/oauth2/v4/token

clientId

The Google Drive application client id. Required when refreshToken is set.

clientSecret

The Google Drive application secret. Required when refreshToken is set.

token

A Google Drive OAuth2 token.

When set, refreshToken, clientId and clientSecret are not required. It can be useful for testing, or if your application handles refreshing tokens.

refreshToken

An OAuth2 refresh token.

See Get a Refresh Token for information on acquiring a refresh token.

mimeTypeMapping

It is not possible to download the Google Docs format via Xillio API directly.

The mimeTypeMapping field is required to make the downloading and exporting the content of the Google Docs format files possible by converting it into any other compatible format.

The mimeTypeMapping field is an another JSON object. So, it can be either null or have the standard JSON structure like:

{
    "application/vnd.google-apps.document": "text/plain",
    "application/vnd.google-apps.spreadsheet": "text/csv"
}

The key must be a googleMimeType and value is an exportMimeType

If the googleMimeType will not be compatible with exportMimeType, e.g.

{
    "application/vnd.google-apps.document": "image/jpeg",
    ...
}

what means you are trying to export a document format as a JPG image, you will get an error

{
    "errorId": "27d9e2d0-0336-4ead-ad8f-a5348532426e",
    "message": "Export Mime Type [image/jpeg] not supported by [application/vnd.google-apps.document]",
    "error": "Bad Request",
    "status": 400,
    "timestamp": "2021-11-25T14:19:36.891+01:00",
    "errorType": "InvalidConfiguration",
    "path": "/v2/configurations",
    "parameters": {}
}

Please refer to the official Google documentation to find everything out about different mimeTypes and their compatibility.

Each Google doc format can be exported only into one format in each distinct mimeTypeMapping. If you enter several export formats for the same Google Docs format e.g.

{
    "application/vnd.google-apps.document": "text/plain",
    "application/vnd.google-apps.document": "application/rtf",
    "application/vnd.google-apps.spreadsheet": "text/csv"
}

only the last one will be used.

As were said, the mimeTypeMapping field is a JSON object but you must provide map only. You can you neither arrays nor nested objects.

If you don’t set up the mimeTypeMapping field or miss a desired format and try to download a Google Doc, you will get an error

{
    "errorId": "b2811db5-21fe-4cb7-9213-edd39c56725b",
    "message": "Configuration for googleMimeType [<missing mimeType>] not added",
    "error": "Method Not Allowed",
    "status": 405,
    "timestamp": "2021-11-25T13:52:04.415+01:00",
    "errorType": "OperationNotAllowed",
    "path": "/v2/contents/googledrive/<file-id>",
    "parameters": {}
}

By providing a refresh token, client id and client secret, the Xillio API will refresh the access token when it expires. In that case, and if the connector operation does not concern binary data, the Xillio API will then retry the request with the new access token.

{
    "id": "googledrive",
    "name": "googledrive",
    "configurationType": "GoogleDrive",
    "passthroughAuthorization": false,
    "config": {
        "clientId": "826514876365-m4hltubt3d3tvu7iu2875m5pvum0fm8l.apps.googleusercontent.com",
        "clientSecret": "BAHEfQjVAN-GVZ9IV9EPbPg_",
        "refreshToken": "4/0AX4XfWgJF1PCbNZmeNwzdJJZi0YEGlRMFGgeiqglu5H2mkt0hJe6b-Tb59YsWx6jiPrflg",
        "mimeTypeMapping": {
            "application/vnd.google-apps.document": "text/plain",
            "application/vnd.google-apps.spreadsheet": "text/csv"
        }
    }
}

If you plan to use only access token (you need one time access, or you plan refreshing the token yourself), you should create a configuration like this one

{
    "id": "googledrive",
    "name": "googledrive",
    "configurationType": "GoogleDrive",
    "passthroughAuthorization": false,
    "config": {
        "token": "ya29.a0ARrdaM_HeAbvtvsIOK2m12dbiZcyCpHnSUFv2NXVDSpdUXCUt8mPo0T5G76_qPtFZtBi38AZrISAm1VtZIIpuIADUoxBvRWDd14vGqHvpaFR7sesocJbCRVMRyEZ6zZYFcTL2GfXuyXRB4xlE1vCgiAk221O",
        "mimeTypeMapping": {
            "application/vnd.google-apps.document": "text/plain",
            "application/vnd.google-apps.spreadsheet": "text/csv"
        }
    }
}

3.12.2. Features and Limitations

Named Queries

This connector supports Named Queries. An example query configuration would be:

Example Query
{
    "name": "fileExcludingTerm",
    "template": "name = '${q_name}' and not fullText contains '${q_exclude_term}'"
}

Please consult the Google Drive API documentation for the full query syntax.

Including Google Drive special characters like ' or " in a search clause without any other characters will not yield any results.
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.12.3. Mappings

These are the decorators that are set for certain types in Google Drive.

A file is considered to have 'binary contents' when it is a file (not a folder) and it is not a Google Docs document from an application such as Google Sheets, Google Slides or Google Docs.

Google Drive mappings
Decorator Used By Field in Google Drive Description

container.hasChildren

Folder

This decorator is only set for folders, and hasChildren is always true.

contentType.displayName

File, Folder

kind

Is set to drive#file for both files and folders.

contentType.systemName

File, Folder

kind

Is set to drive#file for both files and folders.

created

File, Folder

createdTime

The created decorator is always set but only contains the date field.

description

File, Folder

description

The description decorator is directly mapped to the description field of Google Drive. It is always present.

file.rawExtension

File

fileExtension or computed from the item name.

The extension of the file, or an empty string if it has none.

file.extension

File

The sanitized extension of the file.

file.size

File

size

The size in bytes of the file.

hash.md5

File

md5Checksum

The md5 hash is set if the file contains contents (i.e. is not a Google Docs document).

mimeType.type

File

mimeType

The mime type as evaluated by Google Drive. If the mime type is unknown by Google Drive it is based on the extension. If there is no extension the mime type is application/octet-stream.

modified.date

File, Folder

modifiedTime

Contains the last modified date of the requested file, converted to the current time zone.

modified.by

File, Folder

lastModifyingUser

Contains information about the user who last modified this file or folder.

name.displayName

File, Folder

name

The human readable (or chosen) name of the file or folder.

name.systemName

File, Folder

name

The human readable (or chosen) name of the file or folder.

parent.id

File, Folder

parents

The XDIP of the parent entity.

preview

File

webViewLink

The link to the file in google drive.

version

File, Folder

version

The version number of the file or folder.

3.13. JSON RPC

This Connector allows to use third-party connector implementations running as HTTP(S) services independent of the Engine.

Along with enabling anyone to write his own connector, this architecture allows a quicker release for experimental connectors outside of the stringent quality bounds of the Engine.

For every request to the JSON RPC connector the configuration is sent to the external connector along with the request parameters and body. As a consequence the external connector can be fully stateless.

3.13.1. Configuration

The configuration of a JSON RPC connector includes just the URL of the external connector and the configuration for it. A switch is provided to allow non secure HTTPS connections for development.

Configuration parameters:
Parameter Description

baseUrl

The URL of the remote JSON RPC connector endpoint that is going to execute the requests for this configuration.

skipSslValidation

When set to true, the connector will skip validation of the trust chain when connecting to the external connector with the HTTPS protocol, allowing to use self-signed certificates.

Only for testing: should be left to false in production as it will not prevent spoofing and man in the middle attacks.

Default: false

configuration

The external JSON RPC connector configuration fields in the form a JSON object with field names as keys and field values as values.

Arrays, nested objects and null values are not supported in this configuration object.

For example, if the external JSON RPC connector needs a baseUrl and a token field, the configuration map would look as follows:

{
    "baseUrl" : "https://myhost.com/myCms",
    "token" : "mytokenforauthenticationandauthorization"
}
It is important not to confuse the baseUrl of the JSON RPC connector configuration, that points to the external connector, with the baseUrl field of the external connector configuration that points to the target system.
Example Configuration:
{
  "configurationType": "JsonRpc",
  "config" : {
    "baseUrl" : "https://customconnector.com/json-rpc",
    "configuration" : {
      "baseUrl": "https://mycms/store",
      "token":"ljdadn234wqnadnn4"
    }
  }
}

3.13.2. Features

This connector can support all features supported by the external connector it is configured to use. Please refer to the specific external connector documentation for its features and limitations.

3.14. OneDrive

OneDrive is a file hosting service, it allows users to store files as well as other personal data like Windows settings or BitLocker recovery keys in the cloud.

Version(s): we support the latest version of OneDrive.

3.14.1. Configuration

The OneDrive connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the OneDrive API.

Default: https://graph.microsoft.com/v1.0/me/drive/root

redirectUri

The URI where the user is redirected to after authorization is completed.

clientId

The OneDrive application client id. Required when refreshToken is set.

clientSecret

The OneDrive application secret. Required when refreshToken is set.

token

A OneDrive OAuth2 token.

When set, refreshToken, clientId and clientSecret are not required. It can be useful for testing, or if your application handles refreshing tokens.

refreshToken

An OAuth2 refresh token.

These values allow the OneDrive connector to authorize with OneDrive. You don’t have to provide all of these values, as this depends on the authentication flow you choose and on the way you design your application.

Example Configuration:
{
  "configurationType": "OneDrive",
  "config" : {
    "redirectUri" : "https://xillio.com/callback",
    "clientId" : "client-id",
    "clientSecret" : "client-secret",
    "refreshToken" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c"
  }
}
Your Application Refreshes the OneDrive Access Token

For this approach you will only put the access token in the Xillio API configuration and update the configuration whenever you get an authorization error later. In this case your configuration will look like this:

{
  "configurationType": "OneDrive",
  "name" : "My OneDrive",
  "config": {
    "token": "<your-token-here>"
  }
}

The Xillio API will use this token when communicating with OneDrive and you will get Authorization failed after the token expires.

The Xillio API Refreshes the OneDrive Access Token

For this approach you will have to provide the Xillio API with a refresh token, corresponding client ID, client secret and redirect URI. The Xillio API will then ask OneDrive for a new access token before each request. In this case your configuration will look like this:

{
  "configurationType": "OneDrive",
  "name" : "My OneDrive",
  "config": {
    "refreshToken": "<your-refresh-token-here>",
    "clientId" : "<client-Id-of-your-application>",
    "clientSecret" : "<client-secret-of-your-application>",
    "redirectUri" : "<your-redirect-uri>"
  }
}
It is important to not set a value for the token field in this type of OneDrive configuration.

As long as the refresh token is valid, the Xillio API will be generating a new access token for each request and use it when communicating with OneDrive. After the refresh token expires you will get Authorization failed.

OneDrive Authorization

The OneDrive API uses the standard OAuth 2.0 authorization framework to authorize apps and generate access tokens. This means that you are required to register your application with Microsoft to generate access tokens. Xillio API needs such an access token to request files, folders or content from OneDrive.

Register Your Application

The first step is to register your application with Microsoft and provide some details about your application. You can register your application in Microsoft Application Registration Portal.

As of May 2019 this registration portal will no longer be supported and the following method of obtaining tokens might no longer be valid. It is recommended to use the authorization method with Azure AD v2.0.
Sign Users In

Your application must initiate the sign-in process by contacting the Azure Active Directory authorization endpoint with a specified scope. The flow follows standard OAuth 2.0 authorization flows and requires calls from a web browser or web-browser control. The result of the authorization flow will return an access token and optionally other values which your application will provide to Xillio API through configuration.

Authentication Scopes

Scopes determine what type of access the application is granted when the user is signed in. All scopes support single sign-on on the web, which means that if a user is already signed in to OneDrive, then the user can skip the authentication flow and go straight to the authorization flow.

Scopes
Scope name Description

offline_access

Enables your application to work offline even when the user isn’t active. Requires the use of code-flow.

files.read

Grants read-only permission to all of a user’s OneDrive files.

files.read.all

Grants read-only permission to all of a user’s OneDrive files, including files shared with the user.

files.readwrite

Grants read and write permission to all of a user’s OneDrive files.

files.readwrite.all

Grants read and write permission to all of a user’s OneDrive files, including files shared with the user.

As an example, a typical application might request the following scopes:

files.readwrite offline_access
Supported Authentication Flows
Token flow

The most straightforward authorization flow is the token flow. This flow is useful for quickly obtaining an access token in an interactive fashion. This flow does not provide a refresh token, and therefore is not a good fit for long term access to resources.

To start the sign-in process with the token flow, use a web browser or web-browser control to load a URL request.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}&response_type=token&redirect_uri={redirect_uri}
Required query string parameters
Parameter name Description

client_id

The client ID of your application registered with Microsoft.

redirect_uri

The redirect URL that the browser is sent to when authentication is complete.

response_type

The type of response expected from the authorization flow. For this flow, the value must be token.

scope

A space-separated list of scopes your application requires. Don’t forget to encode your URL.

Upon successful authentication and authorization of your application, the web browser is redirected to the redirect URL provided with additional parameters added to the URL.

https://localhost/myapp/auth-redirect#access_token=EwC...EB&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600&scope=onedrive.readwrite&user_id=3626...1d

The value of access_token is what you will have to put into Xillio API configuration to access OneDrive.

Code flow

The code flow for authentication is a three-step process with separate calls to authenticate and authorize the application and to generate an access token to access OneDrive. This also allows your application to receive a refresh token that will enable long-term use of OneDrive access in some scenarios, to allow access when the user isn’t actively using your application.

Step 1. Get an authorization code

To start the sign-in process with the code flow, use a web browser or web-browser control to load this URL request.

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}&response_type=code&redirect_uri={redirect_uri}
Required query string parameters
Parameter name Description

client_id

The client ID of your application registered with Microsoft.

scope

A space-separated list of scopes your application requires. Don’t forget to encode your URL.

response_type

The type of response expected from the authorization flow. For this flow, the value must be code.

redirect_uri

The redirect URL that the browser is sent to when authentication is complete.

Upon successful authentication and authorization of your application, the web browser will be redirected to your redirect URL with additional parameters added to the URL.

https://localhost/myapp/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c

Step 2. Redeem the code for access tokens

After you have received the code value, you can redeem this code for a set of tokens that allow you to authenticate with OneDrive. To redeem the code, make the following request:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
 Content-Type: application/x-www-form-urlencoded
 client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&code={code}&grant_type=authorization_code

The request body is a properly encoded URL string.

Required request body parameters
Parameter name Description

client_id

The client ID of your application registered with Microsoft.

redirect_uri

The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri in the first request. For web apps, the domain portion of the redirect URI must match the domain portion of the redirect URI that you specified in the Microsoft Developer Center.

client_secret

The client secret of your application registered with Microsoft.

code

The authorization code you received in the first authentication request.

If the call is successful, the response for the POST request contains a JSON string that includes several properties, including access_token, token_type, and refresh_token (if you requested the offline_access scope).

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"wl.basic onedrive.readwrite",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

The access token is valid for the number of seconds that is specified in the expires_in property. You can request a new access token by using the refresh token (if available), or by repeating the authentication request from the beginning.

Step 3. Get a new access token or refresh token

If your application has requested the offline_access scope this step will return a refresh_token that can be used to generate additional access tokens after the initial token has expired.

To redeem the refresh token for a new access token, make the following request:

POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_token

The request body is a properly encoded URL string, with some required parameters.

Required request body parameters
Parameter name Description

client_id

The client ID of your application registered with Microsoft.

redirect_uri

The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri in the first request. For web apps, the domain portion of the redirect URI must match the domain portion of the redirect URI that you specified in the Microsoft Developer Center.

client_secret

The client secret of your application registered with Microsoft.

refresh_token

The refresh token you received previously.

If the call is successful, the response for the POST request contains a JSON string that includes several properties including access_token, authentication_token and refresh_token if you requested the offline_access scope.

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope": "basic onedrive.readwrite offline_access",
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

The access token is valid for the number of seconds that is specified in the expires_in property. You can request a new access token by using the refresh token (if available) or by repeating the authentication request from the beginning.

Refresh token for "Personal" OneDrive lasts for several months and can be used multiple times.
OneDrive Authorization with Azure AD v2.0

This method uses the standard OAuth 2.0 authorization framework to authorize apps. It involves registering your application in the Azure Active Directory and sending HTTP requests to obtain and maintain tokens.

Register your application

As a prerequisite, you will need to register your application in the Azure portal. Go to the Azure Active Directory service, then under Application registrations (Preview) use the New Registration button.

In the registration form, it is recommended to select the account type that supports Microsoft personal accounts, see Features and Limitations.

The Redirect URI field in the registration form is marked optional, but it is actually required by the supported authorization flows.

After completing the registration, your application will be assigned Application (client) ID. For the code flow you will also need to generate a client secret in the Certifications & Secrets tab.

Auth Scopes

Part of an authorization flow is dynamically requesting specific permissions which are defined as scopes. In the following table, there are examples of scopes your application might require.

Scopes
Scope name Description

offline_access

Enables your application to work offline even when the user isn’t active. Requires the use of the code flow.

files.read

Grants read-only permission to all of a user’s OneDrive files.

files.read.all

Grants read-only permission to all of a user’s OneDrive files, including files shared with the user.

files.readwrite

Grants read and write permission to all of a user’s OneDrive files.

files.readwrite.all

Grants read and write permission to all of a user’s OneDrive files, including files shared with the user.

All these scopes, except offline_access, need to be prepended with the Microsoft Graph URI: https://graph.microsoft.com/.

An example of what scopes a typical application might request:

offline_access https://graph.microsoft.com/Files.ReadWrite

For more detailed information about scopes, please refer to Microsoft documentation.

Supported flows
Implicit grant flow

This flow can be used as a simple way of generating a short-lived access token in one step. It does not generate a refresh token.

Issuing tokens through the implicit grant flow needs to be allowed in the Azure portal. To do so:

  1. Go to the Azure Active Directory service.

  2. In the left-hand menu select Application Registration (Preview) and select your application.

  3. In the left-hand menu select the Authentication tab and scroll down to Implicit grant under Advanced settings.

  4. Check the Access tokens box and save.

To start the sign-in process with the implicit grant flow, browse to a URL like in the following example:

// Line breaks for legibility only

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
    client_id=6731de76-14a6-49ae-97bc-6eba6914391e
    &response_type=token
    &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
    &scope=https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
Mutable query parameters
Parameter name Description

client_id

The Application (client) ID in the Azure portal, as assigned after the registration of your app.

redirect_uri

The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal.

scope

A space separated list of scopes your application requires. The offline_access scope is not allowed in this flow. The value must be URL encoded.

Upon successful authentication and authorization of your application, you will be redirected to your redirect URI with additional parameters.

Example:

// Line breaks for legibility only

https://localhost/myapp/
    #access_token=EwBoA8l6BAAU...
    &token_type=bearer
    &expires_in=3600
    &scope=https://graph.microsoft.com/Files.ReadWrite
There are other ways to use the implicit grant flow which are omitted here for the sake of brevity. For more information, please refer to the Microsoft documentation.
Code flow

The code flow is a three-step process with separate calls to authenticate and authorize the application and to generate an access token. This flow also allows you to receive a refresh token used for retrieving access tokens. Using this flow enables you to let Xillio API take care of refreshing access tokens.

Step 1. Request authorization code

The authorization code flow begins with the client directing the user to the /authorize endpoint. In this request, the client indicates the permissions it needs to acquire from the user. To start the sign-in process with the code flow, browse to a URL like in the following example:

// Line breaks for legibility only

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
    client_id=49d21bd5-bab5-4bfa-8931-88feff5232f2
    &response_type=code
    &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
    &scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
The request can have optional parameters, which are omitted here for the sake of brevity. For more information, please refer to the Microsoft documentation.
Mutable query parameters
Parameter name Description

client_id

The Application (client) ID in the Azure portal, as assigned after the registration of your app.

redirect_uri

The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal.

scope

A space separated list of scopes your application requires. offline_access is necessary to receive refresh token. The value must be URL encoded.

Upon successful authentication and authorization of your application, the web browser will be redirected to your redirect URL with additional parameters depending on the optional parameters used.

Example:

https://localhost/myapp/?code=M6d343679-6cfb-5bb5-6141-56bba9b2eccc

The value of the code parameter is needed in the following step.

Step 2. Request an access token

Now that you’ve acquired an authorization code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. To do so, send a POST request to the /token endpoint like in the following example:

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=49d21bd5-bab5-4bfa-8931-88feff5232f2
&scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
&code=M976d709d-e045-254a-b650-cf666dfab743
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh
Mutable request parameters
Parameter name Description

client_id

The Application (client) ID in the Azure portal, as assigned after the registration of your app.

scope

Space separated list of requested scopes. Needs to match or be a subset of the list in the first step.

code

The authorization code you received in the first authentication request.

redirect_uri

The same redirect_uri value that was used to acquire the authorization code.

client_secret

The application secret that you created in the app registration portal for your app.

The request body needs to be URL encoded.

A successful token response will contain a JSON body with an access_token. A refresh_token will be present if offline_access scope was requested. For example:

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/Files.ReadWrite",
    "expires_in": 3600,
    "access_token": "EwBgA8l6BAAURSN...",
    "refresh_token": "MCdNsmNMveqITy..."
}

The expires_in indicates the amount of seconds for which access token is valid. A new pair of access and refresh tokens can be obtained by repeating the previous two steps or by using the refresh token in step 3.

By default, refresh tokens are only revoked after 90 days of inactivity. This behavior can be configured. For more information, please refer to the Microsoft documentation.

Step 3. Refresh an access token

If you provide a valid refresh token in the configuration, Xillio API takes care of this step, see configuration option with refresh token.

You can refresh an access token by issuing another POST request similar to the one in step 2.

Example request:

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh
Mutable request parameters
Parameter name Description

client_id

The Application (client) ID in the Azure portal, as assigned after the registration of your app.

scope

Space separated list of requested scopes. Needs to match or be a subset of the list in the first step.

refresh_token

The refresh_token that you acquired in the second step of the flow.

redirect_uri

The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal.

client_secret

The application secret that you created in the app registration portal for your app.

The request body needs to be URL encoded.

A successful token response will contain a JSON body with a new access and refresh token. For example:

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/Files.ReadWrite",
    "expires_in": 3600,
    "access_token": "EwBoA8l6BAAURSN...",
    "refresh_token": "MCaa5HRMEOA8HS..."
}
Refresh tokens are not revoked when used to acquire new access tokens. By default, refresh tokens are only revoked after 90 days of inactivity. This behavior can be configured. For more information, please refer to the Microsoft documentation.

3.14.2. Features and Limitations

The OneDrive connector is designed to connect to personal OneDrive accounts only. However, it should be able to read entities and content of OneDrive business accounts.

The connector does not provide access to:

  • "Shared Items": files and folders that have been shared with the owner of the Drive

  • OneNote notebooks

Versioning

The connector does not allow to delete a specific version of an entity because the Microsoft Graph API for OneDrive personal does not support it.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.14.3. Mappings

These are the decorators that are set for certain types in OneDrive. Entities retrieved via OneDrive can be of kind File or Folder.

OneDrive mappings
Decorator Used By Read-only Field in OneDrive Description

container.hasChildren

Folder

True

Always True

This decorator is only set for folders, and hasChildren is always true.

contentType

created.date

File, Folder

True

createdDateTime

Date and time when the requested entity was created.

created.by

File, Folder

True

createdBy

Name of the user that created the requested entity.

description

File, Folder

False

description

Description associated in OneDrive with the requested entity.

file.rawExtension

File

True (update Name decorator to change extension)

Computed from name

The extension of the requested file, or an empty string if it has none.

file.extension

File

True (update Name decorator to change extension)

Computed from name

The sanitized extension of the requested file.

file.size

File

True

size

The size in bytes of the requested file.

fileSystem.path

File, Folder

True

Computed from path

The path to the requested entity relative to the OneDrive root.

hash.md5

hash.sha1

File

True

hashes.sha1Hash

The sha1 hash of the requested file.

hash.sha256

File

True

hashes.sha256Hash

The sha256 hash of the requested file.

mimeType.type

File

True

mimeType

The mime type of the requested file. This is determined by logic in OneDrive and might not be the value provided when the file was uploaded.

modified.date

File, Folder

True

lastModifiedDateTime

Last modified date and time of the requested entity.

modified.by

File, Folder

True

lastModifiedBy

Name of the user that modified the requested entity as last.

name.displayName

File, Folder

True

name

The name of the requested entity.

name.systemName

File, Folder

False (update this decorator to rename entity or change file’s extension)

name

The name of the requested entity.

parent.id

File, Folder

False (update this decorator to move entity to new location)

Computed from path

The XDIP of the parent entity.

preview

File, Folder

True

webUrl

URL that can display the requested entity in the browser.

version

File

True

id

The current verrsion id of the file.

3.15. Opentext

Version(s): we support version 16.2 of Opentext Content Server.

3.15.1. Configuration

The configuration for the Opentext connector consists of the following parameters:

Configuration parameters:
Parameter Description

baseUrl

The full URL of the OpenText Content Server API extension: server, port and the path to the API root.

username

The username of an account on OpenText.

password

The password of the account.

rootNode

The id of the root node.

Default: 2000

maxAuthAttempts

The number of attempts to get an authentication ticket from Opentext Content Server.

Default: 3

retryAuthAfter

Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt.

Default: 2

ticket

OpenText Content Server authentication ticket.

The optional rootNode parameter is the id of the root node of the OpenText workspace you want to access.

Its default value is 2000, as it is the common id of the root of the Enterprise workspace. It can however differ across Content Server instances, in which case you need to specify it.

The parameter ticket is used internally by the connector to persist the Opentext authentication ticket and reuse it as long as it is valid. This approach restricts requests to Opentext API authentication endpoint to minimum. You can leave it empty when creating or updating configurations.

You can configure Opentext connector to retry getting Content Server authentication ticket if the first attempt fails. By default, the connector will try to get the authentication ticket three times. The delay between the first and second attempt is configurable. For all the following attempts the connector will always double the previous delay. For example, with the default value of two seconds base delay, the connector will wait four seconds between the second and third attempt and eight seconds between the third and fourth attempt.

Example Configuration:
{
  "configurationType": "Opentext",
  "config" : {
    "baseUrl" : "http://otcs.xillio.com:8080/otcs/cs.exe",
    "username" : "username",
    "password" : "password"
  }
}

3.15.2. Features and Limitations

  • Some content types can be created (e.g. 0 = Folder and 144 = Document), some cannot (e.g. 356 = Blog)

  • Special characters in queries must be escaped manually.

  • The content types discovery (/types endpoint) requires read-write access to the node on which the Opentext API call is performed. Our connector uses by default the root node from the configuration, but you can redirect it to a different node by assigning the nickname "xillio_content_type_discovery_node" to this node.

  • This connector supports pagination when requesting a list of children of the folders. But to not lower the performance of the connector only those combinations of offset and limit are supported when the offset is a multiple of limit. Also be aware of the configuration of the Opentext server you are connecting to. It can limit the size of the page. By default this limitation is 100 items.

Named Queries

Opentext uses LQL (livelink query language), more information on how to create queries in LQL can be found in your Opentext instance.

Example: Search by filename

The following request creates a query that will return entities where their name contains the provided string.

$ curl -X POST \
    https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
    -H 'Authorization: bearer <<AUTH_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  	"name":"SearchFileByName",
  	"template":"OTName:\"${q_name}\""
  }'

We can then query the target repository for files containing the string Test:

$ curl -X GET \
  'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchFileByName?scope=entities&q_name=Test' \
  -H 'Authorization: bearer <<AUTH_TOKEN>>' \
  -H 'Content-Type: application/json' \

The result of the previous call will be something similar to (omitting irrelevant information by …​):

{
  "entities": [
    {
      "id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/6514",
      "xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/6514",
      "kind": "Document",
      "original": {
        ... ,
        "name": {
          "systemName": "TestFile.jpg",
          "displayName": "TestFile.jpg"
        },
        ...
      },
      "modified": {
        ...
      }
    },
    ...
  ]
}
Example: Search by modified since

The following requests creates a query that will only return entities that were created before the specified date.

$ curl -X POST \
    https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
    -H 'Authorization: bearer <<AUTH_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  	"name":"SearchByModifiedSince",
  	"template":"OTModifyDate:(>\"${q_date\"})"
  }'

The following request uses the created query to return entities from OpenText that have been modified after 17-07-2018.

$ curl -X GET \
  'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchByModifiedSince?scope=entities&q_date=20180717' \
  -H 'Authorization: bearer <<AUTH_TOKEN>>' \
  -H 'Content-Type: application/json' \

The result of the previous call will be something similar to (omitting irrelevant information by …​):

{
  "entities": [
    {
      "id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/30365",
      "xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/30365",
      "kind": "Folder",
      "original": {
        ...,
        "modified": {
          "date": "2018-09-12T09:05:25.000+02:00",
          "by": {
            "displayName": "1000",
            "systemName": "1000"
          }
        },
        ...
      },
      "modified" : {
        ...
      }
    },
    ...
  ]
}
Example: Search in contents

The following requests creates a query that will only return entities where a certain text can be found in the contents.

$ curl -X POST \
    https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
    -H 'Authorization: bearer <<AUTH_TOKEN>>' \
    -H 'Content-Type: application/json' \
    -d '{
  	"name":"SearchByContents",
  	"template":"OTData:\"${q_text}\""
  }'

The following request uses the created query to return entities from OpenText that have "test" in their contents.

$ curl -X GET \
  'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchByContents?scope=entities&q_text=test' \
  -H 'Authorization: bearer <<AUTH_TOKEN>>' \
  -H 'Content-Type: application/json' \

The result of the previous call will be something similar to (omitting irrelevant information by …​):

{
  "entities": [
    {
      "id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/16573",
      "xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/16573",
      "kind": "Document",
      "original": {
        ...,
        "name": {
          "systemName": "FileContainingTestData.txt",
          "displayName": "FileContainingTestData.txt"
        },
        ...
      },
      "modified" : {
            ...
      }
    },
    ...
  ]
}
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.15.3. Mappings

Opentext Mappings
Decorator Used By Field in Opentext Description

container.hasChildren

Folder

container

Whether the entity has children.

contentType.systemName

All entities

type

The ID of content type.

contentType.displayName

All entities

type_name

The name of content type.

created.date

All entities

create_date

The time the entity was created.

created.by.systemName

All entities

create_user_id

The id of the user who has created the entity.

created.by.displayName

All entities except when retrieved using a query

display_name

The display name of the user who has created the entity.

created.by.email

All entities except when retrieved using a query

business_email if available otherwise personal_email

The email of the user who has created the entity.

description

All entities

description

The description of the entity as displayed in Opentext.

file.rawExtension

Document

Computed from name

The extension of the document as derived from the name.

file.size

Document

file_size

The size of the document in bytes.

mimeType.type

Document

mime_type

The mime type of the requested document.

modified.date

All entities

modify_date

The time the entity was last modified.

modified.by.systemName

All entities except when retrieving versions

modify_user_id

The id of the user who has last modified the entity.

modified.by.displayName

All entities except when retrieved using a query or when retrieving versions.

display_name

The display name of the user who has last modified the entity.

modified.by.email

All entities except when retrieved using a query or when retrieving versions.

business_email if available otherwise personal_email

The email of the user who has created the entity.

name.systemName

All entities

name

The name of the entity that is displayed in Opentext.

parent.id

All entities

parent_id

The XDIP of the parent entity.

version

Document

version_number

The number indicating what version of the Document is presented.

3.15.4. RPC Endpoints

This connector supports RPC for Records Management metadata.

categories

The categories namespace can extract information about category definitions within OpenText.

To get the list of categories, use the API endpoint /templates.

categories/getCategoryAttributes

Returns the list of the attributes of the specific Opentext category.

POST /v2/rpc/{configurationId}/categories/getCategoryAttributes
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the category.

Returns CategoryAttribute[]: the list of the attributes of the specific Opentext category.

Response Fields

Path

Type

Description

[]

CategoryAttribute[]

the list of the attributes of the specific Opentext category
Example Response
[ {
  "id" : 3,
  "name" : "Extra number",
  "required" : false,
  "type" : 2
} ]
members

The members namespace can extract information about members (users or groups) within OpenText.

members/getMember

Returns details about the member (user or group) with the ID id.

POST /v2/rpc/{configurationId}/members/getMember
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the member.

Returns Member: the details about the member (user or group).

Response Fields

Path

Type

Description

name

String

The name of the member.

deleted

boolean

The flag whether the member is deleted.

businessEmail

String

The email of the member.

typeName

String

The member’s type (i.e. user or group).

firstName

String

The first name of the member.

lastName

String

The last name of the member.
Example Response
{
  "typeName" : "User",
  "name" : "John Doe",
  "firstName" : "John",
  "lastName" : "Doe",
  "businessEmail" : "john.doe@your-company.com",
  "deleted" : false
}
nodes

The nodes namespace can extract information from nodes within OpenText.

A 404 - Not Found with a NoSuchEntity error can be thrown when either the provided node does not exist or when the endpoint is not accessible due to, for example, a module as Records Management is not installed.

nodes/assignCategory

Assigns an existing category to an existing node.

POST /v2/rpc/{configurationId}/nodes/assignCategory
------
HTTP/1.1 204 No Content
Input Parameters

Input

Type

Default

Description

nodeId

int

The id of the node.

categoryId

int

The id of the category.
nodes/createRMClassification

Adds a new classification to the node with ID id.

POST /v2/rpc/{configurationId}/nodes/createRMClassification
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

classificationId

int

The id of the classification.

status

String

""

The optional status for the classification of the node.

statusDate

String

""

The optional status date for the classification of the node.

Returns RMClassificationResponse: the classifications of the node.

Response Fields

Path

Type

Description

definitions

RMClassificationDefinition

The definitions of the Records Management classifications data.

data

RMClassification[]

The Records Management classifications data.
Example Response
{
  "data" : [ {
    "name" : "Master documents",
    "rmclassificationId" : 59,
    "type" : 3,
    "fileNumber" : "10.8.54",
    "statusDate" : "2019-08-22T00:00:00",
    "status" : "5",
    "recordDate" : "2019-08-12T00:00:00",
    "recordType" : 31549,
    "establishment" : "Example company",
    "addressee" : "Company",
    "accession" : "ACCESSION-CODE-5",
    "originator" : "HR Department",
    "sentTo" : "External",
    "lastReviewDate" : "2019-08-22T00:00:00",
    "nextReviewDate" : "2019-09-22T00:00:00",
    "subject" : "Quick start guide",
    "official" : false,
    "essential" : "ESSENTIAL-CODE-1",
    "storage" : "Hard disk",
    "cyclePeriod" : 1,
    "receivedDate" : "2019-08-14T00:00:00",
    "primary" : true
  } ],
  "definitions" : {
    "fileNumber" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "status" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}
nodes/createXRef

Adds a new cross-reference to the node with ID id to reference another node.

POST /v2/rpc/{configurationId}/nodes/createXRef
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

xrefId

int

The ID of the node referenced.

xrefType

String

The cross-reference type.

comment

String

The comment for the cross-reference.

Returns XRefResponse: the cross-references of the node.

Response Fields

Path

Type

Description

definitions

XRefDefinition

The definitions of the cross-references data.

data

XRef[]

The cross-references data.
Example Response
{
  "data" : [ {
    "xrefId" : 4659,
    "type" : 144,
    "name" : "graph.png",
    "xrefType" : "ASSETSTORAGEPERSPECTIVE",
    "verNum" : 0,
    "mimeType" : "image/png",
    "relatedCode" : "ASSETSTORAGEPERSPECTIVEFOLDER",
    "location" : "Enterprise",
    "comment" : "Original image for graph"
  } ],
  "definitions" : {
    "relatedCode" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "xrefType" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}
nodes/deleteRMClassification

Removes the classification with ID classificationId from the node with ID id.

POST /v2/rpc/{configurationId}/nodes/deleteRMClassification
------
HTTP/1.1 204 No Content
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

classificationId

int

The id of the classification.
nodes/deleteXRef

Removes the reference with type xrefType from the node with ID id to node with ID xrefId.

POST /v2/rpc/{configurationId}/nodes/deleteXRef
------
HTTP/1.1 204 No Content
Input Parameters

Input

Type

Default

Description

id

int

The id of the node to remove a cross-reference from.

xrefId

int

The id of the referenced node to remove.

xrefType

String

The type of reference to remove.
nodes/getCategories

Returns the categories of the node with ID id.

POST /v2/rpc/{configurationId}/nodes/getCategories
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

Returns OpentextNodeCategoriesInfo[]: the categories of the node.

Response Fields

Path

Type

Description

[]

OpentextNodeCategoriesInfo[]

the categories of the node
Example Response
[ {
  "id" : 1234,
  "name" : "Category A"
} ]
nodes/getCategoryFields

Returns the fields of the selected category.

POST /v2/rpc/{configurationId}/nodes/getCategoryFields
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

nodeId

int

The id of the node.

categoryId

int

The id of the category.

Returns CategoryFieldDefinition[]: the fields of the category.

Response Fields

Path

Type

Description

[]

CategoryFieldDefinition[]

the fields of the category
Example Response
[ {
  "key" : "54117_2",
  "name" : "Number of pages",
  "type" : 2,
  "persona" : "",
  "required" : true,
  "typeName" : "Integer",
  "readOnly" : false,
  "multiValue" : false
} ]
nodes/getRMClassifications

Returns the classifications of the node with ID id.

POST /v2/rpc/{configurationId}/nodes/getRMClassifications
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

Returns RMClassificationResponse: the classifications of the node.

Response Fields

Path

Type

Description

definitions

RMClassificationDefinition

The definitions of the Records Management classifications data.

data

RMClassification[]

The Records Management classifications data.
Example Response
{
  "data" : [ {
    "name" : "Master documents",
    "rmclassificationId" : 59,
    "type" : 3,
    "fileNumber" : "10.8.54",
    "statusDate" : "2019-08-22T00:00:00",
    "status" : "5",
    "recordDate" : "2019-08-12T00:00:00",
    "recordType" : 31549,
    "establishment" : "Example company",
    "addressee" : "Company",
    "accession" : "ACCESSION-CODE-5",
    "originator" : "HR Department",
    "sentTo" : "External",
    "lastReviewDate" : "2019-08-22T00:00:00",
    "nextReviewDate" : "2019-09-22T00:00:00",
    "subject" : "Quick start guide",
    "official" : false,
    "essential" : "ESSENTIAL-CODE-1",
    "storage" : "Hard disk",
    "cyclePeriod" : 1,
    "receivedDate" : "2019-08-14T00:00:00",
    "primary" : true
  } ],
  "definitions" : {
    "fileNumber" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "status" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}
nodes/getSecurityClearance

Returns the current security clearance of the node with ID id.

POST /v2/rpc/{configurationId}/nodes/getSecurityClearance
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

Returns SecurityClearanceResponse: the current security clearance.

Response Fields

Path

Type

Description

definitions

SecurityClearanceDefinition

The definitions of the security clearance data.

data

SecurityClearance

The security clearance data.
Example Response
{
  "data" : {
    "clearanceLevel" : 1,
    "supplementalMarkings" : [ "PUBLIC" ],
    "inheritFrom" : false
  },
  "definitions" : {
    "clearanceLevel" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "supplementalMarkings" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}
nodes/getXRefs

Returns the cross-references of the node with ID id.

POST /v2/rpc/{configurationId}/nodes/getXRefs
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

Returns XRefResponse: the cross-references.

Response Fields

Path

Type

Description

definitions

XRefDefinition

The definitions of the cross-references data.

data

XRef[]

The cross-references data.
Example Response
{
  "data" : [ {
    "xrefId" : 4659,
    "type" : 144,
    "name" : "graph.png",
    "xrefType" : "ASSETSTORAGEPERSPECTIVE",
    "verNum" : 0,
    "mimeType" : "image/png",
    "relatedCode" : "ASSETSTORAGEPERSPECTIVEFOLDER",
    "location" : "Enterprise",
    "comment" : "Original image for graph"
  } ],
  "definitions" : {
    "relatedCode" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "xrefType" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}
nodes/updateCategory

Updates field of node’s category.

POST /v2/rpc/{configurationId}/nodes/updateCategory
------
HTTP/1.1 204 No Content
Input Parameters

Input

Type

Default

Description

nodeId

int

The id of the node.

categoryId

int

The id of the category.

key

String

The key of the field to update.

value

String

The new value of the field.
nodes/updateRMClassification

Updates a classification for the node with ID id.

OpenText only allows updating the classificationId when other fields (such as status and statusDate) are not present. Note that updating the classificationId might remove metadata from the fields of the classification (such as status and statusDate) and default them to the system default. 
POST /v2/rpc/{configurationId}/nodes/updateRMClassification
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

id

int

The id of the node.

classificationId

Integer

``

The optional id of the new classification.

status

String

""

The optional new status of the classification.

statusDate

String

""

The optional new date for the status.

Returns RMClassificationResponse: the classifications of the node.

Response Fields

Path

Type

Description

definitions

RMClassificationDefinition

The definitions of the Records Management classifications data.

data

RMClassification[]

The Records Management classifications data.
Example Response
{
  "data" : [ {
    "name" : "Master documents",
    "rmclassificationId" : 59,
    "type" : 3,
    "fileNumber" : "10.8.54",
    "statusDate" : "2019-08-22T00:00:00",
    "status" : "5",
    "recordDate" : "2019-08-12T00:00:00",
    "recordType" : 31549,
    "establishment" : "Example company",
    "addressee" : "Company",
    "accession" : "ACCESSION-CODE-5",
    "originator" : "HR Department",
    "sentTo" : "External",
    "lastReviewDate" : "2019-08-22T00:00:00",
    "nextReviewDate" : "2019-09-22T00:00:00",
    "subject" : "Quick start guide",
    "official" : false,
    "essential" : "ESSENTIAL-CODE-1",
    "storage" : "Hard disk",
    "cyclePeriod" : 1,
    "receivedDate" : "2019-08-14T00:00:00",
    "primary" : true
  } ],
  "definitions" : {
    "fileNumber" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    },
    "status" : {
      "validValues" : [ "1", "2" ],
      "validValuesName" : [ "1..Confidential", "2..Public" ],
      "type" : 2,
      "name" : "Security Clearance Level",
      "key" : "clearance_level",
      "description" : "The security clearance of a record",
      "required" : true
    }
  }
}

3.15.5. RPC Models

CategoryAttribute

Holds the definition of an attribute of the Opentext category.

Fields

Field

Type

Description

required

boolean

The flag whether value for this attribute will be required when assigning category to a node.

name

String

The name of the attribute.

type

Integer

The type of the attribute (internal Opentext ID of the type).

id

Integer

The ID of the attributes.
CategoryFieldDefinition

Definition of a field of OpenText category.

Fields

Field

Type

Description

key

String

The key of the category field.

name

String

The name of the field.

type

Integer

The ID of the type of the field.

readOnly

Boolean

The flag whether field is read-only.

multiValue

Boolean

The flag whether field can hold multiple values.

persona

String

The indicator whether the field is member or user group reference.

typeName

String

The name of the type of the field.

required

Boolean

The flag whether field is mandatory to fill.
Definition

The definition for a model within OpenText.

This definition contains information about a certain piece of metadata within OpenText. The information could be for example, the name of the metadata, the system key, a description for this piece of metadata and its possible values.

Fields

Field

Type

Description

validValues

String[]

The valid values for this definition.

key

String

The system key for this definition.

required

boolean

Whether this metadata field is required or not.

name

String

The human readable name for this definition.

type

int

description

String

The description for this definition.

validValuesName

String[]

The human readable value names for this definition.
Member

Holds values of certain user or group in Opentext instance.

Fields

Field

Type

Description

name

String

The name of the member.

deleted

boolean

The flag whether the member is deleted.

businessEmail

String

The email of the member.

typeName

String

The member’s type (i.e. user or group).

firstName

String

The first name of the member.

lastName

String

The last name of the member.
OpentextNodeCategoriesInfo

Category information.

Fields

Field

Type

Description

name

String

Name of the category.

id

int

ID of the category.
RMClassification

Records Management classification information for a node.

Fields

Field

Type

Description

cyclePeriod

int

The cycle period for this classification.

receivedDate

String

The received date for this classification.

rmclassificationId

int

The id of the classification.

subject

String

The subject information for this classification.

name

String

The name of the classification.

essential

String

The essential code for this classification.

originator

String

The author or originator of this classification.

status

String

The status of this classification.

nextReviewDate

String

The date at which this classification is next to be reviewed.

recordType

int

The record type value for this classification.

official

boolean

Whether this classification is official or not.

lastReviewDate

String

The date at which the classification was last reviewed.

accession

String

The accession code for this classification.

recordDate

String

The date where this node is recorded.

addressee

String

The addressee(s) for this classification.

type

int

The type ID of the classification.

primary

boolean

Whether this classification is the primary classification for this node.

statusDate

String

The last modified date for the status of this classification.

storage

String

The storage medium code for this classification.

fileNumber

String

The file number for this classification.

establishment

String

The originating organization for this classification.

sentTo

String

The other addressee(s) for this classification.
RMClassificationDefinition

The definitions for Records Management classification metadata fields.

Fields

Field

Type

Description

status

Definition

The definition for a status.

fileNumber

Definition

The definition for a file number.
RMClassificationResponse

The response for retrieving the Records Management classifications of a node.

Fields

Field

Type

Description

definitions

RMClassificationDefinition

The definitions of the Records Management classifications data.

data

RMClassification[]

The Records Management classifications data.
SecurityClearance

Security clearance information for a node.

Fields

Field

Type

Description

inheritFrom

boolean

supplementalMarkings

String[]

Any supplemental markings for this clearance.

clearanceLevel

int

The current clearance level.
SecurityClearanceDefinition

The definitions for Security Clearance metadata fields.

Fields

Field

Type

Description

supplementalMarkings

Definition

The definition for a supplemental marking.

clearanceLevel

Definition

The definition for a clearance level.
SecurityClearanceResponse

The response for retrieving the security clearance of a node.

Fields

Field

Type

Description

definitions

SecurityClearanceDefinition

The definitions of the security clearance data.

data

SecurityClearance

The security clearance data.
XRef

Cross-reference information for one node to another node.

Fields

Field

Type

Description

location

String

The location of the referenced node.

name

String

The name of the node referenced.

mimeType

String

The mime-type of the referenced node.

type

int

The type ID of the node referenced.

relatedCode

String

The type of the reference from the other node.

xrefType

String

The type of the reference to the other node.

comment

String

A comment about this cross-reference.

xrefId

int

The ID of the node referenced.

verNum

Integer

The version of the referenced node.
XRefDefinition

The definitions for cross-reference metadata fields.

Fields

Field

Type

Description

relatedCode

Definition

The definition for the related code.

xrefType

Definition

The definition for the cross-reference type.
XRefResponse

The response for retrieving the cross-reference information of a node.

Fields

Field

Type

Description

definitions

XRefDefinition

The definitions of the cross-references data.

data

XRef[]

The cross-references data.

3.16. S3

Simple Storage Service (S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance.

Version(s): we support S3 APIs with AWS version 4 signatures.

This connector is primarily developed for AWS S3. Other S3 API implementations are supported if implemented correctly.
The connector might produce unexpected results due to small differences in functionality for these APIs. This is especially the case for error handling.

3.16.1. Configuration

The S3 connector operates on a single bucket as is configured in the connector configuration. This bucket must be accessible through the internet for the provided accessKey and secretKey.

Newly created buckets:

It might take some time before the connector can connect to a newly created bucket, as the bucket is still being processed.
During this time, our API returns 500 - Internal Server Error as S3 returns an error message stating that the request signature did not match.
It could take few hours for AWS to fully process a new bucket. It is possible to verify that the bucket is reachable by using S3’s REST API directly.
Connector Configuration

The S3 connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL to the target bucket. It must include the bucket name.

username

The access key id to use for authentication.

password

The secret access key to use for authentication.

region

The region in which this bucket resides. Required for AWS S3 instances.

delimiter

The delimiter for traversing the bucket. See Hierarchy.

Default: /
Example Configuration:
{
  "configurationType": "S3",
  "config" : {
    "baseUrl" : "https://mybucket.s3.amazonaws.com",
    "username" : "AKIAIOSFODNN7EXAMPLE",
    "password" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region" : "eu-central-1"
  }
}

3.16.2. Features and Limitations

Currently, only retrieving object entities and binary content in unencrypted buckets is supported.

Hierarchy

Amazon S3 is a non-hierarchical key-value store. However, to ease the navigation with the Xillio API, you can set a "path delimiter". The default delimiter is /.

Delimiter example

In a bucket containing the following keys:

- infrastructure-audit-jan
- infrastructure-audit-feb
- content-whitepaper

if the delimiter is set to -, the Xillio API will expose the following hierarchy:

infrastructure-
 |
 ├── audit-
 |  |
 |  ├── jan
 |  \── feb
 |
 \── content-
    |
    \── whitepaper

In this example, the entities infrastructure-, audit- and content- can be retrieved in the Xillio API, despite not corresponding to actual objects in Amazon S3. They are the prefixes of their respective sub-keys, and are considered the parents of those entites within the Xillio API. They have the content type Prefix.

To expose a bucket as a key-value store, set the empty string ("") as delimiter. Every entity will then reside in the root.
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

3.16.3. Mappings

S3 Mappings
Decorator Used By Field in S3 Description

container.hasChildren

All entities

Whether the entity could have children. Is always set to true unless using an empty delimiter.

contentType.systemName

All entities

The content type of the entity. Either Prefix or Key.

contentType.displayName

All entities

The content type of the entity. Either Prefix or Key.

file.rawExtension

All entities

Key

The extension of the requested Prefix or Key.

file.extension

All entities

Key

The sanitized extension of the requested Prefix or Key.

file.size

Key

Size

The size in bytes of the requested Key.

fileSystem.path

All entities

Key

The filesystem representation of the Prefix or Key separated by the configured delimiter.

hash.md5

Key

ETag

The MD5 hash of this Key.

mimeType

Key

The mime-type of this Key based on its extension. If the extension is unknown, this is set to application/octet-stream.

modified.date

Key

LastModified

The date in which the requested Key was last modified.

modified.by.displayName

Key

The DisplayName of the Owner, if available. Otherwise the ID of the Owner of this Key.

modified.by.systemName

Key

Owner.ID

The ID of the Owner which owns this Key.

name.displayName

All entities

Key

The name of this entity. The last part of the key as split by delimiter. Trailing delimiters are included. If the delimiter is an empty string, this value will be the entire Key value.

name.systemName

All entities

Key

The name of this entity. The last part of the key as split by delimiter. Trailing delimiters are included. If the delimiter is an empty string, this value will be the entire Key value.

parent.id

All entities

Key

The XDIP of the parent entity, as computed by using the 'Key' value of this entity.

3.17. Salesforce

Salesforce is a complex CRM cloud-based solution. This connector exposes its knowledge base part called Salesforce Knowledge.

Version(s): we support Salesforce Classic and Lightning.

3.17.1. Configuration

Salesforce connector configuration

The Salesforce connector configuration consists of the URL of your Salesforce site and authentication credentials.

Configuration parameters:
Parameter Description

baseUrl

The base URL of the Salesforce API.

Default: https://eu26.salesforce.com

refreshToken

An OAuth2 refresh token.

clientId

The client id. Required when refreshToken is set.

clientSecret

The client secret. Required when refreshToken is set.

token

An OAuth2 token.

When set, refreshToken, clientId and clientSecret are not required. It can be useful for testing, or if your application handles refreshing tokens.
Example Configuration:
{
  "configurationType": "Salesforce",
  "config" : {
    "refreshToken" : "5Axc861F1.ndOFuBX057HR38ot4A7419...",
    "clientId" : "3MFG96_7YM2sI9wTgZjGhoQXR6WBX35X...",
    "clientSecret" : "FB5AE94E81B62A80692F4D9CUR63M890...",
    "token" : "00A4p000000OtwS!AQNEPJgHxpEq9YXP..."
  }
}

Authenticating to Salesforce is done with an OAuth access token. You only need to provide some of the values depending on whether you want to have your application or the Xillio API to handle refreshing the access token.

Your Application Refreshes the Salesforce Access Token

For this approach, you only need to provide the base URL and the access token. Update the configuration whenever you get an authorization error later.
An example configuration might look like this:

{
  "configurationType": "Salesforce",
  "name" : "My Salesforce",
  "config": {
    "baseUrl": "https://eu26.salesforce.com",
    "token": "00A4p000000OtwS!AQNEPJgHxp..."
  }
}

The Xillio API will use this token when communicating with Salesforce. After the token expires you will get an Authorization failed error.

The Xillio API Refreshes the Salesforce Access Token

For this approach, you need to provide the base URL, the refresh token and the corresponding client ID and client secret. Optionally you can provide an initial access token as well.
The Xillio API will then generate new access token whenever it receives a response from Salesforce indicating the current access token is expired.
An example configuration might look like this:

{
  "configurationType": "Salesforce",
  "name" : "My Salesforce",
  "config": {
    "baseUrl": "https://eu26.salesforce.com",
    "refreshToken": "5Axc861F1.ndOFuBX057HR38ot4A74...",
    "clientId" : "3MFG96_7YM2sI9wTgZjGhoQ6WBX35X...",
    "clientSecret" : "FB5AE94E81B62A80692F4D9CUR63M890..."
  }
}

As long as the refresh token is valid, the Xillio API will be generating a new access token whenever necessary. After the refresh token expires you will get an Authorization failed error.

Salesforce Authorization

The Salesforce API uses the standard OAuth 2.0 authorization framework to authorize applications and generate access tokens.

You can find a simple description of how to set up OAuth with Salesforce in this article. For more detailed information, please refer to the resources here and here.

For registration of your application in Salesforce, please note that at least api, refresh_token, offline_access OAuth scopes are required for use with Xillio API.

3.17.2. Features and Limitations

This connector has read, write and translation functionality. There is no custom metadata or search support.
The connected Salesforce instance is required to have Knowledge enabled with multilingual support.

Entity types and hierarchy

The connector exposes three types of Salesforce Knowledge entities: Category Groups, Categories and Articles; as well as two kinds of virtual folders. Write operations are only supported for Article entities.

The following is an example of Salesforce as exposed by this connector. It organizes the entities in a tree structure:

\
| - Articles                        (1)
|   | - FAQ                         (2)
|   |   | - How to do this?         (3)
|   |   \ - How to deal with that?
|    ...
|
| - Category group                  (4)
|   | - This category               (5)
|   |   \ - How to do this?
|   \ - The other category
|       \ - Subcategory
|           | - Non FAQ Article
 ...         ...

The top level always contains a virtual folder Articles 1.
The Articles folder contains a virtual folder for each article type existing in the connected Salesforce instance. These Article Type Folders 2 contain every Article 3 of the given type, including the uncategorized ones. The other top-level entities are Category Groups 4.
Children of Category Groups are Categories 5.
Children of Categories are Other Categories or Articles.

Articles

Articles are the only entities for which write operations are supported.

Articles in Salesforce can have a publication status of draft, online or archived.
This connector exposes draft and online Articles, without any difference.

One Article in Salesforce can exist in both draft and online state, when it has been published and is in the process of being edited. The online version of such articles cannot be updated or deleted, attempts to do so will result in Operation Not Allowed with the XDIP of the draft version in the message of the error.

Articles in Salesforce can have zero, one, or more Category assigned.
As exposed by this connector, Articles have their assigned Categories and their corresponding Type Folder displayed as parents in calls using path_parents_* scope. Additionally, the parent decorator always contains an id of one of those parents.

Creating an Article can be done using an XDIP of either an Article Type Folder or a Category. The first option results in creating an uncategorized Article. The other option results in creating an Article in the specified Category and requires filling the contentType.systemName with the desired type of the Article to be created. All the available Article types of the connected Salesforce instance can be obtained by calling the /types endpoint.
Articles are always created in draft state.

Changing the Category parents of an Article is done by updating the parent decorator as described by the following table:

Salesforce connector parent updates
id filled in original.parent id filled in modified.parent Category assignment

Added.

Removed.

Removed and added, if the values differ.

Articles in Salesforce can have a customized layout assigned to them which can define various custom fields.
This connector exposes the names and values of these fields as binary content. Requesting the binary content of an Article entity returns a JSON similar to the one in the following example:

{
  "additional_text__c": "A text value",
  "number__c": "42.0",
  "another_number__c": null,
  "date_field__c": "2042-01-01",
  "picklist__c": "Option A",
  "file_attachment__Name__s": "filename.txt",
  "file_attachment__Length__s": "206.0",
  "file_attachment__Body__s": "/services/data/v45.0/sobjects/Offer__kav/ka02p000000kqHKAAY/file_attachment__Body__s",
  "file_attachment__ContentType__s": "text/plain",
}

Binary content can be retrieved only from Articles.

Translations

Articles in Salesforce can be translated into different languages.
This connector exposes the existing language mutations of Articles in languages which are added in the Knowledge Base of the connected Salesforce instance. Language mutations can be obtained using the scope translations_all_*. Please note that results of such calls may include duplicate entries for one language, as both draft and online version of the Article may exist in that language.

When creating an Article without the use of translationOf field in the language decorator a master language Article is created. If the tag field is not filled either, the Article is created in the default language of the connected Salesforce instance. Only languages which are marked active in the connected Salesforce Knowledge base are valid tag values.

In Salesforce Categories assigned to an Article are tied to its master language mutation. This has several implications:

  • Translations of Articles are always created with the same set of assigned Categories as the master language Article.

  • Updating parents of master language Article will also change the parents of its translations.

  • Updating parents of Article translations is not a valid operation and will result in Operation Not Allowed.

Deleting a master language Article will result in all of its translations being deleted as well.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_parents_entity path_parents_reference

path_children_entity path_children_reference

version

translation

translation_all_entity translation_all_reference

3.17.3. Mappings

Salesforce mappings
Decorator Used By Field in Salesforce Writable Description

container.hasChildren

Articles folder, Article type folder, Category Group, Category

Whether the entity can have path relation children. Always true for virtual folders, Category Groups and Categories.

contentType.systemName

Article

ArticleType

The type of the Article with its suffix as used by Salesforce backend. Not always present, please see note bellow.

contentType.displayName

Article

ArticleType

The type of the Article in human readable form, i.e. without __kav suffix. Not always present, please see note bellow.

created.date

Article

CreatedDate

Date and time when the Article was created.

created.by.systemName

Article

CreatedBy.Id

The id of the user that created the Article.

created.by.displayName

Article

CreatedBy.Name

The name of the user that created the Article.

created.by.email

Article

CreatedBy.Email

The email of the user that created the Article.

description.short

Article

Summary

The summary of the Article.

language.tag

Article

Language

Only during create operation.

The language of the Article. Only languages active in connected Knowledge base.

language.translationOf

Article

Only during create operation.

The id of the master translation of this Article.

modified.date

Article

LastModifiedDate

Date and time of the last modification of the Article.

modified.by.systemName

Article

LastModifiedBy.Id

The id of the user that last modified the Article.

modified.by.displayName

Article

LastModifiedBy.Name

The name of the user that last modified the Article.

modified.by.email

Article

LastModifiedBy.Email

The email of the user that last modified the Article.

name.systemName

Article type folder

ArticleType

The entity name as used by Salesforce backend.

Category Group and Category

name

Article

UrlName

name.displayName

Article type folder

ArticleType without suffix

A human readable version of the entity name as displayed by Salesforce.

Category Group and Category

label

Article

Title

version.tag

Article

VersionNumber

The version number of the Article.

parent.id

Articles folder, Category Group

The XDIP of the repository root.

Article type folder

The XDIP of the Articles folder.

Category

The XDIP of the parent Category Group or Category.

Article

The XDIP of one of the parent entities of the Article.
The contentType decorator is not filled for Articles which are displayed as a result of requesting the scope path_children_entity of any Category. Otherwise the request would be much more resource expensive operation due to limitations of Salesforce API.

3.17.4. RPC Endpoints

As there is no entity status support in Xillio API yet, this connector supports retrieving and changing the publish status of Articles with the use of RPC.
The supported publish statuses are (case insensitive): draft, online, archived.
Changing status from draft to archived or from archived to online is not supported and will result in OperationNotAllowed error.

Article translations can only change status from online to draft, other changes happen automatically, when the master of the translation changes status.
Furthermore draft Article translations can be marked as "sent for publication" which determines, whether they are automatically published when their master is published.

Once an Article is archived its translations cannot be restored.
article
article/publishStatus

Used to get or set the publish status of the specified Article.

POST /v2/rpc/{configurationId}/article/publishStatus
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

xdip

String

The XDIP of the Article for which the operation is to be executed.

publishStatus

String

""

The desired publish status to be set; leave out or put empty string to get the status.

Returns PublishStatusResult: the result of the operation.

Response Fields

Path

Type

Description

xdipString

String

The current XDIP of the Article.

publishStatus

String

The current publish status of the Article.
Example Response
{
  "publishStatus" : "online",
  "xdip" : "xdip://configuration-id/Article/ka02p000000lKN1AAN"
}
article/translationSentForPublication

Used to get or set whether the specified draft Article translation is sent for publication.
If true, the draft translation is automatically published when its master is published.

POST /v2/rpc/{configurationId}/article/translationSentForPublication
------
HTTP/1.1 200 OK
Content-Type: application/json
Input Parameters

Input

Type

Default

Description

xdip

String

The XDIP of the draft Article translation for which the operation is to be executed.

isSetOperation

boolean

false

Whether to set the state; leave out or set false to get the state.

sentForPublication

boolean

false

Whether to send the translation for publication; only relevant when isSetOperation is true.

Returns TranslationSentForPublicationResult: the result of the operation.

Response Fields

Path

Type

Description

xdipString

String

The current XDIP of the Article translation.

publishStatus

String

The current publish status of the Article translation.

sentForPublication

boolean

Whether the Article translation is sent for publication.
Example Response
{
  "sentForPublication" : true,
  "publishStatus" : "draft",
  "xdip" : "xdip://configuration-id/Article/ka02p000000lLPNAA2"
}

3.17.5. RPC Models

PublishStatusResult

Result of getting or setting the publish status of an Article.

Fields

Field

Type

Description

xdipString

String

The current XDIP of the Article.

publishStatus

String

The current publish status of the Article.
TranslationSentForPublicationResult

Result of sentForPublication call.

Fields

Field

Type

Description

xdipString

String

The current XDIP of the Article translation.

publishStatus

String

The current publish status of the Article translation.

sentForPublication

boolean

Whether the Article translation is sent for publication.

3.18. SharePoint

SharePoint is a web-based collaborative platform.

Version(s): we support the latest version of SharePoint Online and we also support on-premise installations of SharePoint 2013 and 2016.

3.18.1. Configuration

The SharePoint connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the SharePoint instance.

authUrl

The URL of the Microsoft authentication endpoint.

Default: https://login.microsoftonline.com/extSTS.srf

username

The username of an account on SharePoint.

password

The password of the account.

domain

Windows NT Domain name, for SharePoint On-Premises only.

site

Site URL part which usually takes one of 2 forms: "sites/MySite" or just "MySite"

version

The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.

Default: 2016
The "site" and "baseUrl" can be determined when you enter the site home page using the SharePoint user interface. Url in the web browser should be in form of {baseUrl}/{site}/SitePages/Home.aspx For example: https://some.sharepoint.com/MySite/SitePages/Home.aspx
The "domain" property of the configuration should be left empty if you need to connect to SharePoint Online.
Example Configuration:
{
  "configurationType": "SharePoint",
  "config" : {
    "baseUrl" : "https://your-company.sharepoint.com",
    "username" : "username",
    "password" : "password",
    "site" : "MySite"
  }
}

3.18.2. Features and Limitations

Content Types

The SharePoint connector supports two types of the content: files and folders.

Currently, the connector is only capable of creating files with the default SharePoint Content Type.

The SharePoint connector does not support resolving the content type of previous versions of an entity.

Currently, this connector has limited support for the content types and metadata for configurations using SharePoint 2013.

File Versioning

The SharePoint connector supports "versions" and "versionList" scopes and through that allows you to retrieve metadata and content of the previous versions of the files as well. Uploading the new content of a file creates a new version but updating file’s metadata keeps the version.

However your SharePoint site needs to be configured to support file versioning. Otherwise the version of all files will be constant and updating a file’s content won’t create a new version.

Moving Folders

Due to the limitations in the SharePoint REST API the SharePoint connector does not support moving folders.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.18.3. Mappings

These are the decorators that are set for certain kinds of entities in SharePoint. Entities retrieved via SharePoint connector can be of kind SharePointFile or SharePointFolder. There are differences between values provided by SharePoint Online and on-premise versions of SharePoint and the connector always returns all the values that are available at the moment.

The content type decorator is ignored for write-operations and creation of entities with kind SharePointFile will result in creating a file with SharePoint’s default content type.

SharePoint mappings
Decorator Used By Read-only Field in SharePoint Description

container.hasChildren

SharePointFolder

True

This decorator is only set for folders, and value hasChildren indicates whether the requested folder contains any other folders or files. Due to the incorrect response from the SharePoint API, we always set it to true.

contentType.displayName

All entities

True

ContentType.Name

The human readable name of the content type associated with the requested SharePoint entity.

contentType.systemName

All entities

True

Computed from ContentType

The id of the list in which this content type resides followed by the id of the content type associated with the requested SharePoint entity.

created.date

All entities

True

TimeCreated

Date and time when the requested entity was created.

created.by

All entities

True

Author

Details of the user that created the requested entity.

description

All entities

False

CheckInComment

Description associated with the requested SharePoint entity.

file.rawExtension

SharePointFile

True (update Name decorator to change extension)

Computed from ServerRelativeUrl

The extension of the requested file, or an empty string if it has none.

file.extension

SharePointFile

True (update Name decorator to change extension)

Computed from ServerRelativeUrl

The sanitized extension of the requested file.

file.size

SharePointFile

True

Length

The size in bytes of the requested file.

fileSystem.path

All entities

True

Computed from ServerRelativeUrl

The path to the requested entity relative to the SharePoint site’s root.

modified.date

All entities

True

TimeLastModified

Last modified date and time of the requested entity.

modified.by

All entities

True

ModifiedBy

Details of the last user that modified the requested entity.

name.displayName

All entities

True

Name

The name of the requested entity.

name.systemName

All entities

False (update this decorator to rename entity or change file’s extension)

Name

The name of the requested entity.

parent.id

All entities

False (update this decorator to move entity to new location)

Computed from ServerRelativeUrl

The XDIP of the parent entity.

version.tag

SharePointFile

True

UIVersionLabel

Current version of the file.

3.19. SharePointV2

SharePoint is a web-based collaborative platform.

Version(s): we support the latest version of SharePoint Online only. This connector will not work with on-premise installation.

3.19.1. Configuration

The SharePoint connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the SharePoint instance.

authUrl

The URL of the Microsoft authentication endpoint.

Default: https://accounts.accesscontrol.windows.net

clientId

The SharePoint app client-id to access the API.

clientSecret

The SharePoint app client secret to access the API.

tenantId

ID of the SharePoint tenant.

site

Site URL part which usually takes one of 2 forms: "sites/MySite" or just "MySite"

version

The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.

Default: online

resourceId

Resource information identifying Microsoft application.

Default: 00000003-0000-0ff1-ce00-000000000000
The "site" and "baseUrl" can be determined when you enter the site home page using the SharePoint user interface. Url in the web browser should be in form of {baseUrl}/{site}/SitePages/Home.aspx. For example: https://some.sharepoint.com/MySite/SitePages/Home.aspx
Registering SharePoint Add-In (getting clientId and clientSecret)

  1. In browser, enter https://<tenant>.sharepoint.com/_layouts/15/appregnew.aspx, there will appear a 5 field form

  2. For lines Client Id and Client Secret, click the Generate button and store the output in your credential storage

  3. Name the configuration in the Title field

  4. For App Domain and Redirect URI enter some dummy values like localhost and https://localhost respectively, because we don’t use them

  5. Press the Create button

Each field of the form is mandatory
In this example and the example below, the process of registration and granting permissions is shown for all sites at once. If you want to register Add-In for a specific site, add its name between .com/ and /_layouts, e.g. https://<tenant>.sharepoint.com/<site>/_layouts/15/appregnew.aspx. Example for granting permissions will be presented below.
Granting the permission to Add-In

  1. In browser, enter https://<tenant>.sharepoint.com/_layouts/15/appinv.aspx, there will appear a form with 4 field and 1 text box.

  2. In the App Id field, enter your previously generated Client Id and press Lookup

  3. In the Permission Request XML text box enter the below XML

    <AppPermissionRequests AllowAppOnlyPolicy="true">
<AppPermissionRequest Scope="<value>" Right="<value>" />
</AppPermissionRequests>
    Possible values will be described in a note below

  4. Press Create

  5. You will be redirected to a page where you are asked if you trust the Add In to manage the site

  6. Press Trust it

As was mentioned in the previous note, you can grant permission to a specific site only by adding its name between .com/ and /_layouts, e.g. https://<tenant>.sharepoint.com/<site>/_layouts/15/appinv.aspx.
There are several possible scopes and rights. For most cases, we recommend using the Scope of "http://sharepoint/content/sitecollection" and Right of "Write". In case of any specific requirements, you can refer to the official Microsoft documentation regarding the scopes and rights.
Getting Tenant Id

  1. Go to https://<tenant>.sharepoint.com/<site>/_layouts/15/appprincipals.aspx

  2. In the App Display Name column, find the required application

  3. In the opposite column of App Identifier you will se a string like i:0i.t|ms.sp.ext|ClientId@TenantId where you can copy the value

Getting Resource Id

If you use SharePoint on-premises, please, contact your administrator to receive your Resource Id.

In case of SharePoint online, use the default value.

Example Configuration:
{
  "configurationType": "SharePointV2",
  "config" : {
    "baseUrl" : "https://your-company.sharepoint.com",
    "clientId" : "91391ad5-f8b4-4007-8e98-e2e695c0bcb2",
    "clientSecret" : "mQ1eApeD251QJkNBodWRGYCES2PnEhaq1+YoM0DHrw8=",
    "tenantId" : "f15805d7-484f-456f-b28d-5f3afae0f44b",
    "site" : "MySite"
  }
}

3.19.2. Features and Limitations

Content Types

The SharePoint connector supports two types of the content: files and folders.

Currently, the connector is only capable of creating files with the default SharePoint Content Type.

The SharePoint connector does not support resolving the content type of previous versions of an entity.

Currently, this connector has limited support for the content types and metadata for configurations using SharePoint 2013.

File Versioning

The SharePoint connector supports "versions" and "versionList" scopes and through that allows you to retrieve metadata and content of the previous versions of the files as well. Uploading the new content of a file creates a new version but updating file’s metadata keeps the version.

However, your SharePoint site needs to be configured to support file versioning. Otherwise, the version of all files will be constant and updating a file’s content won’t create a new version.

Moving Folders

Due to the limitations in the SharePoint REST API the SharePoint connector does not support moving folders.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.19.3. Mappings

These are the decorators that are set for certain kinds of entities in SharePoint. Entities retrieved via SharePoint connector can be of kind SharePointFile or SharePointFolder. There are differences between values provided by SharePoint Online and on-premise versions of SharePoint and the connector always returns all the values that are available at the moment.

The content type decorator is ignored for write-operations and creation of entities with kind SharePointFile will result in creating a file with SharePoint’s default content type.

SharePoint mappings
Decorator Used By Read-only Field in SharePoint Description

container.hasChildren

SharePointFolder

True

This decorator is only set for folders, and value hasChildren indicates whether the requested folder contains any other folders or files. Due to the incorrect response from the SharePoint API, we always set it to true.

contentType.displayName

All entities

True

ContentType.Name

The human readable name of the content type associated with the requested SharePoint entity.

contentType.systemName

All entities

True

Computed from ContentType

The id of the list in which this content type resides followed by the id of the content type associated with the requested SharePoint entity.

created.date

All entities

True

TimeCreated

Date and time when the requested entity was created.

created.by

All entities

True

Author

Details of the user that created the requested entity.

description

All entities

False

CheckInComment

Description associated with the requested SharePoint entity.

file.rawExtension

SharePointFile

True (update Name decorator to change extension)

Computed from ServerRelativeUrl

The extension of the requested file, or an empty string if it has none.

file.extension

SharePointFile

True (update Name decorator to change extension)

Computed from ServerRelativeUrl

The sanitized extension of the requested file.

file.size

SharePointFile

True

Length

The size in bytes of the requested file.

fileSystem.path

All entities

True

Computed from ServerRelativeUrl

The path to the requested entity relative to the SharePoint site’s root.

modified.date

All entities

True

TimeLastModified

Last modified date and time of the requested entity.

modified.by

All entities

True

ModifiedBy

Details of the last user that modified the requested entity.

name.displayName

All entities

True

Name

The name of the requested entity.

name.systemName

All entities

False (update this decorator to rename entity or change file’s extension)

Name

The name of the requested entity.

parent.id

All entities

False (update this decorator to move entity to new location)

Computed from ServerRelativeUrl

The XDIP of the parent entity.

version.tag

SharePointFile

True

UIVersionLabel

Current version of the file.

3.20. Sitecore

Sitecore is a CMS with additional marketing functionality that analyses customer data from multiple sources and makes it possible to show custom content.

Version(s): we support version 9 of Sitecore.

3.20.1. Configuration

The configuration for the Sitecore connector consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The base URL of the Sitecore instance.

username

The username of an account on Sitecore.

password

The password of the account.

database

Database on the Sitecore target system.

Valid values are core, master or web.

domain

The domain to which to connect.

ignoreExpiryDateOnCookies

Enable this setting to ignore the expiry date on cookies.

For development only. Omit in a production environment.

Default: false
Example Configuration:
{
  "configurationType": "Sitecore",
  "config" : {
    "baseUrl" : "https://sitecore.mydomain.com",
    "username" : "username",
    "password" : "password",
    "database" : "master",
    "domain" : "sitecore"
  }
}
Settings

To use the Sitecore connector you will need to change some settings.

  • You need to set Media.RequestProtection.Enabled in the file Sitecore.Media.RequestProtection.config to False.

  • You need to set Sitecore.Services.SecurityPolicy in the file Sitecore.Services.Client.config to "Sitecore.Services.Infrastructure.Web.Http.Security.ServicesOnPolicy, Sitecore.Services.Infrastructure".

  • You need to add the following line to the services block in the file Sitecore.Services.Client.config:
    <configurator type= "XillioSitecorePlugin.ItemService.XillioItemServiceConfigurator, XillioSitecorePlugin" />.

  • You need to replace the line:
    <add verb="*" path="sitecore_media.ashx" type="Sitecore.Resources.Media.MediaRequestHandler, Sitecore.Kernel" name="Sitecore.MediaRequestHandler"/>
    with the line:
    <add verb="*" path="sitecore_media.ashx" type="XillioSitecorePlugin.ItemService.XillioMediaRequestHandler, XillioSitecorePlugin" name="Sitecore.MediaRequestHandler"/>
    in the file Web.config.

Plugin

To use the Sitecore connector you will need to install the Xillio Sitecore Plugin into the Sitecore instance. This is done by adding the .dll file to the bin folder in your Sitecore site. This folder is located at: wwwroot\<your-site-name>\bin.

3.20.2. Features and Limitations

DisplayName is only updatable on the base language. Furthermore changing the DisplayName alone is not seen as a change by Sitecore and thus is not handled.

Languages

An entity can be translated to multiple languages. To do this you will have to call Create a New Entity or Create a New Entity With Contents on an already existing entity. This means that an entity in the Sitecore base language must already be present at the location that you are pointing to in your request. To add a translation simply set the language decorator to the language of the translation you want to create.

It is not allowed to create a new item in a different langauge than the base Sitecore language.

Plugin

When you don’t want to or are not able to use the above mentioned plugin some functionality of the Sitecore connector will be lost.

The following functions will cease to work:

  • Translation scope.

  • Version scope.

  • Create file in Media Library.

  • Update contents of file in Media Library.

Media Limitations

  • Items inside the Media Library are seen as a MediaItem. These items behave differently from normal items.

  • A MediaItem can only be created in the Media Library.

  • When creating a MediaItem using Create a New Entity With Contents the contents is the binary contents of the file that will be created. For other items (anything created outside of the Media Library) the contents is JSON containing raw data to be put into Sitecore. The same goes for the content of Update an Entity's Contents and Download an Entity's Contents.

  • Because of how Sitecore is designed it is not possible to have multiple versions of a media item that contain different content. It is possible to have multiple versions or language of a media item. These versions and languages can also have different metadata. But the contents of the media item will always be te content that was last uploaded to the item. Because of this the version of the media item is not incremented when Update an Entity's Contents is called.

Character Limitations

By default Sitecore has very strict rules on how its items can be named. The default settings for this are:

<setting name="InvalidItemNameChars" value="\/:?"<>|[]" /> and
<setting name="ItemNameValidation" value="^[\w\*\$][\w\s\-\$]*(\(\d{1,}\)){0,1}$" />

These settings can be found in the Sitecore.config file. The ItemNameValidation setting is most restrictive as it dictates the regex that a new name will have to comply with.

If a wider range of symbols is needed, you can change the settings. There are some character that are not supported by Sitecore even if they are allowed in the settings. These characters are:

< > | / \ "

When using one of the characters that is not allowed a Operation Not Allowed error will be thrown.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

translation_all_entity translation_all_reference

3.20.3. Mappings

Sitecore Mappings
Decorator Used By Field in Sitecore Description

container.hasChildren

All entities

Whether the item has children.

contentType.displayName

All entities

TemplateId

The template that the item uses.

contentType.systemName

All entities

TemplateId

The template that the item uses.

created.date

All entities

__Created

The time and date that the item was created.

created.by

All entities

__Created by

The user that created the item.

description

All entities

__Short description

The description of the item.

file.rawExtension

All entities

Extension

The extension of the media item.

file.extension

All entities

Computed from the raw extension.

file.size

All entities

Size

The size of the file in bytes.

fileSystem.path

hash.md5

hash.sha1

hash.sha256

language

All entities

ItemLanguage

The ISO 639-1 language of the item.

mimeType.type

All entities

Mime Type

The mime type of the requested file, based on the extension. If the extension is unknown, this is set to application/octet-stream.

modified.date

All entities

__Updated

The time and date the item was last modified.

modified.by

All entities

__Updated by

The user who last modified the item.

name.systemName

All entities

ItemName

The name of the item as used by Sitecore.

name.displayName

All entities

Title

The name of the item as displayed by Sitecore.

parent.id

All entities

Computed from the path of the item.

preview

version

All entities

ItemVersion

The version number of the item.

3.21. TRIM (HPE Content Manager)

This is the connector for the HPE Content Manager, which was previously named HPE Records Manager and HP TRIM. This system will be referred to as TRIM in the remainder of the documentation. TRIM is an electronic document and records management system.

Version(s): we support version 9.10 of TRIM.

3.21.1. Configuration

The configuration for this connector consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The absolute URL to the TRIM Service API.

username

The username of an account on TRIM.

password

The password of the account.

rootQuery

A TRIM query string, see Root Query.

Default: *
The connector currently only supports HTTP basic authentication, this can be configured on the IIS instance serving the TRIM Service API.
Example Configuration:
{
  "configurationType": "Trim",
  "config" : {
    "baseUrl" : "http://trim.xillio.com/HPECMServiceAPI/",
    "username" : "username",
    "password" : "password"
  }
}
Root Query

The rootQuery configuration parameter defines the set of children of the root entity. It is formatted as a TRIM query string which is passed to TRIM and determines what records to fetch. The following are common examples of queries:

Common query parameters:
Parameter name Description

* or All

All documents

container:[uri:1234]

Documents in container 1234

container:[]

Documents not in any container
The root query string will be passed to the q parameter of the TRIM Record endpoint. Refer to the TRIM documentation for more details on building queries.
The root query results will be fetched from TRIM using pagination. This uses the default page size configured in TRIM.

3.21.2. Features and Limitations

When using the TRIM connector, keep in mind the following:

  • TRIM record metadata can be retrieved using the /entities endpoint.

  • Electronic documents attached to TRIM records can be retrieved using the /contents endpoint.

  • The connector is read-only: only GET is supported on the endpoints mentioned above.

  • The children of the root entity can be specified using the Root Query.

  • TRIM record renditions are not currently supported.

  • HTTP basic is currently the only supported authentication method.

  • Versioning in the TRIM Connector is based on the revisions of the HP Trim system. These revisions are incremental but not necessarily starting from 0, and with the same step size. This should be noted when working with versions.

  • Retrieving the revisions of content is currently not supported.

  • This connector fully supports Named Queries.

Requesting Records and Their Documents

The TRIM connector can be used to retrieve TRIM Records and electronic documents attached to these records. The /entities endpoint will retrieve record metadata from TRIM, while the /contents endpoint can be used to retrieve records' electronic documents.

The URLs for the /entities and /contents endpoints follow a rigid structure when using the TRIM connector:

https://demo-tenant.xill.io/v2/entities/{configuration}/{type}/{id}
URL elements:
Field Type Description

configuration

String

The configuration id of the TRIM connector configuration.

type

String

Currently, only the record type is supported. This corresponds to TRIM objects of type Record.

id

Long

The id of the requested entity, corresponds to the id in TRIM.
The connector is read-only: only GET on the /entities and /contents endpoints is supported.
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

3.21.3. Mappings

These are the decorators that are set for TRIM. These only map to entities of kind Record, since that is the only entity kind currently supported.

TRIM mappings
Decorator field Used By Field in TRIM Description

container

Record

contentType.displayName

Record

TrimType

Internal type name

contentType.systemName

Record

TrimType

Internal type name.

created.date

Record

DateCreated.DateTime

Creation timestamp.

created.by.displayName

Record

RecordCreator.NameString.Value

Creator’s display name.

created.by.systemName

Record

RecordCreator.URI

Creator’s internal id.

created.by.email

Record

RecordCreator.LocationEmailAddress.Value RecordCreator.LocationInternetMailAddress.Value

Creator’s email.

description.shortDescription

Record

RecordDocumentDetails.Value

Description of the record’s state.

file.rawExtension

Record

RecordExtension.Value

Associated document file name extension, as is.

file.extension

Record

computed

Associated document file name extension, normalized.

file.size

Record

RecordDocumentSize.Value

Associated document size in bytes.

fileSystem

hash

language

mimeType.type

Record

RecordMimeType.Value

Associated document mime type.

modified.date

Record

DateLastUpdated.DateTime

Last modification timestamp.

modified.by.displayName

Record

LastUpdatedBy.NameString.Value

Last updater’s display name.

modified.by.systemName

Record

LastUpdatedBy.URI

Last updater’s internal id.

modified.by.email

Record

LastUpdatedBy.LocationEmailAddress.Value LastUpdatedBy.LocationInternetMailAddress.Value

Last updater’s email, LocationEmailAddress takes precedence.

name.systemName

Record

URI

Internal id.

name.displayName

Record

RecordTitle.Value

Title.

parent

preview

version.tag

Record

RecordRevisionNumber.Value

Version’s id.

3.22. WordPress

WordPress is a free and open-source content management system (CMS). Features include a plugin architecture and a template system.

Version(s): we support WordPress version 4.7 or higher.

3.22.1. Configuration

Authentication plugins

Xillio API WordPress connector requires either JWT Authentication for WPI-API plugin or Application Passwords plugin to be installed in target WordPress instance.

Having both of these plugins installed and active at the same time can lead to unexpected behavior.
"Application passwords" plugin

You can find the plugin here. This plugin is easy to install and provides users a new login password just for WP REST API. This new password cannot be used to login into WP Administration area.

After installing the plugin, navigate to Users - Your Profile - Application Passwords, here you can create your new WP REST API password.

To make Xillio API WordPress connector use this type of authentication, set authenticationType in configuration to basic.

"JWT Authentication for WP-API" plugin

You can find an installation guide here. This plugin extends the WP REST API with JSON Web Tokens Authentication as an authentication method.

After installing the plugin, make absolutely sure you override the default JWT secret. The CONFIGURATION section of the installation guide walks you through the process.

To make Xillio API WordPress connector use this type of authentication, set authenticationType in configuration to jwt

WordPress connector configuration

The WordPress connector configuration consists of the following values:

Configuration parameters:
Parameter Description

baseUrl

The URL of the WordPress site.

username

The username of an account on WordPress (with Administrator privileges).

password

The password of the account, or the generated application password, depending on the authentication type.

token

A WordPress OAuth2 token.

Optional if logging in with a username and password combination.

authenticationType

Specifies which authentication type the connector should use. Valid options are basic and jwt.

Default: jwt

These values allow the WordPress connector to connect and authorize with the target WordPress site.

The Administrator role is needed for the connector to be able to retrieve author information and more detailed metadata.

Example Configuration:
{
  "configurationType": "WordPress",
  "config" : {
    "baseUrl" : "https://demo.wp-api.org/",
    "username" : "username",
    "password" : "password"
  }
}

3.22.2. Features and Limitations

Entity types and hierarchy

The connector reveals all types of WordPress entities that are defined visible for the WordPress REST API.

The children of root are virtual collections grouping the entities of each of these types. The collections are strictly read-only. All entities of certain type can be retrieved by requesting the children of the respective collection.

On top of that WordPress pages can be organized in a tree structure defining parent page of a page. WordPress connector allows you to set and modify the parent page. To "unset" parent page set the parent of page to Pages collection.

When you delete a page that is set as parent of other pages then these pages will only lose their parent relation. They and their content still remain part of WordPress site and you can list them as children of Pages collection.

Example Hierarchy

  • /Pages

    • Page: Home

    • Page: About Us

      • Page: The Team (A sub-page of 'About Us')

    • Page: Contact

  • /Media

    • logo.png

    • welcome.jpg

  • /Posts

    • Post: Welcome to WordPress

    • Post: How to Connector to WordPress Using Xillio API

General limitations

All entities are created as "Draft" unless indicated otherwise using the workflow decorator. Currently, the WordPress connector does not support custom statuses. Furthermore, changing the visibility of a page or post, such as from public (which is shown as publish) to private, is only possible for the master post, not its translation. Changing to draft is possible for any page or post.

When creating or updating an entity, the value name.systemName is always converted internally by WordPress. The conversions consist of lowering upper case letters, replacing dots with dash, etc.

When an entity is deleted from WordPress, it is deleted permanently.

Media limitations

WordPress does not allow to create media entities without content and versioned media entities. In addition, media item’s binary content cannot be updated.

When creating a media entity the value name.systemName is used as a WordPress filename and must conform to internal WordPress rules. WordPress will refuse your request if an invalid filename is used.

Permalinks settings

A permalink is the web address used to link to your WordPress content. WordPress allows you to choose your permalink structure. Here you can learn what Permalinks settings are and how to change it.

If your WordPress server uses the 'Plain' setting for permalinks by default and our connector is not able to reach the API with these settings. Make sure to resolve this, either by picking another permalink setting (e.g. Numeric) or by adding server rewrite rule similar to the one in the example below.

Nginx rewrite rule example to bypass WordPress 'Plain' permalinks settings limitation:

location ~ ^/wp-json/ {
    rewrite ^/wp-json/(.*?)$ /?rest_route=/$1 last;
}
Translation scope support

Our WordPress connector can support translation scope if

  • target WordPress instance uses WPML plugin

  • target WordPress instance uses Xillio WPML REST API plugin

WPML is the WordPress Multilingual Plugin allowing to build and run multilingual sites. But WPML plugin does not extend WordPress Rest API to allow to retrieve multilingual details, so Xillio made a plugin to extend the WordPress API. Therefore you need one additional plugin. You can download Xillio WPML REST API Plugin version 1.3 from Cloudsmith.io.

It is a zip file that you can use to install the plugin manually. To install the plugin go to the Plugins section of the WP Admin, click "Add new", click "Upload Plugin", select the downloaded zip file and click "Install now". WordPress decompresses the file and installs the plugin automatically.

Note that the WPML plugin allows for creating custom language definitions. The value of the field code of language definition in WPML settings is what is used to fill the language decorator of entities and as such is required to be BCP-47 compliant. Existing entities with non-compliant language codes will be exposed having no language decorator, empty translation list and will not appear in translation list of other entities.

Creating new translations

Translations are supported for all types of entities.

When creating an entity you can also specify its language. To do so, just fill the value of language.tag with the WordPress code of the language. For example

{
    "kind" : "Page",
    "original" : {
        "name" : {
            "systemName" : "a-new-wordpress-page",
            "displayName" : "A new WordPress page"
        },
        "language": {
            "tag": "en"
        }
    }
}

If you don’t specify the value of language.tag, the entity will be created using the default language of the WordPress site.

To create a new translation of an existing entity, fill the value of language.translationOf with id of its desired master entity. For example

{
    "kind" : "Page",
    "original" : {
        "name" : {
            "systemName" : "neue-deutsch-seite",
            "displayName" : "Neue Deutsch Seite"
        },
        "language": {
            "tag": "de",
            "translationOf": "https://demo-tenant.xill.io/v2/entities/wordpress/pages/12345"
        }
    }
}

As values of language.tag always use language’s code as defined in your WordPress instance. You can find those codes in WordPress Admin in WPML section.

If WPML’s 'When uploading media to the Media library, make it available in all languages' option is checked, creation of new media will result in creation of media for each language that is configured in WPML plugin.

This is default WPML behaviour and it can be changed in WPML plugin settings.

Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

version_all_entity version_all_reference

translation

translation_all_entity translation_all_reference

3.22.3. Mappings

These are the decorators that are set for certain types in WordPress. Entities retrieved via WordPress can be of kind Page, Post or Media.

WordPress mappings
Decorator Used By Writeable Field in WordPress Description

contentType.systemName

Page, Post, Media

False

type

Type of the entity

contentType.displayName

Page, Post, Media

False

type

Type of the entity

container.hasChildren

Page

False

n/a

This decorator is set for Pages only, and value hasChildren is always set to true.

created.date

Page, Post, Media

True

date for write operations. date_gmt for read operations.

Date and time when the requested entity was published.

created.by.systemName

Page, Post, Media

False

author

Login name for the user that published the requested entity.

created.by.displayName

Page, Post, Media

False

name

Name of the user that published the requested entity.

created.by.email

Page, Post, Media

False

name

Email of the user that published the requested entity.

description.short

Media

True

description

Media entity description.

fileSystem.path

Media

False

media_details.file

The path to the requested media relative to the WordPress media root.

language.tag

Page, Post, Media

True

language

The language tag of the requested entity

language.translationOf

Page, Post, Media

Can be specified when creating an entity to create a translation relation between entities. However, it is ignored during entity updates.

translationOf

The id of the entity from which the requested entity was translated

mimeType.type

Media

False

mime_type

The mime type of the requested Media resource.

modified.date

Page, Post, Media

False

modified_gmt

Last modified date and time of the requested entity.

name.displayName

Page, Post, Media

True

title.renderer

Title of the requested entity.

name.systemName

Page, Post, Media

True

slug, id

Alphanumeric identifier for the entity unique to its type.

parent.id

Page, Post, Media

False for Post, Media, True for Page

Computed from XDIP or parent for Page that has a parent

The XDIP of the parent entity.

preview.html

Page, Post, Media

False

link

URL that can display the requested entity in the browser.

version.tag

Page, Post

False

id

The version number of the Page or Post.

workflow.status

Page, Post, Media

True

status

The publication status of an entity.

3.23. Zendesk

Zendesk Guide is a knowledge base for smart self-service. It helps companies increase customer and agent satisfaction, while also reducing support costs.

Version(s): we support the online version of Zendesk.

3.23.1. Configuration

Zendesk connector configuration

The Zendesk connector configuration consists of the URL of your Zendesk site, authentication credentials and optional permission information.

Configuration parameters:
Parameter Description

baseUrl

The URL of the target Zendesk site.

username

Depending on your authentication method, either of:

  • The email you are using to log in to the Zendesk web interface

  • The concatenation of your username and /token

password

Depending on your authentication method, either of:

  • The password you are using to log in to the Zendesk web interface

  • The API token assigned to the selected user

token

A Zendesk OAuth2 token.

Should not be provided if username and password are provided.

permissionGroupId

Optional.
The id of the management permission group that is used when creating articles.
Management Permission Groups

A management permission group defines which agents can create, update, archive, and publish articles. The articles created with Xillio API will have the permission group set to the one specified in the configuration.
The field permissionGroupId is optional. When left empty, the id of the built-in group Managers is used.

The credentials used in the configuration must belong either to an administrator or to a user who is a member of the used permission group. Otherwise, requests for creating articles will result in unexpected behavior.

For how to obtain a permission group id and more information, please see Zendesk documentation.

Authentication in Zendesk

Authenticating to Zendesk can be done in three different ways:

  • With a username and a password

  • With a username and an API token

  • With an OAuth access token

All three ways can be enabled or disabled in the Zendesk Support admin interface at Admin  Channels  API. Check or ask in advance what ways of authentication are actually allowed in your Zendesk instance.

Configuration with username and password
Please note that this way of authenticating to Zendesk API works only if the user account does not have two-factor authentication enabled.
Configuration parameters:
Parameter Description

baseUrl

The URL of the target Zendesk site.

username

The email you use to login to the Zendesk web interface.

password

The password you use to login to the Zendesk web interface.

permissionGroupId

Optional. The id of the management permission group that is used when creating articles.
Example Configuration:
{
  "configurationType": "Zendesk",
  "config": {
    "baseUrl": "https://yoursite.zendesk.com",
    "username": "your@email.com",
    "password": "password",
    "permissionGroupId": 2102353
  }
}
Configuration with API token

API tokens are different from OAuth tokens, which are detailed in the next section. API tokens are auto-generated passwords in the Support admin web interface.

As passwords, API tokens can be used to impersonate anyone in the account, including admins. Make sure to keep them secure, and delete any unused tokens.

API tokens are managed in the Support admin interface at Admin  Channels  API. The page lets you view, add, or delete tokens. More than one token can be active at the same time. Deleting a token deactivates it permanently.

Configuration parameters:
Parameter Description

baseUrl

The URL of the target Zendesk site.

username

The email you use to login to the Zendesk web interface appended with the string /token.

password

A valid API token.

permissionGroupId

Optional. The id of the management permission group that is used when creating articles.
Example Configuration:
{
  "configurationType": "Zendesk",
  "config": {
    "baseUrl": "https://yoursite.zendesk.com",
    "username": "your@email.com/token",
    "password": "svK9aw4O8wFqIj7qpTpml0Sgh9QXc1oK2q857IjN",
    "permissionGroupId": 2102353
  }
}
Configuration with OAuth token

OAuth provides a secure way for your application to access Zendesk data without having to store and use the passwords of Zendesk users, which is sensitive information.

You must register your application to generate OAuth credentials that your application can use to authenticate API calls to Zendesk.

You can find in depth description how to set up OAuth with Zendesk in this article.

Configuration parameters:
Parameter Description

baseUrl

The URL of the target Zendesk site.

token

A Zendesk OAuth2 token.

permissionGroupId

Optional. The id of the management permission group that is used when creating articles.
Example Configuration:
{
  "configurationType": "Zendesk",
  "config": {
    "baseUrl": "https://yoursite.zendesk.com",
    "token": "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
    "permissionGroupId": 2102353
  }
}

3.23.2. Features and Limitations

This connector has read, write and translation functionality. There is no custom metadata and search support.

User privileges

The Admin or Agent user privileges are required for many operations of this connector. Using credentials with lesser privileges might result in errors or not being able to access all the available content.

If you don’t provide the permissionGroupId in the configuration then the connector will set the permission group of the new articles to the "Managers" group. This will only succeed if you provide credentials of the user that is classified as Manager.

Entity types and hierarchy

The connector exposes three types of Zendesk entities: Categories, Sections, and Articles.

Zendesk entities are organized in a tree structure. Top level entities are Categories. Categories contain Sections and only Sections can contain Articles. The children entities (Articles and Sections) have always just one parent entity.

Binary content can be retrieved only from Articles.

Our connector also exposes three virtual collections called categories, sections and articles, grouping entities of the respective type. These collections are strictly read-only and can be reached by explicit request. All source language entities of one type can be retrieved by requesting the children of the respective collection.

For example, You can get information about all articles in their source language(s) with the following request:

GET /v2/entities/{configurationId}/articles?scope=path_children_entity
Translations

Zendesk employs the concept of source translation. An entity can be created in any language enabled in the Zendesk Guide administration UI. Once created, its language becomes the source language of this entity and all of its translations.

When an entity is deleted, all of its translations are deleted as well.

Translations cannot be moved on their own. Instead, all translations of an entity are moved together when the source entity itself is moved.

The source translation of an entity cannot be deleted, an attempt to do so will result in an Operation Not Allowed error.

Supported operations for translation:
Operation Supported Remark

Get translation entity

Use the id obtained from a translation scope call on the source entity.

Create new entity with language specified

Entity can exist in non-default language. The specified language becomes the source language for this entity.

Create new translation of existing entity

Use the field translationOf in the language decorator.

Delete translation entity

Non-source translations only.

Update translation entity

Name

Description

Parent

Not supported in Zendesk.

Language

Update entity language

Not supported in Zendesk.

Get binary content of translation

Articles only.

Update binary content of translation

Articles only.
Scopes
Supported return types:

  • entity

  • metadata

Supported scopes:
parents children all

path

path_children_entity path_children_reference

version

translation

translation_all_entity translation_all_reference

3.23.3. Mappings

These are the decorators that are set for certain types in Zendesk. Entities retrieved from Zendesk can be of kind Category, Section or Article.

Zendesk mappings
Decorator Used By Writable Field in Zendesk Description

contentType.systemName

Category, Section, Article

False

n/a

Type of the entity.

container.hasChildren

Category, Section

False

n/a

This decorator is set for Categories and Sections only, and value hasChildren is always set to true.

created.date

Category, Section, Article

False

created_at

Date and time when the requested entity was created.

created.by.systemName

Article

False

author_id

The name for the user that published the requested entity.

description.short

Category, Section

True

description

The entity description.

language.tag

Category, Section, Article

True

locale

The language of requested entity.

modified.date

Category, Section, Article

False

edited_at for Article, updated_at for Category and Section

Last modified date and time of the requested entity.

name.systemName

Category, Section, Article

True

title for Article, name for Category and Section

The entity name

parent.id

Section

True

category_id

The XDIP of the parent entity.

parent.id

Article

True

section_id

The XDIP of the parent entity.

preview.html

Category, Section, Article

False

html_url

URL that can display the requested entity in the browser.

workflow.status

Article

True

draft

The publication status of an article within Zendesk.