Writing Data

Introduction

Once you are familiar with reading data from the API, writing data is just as easy and can be done using one of two calls depending if you want to add a new record or update an existing record.

Adding Records

In order to add a new record data will need to be sent via a POST request to a URL similar to the following (replacing "company" with the page name you wish to add data too);

https://ofd-api.blueprintcpq.net/data/company

The API will only accept data in a structure like the following;

[
    {
        "Section": "69993d68-3fe5-e511-80cd-00155d2d8e03",
        "Data": [
            {
                "Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03"
                "Value": "8503d6d4-94ae-4416-b3b6-291e20d9d96e"
            },
            {
                "Field": "a0983d68-3fe5-e511-80cd-00155d2d8e03"
                "Value": "Q002262"
            },
            {
                "FieldName": "CustomerGuid",
                "Value": "247d2c2f-c02a-45d1-8147-c5eeb4ce8a42"
            },
            ...
        ]
    },
    ...
]

When sending data to the API, you can use either Field or FieldName to reference the field you wish to set the value of depending on if you are referencing the fields by identifier or name.

If, based on the metadata for a field there is a relationship that means the field is a link to another record, you may need to lookup values that are valid for the field. This is covered in the relationships documentation.

If you do not wish to add a record into a section you can insert directly into the page by passing null as the section value. You can find a list of all of the fields that can be sent for a page by calling the get defaults method of the metadata interface.

Once a record has been created the API will respond with the new Id of the record from the base table.

Updating Records

If rather than add a record you wish to update one that already exists, you will need to know the following;

• Page name
• Record Identifier
• Section

Updating a record makes use of the HTTP verb PUT. This works in a similar way to POST but lets us know that we are updating rather than creating. The first step is to build the URL that you will need to send the data to. This will be similar to the following (again, replacing the page name and record identifiers);

https://ofd-api.blueprintcpq.net/data/company/45ff04ee-ce18-4cb5-b14d-b7cd9930ad58

Then, in the body of the document you will need to build a data structure similar to the one used for adding records, specifying the section and array of fields and values to set. Again, it is possible to leave the Section set to null in order to write directly to the page. You should have a JSON structure similar to the following;

[
    {
        "Section": "69993d68-3fe5-e511-80cd-00155d2d8e03",
        "Data": [
            {
                "Field": "9c983d68-3fe5-e511-80cd-00155d2d8e03"
                "Value": "8503d6d4-94ae-4416-b3b6-291e20d9d96e"
            },
            {
                "FieldName": "OurReference",
                "Value": "Q002274"
            },
            {
                "Field": "a2983d68-3fe5-e511-80cd-00155d2d8e03",
                "Value": "247d2c2f-c02a-45d1-8147-c5eeb4ce8a42"
            },
            ...
        ]
    },
    ...
]

Once you have made the request the API will respond with a true or false statement depending on if the action was successful.

Things to Remember

When creating data, remember that some fields are mandatory and a record will not be created if a certain field is not filled in. You can tell which fields are required by requesting the metadata for a section using the API and checking the Required property of a field.