With the Xillio API we provide 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. We realise this by defining a set of operations which can be performed on every repository agnostically.

1. REST API

1.1. Overview

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.

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 we use an internal protocol called XDIP. 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 through the API. This can be done by starting at the root entities endpoint and requesting the children scope. 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}.

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. Downloading Files

The Xillio API allows you to download files that are stored in any content repository. You can download a file 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 you will receive a No Binary Content error.

When updating or downloading an entity’s contents you need 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.1.2. Updating Entities

The Xillio API allows you 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.1.3. Getting User-defined Metadata

The metadata scope allows you 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.1.4. 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.1.5. 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_.

For instance, 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.

1.2. Authorization and Authentication

Calling API endpoints requires an Authorization header with a Bearer token. To get a token, you can use the OAuth2 token endpoint at /oauth/token. Getting a token requires that you have:

  • Your client id and secret.

  • A username and password combination.

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 -u 'O1rlwSfUL25BW9JaVQ7m:demo-secret' -X POST -H 'Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1' -d 'grant_type=password&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.

Example Response
HTTP/1.1 200 OK

{
  "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsieGlsbGlvX2FwaSJdLCJ1c2VyX25hbWUiOiJkZW1vLXVzZXIiLCJzY29wZSI6WyJ1c2VyIiwidXNlcnMiLCJjb25maWd1cmF0aW9ucyIsImNvbnRlbnRzY3JpcHRzIiwicXVlcnk6Y29uZmlndXJlIiwicXVlcnk6ZXhlY3V0ZSIsInR5cGVzIiwidGVtcGxhdGVzIiwiZW50aXRpZXMiLCJjb250ZW50cyIsInRlbmFudCJdLCJleHAiOjE1NDUxNjUwNDEsImF1dGhvcml0aWVzIjpbIlJPTEVfQ09OVEVOVFNDUklQVF9BRE1JTiIsIlJPTEVfQ09ORklHX0FETUlOIiwiUk9MRV9FTlRJVFlfQURNSU4iLCJST0xFX0VOVElUWV9VU0VSIiwiUk9MRV9VU0VSX0FETUlOIiwiUk9MRV9RVUVSWV9BRE1JTiJdLCJqdGkiOiJhYmRiNTcyZC05YTc4LTQ1M2UtOTkzMi1hYzEzYzE0NDc1MjIiLCJjbGllbnRfaWQiOiJPMXJsd1NmVUwyNUJXOUphVlE3bSJ9.7DgpnIn7NpT0RQGsLcR5lZBONpWtcg5BmA9yY277dDI",
  "token_type" : "bearer",
  "expires_in" : 43199,
  "scope" : "user users configurations contentscripts query:configure query:execute types templates entities contents tenant",
  "jti" : "abdb572d-9a78-453e-9932-ac13c1447522"
}
Nearly all endpoints require an Authorization header with a Bearer access token (each endpoint documents the need for such a header, if any).

1.2.2. Passthrough Authorization

If you created a configuration using the passthroughAuthorization option set to true, the Passthrough-Authorization header is 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.

1.2.3. Scopes and Roles

The access_token must be provided in other API calls as a Bearer token in the Authorization header. All the API endpoint snippets in this documentation include an example header whenever it is required.

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.

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.3. /entities

1.3.1. List Available Repositories

List all available repositories as entities. When requesting the root entity (/entities) with the scope children, 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=children
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities?scope=children' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

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

Unauthorized

Access Denied

Connector Operation Failed

1.3.2. Get an Entity

Get a set of decorators containing metadata about the requested entity and/or its children, based on the given scopes. By default this endpoint only returns the entity itself.

1.3.2.1. 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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/deb5860d6e5c4783895b167b9add3a46/Documents?scope=entity&include=name,file' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/deb5860d6e5c4783895b167b9add3a46/Documents",
    "xdip" : "xdip://deb5860d6e5c4783895b167b9add3a46/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

1.3.3. Get an Entity's Metadata

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

1.3.3.1. 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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/bbbe23afa07f48cdabd240835fde37ec/Documents/Resume.docx?scope=metadata' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "metadata" : {
    "contentType" : {
      "displayName" : "FileData",
      "systemName" : "FileData",
      "properties" : {
        "lastModifiedTime" : {
          "value" : "2018-12-18T08:30:56.759982Z"
        },
        "lastAccessTime" : {
          "value" : "2018-12-18T08:30:56.759982Z"
        },
        "creationTime" : {
          "value" : "2018-12-18T08:30:56.759982Z"
        },
        "size" : {
          "value" : "360"
        },
        "isSymbolicLink" : {
          "value" : "false"
        },
        "isRegularFile" : {
          "value" : "true"
        },
        "fileKey" : {
          "value" : "(dev=4a,ino=22942606)"
        },
        "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

1.3.4. List an Entity's Children

Get a reference to the children 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=childList
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/1d5b87041b8f47c3b154e4d020d8a572/path/to/folder?scope=childlist' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

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

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

1.3.5. Get an Entity's Children

Get all of the entity’s children as full entity objects. Note that this is an expensive operation. Only request this scope if you need the children’s details. If you are looking for a listing instead, use the childList 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=children
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/c68038d4a52048799547cd18d4706fa7/subdirectory?scope=children' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

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

No Such Entity

No Such Configuration

Invalid XDIP

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

1.3.6. List an Entity's Translations

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=translationList
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/4a44f5513bb14aff80d51de7c444aff0/biography.pdf?scope=translationList' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "translationList" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/4a44f5513bb14aff80d51de7c444aff0/biography.pdf?language=cs-CZ",
    "tag" : "cs-CZ"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/4a44f5513bb14aff80d51de7c444aff0/biography.pdf?language=es-ES",
    "tag" : "es-ES"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/4a44f5513bb14aff80d51de7c444aff0/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

1.3.7. Get an Entity's Translations

Get all of the entity’s translations 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 looking for a listing instead, use the translationList 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=translations
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?scope=translations' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "translations" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?language=cs-CZ",
    "xdip" : "xdip://11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=cs-CZ"
      },
      "language" : {
        "tag" : "cs-CZ",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=cs-CZ"
      },
      "language" : {
        "tag" : "cs-CZ",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?language=fr-FR"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?language=es-ES",
    "xdip" : "xdip://11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=es-ES"
      },
      "language" : {
        "tag" : "es-ES",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=es-ES"
      },
      "language" : {
        "tag" : "es-ES",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?language=fr-FR"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/appointments.docx?language=es-MX",
    "xdip" : "xdip://11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=es-MX"
      },
      "language" : {
        "tag" : "es-MX",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/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/11a9deb72476479286fa8d329d54d89a?language=es-MX"
      },
      "language" : {
        "tag" : "es-MX",
        "translationOf" : "https://demo-tenant.xill.io/v2/entities/11a9deb72476479286fa8d329d54d89a/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

1.3.8. List an Entity's Versions

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=versionList
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/351c5a417b4f46e68174c5352a3de30b/biography.pdf?scope=versionList' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "versionList" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/351c5a417b4f46e68174c5352a3de30b/biography.pdf?version=1.0",
    "tag" : "1.0"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/351c5a417b4f46e68174c5352a3de30b/biography.pdf?version=1.1",
    "tag" : "1.1"
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/351c5a417b4f46e68174c5352a3de30b/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

1.3.9. Get an Entity's Versions

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 looking for a listing instead, use the versionList 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=versions
------
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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/9b9e5331579845a8bbd9e0861cef306a/appointments.docx?scope=versions' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "versions" : [ {
    "id" : "https://demo-tenant.xill.io/v2/entities/9b9e5331579845a8bbd9e0861cef306a/appointments.docx?version=1.0",
    "xdip" : "xdip://9b9e5331579845a8bbd9e0861cef306a/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/9b9e5331579845a8bbd9e0861cef306a?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/9b9e5331579845a8bbd9e0861cef306a?version=1.0"
      },
      "version" : {
        "tag" : "1.0"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/9b9e5331579845a8bbd9e0861cef306a/appointments.docx?version=1.1",
    "xdip" : "xdip://9b9e5331579845a8bbd9e0861cef306a/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/9b9e5331579845a8bbd9e0861cef306a?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/9b9e5331579845a8bbd9e0861cef306a?version=1.1"
      },
      "version" : {
        "tag" : "1.1"
      }
    }
  }, {
    "id" : "https://demo-tenant.xill.io/v2/entities/9b9e5331579845a8bbd9e0861cef306a/appointments.docx?version=2.0",
    "xdip" : "xdip://9b9e5331579845a8bbd9e0861cef306a/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/9b9e5331579845a8bbd9e0861cef306a?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/9b9e5331579845a8bbd9e0861cef306a?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

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

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

The parent of a new entity is given by {path} in the URL (see below). If no {path} is provided, the parent is "root".

1.3.10.1. 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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/4e4075f44528474baf55dd970b94584a/' -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
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 201 Created

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/4e4075f44528474baf55dd970b94584a/a-new-file.txt",
    "xdip" : "xdip://4e4075f44528474baf55dd970b94584a/a-new-file.txt",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2018-12-18T08:30:55.847Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 0
      },
      "hash" : {
        "md5" : "d41d8cd98f00b204e9800998ecf8427e",
        "sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2018-12-18T08:30:55.847Z"
      },
      "name" : {
        "systemName" : "a-new-file.txt",
        "displayName" : "a-new-file.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/4e4075f44528474baf55dd970b94584a"
      },
      "fileSystem" : {
        "path" : "/a-new-file.txt"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2018-12-18T08:30:55.847Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 0
      },
      "hash" : {
        "md5" : "d41d8cd98f00b204e9800998ecf8427e",
        "sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2018-12-18T08:30:55.847Z"
      },
      "name" : {
        "systemName" : "a-new-file.txt",
        "displayName" : "a-new-file.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/4e4075f44528474baf55dd970b94584a"
      },
      "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

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

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

