Xpenser API: Project Creation and Participant Guide

This document provides a guide for using the Xpenser APIs to create projects and to assign participants to those projects.

This can be used, for example, to integrate Xpenser with your existing project management system, such that creating a project in your project management system results in the creation of a project in Xpenser, and assigning participants to that project in your project management tool results in assignment of the corresponding Xpenser employee account to the Xpenser Project.

Overview

We will demonstrate how to use the APIs to:

We will use curl, a command-line tool for accessing Web APIs, to demonstrate API access in this guide. You can use your favorite programming language to access the same APIs to implement your own integration.

Implementation

Create a Project in Xpenser

Using the Xpenser Project Creation API, we will create a project called "Phase 1, Client X". We'll assign this project the externalid 6789, which represents the id of the project in our project management system (note that this is optional).

curl -u apiuser@mycompany.com:password \
    -d "name=Phase+1,+Client+X&externalid=6789" \
    "http://xpenser.com/api/v1.0/projects/project"

which will produce the response:

{
    "status": "A", 
    "organization_id": 39659, 
    "externalid": "6789", 
    "name": "Phase 1, Client X", 
    "id": 293
}

This tells us the project has been created in Xpenser, and Xpenser has assigned it the id 293. The organization_id represents the id for your company's Xpenser account. externalid represents this project's id in our external system, and can be used when integrating systems to tie the Xpenser id for a project to the id used by the other systems.

Now that the project has been created, let's go to the Xpenser Projects page to verify it exists:

Xpenser Project Created

Assigning Participants to the Project

Now that we've created the project we'd like to assign participants to this project - that is, we would like to specify which Xpenser employee accounts participate in this project.

The first step is to find the id for the employee account we want to include.

The Employee Accounts API allows us to inspect our employee accounts:

curl -u apiuser@mycompany.com:password http://xpenser.com/api/v1.0/orgchart/people/

This returns the full list of employee accounts in our company:

[
    {
        "first_name": "Anthony", 
        "last_name": "Cedecas", 
        "user_id": 53867, 
        "level": 3, 
        "type": "I", 
        "id": 53811, 
        "parent_id": 53810, 
        "role": "", 
        "deptname": "", 
        "email": "anthony@crossrec.com"
    }, 
    {
        "first_name": "Norbert", 
        "last_name": "Crosan", 
        "user_id": 53868, 
        "level": 3, 
        "type": "I", 
        "id": 53812, 
        "parent_id": 53810, 
        "role": "", 
        "deptname": "", 
        "email": "norbert@crossrec.com"
    }, 
    {
        "first_name": "Jim", 
        "last_name": "Jimminy", 
        "user_id": 42708, 
        "level": 2, 
        "type": "I", 
        "id": 42577, 
        "parent_id": 52086, 
        "role": "", 
        "deptname": "", 
        "email": "jimj@crossrec.com"
    }, 
    {
        "first_name": "Mark", 
        "last_name": "Spencer", 
        "user_id": 52164, 
        "level": 1, 
        "type": "I", 
        "id": 52087, 
        "parent_id": 39659, 
        "role": "", 
        "deptname": "", 
        "email": "reallynew@crossrec.com"
    }
]

Let's make Anthony Cedecas a participant in our newly created project. As we can see from the API response that Anthony's Xpenser id is 53811 .

The Project Participants API allows us to add, remove, and update project participants. To add Anothony to our project we will need:

This call performs an HTTP POST call to the project participants API, specifying the id of the project and that of the participant.

Xpenser will respond with:

{
    "contact_id": 53811, 
    "project": {
        "status": "A", 
        "name": "Phase 1, Client X", 
        "level": 0, 
        "organization_id": 39659, 
        "externalid": "6789", 
        "id": 293
    }, 
    "approvalrole": null, 
    "contact": {
        "first_name": "Anthony", 
        "last_name": "Cedecas", 
        "user_id": 53867, 
        "type": "I", 
        "id": 53811, 
        "role": "", 
        "deptname": "", 
        "email": "anthony@crossrec.com"
    }, 
    "role": null, 
    "rule": "I", 
    "id": 277
}

There we have it: Anthony is now a participant in this project. We can verify this by going to the Xpenser Projects page and clicking on the Phase 1, Client X project:

Xpenser Project Participant

Account Setup and Permissions

It's best to create a separate user for API access instead of reusing our regular Xpenser login. This will help us keep the API access separate from normal employee Xpenser access.

Create a new user account in Xpenser via the Account->Company and Org Chart page. Call this user apiuser@mycompany.com. Then drop us a quick email at feedback@xpenser.com requesting this user be made an administrator.