Articles in this section

Using the API To Create & Update Folios

Avatar
Jack Davenport
Follow

The mutations you use for Creating & Updating in Folio are slightly different but all use the same structure for the fields and values.

The fieldResponses is an array of objects where each object represents a field. The object contains the field’s id and the value that will be stored in that field.

So for example if you were updating 3 fields on a Folio you would have three objects in the array - each having the corresponding fieldid and content in the specified format for that field type. 

An example of the array for creating a Folio is shown below

fieldResponses: [{fieldId: "MDBGaWVsZC0xNDI", text: "Some Example Text"}]

Another example below shows the array but the field i am using ia a multi select, so my values for the field are in an array called “fieldAnswerResponses” , where i use the fieldAnswerId to select the answers and on my second one have set the freeFormText for that answer to “I do my taxes myself”. 

fieldResponses: [
 {
   fieldId: "MDBGaWVsZC00MzA"
   fieldAnswerResponses: [
     {fieldAnswerId: "MDBGaWVsZEFuc3dlci05N"}
     {
       fieldAnswerId: "MDBGaWVsZEFuc3dlci05OQ",
       freeFormText: "I do my taxes myself"
     }
   ]
 }
]

mceclip0.png

The rules for how you pass values for each field type are explained here

To get the fieldId for a field you use the folioFields query explained here

Creating a Folio

There are two ways of creating a new Folio, one for using the Public link app and one for using a Server app.

Creating a Public Link Folio

To create a public link folio you will be using mutations so each query should be like below at a minimum (For creating a Folio as a Server you will use the createFolio mutation below)

This example will create a new folio and fill in one long text field with the text “some Example text”

Request

 Response 
mutation {
  createPublicLinkFolio(input: {
      submitterEmail: "person@example.com", 
      fieldResponses: [
        {
         fieldId: "MDBGaWVsZC0xNDI", 
         text: "Some Example Text"
        }
      ]
   }
  ) {
   data {
     id
     key
     title
  }
  errors {
     message
  }
  }
}
 
{
 "data": {
   "createFolio": {
     "data": {
       "id": "Contract-3871",
       "key": "LIT-29",
       "title": "Example Template"
     }
   }
 }
}

Creating a Folio as a Server

To create a folio you will use the createFolio mutation, which requires you to nominate the template that you are creating for, you can find the template id using the folioTemplates explained here

Request

 Response 
mutation {
 createFolio(input: {
    folioTemplateId:"MDBDb2lLTMxOQ", 
    fieldResponses: [
     {
       fieldId: "MDBGaWC0xNDI"
       text: "folio <i>description</i>"
     }
   ]
 })
{
 data {
   id
   key
   title
   }
 }
}
 
{
 "data": {
   "createFolio": {
     "data": {
       "id": "Contract-3871",
       "key": "LIT-30",
       "title": "Example Template",
     }
   }
 }
}

Updating Folios

A Server app will let you update Folios that the executed as user is able to update within Folio. 

After the mutation is run the fields will now reflect the values you specified on the mutation Except for multi selects where the existing answers will remain and any new answers will be selected alongside the existing answers. 

Mutation

Updating a folio uses the updateFolio mutation. The Update mutation however requires the id of the folio you are going to update (You can get this id from the folios query, explained here Getting Folios). 

Below is a very basic example of how to update a Folio. Where I am updating a numeric field to the new value of 175. I then get the key and title of the Folio as a confirmation that it has been updated - as well as any errors that have occurred.

Request

 Response 
mutation {
  updateFolio(
    input: {
      folioId: "MDBDb250cmFjdC0zOTUz",
      fieldResponses: [
         {
           fieldId: "MDBGaWVsZC05MjYw", 
           numeric: 175
         }
      ]
     }
  ) 
 {
    data {
      key
      title
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}
 
{
  "data": {
    "updateFolio": {
      "data": {
        "key": "CON-1",
        "title": "Contract with Example Corp"
      },
      "errors": null
    }
  }
}

 

Another example of using the update, here I am updating three fields on my example record;

  • The first is the title which i am going to change to “2021 Contract with Example Corp”
  • The second is a business unit field which i am going to update to Finance and South
  • The third is a custom field i have called Contract Type which i will be updating to Services Contract

To start im going to grab the ID of the Folio using the folios query, so in my case my id is

folioId: "MDBDb250cmFjdC0zOTUz"

Then im going to grab the templates id using the folioTemplates query, which in my example is 

"id": "MDBDb250cmFjdFRlbXBsYXRlLTMxOQ"

Then using that id i can find the ids of the fields on the template, using the query below:

{folioFields(folioTemplateId:"MDBDb250cmFjdFRlbXBsYXRlLTMxOQ"){edges {
  node {
    builtInFieldName
    name
    id
  }
}}}

Before i can update the Folio i just need to grab the field answers for my Contract Type and the ID’s of my two business units i want to use. 

For my business units i use

{businessUnits{edges {
  node {
    id
    title
  }
}}}

And for Contract Type i use 

{fieldAnswers(fieldId:"MDBGaWVsZC05MjMy"){edges {
  node {
    id
    text
  }
}}}

So now i have everything i need to create the update mutation. Below is my final mutation that will update my Folio to have the new title, business units and Contract Type

mutation {
  updateFolio(
    input: {
      folioId: "MDBDb250cmFjdC0zOTUz",
      fieldResponses: [
         {
           fieldId: "MDBGaWVsZC04OTA5", 
           text:  “2021 Contract with Example Corp”
         },
         {
           fieldId: "MDBGaWVsZC04OTgy", 
           businessUnitIds: [“MDBCdXNpbmVzc1VuaXQtNQ”, “MDBCdXNpbmVzc1VuaXQtMjg” ]
         },
         {
           fieldId: "MDBGaWVsZC05NDY1", 
           fieldAnswerResponses: [{fieldAnswerId:”MDBGaWVsZEFuc3dlci0xOTMyMA”}]
         }
      ]
     }
  ) 
 {
    data {
      key
      title
    }
    errors {
      extensions {
        fieldName
      }
      message
    }
  }
}

Notes: 

You are unable to update signature fields using the API

Related articles