Currently, we support creating files up to 1 gigabyte using this endpoint. For uploading larger filesizes see the Update an Entity's Contents endpoint.

1.3.11.1. 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: childList, children, translationList, translations, versionList, versions, entities, entityList (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/4f23b73fc0f549e89ab0717ada64c653/' -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
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 201 Created

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/4f23b73fc0f549e89ab0717ada64c653/a-new-file-with-contents.txt",
    "xdip" : "xdip://4f23b73fc0f549e89ab0717ada64c653/a-new-file-with-contents.txt",
    "kind" : "File",
    "original" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2018-12-18T08:30:55.907Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 28
      },
      "hash" : {
        "md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
        "sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
        "sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2018-12-18T08:30:55.907Z"
      },
      "name" : {
        "systemName" : "a-new-file-with-contents.txt",
        "displayName" : "a-new-file-with-contents.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/4f23b73fc0f549e89ab0717ada64c653"
      },
      "fileSystem" : {
        "path" : "/a-new-file-with-contents.txt"
      }
    },
    "modified" : {
      "contentType" : {
        "systemName" : "FileData",
        "name" : "FileData",
        "displayName" : "FileData"
      },
      "created" : {
        "date" : "2018-12-18T08:30:55.907Z"
      },
      "file" : {
        "rawExtension" : "txt",
        "extension" : "txt",
        "size" : 28
      },
      "hash" : {
        "md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
        "sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
        "sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
      },
      "mimeType" : {
        "type" : "text/plain"
      },
      "modified" : {
        "date" : "2018-12-18T08:30:55.907Z"
      },
      "name" : {
        "systemName" : "a-new-file-with-contents.txt",
        "displayName" : "a-new-file-with-contents.txt"
      },
      "parent" : {
        "id" : "https://demo-tenant.xill.io/v2/entities/4f23b73fc0f549e89ab0717ada64c653"
      },
      "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

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

1.3.12.1. 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: childList, children, translationList, translations, versionList, versions, entities, entityList (default: entity).

Example Using curl
$ curl 'https://demo-tenant.xill.io/v2/entities/473105985f5a418fa1b2517ff4e130af/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
Path Type Description

entity

Entity

This field contains the entity if the 'scope' parameter is left empty or contains 'entity'.

entities

Entity[]

This field contains an array of entities if the 'scope' parameter contains 'entities'.

entityList

Array

This field contains an array of reference to entities if the 'scope' parameter contains 'entityList'.

children

Entity[]

This field contains an array of all children of this entity if the 'scope' parameter contains 'children'.

childList

Array

This field contains an array of references to this entity’s children if the 'scope' parameter contains 'childList'.

translations

Entity[]

This field contains an array of all known translations of this entity if the 'scope' parameter contains 'translations'.

translationList

Array

This field contains an array of references to this entity’s translations if the 'scope' parameter contains 'translationList'.

versions

Entity[]

This field contains an array of all known versions of this entity if the 'scope' parameter contains 'versions'.

versionList

Array

This field contains an array of references to this entity’s versions if the 'scope' parameter contains 'versionList'.

metadata

Object

This field contains all user-defined metadata. The metadata is grouped in 'contentType' and 'templates'.

Example Response
HTTP/1.1 200 OK

{
  "entity" : {
    "id" : "https://demo-tenant.xill.io/v2/entities/473105985f5a418fa1b2517ff4e130af/updated-entity.xml",
    "xdip" : "xdip://473105985f5a418fa1b2517ff4e130af/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

1.3.13. Delete an Entity

Delete an entity, its contents, and its children (if any). If the entity does not exist, nothing happens.

1.3.13.1. 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/b632ef259d20499697dfc9eaf6a1e3ce/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

1.4. /queries

1.4.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/6fd097473542469786c0f5f2ea82b72b' -i -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

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

1.4.2.1. 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/87e2bc0d6d834ea2a527c60444c9456b/my_query?scope=entities&q_variable=value' -i -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

1.5. /contents

1.5.1. Download an Entity's Contents

Get the contents of an entity.

1.5.1.1. 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/5b3c732b48f447f7af08b5dee6756741/note.xml' -i -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

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

1.5.2.1. 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/5f6b894c4663411aa456414f3640de71/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

1.6. /types

1.6.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/2c1a9850067d41bbbd3878b8c459e130' -i -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/2c1a9850067d41bbbd3878b8c459e130/FileData"
} ]
Possible Errors

No Such Configuration

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

1.7. /templates

1.7.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/ea0183705d424439935c816893219dca' -i -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/ea0183705d424439935c816893219dca/contact"
}, {
  "systemName" : "employer",
  "displayName" : "Employer",
  "description" : "A person conducting a business or undertaking",
  "id" : "https://demo-tenant.xill.io/v2/templates/ea0183705d424439935c816893219dca/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/ea0183705d424439935c816893219dca/employee"
} ]
Possible Errors

No Such Configuration

Authorization Failed

Host Not Reached

Quota Exceeded

Unauthorized

Access Denied

Connector Operation Failed

1.8. /tenant

1.8.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 -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" : "2c91808267c06fbb0167c0701b3600e4",
  "name" : "demo-tenant",
  "displayName" : "demo-tenant",
  "description" : "Free form description of the demo-tenant tenant.",
  "availableConnectors" : [ "FileSystem" ]
}
Possible Errors

Unauthorized

Access Denied

1.9. /configurations

1.9.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 -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" : "4af754ecdaad4b348138073ccf09aaa9",
  "name" : "My filesystem configuration",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT1131111141730104881/"
  }
} ]
Possible Errors

Unauthorized

Access Denied

1.9.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/fd7e02ac39ba43f28db3c39fe6d9d712' -i -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" : "fd7e02ac39ba43f28db3c39fe6d9d712",
  "name" : "My filesystem configuration",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT8708199228983594294/"
  }
}
Possible Errors

No Such Configuration

Unauthorized

Access Denied

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

The configurationType for each connector can be found through the connectors endpoint.

1.9.3.1. 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/ApiDocumentationIT4069315836820898262/"
  }
}'
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/ApiDocumentationIT4069315836820898262/"
  }
}
Possible Errors

Invalid Configuration

Deprecated

Unauthorized Configuration Type

Unauthorized

Access Denied

Configuration Already Exists

1.9.4. Update a Configuration

Update one of your configurations, 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 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/2660e09f559548c8a1d2f1df938c2e5f' -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/ApiDocumentationIT8376559486296066417/"
  }
}'
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" : "2660e09f559548c8a1d2f1df938c2e5f",
  "name" : "\"New Name\"",
  "configurationType" : "FileSystem",
  "passthroughAuthorization" : false,
  "config" : {
    "rootPath" : "file:///tmp/ApiDocumentationIT8376559486296066417/"
  }
}
Possible Errors

