Docs Developer Site
Developer Docs Code Stable Libraries Lib Project

Content Project library

Contents

This API provides functions for management of Content Projects.

Usage

Add the following dependency to your build.gradle file:

dependencies {
  include xplibs.project
}

Add the import statement to your code:

import projectLib from '/lib/xp/project';

You are now ready to use the API.

Functions

addPermissions

Adds permissions to an existing Content Project.

To modify permissions, user must have Owner permissions for the project, or either system.admin or cms.admin role.
You can read about project permissions in the dedicated Content Projects section

Parameters

Name Kind Details

id

string

Unique project id to identify the project.

permissions

Object.<string, string[]>

Project permissions to add. 1 to 5 properties where key is role id and value is an array of principals.

Returns

Object : All current project permissions.

Example

Add permissions to a project with id 'my-project'
import {addPermissions} from '/lib/xp/project';

const currentPermissions = addPermissions({
    id: 'my-project',
    permissions: {
        owner: ['user:mystore:user1', 'user:mystore:user2'],
        editor: ['user:mystore:user3']
    }
});
Sample response
const expected = {
    permissions: {
        owner: [
            'user:mystore:user1',
            'user:mystore:user2'
        ],
        editor: [
            'user:mystore:user3'
        ]
    }
}

create

Creates a new Content Project.

Only system.admin and cms.admin roles have permissions to create new projects.

Parameters

Name

Type

Attributes

Description

id

string

Unique project id (alphanumeric characters and hyphens allowed).

displayName

string

Project display name.

parents

string[]

<optional>

Parent project ids. If provided, the new project will be a Content Layer that automatically inherits changes from its parent projects.

description

string

<optional>

Project description.

language

string

<optional>

Default project language.

siteConfig

Object.<string, Object>[]

<optional>

Applications (with optional configurations) to be assigned to the project

Name

Type

Description

applicationKey

string

Application key

config

Object

Application config json

permissions

Object.<string, string[]>

<optional>

Project permissions. 1 to 5 properties where key is role id and value is an array of principals.

Name

Type

Description

role

string

Role id (one of owner, editor, author, contributor, viewer).

principals

string[]

Array of principals.

publicRead

boolean

true to grant READ permissions to system.everyone, false otherwise.

Returns

Object : Project object.

Example

Create a Content Project with minimal properties
import {create} from '/lib/xp/project';

try {
    const project = create({
        id: 'my-project',
        displayName: 'My Content Project',
        publicRead: true
    });
} catch (e) {
    log.error('Failed to create a project: %s', e.message);
}
Sample response
const expected = {
  id: 'my-project',
  displayName: 'My Content Project',
  permissions: {},
  publicRead: true
}
Create a Content Project with extended properties
import {create} from '/lib/xp/project';

const project = create({
    id: 'my-project',
    displayName: 'My Content Project',
    description: 'Some exciting content is stored here',
    language: 'no',
    permissions: {
        owner: ['user:mystore:user1'],
        editor: ['user:mystore:user2'],
        author: ['user:mystore:user3'],
        contributor: ['user:mystore:user4'],
        viewer: ['user:mystore:user5']
    },
    siteConfig: [{
            applicationKey: 'app1',
            config: {
                a: 'b'
            }
        } ,{
            applicationKey: 'app2',
            config: {
                a: true,
                b: 3.4
            }
        }],
    publicRead: false
});
Sample response
const expected = {
  id: 'my-project',
  displayName: 'My Content Project',
  description: 'Some exciting content is stored here',
  language: 'no',
  siteConfig: [
        {
            applicationKey: 'app1',
            config: {
                a: 'b'
            }
        },
        {
            applicationKey: 'app2',
            config: {
                a: true,
                b: 3.4
            }
        }
    ],
  permissions: {
    owner: [
        'user:mystore:user1'
    ],
    editor: [
        'user:mystore:user2'
    ],
    author: [
        'user:mystore:user3'
    ],
    contributor: [
        'user:mystore:user4'
    ],
    viewer: [
        'user:mystore:user5'
    ]
  },
  publicRead: false
}

deleteProject

Deletes an existing Content Project and the project repository along with all the data inside.

To delete a project, user must have either system.admin or cms.admin role.

Parameters

Name Kind Details

id

string

Unique project id to identify the project.

Returns

boolean : true if the project is successfully deleted.

Example

Delete an existing content project
import {deleteProject} from '/lib/xp/project';

const result = deleteProject({
    id: 'my-project'
});
Sample response
const expected = true;

get

Returns an existing Content Project.

To access a project, user must have sufficient permissions for this project, or either system.admin or cms.admin role.

Parameters

Name Kind Details

id

string

Unique project id to identify the project.

Returns

Object : Content Project object or null if not found.

Example

