@cabutter_su/workfront_api v0.1.9

Workfront Typescript Client

Soft Type support for Workfront API Client. Making it easier to work with Workfront data.

Usage

Import the client

import WF from "@cabutter_su/workfront_api"

The default WfAPI import object includes a client() method which returns an axios instance with custom methods and a builder instance which is a utility class to help build config options.

Initialize the clinet

const Client = WF.client({
  subDomain: "example",
  withAuth: {
    apiKey: process.env.APIKEY
  }
})

NOTE Set up env variable to read the API Key For testing apiKey in development you can use the dotenv package.

import dotenv from "dotenv"
dotenv.config()

// add error catch
if(!process.env.APIKEY) throw new Error("API Key not found")

Examples

Note Functions are written with async/await syntax, which requires calling from within an async function (waiting on support for top-level await). You can, of course, use .then()

Client.search("/proj", {
    name: "TEST",
    name_Mod: "contains"
  },
  WF.builder.addFields(["owner", "owner:emailAddr"]))
  .then(data => {
    console.log(data)
  }
)

Create an Object

async function main() {
  await Client.post("/PROJ", {
    name: "An Example Projct"
  })
  
  // or
  
  await Client.create("PROJ", {
    name: "An Example Project"
  })
  
  // or
  
  await Client.createProject({
    name: "An Example Project"
  })
}

main()

Uploading a File

const filename = "test.png"
const filePath = __dirname + "/" + filename
await Client.uploadFile(filePath, {
  name: filename,
  docObjCode: "PROJ",
  objID: "5f847540038568e051176ae859866f3f" // TEST - Barnes Student Experience
}) // returns - { data: { ID: 1234, name: 'test', objCode: 'Docu', description: null } }

ReqBuilder

The ReqBuilder is a utility builder class that provides inline documentation to help interact with APIs

await Client.put("/proj", { name: "some data" }, WfAPI.builder
    .addFields(["owner", "owner:emailAddr"])
    .setParams({
      ID: "5f847540038568e051176ae859866f3f"
    })
)

Why

• Whether using TypeScript or not (but it's much better with), this library can help streamline intellisense autocomplete code and highlihgt bugs before you run them.

• The file upload on the official Workfront Client was not working for me.

• Writing a library for an API I use regularly and with TypeScript was a valuable learning experience

How it Works

The HttpApi function abstracts an axios instance providing main methods (GET, PUT, POST, REMOVE) as well as set up a basic Error Handler using interceptors.

HttpApi is called to create a new instance of a desired API client. In this case, Workfront.

function WorkfrontApi(customOpts?: WF.ClientOptions) {  
  // Default client options - can be easily extended
  const clientOpts: WF.ClientOptions = {
    ...customOpts
  }
  
  // Returns a minified axios instance with types!
  const instance = HttpApi<WF.Urls, WF.WorkItemPayload, WF.RequestConfig, WF.Results>(WF_AXIOS_OPTIONS, clientOpts)

  /* ... */

  const { get, post, put, remove, request } = instance
  return {
    get,
    post,
    put,
    remove,
    request,

    /* custom methods defined below... */
  }
}