No Such Configuration

Unauthorized Configuration Type

Invalid Configuration

Deprecated

Unauthorized

Access Denied

Connector Operation Failed

1.9.5. 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/5c3a17b499414c45902b9b64930eaa60' -i -X DELETE -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

1.10. /configurations/contentScripts

1.10.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/ded9de95671d44f8ada3ee3b910f8d2a/contentScripts' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 200 OK

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

Unauthorized

Access Denied

1.10.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/1223c7f80f0240668faebe836593ac4a/contentScripts/2c91808267c06fbb0167c0707c680215' -i -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 200 OK

{
  "id" : "2c91808267c06fbb0167c0707c680215",
  "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

1.10.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/2dd69c02c9bb4c058dbffe4293516962/contentScripts' -i -X POST -H 'Authorization: Bearer <<YOUR_TOKEN>>' -H 'Content-Type: application/json' -d '{
  "id" : "2c91808267c06fbb0167c07078fb01f7",
  "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" : "2c91808267c06fbb0167c07078fb01f7",
  "type" : "read",
  "mimeType" : "application/filedata",
  "description" : "This is the description of an example content script",
  "passEntity" : false
}
Possible Errors

Unauthorized

Access Denied

Invalid Configuration

1.10.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/0ccc1bc75b374dd180e1312c63a97ac6/contentScripts/2c91808267c06fbb0167c0707eb0022f' -i -X PUT -H 'Authorization: Bearer <<YOUR_TOKEN>>' -H 'Content-Type: application/json' -d '{
  "id" : "2c91808267c06fbb0167c0707eb0022f",
  "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" : "2c91808267c06fbb0167c0707eb0022f",
  "type" : "read",
  "mimeType" : "application/filedata",
  "description" : "This description has been updated",
  "passEntity" : false
}
Possible Errors

No Such Content Script

Unauthorized

Access Denied

1.10.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/207eb08573214719b0c23e5fd9204c57/contentScripts/2c91808267c06fbb0167c0707a0901ff' -i -X DELETE -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Example Response
HTTP/1.1 204 No Content
Possible Errors

Unauthorized

Access Denied

1.10.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/f4d7401e9ba64650ad332a14403a3f50/contentScripts/2c91808267c06fbb0167c0707c980217/code' -i -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

1.10.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/161fbffe05894c7cbe7f9563b0414f7e/contentScripts/2c91808267c06fbb0167c0707ee20231/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

1.11. /configurations/queries

1.11.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/73bb1a073b454a37965a287d17575320/queries' -i -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

1.11.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/be88db977cb14ce1bb9cf7340c85a91d/queries/my_query' -i -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

1.11.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/0ab5b9ebe54645ac9de25f9dc0c0ad09/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

1.11.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/e79ab12cbe294ee48952082934fd139f/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

1.11.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/d8633715030e46f6aa510e9f948008e6/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

1.12. /users

1.12.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 -H 'Authorization: Bearer <<YOUR_TOKEN>>'
Response Fields
Path Type Description

[]

Array

An array of all users.

Example Response
HTTP/1.1 200 OK

[ {
  "id" : "2c91808267c06fbb0167c0709a210289",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "CONFIG_ADMIN", "CONTENTSCRIPT_ADMIN", "USER_ADMIN", "ENTITY_USER", "ENTITY_ADMIN", "QUERY_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709a5b028a",
  "username" : "USER_ADMIN",
  "displayName" : "USER_ADMIN",
  "roles" : [ "USER_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709a96028b",
  "username" : "CONFIG_ADMIN",
  "displayName" : "CONFIG_ADMIN",
  "roles" : [ "CONFIG_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709ad0028c",
  "username" : "ENTITY_ADMIN",
  "displayName" : "ENTITY_ADMIN",
  "roles" : [ "ENTITY_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709b0a028d",
  "username" : "ENTITY_USER",
  "displayName" : "ENTITY_USER",
  "roles" : [ "ENTITY_USER" ]
}, {
  "id" : "2c91808267c06fbb0167c0709b45028e",
  "username" : "CONTENTSCRIPT_ADMIN",
  "displayName" : "CONTENTSCRIPT_ADMIN",
  "roles" : [ "CONTENTSCRIPT_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709b7f028f",
  "username" : "QUERY_ADMIN",
  "displayName" : "QUERY_ADMIN",
  "roles" : [ "QUERY_ADMIN" ]
}, {
  "id" : "2c91808267c06fbb0167c0709e8d0292",
  "username" : "new-user",
  "displayName" : "New user",
  "email" : "new-user@example.com",
  "roles" : [ "ENTITY_USER", "ENTITY_ADMIN" ]
} ]
Possible Errors

Unauthorized

Access Denied

1.12.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 -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" : "2c91808267c06fbb0167c0709a210289",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "CONFIG_ADMIN", "CONTENTSCRIPT_ADMIN", "USER_ADMIN", "ENTITY_USER", "ENTITY_ADMIN", "QUERY_ADMIN" ]
}
Possible Errors

No Such User

Unauthorized

Access Denied

1.12.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" : "2c91808267c06fbb0167c0709e8d0292",
  "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

1.12.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" : "2c91808267c06fbb0167c0709a210289",
  "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

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

1.13. /user

1.13.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 -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" : "2c91808267c06fbb0167c0702dc10115",
  "username" : "demo-user",
  "displayName" : "Demo user",
  "email" : "demo-user@example.com",
  "roles" : [ "CONFIG_ADMIN", "CONTENTSCRIPT_ADMIN", "USER_ADMIN", "ENTITY_USER", "ENTITY_ADMIN", "QUERY_ADMIN" ]
}
Possible Errors

Unauthorized

Access Denied

1.13.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" : "2c91808267c06fbb0167c0702dc10115",
  "username" : "demo-user",
  "displayName" : "Updated Demo User",
  "email" : "updated-demo-user@example.com",
  "roles" : [ "CONFIG_ADMIN", "CONTENTSCRIPT_ADMIN", "USER_ADMIN", "ENTITY_USER", "ENTITY_ADMIN", "QUERY_ADMIN" ]
}
Possible Errors

Invalid User

Unauthorized

Access Denied

1.14. /connectors

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

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

[]

Array

An array of information of all configurations in the connectors.

Example Response
HTTP/1.1 200 OK

[ {
  "configurationType" : "Bitbucket",
  "description" : "Bitbucket is a web-based version control repository hosting service for source code and development projects.",
  "config" : [ {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The Bitbucket username",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the Bitbucket user",
    "secret" : true
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : false,
    "description" : "The baseURL of the Bitbucket API",
    "secret" : false
  }, {
    "name" : "owner",
    "type" : "STRING",
    "required" : false,
    "description" : "The owner of the repositories. If this is not provided, the username is used as owner",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "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" : "token",
    "type" : "STRING",
    "required" : true,
    "description" : "The access token to be used for the request.",
    "secret" : true
  }, {
    "name" : "uploadUrl",
    "type" : "STRING",
    "required" : false,
    "description" : "URL of the Box API upload endpoint. (Default: https://upload.box.com/api/2.0).",
    "secret" : false
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : false,
    "description" : "The base URL of the Box REST API. (Default: https://api.box.com/2.0).",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "SUPPORTED"
  }
}, {
  "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",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED"
  }
}, {
  "configurationType" : "Egnyte",
  "description" : "Egnyte CONNECT: Secure File Sharing & Collaboration.",
  "config" : [ {
    "name" : "token",
    "type" : "STRING",
    "required" : true,
    "description" : "The access token that authorizes your request for a user",
    "secret" : true
  }, {
    "name" : "address",
    "type" : "STRING",
    "required" : true,
    "description" : "The Egnyte address",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "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" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the user that will be used to do operations on Episerver",
    "secret" : true
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The Address of the Episerver api extension.\nExample: http://12.3.17.100:49700/episerverapi",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of the user that will be used to do operations on Episerver",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "The user token for a user on Episerver. (a token lasts 5 minutes after which a new one will be requested)",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "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" : "STRING",
    "required" : true,
    "description" : "The address of the FileNet server api extension.\nExample: http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the user that will be used to do operations",
    "secret" : true
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of the user that will be used to do operations",
    "secret" : false
  }, {
    "name" : "stanza",
    "type" : "STRING",
    "required" : false,
    "description" : "The communication protocol that will be used to do operations.\nDefault: FileNetP8WSI",
    "secret" : false
  }, {
    "name" : "objectstore",
    "type" : "STRING",
    "required" : true,
    "description" : "The object store name that will be used to do operations",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "GoogleDrive",
  "description" : "A safe place for all your files.",
  "config" : [ {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : false,
    "description" : "The base URL of the google drive api. (Default: https://www.googleapis.com)",
    "secret" : false
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The clientId of your Google API application",
    "secret" : false
  }, {
    "name" : "oauthUrl",
    "type" : "STRING",
    "required" : false,
    "description" : "The token URL of the google authorization server. (Default: https://www.googleapis.com/oauth2/v4/token)",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "The access token",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "The token which is used to generate access tokens",
    "secret" : true
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The client secret of your Google API application",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "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" : "clientId",
    "type" : "STRING",
    "required" : false,
    "description" : "The client id of your application registered with Microsoft",
    "secret" : false
  }, {
    "name" : "redirectUri",
    "type" : "STRING",
    "required" : false,
    "description" : "The redirect uri is required when redeeming the authorization code for access tokens",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "The access token that authorizes your request for a user",
    "secret" : true
  }, {
    "name" : "refreshToken",
    "type" : "STRING",
    "required" : false,
    "description" : "The refresh token is used for getting access token",
    "secret" : true
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : false,
    "description" : "The client secret of your application registered with Microsoft",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "NOT_AVAILABLE"
  }
}, {
  "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" : "STRING",
    "required" : true,
    "description" : "The address of the OpenText Content Server api extension.\nExample: http://otcs.xillio.com",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the user that will be used to do operations",
    "secret" : true
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of the user that will be used to do operations",
    "secret" : false
  }, {
    "name" : "rootNode",
    "type" : "NUMBER",
    "required" : false,
    "description" : "The id of the root node (default is 2000)",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED"
  }
}, {
  "configurationType" : "SharePoint",
  "description" : "SharePoint is web-based, collaborative platform that integrates with Microsoft Office.",
  "config" : [ {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials to access SharePoint",
    "secret" : false
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The base URL of your SharePoint Online sites. Eg. https://our-company.sharepoint.com",
    "secret" : false
  }, {
    "name" : "site",
    "type" : "STRING",
    "required" : true,
    "description" : "Name of the site to connect to",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials to access SharePoint",
    "secret" : true
  }, {
    "name" : "domain",
    "type" : "STRING",
    "required" : false,
    "description" : "MS Windows Domain for SharePoint OnPremise only",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "SUPPORTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "SUPPORTED"
  }
}, {
  "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" : "STRING",
    "required" : true,
    "description" : "Base URL of the Sitecore target system",
    "secret" : false
  }, {
    "name" : "database",
    "type" : "STRING",
    "required" : true,
    "description" : "Database on the Sitecore target system",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials for the target Sitecore instance",
    "secret" : true
  }, {
    "name" : "domain",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials for the target Sitecore instance",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials for the target Sitecore instance",
    "secret" : false
  }, {
    "name" : "ignoreExpiryDateOnCookies",
    "type" : "BOOLEAN",
    "required" : false,
    "description" : "Enable this setting to ignore the expiry date on cookies. Do not use this setting in a production environment!",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "SUPPORTED",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "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" : "STRING",
    "required" : true,
    "description" : "The absolute URL to the TRIM system Service API, e.g. http://trim.xillio.com/HPECMServiceAPI/",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials for the target TRIM instance",
    "secret" : true
  }, {
    "name" : "rootQuery",
    "type" : "STRING",
    "required" : false,
    "description" : "Defines the set of records in the root for this connector",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "Credentials for the target TRIM instance",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "NOT_IMPLEMENTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "SUPPORTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_AVAILABLE",
    "versionScope" : "SUPPORTED",
    "metadataScope" : "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" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "The username of the user that will be used to do operations",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "The token that is used for authenticating requests with WordPress. (generated automatically)",
    "secret" : true
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The address of the WordPress site.",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "The password of the user that will be used to do operations",
    "secret" : true
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_IMPLEMENTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED"
  }
}, {
  "configurationType" : "Xde",
  "description" : "Connect to Xde, unlocking the full flexibility of our scripted connectors for systems such as Alfresco, Nuxeo, Documentum, Liferay, Confluence, Zendesk, AEM and GitHub.",
  "config" : [ {
    "name" : "targetPort",
    "type" : "STRING",
    "required" : false,
    "description" : "The port the target system is running on",
    "secret" : false
  }, {
    "name" : "type",
    "type" : "STRING",
    "required" : true,
    "description" : "Type of the Xill connector, i.e. the target system",
    "secret" : false
  }, {
    "name" : "token",
    "type" : "STRING",
    "required" : false,
    "description" : "Token used for OAuth. Is generated using the other credentials specified",
    "secret" : true
  }, {
    "name" : "targetPassword",
    "type" : "STRING",
    "required" : true,
    "description" : "Password for the target system",
    "secret" : true
  }, {
    "name" : "zendeskToken",
    "type" : "STRING",
    "required" : false,
    "description" : "The application token accompanying the zendesk username and password",
    "secret" : true
  }, {
    "name" : "tokenUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The absolute URL to the XDE authentication service token endpoint, e.g. http://xde.xillio.com/oauth/token",
    "secret" : false
  }, {
    "name" : "clientId",
    "type" : "STRING",
    "required" : true,
    "description" : "Client Id for the XDE OAuth2 authentication",
    "secret" : false
  }, {
    "name" : "targetUsername",
    "type" : "STRING",
    "required" : true,
    "description" : "Username for the target system",
    "secret" : false
  }, {
    "name" : "username",
    "type" : "STRING",
    "required" : true,
    "description" : "User name for the XDE OAuth2 authentication",
    "secret" : false
  }, {
    "name" : "documentumRepository",
    "type" : "STRING",
    "required" : false,
    "description" : "The repository to browse using the Documentum connector",
    "secret" : false
  }, {
    "name" : "clientSecret",
    "type" : "STRING",
    "required" : true,
    "description" : "Client secret for the XDE OAuth2 authentication",
    "secret" : true
  }, {
    "name" : "additionalConfig",
    "type" : "MAP",
    "required" : false,
    "description" : "Additional configuration for the Xill Connector: json structure of key-value pairs (one level, no nested objects)",
    "secret" : false
  }, {
    "name" : "cmisBindingType",
    "type" : "STRING",
    "required" : false,
    "description" : "Binding type for CMIS base connector",
    "secret" : false
  }, {
    "name" : "baseUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The absolute URL to the XDE project robots, e.g. http://xde.xillio.com/xps/api/1.0/projects/MyProject/robots",
    "secret" : false
  }, {
    "name" : "password",
    "type" : "STRING",
    "required" : true,
    "description" : "User password for XDE OAuth2 authentication",
    "secret" : true
  }, {
    "name" : "targetBaseUrl",
    "type" : "STRING",
    "required" : true,
    "description" : "The absolute URL to the target system's API",
    "secret" : false
  } ],
  "features" : {
    "read" : "SUPPORTED",
    "write" : "SUPPORTED",
    "contentTypeDiscovery" : "NOT_IMPLEMENTED",
    "namedQueries" : "NOT_IMPLEMENTED",
    "entityScope" : "SUPPORTED",
    "translationScope" : "NOT_IMPLEMENTED",
    "versionScope" : "NOT_IMPLEMENTED",
    "metadataScope" : "NOT_IMPLEMENTED"
  }
} ]

1.15. /system

1.15.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
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" : "2018-12-18T08:30:21.404Z"
}
Possible Errors

No Such Tenant

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

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

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:

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

{
  "message" : "No entity was found at xdip://59e4b5a7857aba0005a2822a/non/existing/entity",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.977Z",
  "errorType" : "NoSuchEntity",
  "parameters" : { }
}

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

{
  "message" : "No configuration was found for '59e4b5a7857aba0005a28228'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.973Z",
  "errorType" : "NoSuchConfiguration",
  "parameters" : { }
}

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

{
  "message" : "No content script was found for '59e4b5a7853aba0005a2822a'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.975Z",
  "errorType" : "NoSuchContentScript",
  "parameters" : { }
}

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

{
  "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" : "2018-12-18T08:30:15.930Z",
  "errorType" : "ContentScriptAlreadyExists",
  "parameters" : { }
}

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

{
  "message" : "No named query was found for 'queryName' on configuration '59e4b5a7353aba0005a2822a'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.978Z",
  "errorType" : "NoSuchQueryConfiguration",
  "parameters" : { }
}

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

{
  "message" : "The named query configuration 'queryName' on configuration with id '59e4b5a7353aba0005a2822a' already exists.",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2018-12-18T08:30:15.989Z",
  "errorType" : "QueryConfigurationAlreadyExists",
  "parameters" : { }
}

1.16.7. Invalid Template Variable

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

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

{
  "message" : "All template variables must be not empty and prefixed with 'q_'. Invalid variable names: variable",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.950Z",
  "errorType" : "InvalidTemplateVariable",
  "parameters" : { }
}

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

{
  "message" : "Invalid query variables. Missing: [q_my-missing-variable]. Unused: [q_my-unused-variable]",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.948Z",
  "errorType" : "InvalidQueryVariable",
  "parameters" : { }
}

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

{
  "message" : "The query could not be parsed by the target system: The query is not valid",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.946Z",
  "errorType" : "InvalidQuery",
  "parameters" : { }
}

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

{
  "message" : "Missing required field 'rootPath'",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.945Z",
  "errorType" : "InvalidConfiguration",
  "parameters" : { }
}

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

{
  "message" : "The configuration id 'customConfigurationId' already exists",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2018-12-18T08:30:15.926Z",
  "errorType" : "ConfigurationAlreadyExists",
  "parameters" : { }
}

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

{
  "message" : "No user with id 'myUsername' was found in tenant 'myTenant'",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.985Z",
  "errorType" : "NoSuchUser",
  "parameters" : { }
}

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

{
  "message" : "Supplied user was not valid: A user with the username 'myUsername' already exists.",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.954Z",
  "errorType" : "InvalidUserArgument",
  "parameters" : { }
}

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

{
  "message" : "'xdip://59e4b5a6857aba0005a28227/existing/entity' already exists.",
  "error" : "Conflict",
  "status" : 409,
  "timestamp" : "2018-12-18T08:30:15.940Z",
  "errorType" : "EntityAlreadyExists",
  "parameters" : { }
}

1.16.15. Missing Decorator

This error occurs when performing an operation which requires a certain decorator and the decorator is not present. For example, if you 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

{
  "message" : "Missing required decorator: parent",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.969Z",
  "errorType" : "MissingDecorator",
  "parameters" : { }
}

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

{
  "message" : "No content found at xdip://59e4b5a6857aba0005a28227/New%20Folder",
  "error" : "Method Not Allowed",
  "status" : 405,
  "timestamp" : "2018-12-18T08:30:15.971Z",
  "errorType" : "NoBinaryContent",
  "parameters" : { }
}

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

{
  "message" : "Something went wrong while running the content script.",
  "error" : "Unprocessable Entity",
  "status" : 422,
  "timestamp" : "2018-12-18T08:30:15.932Z",
  "errorType" : "ContentScriptFailed",
  "parameters" : { }
}

1.16.18. Operation Not Allowed

This error occurs when performing an operation that cannot complete due to limitations. For example, if you try to move 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

{
  "message" : "Files cannot contain other files",
  "error" : "Method Not Allowed",
  "status" : 405,
  "timestamp" : "2018-12-18T08:30:15.987Z",
  "errorType" : "OperationNotAllowed",
  "parameters" : { }
}

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

{
  "message" : "You are not allowed to create files in this folder",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2018-12-18T08:30:15.924Z",
  "errorType" : "AuthorizationFailed",
  "parameters" : { }
}

1.16.20. Host Not Reached

This error occurs when we were 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

{
  "message" : "Could not find host at https://hostisnotfound.com",
  "error" : "Service Unavailable",
  "status" : 503,
  "timestamp" : "2018-12-18T08:30:15.941Z",
  "errorType" : "HostNotReached",
  "parameters" : { }
}

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

{
  "message" : "Configuration type 'BitBucket' is not available for your tenant.",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2018-12-18T08:30:15.995Z",
  "errorType" : "UnauthorizedConfigurationType",
  "parameters" : { }
}

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

{
  "message" : "application/vnd.google-apps.folder is not supported by Episerver",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.996Z",
  "errorType" : "UnsupportedContentType",
  "parameters" : { }
}

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

{
  "message" : "Rate Limit exceeded Please retry after 42 seconds.",
  "error" : "Too Many Requests",
  "status" : 429,
  "timestamp" : "2018-12-18T08:30:15.991Z",
  "errorType" : "QuotaExceeded",
  "parameters" : { }
}

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

{
  "message" : "The maximum storage quota has been reached.",
  "error" : "Internal Server Error",
  "status" : 500,
  "timestamp" : "2018-12-18T08:30:15.943Z",
  "errorType" : "InsufficientStorage",
  "parameters" : { }
}

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

{
  "message" : "You are not authenticated",
  "error" : "Unauthorized",
  "status" : 401,
  "timestamp" : "2018-12-18T08:30:15.993Z",
  "errorType" : "Unauthorized",
  "parameters" : { }
}

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

{
  "message" : "Access is denied",
  "error" : "Forbidden",
  "status" : 403,
  "timestamp" : "2018-12-18T08:30:15.863Z",
  "errorType" : "AccessDenied",
  "parameters" : { }
}

1.16.27. Misconfigured System

The target system has unmet preconditions meaning we 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

{
  "message" : "The target system has disabled the 'integrations api'. Please enable the 'integrations api' feature to connect.",
  "error" : "Service Unavailable",
  "status" : 503,
  "timestamp" : "2018-12-18T08:30:15.962Z",
  "errorType" : "MisconfiguredSystem",
  "parameters" : { }
}

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

{
  "message" : "An internal server error occurred, please contact an administrator.",
  "error" : "Internal Server Error",
  "status" : 500,
  "timestamp" : "2018-12-18T08:30:15.928Z",
  "errorType" : "ConnectorOperationFailed",
  "parameters" : { }
}

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

{
  "message" : "No tenant with name 'my-tenant' was found",
  "error" : "Not Found",
  "status" : 404,
  "timestamp" : "2018-12-18T08:30:15.983Z",
  "errorType" : "NoSuchTenant",
  "parameters" : { }
}

1.16.30. 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 query 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

{
  "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" : "2018-12-18T08:30:15.956Z",
  "errorType" : "InvalidXDIP",
  "parameters" : { }
}

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

{
  "message" : "The connector 'DeprecatedConnector' is deprecated. Please use 'NotDeprecatedConnector'",
  "error" : "Unprocessable Entity",
  "status" : 422,
  "timestamp" : "2018-12-18T08:30:15.934Z",
  "errorType" : "Deprecated",
  "parameters" : { }
}

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

{
  "message" : "Scope 'my:scope' is not valid. Valid scopes are: childList, children, translationList, translations, versionList, versions, entities, entityList. Valid relationship names in the 3-part form of <relationship>_<navigation>_<return type> are: path, version, translation",
  "error" : "Bad Request",
  "status" : 400,
  "timestamp" : "2018-12-18T08:30:15.982Z",
  "errorType" : "NoSuchScope",
  "parameters" : { }
}

2. Entities

The Xillio API describes entities from many different content repositories, and allows you 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. You might find this value in error messages.

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:50Z"
      },
      "modified" : {
        "date" : "2017-08-22T14:24:50Z"
      },
      "name" : {
        "systemName" : "root",
        "displayName" : "root"
      },
      "fileSystem" : {
        "path" : "/"
      }
    },
    "modified" : {
      "container" : {
        "hasChildren" : true
      },
      "created" : {
        "date" : "2017-08-22T14:24:50Z"
      },
      "modified" : {
        "date" : "2017-08-22T14:24:50Z"
      },
      "name" : {
        "systemName" : "root",
        "displayName" : "root"
      },
      "fileSystem" : {
        "path" : "/"
      }
    }
  }
}

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

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.