Fetch an existing content project
import {get as getProject} from '/lib/xp/project';

const project = getProject({
    id: 'my-project'
});
Sample response
const expected = {
    id: 'my-project',
    displayName: 'My Content Project',
    permissions: {
        owner: [
            'user:mystore:user1'
        ],
        editor: [
            'user:mystore:user2'
        ]
    },
    readAccess: {
        public: true
    }
}

list

Returns all Content Projects that user in the current context has permissions for.

Users with system.admin or cms.admin roles will get the list of all projects.

Returns

Object[] : Array of Content Project objects.

Example

Fetch the list of existing content projects
import {list} from '/lib/xp/project';

const projects = list();
Sample response
const expected = [{
    id: 'default',
    displayName: 'Default',
    description: 'Default project',
    permissions: {},
    readAccess: {
        public: true
    }
},
{
    id: 'my-project',
    displayName: 'My Content Project',
    permissions: {},
    readAccess: {
        public: true
    }
}]

modify

Modifies an existing Content Project.

Pass an editor function that receives the current project, mutates fields on it, and returns it. Fields the editor doesn’t touch are left unchanged. Setting description, language, or siteConfig to null clears them. displayName is required and cannot be cleared.

To modify a project, user must have Owner permissions for this project, or either system.admin or cms.admin role.

Parameters

Name Type Description

id

string

Unique project id (alpha-numeric characters and hyphens allowed).

editor

Function

Function that receives the editable project, mutates fields, and returns it.

The editor’s input has the same shape as a Project plus the editable fields displayName, description, language, and siteConfig.

Returns

Object : Modified project object.

Example

Modify an existing content project
import {modify} from '/lib/xp/project';

const project = modify({
    id: 'my-project',
    editor: (project) => {
        project.displayName = 'New project name';
        project.description = 'New project description';
        project.language = 'en';
        project.siteConfig = [{
            applicationKey: 'app1',
            config: { a: 'b' }
        }, {
            applicationKey: 'app2',
            config: { a: true, b: 3.4 }
        }];
        return project;
    }
});
Sample response
const expected = {
    id: 'my-project',
    displayName: 'New project name',
    description: 'New project description',
    language: 'en',
    siteConfig: [
        {
            applicationKey: 'app1',
            config: {
                a: 'b'
            }
        },
        {
            applicationKey: 'app2',
            config: {
                a: true,
                b: 3.4
            }
        }
    ],
    permissions: {},
    publicRead: true
}

setPublicRead

Toggles public/private READ access for an existing Content Project. This will modify permissions on ALL the content items inside the project repository by adding or removing READ access for system.everyone.

To modify READ access, user must have Owner permissions for the project, or either system.admin or cms.admin role.

Parameters

Name Type Description

id

string

Unique project id (alpha-numeric characters and hyphens allowed).

publicRead

boolean

true to grant READ permissions to system.everyone, false otherwise.

Returns

boolean : Resulting public-read state.

Example

Set content project as not available for public READ access
import {setPublicRead} from '/lib/xp/project';

const publicRead = setPublicRead({
    id: 'my-project',
    publicRead: false
});
Sample response
const expected = false;

removePermissions

Removes permissions from an existing Content Project.

To remove permissions, user must have Owner permissions for the project, or either system.admin or cms.admin role.

Parameters

Name Type Description

id

string

Unique project id (alpha-numeric characters and hyphens allowed).

permissions

Object.<string, string[]>

Project permissions to delete. 1 to 5 properties where key is role id and value is an array of principals.

Name

Type

Description

role

string

Role id (one of owner, editor, author, contributor, viewer).

principals

string[]

Array of principals to delete from this project role.

Returns

Object : All current project permissions.

Adds and then removes permissions from an existing content project
import {addPermissions,removePermissions} from '/lib/xp/project';

addPermissions({
    id: 'my-project',
    permissions: {
        owner: ['user:mystore:user1', 'user:mystore:user2'],
        editor: ['user:mystore:user3']
    }
});

const currentPermissions = removePermissions({
    id: 'my-project',
    permissions: {
        owner: ['user:mystore:user2']
    }
});
Sample response
const expected = {
    permissions: {
        owner: [
            'user:mystore:user1'
        ],
        editor: [
            'user:mystore:user3'
        ]
    }
}

getAvailableApplications

Returns available applications of a specified project. The result contains active apps assigned to the project and all of its parents, if any.

User must be a member of one of the project roles, or either system.admin or cms.admin role.

Parameters

Name Kind Details

id

string

Unique project id to identify the project.

Returns

string[] : Application keys.

Example

Fetch available applications.
import {getAvailableApplications} from '/lib/xp/project';

const project = getAvailableApplications({
    id: 'my-project'
});
Sample response
const expected = ['app1', 'app2']

Contents

Contents