2.1.1. Container

The container decorator signifies an entity that can have children. This decorator must be absent if it is impossible for the object to have children.

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

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

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

2.1.3. Created

The created decorator signifies when an entity was created.

The Created Decorator
{
  "created": {
    "date": "2017-08-22T14:29:53+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.

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

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

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

STRING

rawExtension

The extension of the file as found on the filesystem.

STRING

size

The size of the file in bytes.

NUMBER

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

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

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

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

2.1.8.1. Notes

System specific language tags are converted into BCP-47 compliant tags. If that fails it will return a tag formatted as 'x-<customlanguage>', where <customlanguage> is the system specific language tag.

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

2.1.10. Modified

The modified decorator signifies when an entity was last modified.

The Modified Decorator
{
  "modified": {
    "date": "2017-08-22T14:29:53+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.

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

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

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

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

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

2.1.13.1. Notes

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

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

2.1.14.1. Notes

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

3. Connectors

You can find the current capabilities of the connectors on: https://api.xill.io/connectors

Connector Descriptions

Connector Descriptions start with the name of the connector, a bit of information on the system the connector is for and a short overview of the version(s) of the system that are supported through this connector. A version not being supported does not necessary mean that the connector will not work at all, but the behavior could be unpredictable and we will not be able to help you with resolving issues.

Configuration

The Configuration section describes all you need to do to configure the connector to work with your system. The content of this section is very system dependent.

Features and Limitations

The Features and Limitations section describes what you can expect from the connector. We try to make connectors as complete as possible, but in some cases the system just doesn’t support certain functionality or behaves a bit different from what you might expect.

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 colums 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. 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.1.1. Configuration

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

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

baseUrl

The absolute URL to a Bitbucket v2 cloud service (defaults to https://api.bitbucket.org/2.0).

username

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

password

The corresponding password.

owner

The owner is used to select repositories. When not provided, the connector will use the username as owner. Please note that the repositories shown with this setting, are just the ones owned by owner, not the repositories to which username has access to.

Example Configuration
{
  "configurationType": "Bitbucket",
  "config" : {
    "baseUrl" : "https://api.bitbucket.org/2.0",
    "username" : "<Bitbucket-username>",
    "password" : "<Bitbucket-password>",
    "owner": "<Bitbucket-owner>"
  }
}

3.1.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. The XDIP for an entity can be defined as xdip://<configuration>/<repository>/<branch>/<path> where path can be a concatenation of zero or more folder names and zero or one file name.

This connector has the following limitations:

  • Only basic authentication is supported using this connector.

  • Only read operations are allowed on repositories and branches.

  • With a git repository, it is possible to have one or more slashes (/) in a branch name. This would raise a conflict with the way we have implemented the url like references to content with XDIPs. To overcome this limitation, we replace a slash in a branch name with a space. e.g. branch feature/new-feature-branch becomes feature%20new-feature-branch. The original.name.displayName property will show the actual name of the branch.

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

3.1.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 - it’s commit id.

3.2. Box

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

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

3.2.1. Configuration

The configuration for the Box connector consists only of the Box access token. The access token grants access to the content of a Box account and is needed for all requests to the Box API.

3.2.1.1. Setting up the Box application

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

  1. Register your application within Box.

  2. Set your redirect URI (in the Configuration section of your application settings).

  3. Select your Scopes.

  4. Make a note of both your client_id and client_secret.

3.2.1.2. Authorize the Box application

Box uses OAuth2, and therefore requires a user to log in to their Box account and grant your application permission to access their files and folders. This has to be done through the Box API at https://account.box.com/api/oauth2/authorize?client_id={{clientId}}&redirect_uri={{redirect_uri}}&response_type=code where client_id and redirect_uri (url-encoded) are equal to the same ones as defined in the Box application.

3.2.1.3. Request an access token

The user is then forwarded to the redirect_uri where the refresh token is located in the query parameter code in the uri. The user could now request an access token at POST https://api.box.com/oauth2/token with the client_id, client_secret, code (refresh token) and grant_type=authorization_code as the content of the body. This request will return a new refresh_token and an access_token which is in the configuration in order to make authenticated calls to Box.

The access token is valid for 60 minutes until it needs to be refreshed. To do so, the user has to perform the /oauth2/token request again with the previous refresh_token.

The Box Developers portal provides a detailed walkthrough which holds more information on Box’s authentication. It also provides useful examples of the whole OAuth2 protocol.

3.2.2. Features and Limitations

To use the Box connector, your application needs to handle the refreshing of the token and constantly update the corresponding Xillio API configuration.

Currently, this connector supports operations on files and folders. This includes special files as Box Note as well.

Example Configuration
{
  "configurationType": "Box",
  "config": {
    "token": "<your-token-here>"
  }
}

If you try to use the configuration with an expired, invalid or no token at all, the Xillio API will respond with an Authorization Failed error.

Example of an Authorization Failed Error
{
  "message": "Box authentication expired or invalid.",
  "error": "Forbidden",
  "status": 403,
  "timestamp": "2017-12-01T09:36:09.797+01:00",
  "errorType": "AuthorizationFailed",
  "path": "/v2/entities/5a1fe32532d528116ce2eb0c",
  "parameters": {
    "scope": [
      "children"
    ]
  }
}

3.2.3. Mappings

Box Mappings
Decorator Used By Field in Box Description

container.hasChildren

Folder

Whether the entity has children.

contentType

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

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

All entities

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

version

File

version_number

The version number as shown in Box.

3.3. 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.3.1. Configuration

The configuration for the Dropbox connector consists only of an API token. To generate a token visit https://www.dropbox.com/developers/apps and click the "Create app" button. Select the Dropbox API (the Dropbox Business API is not supported by this connector), select the type of access, enter a name and click "Create app". Then to get the token click the "Generate" button under "Generated access token".

Example Configuration
{
  "configurationType": "Dropbox",
  "config": {
    "token": "<your-token-here>"
  }
}

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

3.3.2.1. 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\"}"
}
3.3.2.2. 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.3.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.

3.3.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.4. 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 on-line version of Egnyte.

3.4.1. Configuration

The configuration for the Egnyte connector consists of both an Egnyte access token and the address your domain can be reached at. The access token grants access to the content of a certain Egnyte domain and is needed for all requests to Egnyte.

Example Configuration
{
  "configurationType": "Egnyte",
  "config": {
    "token": "<your-token-here>",
    "address": "https://example.egnyte.com"
  }
}

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 yet have one.

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

  3. Once the API key has been approved authenticate with the domain from step 1 (for more information see https://developers.egnyte.com/docs/read/Public_API_Authentication).

  4. The access_token can now be used in the connector configuration.

3.4.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).

3.4.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.5. 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.5.1. Configuration

To configure Episerver you need the following:

  • The username of an authenticated Episerver user.

  • The password of the aforementioned user.

  • The URL that the Episerver API can be found at.

  • Optionally an acquired API token can also be provided.

The username and password will be used to generate a token if no token has been provided.
The URL needs to have "/episerverapi" at the end (because that is how the api can be reached).

Example Configuration
{
  "configurationType": "Episerver10",
  "config": {
    "username": "<your-username-here>",
    "password": "<your-password-here>",
    "baseUrl": "<the-url-of-your-episerver>",
    "token": "<your-token-here>"
  }
}
3.5.1.1. 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.5.2. Features and Limitations

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

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

3.5.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.6. IBM FileNet

IBM FileNet Content Manager is a document management engine for enterprise content, security and storage features plus process management capabilities. Our FileNet connector allows to connect 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.6.1. Configuration

The FileNet connector configuration require the following values:

Input values for configuration
Name Description

baseUrl

The address of the FileNet server API extension. Example: http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM.

username

Credentials to authorize with the FileNet target system.

password

Credentials to authorize with the FileNet target system.

objectstore

The name of the object store to connect to.

stanza

The communication protocol that will be used to do operations. If you are not sure about what value to use for stanza then leave it empty. The FileNet connector will use "FileNetP8WSI" (Web Service Interface) by default.

With one configuration you can access only entities from one object store.

3.6.2. Features and Limitations

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

3.6.2.1. Multiple parents of a document

FileNet supports documents (not folders) to have multiple parents at the same time. The Xillio API 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 internal ID.

Though our FileNet connector cannot deliver multiple parents of a document it will allow you to add or remove additional parents. The following table shows how to add, remove or update parent reference of the document with FileNet connector.

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.

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

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.

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

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

3.6.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.7. Google Drive

Google Drive provides cloud storage and file backup.

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

3.7.1. Configuration

Google Drive uses OAuth2 to secure the web api. This means you will require an app (as described below) which you can use to generate access tokens.

3.7.1.1. 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'.

3.7.1.2. Get a Refresh Token

Now you have created the API app. You can use it to create a refresh token.

Send your user to the following url:

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)
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 your with a code that can be used to get a new token, or token with will return a short-lived token.
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 urn:ietf:wg:oauth:2.0:oob to prompt the user to manually copy the code.
4 You can find your client_id in your Credentials overview.
5 The https://www.googleapis.com/auth/drive scope is required to manipulate and inspect files in the user’s drive.

When the user accepts the requested scopes, the request contains a code. You can use this code to generate a refresh token.

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 received in the previous step.

If everything went well, the response looks like this:

{
 "access_token": "<< ACCESS_TOKEN >>",  (1)
 "token_type": "Bearer",
 "expires_in": 3600,
 "refresh_token": "<< REFRESH_TOKEN >>" (2)
}
1 This is a short-lived token which you can use to make request.
2 This is a refresh token which you can use in your configuration to allow the Xillio API to refresh your access tokens.
Example configuration
{
  "configurationType": "GoogleDrive",
  "config": {
    "refreshToken": "1/CWEaui3J_4X5sQlYGP0S4lwZ6er59YsWx6jiPrflAiA",
    "clientId": "826514876365-m4hltubt3d3tvu7iu2875m5pvum0fm8l.apps.googleusercontent.com",
    "clientSecret": "BAHEfQjVAN-GVZ9IV9EPbPg_"
  }
}

By providing a refresh token, client id and client secret, the Xillio API will try to refresh the access token when it is expired. If the connector operation does not concern binary data, the Xillio API will then retry the request with the new access token.

3.7.2. Features and Limitations

There are currently certain limits to the Google Drive connector.

The filetypes from Google (Docs, Sheets, Slides etc.) are not supported by the connector. When using the connector with these kind of files please keep in mind that unexpected behaviour can occur. Also some operations are not working on these files.

Google Drive file limitation
Type Get Get Content Create Delete UpdateContent Update

Any non-Google file

Google file (Docs, Sheets, Slides)

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

3.7.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.8. 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.8.1. Configuration

The OneDrive connector configuration consists of the following values:

Input values for configuration
Name Description

Access token

Token used to access a user’s OneDrive account.

Refresh token

Token used to get a new token when the original token has expired.

Client ID

The client ID of your application registered with Microsoft.

Client Secret

The client secret of your application registered with Microsoft.

Redirect URI

URI where the user is redirected to after authorization is completed.

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 how you design your application. We expect one of the following two approaches to be used:

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

2. 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 not to set token in this type of OneDrive configuration.

As long as the refresh token will be 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.

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

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

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
1. 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 longterm 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://myapp.com/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.

2. 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://myapp.com/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.

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

There are currently certain limits to the OneDrive connector. It does not provide access to

  • "Shared Items" - files and folders that have been shared with the owner of the Drive

  • OneNote notebooks

Note: Deleting items will move the items to the recycle bin instead of permanently deleting the item.

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

Computed from childCount

This decorator is only set for folders, and value hasChildren indicates whether the requested folder contains any other entities.

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

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.8.4. Additional information

Deleting items will move the items to the recycle bin instead of permanently deleting the item.

There are currently certain limits to the OneDrive connector. It does not provide access to:

  • "Shared Items" - files and folders that have been shared with the owner of the Drive

  • OneNote notebooks

3.9. Opentext

Version(s): we support version 16.2 of Opentext Content Server.

3.9.1. Configuration

The configuration for the Opentext connector consists of 3 required and 1 optional parameter.

Example Configuration
{
  "configurationType": "Opentext",
  "config": {
    "username": "<your-username>",
    "password": "<your-password>",
    "baseUrl": "<url-of-the-opentext-server>",
    "rootNode": "<id-of-the-root-node>"
  }
}

rootNode is an optional parameter for the OpenText node ID of the root of the workspace you want to access. Default value of this parameter is 2000, common ID of the root of the Enterprise workspace. However ID of this node can differ across Content Server instances and you might need to set it up.

3.9.2. Features and Limitations

  • Some content types can be created by API (e.g. 0 = Folder and 144 = Document) while some cannot (e.g. 356 = Blog)

  • Special characters in queries must be escaped manually.

3.9.2.1. 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" : {
            ...
      }
    },
    ...
  ]
}

3.9.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.10. 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.10.1. Configuration

To connect to SharePoint on-premise installation create SharePoint connector configuration with following values

Input values for SharePoint OnPremise configuration
Name Description

baseUrl

The base URL of your SharePoint installation. E.g. https://sharepoint.our-company.com.

site

Name of the site you want to connect to.

username

Credentials to access SharePoint.

password

Credentials to access SharePoint.

domain

Windows NT Domain name.

To connect to SharePoint Online create SharePoint connector configuration with following values

Input values for SharePoint Online configuration
Name Description

baseUrl

The base URL of your SharePoint Online sites. E.g. https://our-company.sharepoint.com.

site

Name of the site you want to connect to.

username

Credentials to access SharePoint.

password

Credentials to access SharePoint.

The "domain" property of the configuration should be left empty if you need to connect to SharePoint Online.

3.10.2. Features and Limitations

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

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

3.10.2.3. Moving Folders

Due to the limitations in the SharePoint REST API the SharePoint connector does not support moving folders.

3.10.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.11. 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.11.1. Configuration

The configuration for the Sitecore connector consists of five elements. A URL, username, password, the domain and the database. The database can be either: core, master or web.

Example Configuration
{
  "configurationType": "Sitecore",
  "config": {
    "username": "<your-username>",
    "password": "<your-password",
    "domain": "<your-domain-or-site>",
    "database": "<the-database-that-is-used>",
    "baseUrl": "<the-url-that-sitecore-can-be-found-on>"
  }
}
3.11.1.1. 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.

3.11.1.2. Plugin

To use the Sitecore connector you will need to install the XillioSitecorePlugin 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.11.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.

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

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

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

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

3.11.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.12. 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.12.1. Configuration

The configuration for this connector consists of a URL to the TRIM Service API, user credentials and a query to define the children of the root entity (explained in Root Query).

The connector currently only supports HTTP basic authentication, this can be configured on the IIS instance serving the TRIM Service API.
Configuration:
Parameter Description

username

The username of the user on the TRIM system.

password

The corresponding password.

baseUrl

The absolute URL to the TRIM Service API (e.g. https://trim-instance.xill.io/HPECMServiceAPI).

rootQuery

A TRIM query string, see Root Query.

Example Configuration:
{
  "configurationType": "Trim",
  "config": {
    "baseUrl": "http://trim.xillio.com/HPECMServiceAPI/",
    "username": "xillio",
    "password": "my password",
    "rootQuery": "*"
  }
}
3.12.1.1. 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.12.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.

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

3.12.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.13. 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 the version of WordPress having compatible REST API with version 4.9.X.

3.13.1. Configuration

3.13.1.1. "JWT Authentication for WP-API" plugin

Xillio API WordPress connector requires the JWT Authentication for WP-API plugin to be installed in target WordPress instance. 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.

3.13.1.2. WordPress connector configuration

The WordPress connector configuration consists of the following values:

Input values for configuration
Name Description

baseUrl

The URL of the target WordPress site. Example: https://demo.wp-api.org/

username

The username of a WordPress user which has Administrator privileges.

password

The password for WordPress user.

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": "<the-url-that-wordpress-can-be-found-on>",
    "username": "<your-username>",
    "password": "<your-password"
  }
}

3.13.2. Features and Limitations

3.13.2.1. Entity types and hierarchy

The connector reveals three types of WordPress entities: pages, posts and media.

There are three virtual collections called Pages, Posts and Media grouping the entities of respective type. These collections are returned as children of root and they are strictly read-only. All entities of the 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

3.13.2.2. General limitations

At the moment the WordPress connector does not implement versioning, language support and metadata scope.

All pages and posts are created as "Published".

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.

3.13.2.3. Media limitations

WordPress does not allow to create media entities without content. In addition, media item’s binary content cannot be updated. of media item in WordPress.

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.

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 'Default' setting for permalinks, our connector will not be able to reach the API. To resolve this, either pick another permalink setting or add a rewrite rule in your server.

For nginx, you can find an example below

location ~ ^/wp-json/ {
    rewrite ^/wp-json/(.*?)$ /?rest_route=/$1 last;
}

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

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.

mimeType.type

Media

False

mime_type

The mime type of the requested Media resource.

modified.date

Page, Post, Media

False

modified

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.

3.14. XDE

The Xill Distributed Environment (XDE) runs tier 2 connectors for easy integration with the Xillio API. Their usage in the Xillio API is exactly the same as native connectors, but the configuration involves interfacing with an XDE instance, as is explained below.

The following connectors are exposed through XDE:

Configuration

The XDE connector configuration consists of the following parts:

  • Attributes configuring the access to an XDE cluster, containing the same values for each target system

  • Attributes configuring the access to the target system, containing system specific values

Common Configuration:
Parameter Description

username

The OAuth2 username of the user on the XDE cluster.

password

The corresponding password.

tokenUrl

The OAuth2 endpoint, on the XDE auth-service, to get a token.

clientId

The OAuth2 client id.

clientSecret

The corresponding client secret.

baseUrl

The URL on the XDE cluster of the project and folder in which the robots are contained.

3.15. AEM

Configuration

Configuration:
Parameter Description

type

The constant "aem".

targetUsername

Username for authentication to AEM.

targetPassword

User password for authentication to AEM.

targetBaseUrl

AEM base URL.

Example Configuration:
{
  "name": "AEM Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "aem",
    "targetUsername": "aem_username",
    "targetPassword": "aem_password",
    "targetBaseUrl": "http://aem.xillio.com"
  }
}

Features and Limitations

  • getContents returns the AEM metadata in JSON format.

  • updateEntity is not supported.

3.16. Alfresco

Configuration

Configuration:
Parameter Description

type

The constant "alfresco".

targetUsername

Username for authentication to Alfresco.

targetPassword

User password for authentication to Alfresco.

targetBaseUrl

Alfresco CMIS API base URL.

cmisBindingType

CMIS API type, "browser" is the most performant, default is "atompub".

Example Configuration:
{
  "name": "Alfresco Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "alfresco",
    "targetUsername": "alfresco_username",
    "targetPassword": "alfresco_password",
    "targetBaseUrl": "http://alfresco.xillio.com/alfresco/api/-default-/public/cmis/versions/1.1/atom",
    "cmisBindingType": "browser"
  }
}

Features and Limitations

  • Supports only the cmis:Document and cmis:Folder CMIS types.

  • Moving (i.e. updating the parent decorator of an entity) is not supported.

3.17. Confluence

Configuration

Configuration:
Parameter Description

type

The constant "confluence".

targetUsername

Username for authentication to Confluence.

targetPassword

User password for authentication to Confluence.

targetBaseUrl

Confluence base URL.

Example Configuration:
{
  "name": "Confluence Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "confluence",
    "targetUsername": "confluence_username",
    "targetPassword": "confluence_password",
    "targetBaseUrl": "https://my-wiki.atlassian.net/wiki"
  }
}

Features and Limitations

  • Only entities of kind Page can be created and updated.

3.18. Documentum

Configuration

Configuration:
Parameter Description

type

The constant "documentum".

targetUsername

Username for authentication to Documentum.

targetPassword

User password for authentication to Documentum.

targetBaseUrl

Documentum base URL.

documentumRepository

Documentum repository id.

Example Configuration:
{
  "name": "Documentum Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "documentum",
    "targetUsername": "documentum_username",
    "targetPassword": "documentum_password",
    "targetBaseUrl": "http://documentum.xillio.com",
    "documentumRepository": "MyRepo"
  }
}

Features and Limitations

  • Supports only dm_document, dm_cabinet and dm_folder.

  • When creating a Document with binary contents, the mimeType decorator is mandatory.

  • Entities of kind Cabinet (corresponding to dm_cabinet) cannot be created, only read.

  • Moving (i.e. updating the parent decorator of an entity) is not supported.

3.19. Github

Configuration

Configuration:
Parameter Description

type

The constant "github".

targetUsername

Username for authentication to Github.

targetPassword

User password for authentication to Github.

targetBaseUrl

Github base URL.

Example Configuration:
{
  "name": "Github Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "github",
    "targetUsername": "github_username",
    "targetPassword": "github_password",
    "targetBaseUrl": "https://api.github.com"
  }
}

Features and Limitations

  • createEntity can only create files.

  • New folders are implicitly created when creating files in them.

  • Moving (i.e. updating the parent decorator of an entity) is not supported.

3.20. Liferay

Configuration

Configuration:
Parameter Description

type

The constant "liferay".

targetUsername

Username for authentication to Liferay.

targetPassword

User password for authentication to Liferay.

targetBaseUrl

Liferay base URL.

Example Configuration:
{
  "name": "Liferay Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "liferay",
    "targetUsername": "liferay_username",
    "targetPassword": "liferay_password",
    "targetBaseUrl": "http://liferay.xillio.com"
  }
}

Features and Limitations

  • Entities of kind File and Folder can be created at urls in the form of: https://api.xill.io/ConfigurationID/LiferaySiteID/dm.

  • Entities of kind Article and Folder can be created at urls in the form of: https://api.xill.io/ConfigurationID/LiferaySiteID/content.

  • Creating entities other than the kinds described above is not supported.

  • When getting the contents of documents, enable the "Auto Login Basic Authentication Header" setting and add /documents/* to "urls-include" of the "Basic Auth Header Verifiers" setting in Liferay.

  • When creating an Article, the language decorator must contain the default language configured in Liferay. The en_US language is used by default. Adding additional languages is not yet supported.

  • When creating an Article, its contents must be in the Liferay XML format.

  • Moving (i.e. updating the parent decorator of an entity) is not supported.

  • Updating an entity of type File is not supported by Liferay.

3.21. Nuxeo

Configuration

Configuration:
Parameter Description

type

The constant "nuxeo".

targetUsername

Username for authentication to Nuxeo.

targetPassword

User password for authentication to Nuxeo.

targetBaseUrl

Nuxeo base URL.

cmisBindingType

CMIS API type, "browser" is the default and most performant.

Example Configuration:
{
  "name": "Nuxeo Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "nuxeo",
    "targetUsername": "nuxeo_username",
    "targetPassword": "nuxeo_password",
    "targetBaseUrl": "http://nuxeo.xillio.com/nuxeo/json/cmis",
    "cmisBindingType": "browser"
  }
}

Features and Limitations

  • Supports only the cmis:Document and cmis:Folder CMIS types.

  • Moving (i.e. updating the parent decorator of an entity) is not supported.

  • Updating the description field is not supported.

3.22. Zendesk

Configuration

Configuration:
Parameter Description

type

The constant "zendesk".

targetUsername

Username for authentication to Zendesk.

targetPassword

User password for authentication to Zendesk.

targetBaseUrl

Zendesk base URL.

zendeskToken

Application token for the given credentials (targetUsername and targetPassword).

Example Configuration:
{
  "name": "Zendesk Sample Configuration",
  "configurationType": "Xde",
  "config": {
    "username": "xde_user",
    "password": "xde_password",
    "tokenUrl": "https://xcs.xillio.com/oauth/token",
    "clientId": "xde_client_id",
    "clientSecret": "xde_client_secret",
    "baseUrl": "https://xcs.xillio.com:8082/xde/xps/api/1.0/projects/xill-connector-suite/robots",
    "type": "zendesk",
    "targetUsername": "zendesk_username",
    "targetPassword": "zendesk_password",
    "targetBaseUrl": "https://mysupport.zendesk.com/api/v2/",
    "zendeskToken": "my-token"
  }
}

Features and Limitations

  • getEntity only supports entities of kind Categories, Sections and Articles.

  • createEntity and deleteEntity only support entities of kind Articles.

  • Creating an Article without content is not supported.